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: 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.