inline-schema/AGENTS.md

# 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:** `npm run typecheck`
- **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()` (eager resolution) and `csvToModule()` (accessor-based output with lazy resolution); `resolveReferences: false` mode stores IDs instead of resolved objects
  - `webpack.ts`, `rollup.ts`, `esbuild.ts` — bundler plugin wrappers around `csvToModule`

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
- Unknown identifiers throw a `ParseError` — only recognized keywords (`string`, `number`, `int`, `float`, `boolean`) and string literals (`"on"`, `'off'`) are valid types
- `@tablename` / `@tablename[]` are reference schemas resolved at CSV load time
- `csvToModule()` emits accessor functions (`getData()`) for tables with references, and static JSON for tables without; bundler loaders all use `csvToModule`
- `parseCsv({ resolveReferences: false })` stores reference IDs instead of resolved objects — used by `csvToModule` to emit import-based lazy resolution
- References can appear nested inside tuples, arrays, and unions; the loader resolves them recursively

## Gotchas

- **Circular references** between CSV tables are supported in `csvToModule` output via accessor-based lazy resolution. `parseCsv()` with `resolveReferences: true` (default) still detects and throws on circular references via an in-progress loading set.
- **Run `npm run typecheck` before committing** to catch type errors.
- **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 single-quoted string literals (`'on' | 'off'`) or 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`.