@rayspec/spec 1.5.0

package/dist/lint.d.ts

@@ -0,0 +1,79 @@
+import { type SpecError, type SpecWarning } from './errors.js';
+import { type RaySpec } from './grammar.js';
+/**
+ * Column names the table generator INJECTS on every product table (the tenancy/GDPR pattern —
+ * see packages/db/src/schema.ts). An author-declared business column with one of these names
+ * would shadow/collide with the injected column, so the linter rejects it fail-closed.
+ */
+export declare const RESERVED_COLUMN_NAMES: ReadonlySet<string>;
+/**
+ * The list-query CONTROL keywords — the reserved query-string keys the declarative `list` route
+ * uses to steer sorting, keyset pagination, and substring search (mirrors `CONTROL_KEYS` in the compose
+ * package's store-query.ts; @rayspec/spec cannot import the compose package, so this is the KEEP-IN-SYNC
+ * copy).
+ *
+ * A declared BUSINESS column of one of these names is a config error, because at the `list` route it is
+ * (a) silently un-equality-filterable — `buildListQuery` routes `?order=`/`?after=`/`?limit=`/`?search=`
+ * to the control parsers and never reaches the per-column equality lookup — AND (b) it makes the emitted
+ * OpenAPI document carry a DUPLICATE query parameter (the hard-coded control param + the per-column
+ * filter param share a `name`+`in`), which is an INVALID OpenAPI 3.1 doc. This is a SEPARATE set from
+ * `RESERVED_COLUMN_NAMES` on purpose — that Set is meta-test-locked to equal the injected columns
+ * (`INJECTED_COLUMN_NAMES`); these keywords are not injected columns, they are query controls.
+ */
+export declare const RESERVED_QUERY_KEYWORDS: ReadonlySet<string>;
+/**
+ * The name of the GENERATED tsvector column the store generator injects when a store declares
+ * `fullTextSearch: true` (a GENERATED-ALWAYS-STORED `to_tsvector('simple', …)` column over the store's
+ * text columns, backed by a GIN index — see @rayspec/db generate-product-sql). It is a DB-level search
+ * structure (NOT represented in the Drizzle ORM twins, exactly like the injected `<table>_tenant_idx`
+ * and the idempotency unique index), so it never surfaces in a list response. Reserved: an FTS store may
+ * not declare a business column of this name (the FTS coherence check below rejects the clash).
+ */
+export declare const FTS_COLUMN_NAME = "search_vector";
+/**
+ * The ranked full-text-search list-query control key (`?__search=<term>`). Distinct from the substring
+ * `search` control key: `__search` is available ONLY on a store that declares `fullTextSearch: true`,
+ * runs a `search_vector @@ websearch_to_tsquery('simple', term)` match, and orders by `ts_rank` DESC.
+ * A store WITHOUT full-text search rejects the param fail-closed. Mirrored in the compose package's
+ * store-query.ts `CONTROL_KEYS` (this package cannot import compose — a KEEP-IN-SYNC copy, guarded by
+ * the reserved-keyword membership above).
+ */
+export declare const FTS_SEARCH_PARAM = "__search";
+/**
+ * Route prefixes the PLATFORM owns — a declared static frontend mount may neither claim one nor nest
+ * under one (the frontend lint rule below), and the static runtime declines any request under one so a
+ * platform miss falls through to the uniform JSON 404 rather than a served file / SPA shell
+ * (serve-static.ts consumes this SAME constant so the two never drift). Root `/` is NOT here: it is a
+ * legitimate static catch-all that coexists with `/v1/*` via registration order + fall-through.
+ */
+export declare const RESERVED_ROUTE_PREFIXES: readonly ["/v1", "/health", "/oidc"];
+/**
+ * snake_case -> camelCase, IDENTICAL to the generator's `toCamel` (generate-product-schema.ts), so
+ * the collision check here predicts the exact JS identifier the generator would emit. (TEN-3)
+ *
+ * EXPORTED for the product-store column-collision check in `product-lint.ts` —
+ * the ONE spec-side copy of the rule. KEEP-IN-SYNC (honest replication, dependency direction:
+ * spec must not import platform/db): the SAME rule also lives in
+ *  - packages/db/src/generated/generate-product-schema.ts (`toCamel`) + build-product-tables.ts,
+ *  - packages/platform/src/handlers/store-facade.ts (`snakeToCamel`),
+ *  - packages/api-auth/src/engine/injected-columns-view.ts (`snakeToCamel`).
+ * A literal-example pin test (product-stores.test.ts, "snake→camel pin") guards this copy against
+ * drift; if the rule ever changes, ALL copies + the pin must move together.
+ */
+export declare function toJsIdentifier(name: string): string;
+/** The full semantic pass. Input is already shape-valid (post-Zod-parse). */
+export declare function lintSpec(spec: RaySpec): SpecError[];
+/**
+ * The NON-FATAL semantic-warning pass — advisory findings that do NOT fail a parse (unlike `lintSpec`).
+ * Pure over an already-shape-valid `RaySpec`. `doctor`/`plan` surface these alongside the `ok` result so
+ * an author sees a documented interaction without being blocked.
+ *
+ * Today it flags ONE interaction: a `softDelete` store that is the TARGET of a `restrict` foreign key —
+ * EITHER an id-target FK (referencing the parent's injected `id`) OR a business-key FK
+ * (`referencesColumn`). Both carry the identical footgun: soft-deleting such a parent is an
+ * `UPDATE(deleted_at)` that does NOT fire the database ON DELETE restrict, so the referencing rows keep
+ * pointing at the (tombstoned) parent — the restrict guarantee only binds on a HARD delete. This is a
+ * permitted, documented interaction, so it is a WARNING, not a fail-closed error.
+ */
+export declare function lintSpecWarnings(spec: RaySpec): SpecWarning[];
+//# sourceMappingURL=lint.d.ts.map

package/dist/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AA8CA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAA0B,MAAM,aAAa,CAAC;AACvF,OAAO,EAA0C,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAOpF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAUpD,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAStD,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,sCAAuC,CAAC;AA+B5E;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAoSD,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,EAAE,CAitBnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,CAqD7D"}