From ae2445b79c90584491bcc82ff181f77ab81cc5c3 Mon Sep 17 00:00:00 2001
From: hypercross <helios.tnak@gmail.com>
Date: Wed, 15 Apr 2026 14:01:50 +0800
Subject: [PATCH] feat: add AGENTS.md

---
 AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e50c568
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# AGENTS.md
+
+## Commands
+
+- **Build:** `npm run build` (tsup, CJS + ESM + d.ts for all entry points)
+- **Test:** `npm run test` (vitest run) | `npm run test:watch` (vitest watch)
+- **Type check:** `npx tsc --noEmit` (no dedicated script; run before committing)
+- **Run a single test:** `npx vitest run -t "test name pattern"`
+
+No linter or formatter is configured. No CI pipeline exists.
+
+## Architecture
+
+Single-package TypeScript library with two runtime entry points:
+
+- **`inline-schema`** (`src/index.ts`) — core schema parser, value parser, and validator
+  - `src/parser.ts` — `parseSchema()` turns schema strings into AST (`Schema` type)
+  - `src/validator.ts` — `parseValue()` and `createValidator()` operate on the AST
+  - `src/types.ts` — union type `Schema = Primitive | Tuple | Array | Reference | StringLiteral | Union`
+
+- **`inline-schema/csv-loader`** (`src/csv-loader/loader.ts`) — CSV loader with `@table` reference resolution
+  - `loader.ts` — `parseCsv()` and `csvToModule()`; resolves `@tablename` references by loading referenced CSV files from disk
+  - `webpack.ts`, `rollup.ts`, `esbuild.ts` — bundler plugin wrappers around `parseCsv`
+
+Build produces separate bundles per entry point (see `tsup.config.ts`). The csv-loader entries externalize `csv-parse`, `@rspack/core`, `esbuild`, and `rollup`.
+
+## Key conventions
+
+- Schema syntax uses **semicolons** (`;`) as separators, not commas
+- Identifiers with hyphens (e.g., `word-smith`) are treated as string schemas
+- `@tablename` / `@tablename[]` are reference schemas resolved at CSV load time
+- References can appear nested inside tuples, arrays, and unions; the loader resolves them recursively
+- `src/test.ts` is an ad-hoc console script, not a vitest suite — don't treat it as a real test
+
+## Gotchas
+
+- **Circular references** between CSV tables cause stack overflow. The loader detects this via an in-progress loading set and throws `"Circular reference detected"`.
+- **No `lint` or `typecheck` npm script** — run `tsc --noEmit` manually before committing changes.
+- **Union member ordering matters** — `parseValue` tries union members in order; the first one that parses wins. This affects references in unions (e.g., `@users[] | string` will try `@users[]` first).
+- **csv-parse quote handling** — Double-quoted schema values like `"active" | "inactive"` in CSV rows confuse the csv-parse library. Use unquoted identifiers in the schema row of CSV data when possible.
+- **Module imports use `.js` extension** — source files import from `../index.js` etc. (ESM convention), not `../index.ts`.