@lovrozagar/oat 0.9.1 → 0.11.0

package/dist/conformance/suite.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Conformance suite: the measurement loop.
+ *
+ * For each injected defect, assert oat reports exactly the check that defect should trip — and
+ * for the clean baseline, assert it reports nothing at all. The baseline is the harder bar: a
+ * tool that cries wolf on a correct backend is worse than no tool.
+ *
+ * Adding a check to oat means adding a defect here and expecting it. That keeps "smart" honest.
+ */
+import { type DefectName } from "../reference/defects.ts";
+import type { Finding } from "../runtime/finding.ts";
+import { type PrincipalSpec } from "../runtime/run.ts";
+export interface ParserResult {
+    name: string;
+    why: string;
+    ok: boolean;
+    detail: string;
+}
+/**
+ * Parser robustness. These fixtures are shapes real published documents contain; the bar is that
+ * oat never throws and never hangs on them, not that it models them well.
+ */
+export { runSeedContractSuite } from "./seed-contract.ts";
+export { runEffectsSuite } from "./effects.ts";
+export declare function runParserSuite(): ParserResult[];
+/**
+ * The annotated example document must resolve to what its comments claim.
+ *
+ * `labs/annotated-openapi.yaml` is the only place that shows a reader where each tag goes in a
+ * real document, and documentation that drifts from the implementation is worse than none — it
+ * teaches a shape that no longer works. Asserting the derived model here means the example cannot
+ * rot: rename a tag or change how a role resolves, and this fails.
+ *
+ * It also proved its worth immediately. The first version was invalid YAML (`{workspace_id}` inside
+ * a flow sequence) and named an `x-invalidate` route that did not exist in the document.
+ */
+export declare function runExampleSpecSuite(): Promise<ParserResult[]>;
+/**
+ * A skip on one entity must not look like the check never ran.
+ *
+ * Multi-entity labs made this lie: invalidate ran on every child and the console still said
+ * "did not apply" because the parents skipped it.
+ */
+export declare function runCoverageReportSuite(): ParserResult[];
+/**
+ * `doctor` claims each tag unlocks specific checks. This proves it.
+ *
+ * The reference backend is run twice — with its tags and with them stripped — and the checks that
+ * disappear must be exactly the set `TAG_UNLOCKS` promises. Without this the claim is a hand-
+ * maintained list that drifts the moment a check's applicability changes, and a coverage promise
+ * nobody verified is worse than no promise.
+ */
+/**
+ * `baselines`, when given, are the checks the defect matrix's two clean baselines ran — the same
+ * two runs this would otherwise make again.
+ */
+export declare function runTagUnlockSuite(baselines?: {
+    tagged: readonly string[];
+    untagged: readonly string[];
+}): Promise<ParserResult[]>;
+/**
+ * A public catalogue is unscoped. Two principals, create as A, GET or filter as B → 200 is
+ * the contract, and the isolation checks must not apply. The workspace-scoped widget fixture
+ * is unchanged: tag → SECURITY, heuristic → AMBIGUITY. Same split for item GET and for
+ * `filter=id.eq.<other tenant>`.
+ */
+export declare function runTenantScopeSuite(): Promise<ParserResult[]>;
+export declare function runPayloadCatalogSuite(): ParserResult[];
+export declare function renderParserSuite(results: ParserResult[]): {
+    text: string;
+    failures: number;
+};
+/**
+ * Generated reproducers are shell scripts, so a quoting mistake turns them into scripts that run
+ * against a literal `$BASE` with a literal `$TOKEN` — they look right and do the wrong thing.
+ * `bash -n` parses without executing, which catches that class before anyone copies one.
+ */
+export declare function checkReproSyntax(findings: Finding[]): Promise<string[]>;
+/**
+ * Which check each defect must trip.
+ *
+ * The first id is the primary — the diagnosis oat is required to reach. Any further ids are
+ * *acceptable* consequences: one defect can legitimately violate several properties at once, and
+ * calling those false positives would push oat toward under-reporting real problems.
+ */
+export declare const EXPECTED: Record<DefectName, string | string[]>;
+/**
+ * Defects only the SQL-backed reference can exhibit.
+ *
+ * The in-memory store has no physical column names, so a DDL/read naming mismatch has nowhere
+ * to happen. Every other defect is defined above the stores and runs on every engine.
+ */
+export declare const SQL_ONLY: ReadonlySet<DefectName>;
+export type Backend = "memory" | "sqlite" | "postgres" | "d1";
+/**
+ * The only defects a remote D1 can say anything an in-process engine cannot.
+ *
+ * Every statement against D1 is a network round trip, so a full pass costs minutes. The defects
+ * worth paying that for are the ones whose behaviour comes from the *engine build* — collation,
+ * type affinity, NULL ordering, LIKE escaping, identifier resolution. Everything else is decided
+ * in the request handler, where D1 would re-derive a result `node:sqlite` already gave for free.
+ * The lost update is not among them: the handler holds the write open on purpose, so it is real on
+ * any engine and runs on the in-memory one only (`ONE_ENGINE`).
+ */
+export declare const ENGINE_SENSITIVE: ReadonlySet<DefectName>;
+/**
+ * Defects that need cursor pagination to exist at all. A dialect that pages only by number
+ * cannot exhibit them, so reporting a miss there would be reporting the absence of a feature.
+ */
+/**
+ * Dialects that publish a cursor. Named rather than inferred, because "which defects can this
+ * shape even exhibit" is a property of the fixture, and a new dialect that forgets to declare
+ * itself here shows up as missed detections rather than as silent exclusions.
+ */
+export declare const DIALECTS_WITH_CURSOR: ReadonlySet<string>;
+/**
+ * Dialects that report a total. A shape publishing no count cannot publish a wrong one, so the
+ * count defects have nowhere to happen — the same reasoning that excuses cursor defects on a
+ * cursorless API, and not an excuse for a check that merely failed to fire.
+ */
+export declare const DIALECTS_WITH_TOTAL: ReadonlySet<string>;
+/**
+ * Dialects whose filtering is an expression language rather than one parameter per field.
+ *
+ * Equality-per-field has no expression to malform, no unknown *field* distinct from an unknown
+ * query parameter, and no way to write a pattern — so the defects that live inside a filter
+ * grammar have nowhere to happen.
+ */
+export declare const DIALECTS_WITH_FILTER_EXPRESSION: ReadonlySet<string>;
+export declare const COVERAGE_FLOOR: Record<string, number>;
+/** Defects that need a filter expression language to exist at all. */
+export declare const EXPRESSION_ONLY: ReadonlySet<DefectName>;
+/**
+ * Defects that need a postgrest-shaped filter writer (`in` / `ilike` / `is`). Colon and
+ * equality cannot emit those operators, so injecting the lie there is a miss that names the
+ * grammar rather than oat.
+ */
+export declare const POSTGREST_OP_ONLY: ReadonlySet<DefectName>;
+/** Defects that need a search-mode parameter, which only some dialects publish. */
+export declare const SEARCH_MODE_ONLY: ReadonlySet<DefectName>;
+/** Defects that need a nulls token in the sort grammar — only the dotted grammar writes one. */
+export declare const NULLS_TOKEN_ONLY: ReadonlySet<DefectName>;
+export declare const DIALECTS_WITH_POSTGREST_FILTER: ReadonlySet<string>;
+/** Defects that need a reported total to exist at all. */
+export declare const COUNT_ONLY: ReadonlySet<DefectName>;
+export declare const CURSOR_ONLY: ReadonlySet<DefectName>;
+/** Whether this runtime can host the SQLite backend (`node:sqlite` needs a flag on Node 22). */
+export declare function sqliteAvailable(): Promise<boolean>;
+/**
+ * Whether D1 credentials are present. Deliberately not a live probe: a network call on every
+ * `oat conformance` would tax the common path to answer a question about an opt-in backend.
+ */
+export declare function d1Available(): boolean;
+/** Whether a Postgres server is reachable. Requires a running server, not just the driver. */
+export declare function postgresAvailable(): Promise<boolean>;
+export declare const PRINCIPALS: PrincipalSpec[];
+export interface CaseResult {
+    label: string;
+    defect: DefectName | null;
+    expected: string | null;
+    detected: boolean;
+    /** Findings unrelated to the injected defect — false positives. */
+    spurious: Finding[];
+    findings: Finding[];
+    entitiesTested: string[];
+    /** Checks that actually executed. A clean run that ran nothing is not a pass. */
+    checksRun: string[];
+    /** Records created and not cleaned up. */
+    leaked?: number;
+    /** Checks that ran and could not reach a verdict, as `check@entity: reason`. */
+    inconclusive?: string[];
+    /** Checks this defect may legitimately trip, primary first. */
+    acceptable?: string[];
+    error?: string;
+}
+export declare function runSuite(filter?: string[], backend?: Backend, dialect?: string): Promise<CaseResult[]>;
+/** A leg's answer, from its results in order: the two baselines first, then its defects. */
+export declare function passAnswer(results: CaseResult[], backend: Backend, dialect: string): {
+    text: string;
+    failures: number;
+    proven: string[];
+    baselines: {
+        tagged: string[];
+        untagged: string[];
+    };
+    primaryOps: Record<string, string[]>;
+};
+/**
+ * A case's result as it can cross to another thread: findings keep everything the verdicts read,
+ * and drop the exchanges they cite, which hold live bodies.
+ */
+export declare function portableResult(result: CaseResult): CaseResult;
+/** The two clean baselines of a leg: tagged, then with every meta tag stripped. */
+export declare function runBaselines(backend?: Backend, dialect?: string): Promise<CaseResult[]>;
+/** Every defect this backend and dialect can exhibit, narrowed to `filter` when one is given. */
+export declare function defectsFor(backend: Backend, dialect: string, filter?: readonly string[]): DefectName[];
+/** One defect, injected alone: detected, and nothing reported that it does not explain. */
+export declare function judgeDefect(defect: DefectName, backend: Backend, dialect: string, shape?: string, label?: string): Promise<CaseResult>;
+export declare function renderSuite(results: CaseResult[], dialect?: string, backend?: Backend): {
+    text: string;
+    failures: number;
+    proven: Set<string>;
+};
+/** Registered checks no injected defect made fire anywhere in the run. Each one fails the suite. */
+export declare function renderUnproven(proven: ReadonlySet<string>): {
+    text: string;
+    failures: number;
+};
+//# sourceMappingURL=suite.d.ts.map

package/dist/conformance/suite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite.d.ts","sourceRoot":"","sources":["../../src/conformance/suite.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAKlE,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,KAAK,aAAa,EAAO,MAAM,mBAAmB,CAAA;AAQ3D,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,wBAAgB,cAAc,IAAI,YAAY,EAAE,CAgE/C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAkEnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,EAAE,CAyCvD;AAED;;;;;;;GAOG;AACH;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,CAAC,EAAE;IACnD,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsC1B;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CA6LnE;AA4LD,wBAAgB,sBAAsB,IAAI,YAAY,EAAE,CAUvD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAe7F;AAID;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAU7E;AA2BD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CA2Q1D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAAiD,CAAA;AAE9F,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,IAAI,CAAA;AAE7D;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,UAAU,CAQnD,CAAA;AAEF;;;GAGG;AACH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAA0B,CAAA;AAE/E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAgD,CAAA;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,MAAM,CAK9D,CAAA;AAiBF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMjD,CAAA;AAED,sEAAsE;AACtE,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,UAAU,CAelD,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,UAAU,CAapD,CAAA;AAEF,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,UAAU,CAAiD,CAAA;AAEtG,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,UAAU,CAAwD,CAAA;AAE7G,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAA+C,CAAA;AAE9G,0DAA0D;AAC1D,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,UAAU,CAAsE,CAAA;AAErH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,UAAU,CAAmE,CAAA;AAEnH,gGAAgG;AAChG,wBAAsB,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAUxD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAMrC;AAED,8FAA8F;AAC9F,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAa1D;AAUD,eAAO,MAAM,UAAU,EAAE,aAAa,EA0CrC,CAAA;AAED,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,QAAQ,EAAE,OAAO,CAAA;IACjB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,iFAAiF;IACjF,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAqDD,wBAAsB,QAAQ,CAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,OAAkB,EAC3B,OAAO,SAAc,GACnB,OAAO,CAAC,UAAU,EAAE,CAAC,CAMvB;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,CACzB,OAAO,EAAE,UAAU,EAAE,EACrB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,GACb;IACF,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IACnD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CACpC,CAcA;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAG7D;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CAAC,OAAO,GAAE,OAAkB,EAAE,OAAO,SAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAmE5G;AAqCD,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,EAAE,CA2BtG;AAED,2FAA2F;AAC3F,wBAAsB,WAAW,CAChC,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,EACd,KAAK,GAAE,MAAe,GACpB,OAAO,CAAC,UAAU,CAAC,CA8CrB;AAED,wBAAgB,WAAW,CAC1B,OAAO,EAAE,UAAU,EAAE,EACrB,OAAO,SAAc,EACrB,OAAO,GAAE,OAAkB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CAuGzD;AAED,oGAAoG;AACpG,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAa9F"}