@descryy/ir 0.1.0

package/dist/model-tables.js

@@ -0,0 +1,103 @@
+/**
+ * `DATABASE_TABLE`/`DATABASE_COLUMN` from a `MODEL`'s own mapped shape —
+ * DEC-240's Option 2.
+ *
+ * `adapter-sql` is the only producer of these two types until now, reading
+ * `*.sql` DDL. A Python (or, later, Java/C#) stack that maps its tables
+ * through an ORM and never checks in a migration file has no producer at
+ * all — 17 real tables on the stack this was measured against, zero
+ * `DATABASE_TABLE` nodes. DEC-240 ruled that the fix is not "teach
+ * `adapter-python`'s `orm.ts` to mint these too": a language adapter that did
+ * would also have to decide Django's/JPA's/EF Core's own implicit
+ * table-naming convention (app label + lowercased model name, a class name,
+ * a pluralisation rule) to cover the common case where no explicit table
+ * name is written — three adapters each independently inventing, or
+ * independently refusing, the same class of naming inference is three
+ * chances to disagree on the one byte that has to be identical for a join to
+ * happen at all. So the naming judgement — explicit name or refuse, never
+ * infer — lives here instead, once, and every adapter calls this function
+ * at its own emit time rather than re-deriving the rule.
+ *
+ * ## The part DEC-240's own ruling did not check, and the fix could not
+ * ship correctly without
+ *
+ * `nodeId` hashes `[scope, language, kind, qualifiedSymbolPath]` for every
+ * node type **except** the three in `FILELESS_NODE_TYPES` — and
+ * `DATABASE_TABLE`/`DATABASE_COLUMN` are not in that list. `adapter-sql`
+ * already hashes its own nodes with `language: "sql"`. A second producer
+ * hashing with its own language — `"python"`, later `"java"`, `"csharp"` —
+ * would mint a *different* id for the same real table than every other
+ * producer, and DEC-054's whole point (a Python `DATABASE_COLUMN` and a
+ * TypeScript `COMPONENT` meeting through one `API_ENDPOINT`) fails silently
+ * the identical way DEC-055 already found once: everything resolves,
+ * nothing errors, and the join returns nothing. So this function — and, to
+ * match it, `adapter-sql`'s own two call sites — hash with `language: null`
+ * unconditionally.
+ *
+ * **The emitted node's own `language` field is `null` too, not the real
+ * per-producer language.** The first cut of this function kept the real
+ * language there ("only the identity hash has to be language-blind, not the
+ * metadata") and that was wrong: the graph builder's collision detector
+ * (`identityFingerprint`, `packages/core/src/graph/merge.ts`) compares
+ * `[type, language]` for any two nodes that land on one id, precisely to
+ * catch two *different* things sharing an id by accident (DEC-024). A real
+ * per-producer language on this field means two genuine producers of the
+ * *same* table — a Python ORM and the `*.sql` DDL for it, this function's own
+ * motivating case — always disagree on `language` and always trip that
+ * detector, discarding one side's `DATABASE_COLUMN`s outright. `origin.language`
+ * is kept on {@link ModelTableOrigin} only as caller-supplied provenance for
+ * future use (e.g. `attrs`); it is not echoed onto the node. Per-producer
+ * provenance is still recoverable after a real merge through the node's
+ * `attrs.corroboratedBy`, the same mechanism every other cross-producer merge
+ * in this project already uses instead of a scalar field.
+ *
+ * `schema` defaults to `"public"` when a shape names none, matching
+ * `adapter-sql`'s own `DEFAULT_SCHEMA` — duplicated as a literal because
+ * `@descry/ir` cannot depend on an adapter package to import the constant.
+ * A model that maps to a non-default schema and never says so joins nothing
+ * either, the same silent-refusal shape `tableOf()` already accepts for an
+ * implicit table name.
+ */
+import { nodeId, tableQsp } from "./identity.js";
+/** Matches `adapter-sql`'s own `DEFAULT_SCHEMA` (`packages/adapter-sql` in `descry-adapters`). */
+export const DEFAULT_MODEL_SCHEMA = "public";
+/**
+ * `DATABASE_TABLE` plus one `DATABASE_COLUMN` per mapped field, or `[]` when
+ * `shape.table` is `null` — the disclosed refusal `tableOf()` already makes
+ * for an implicit table name, carried through rather than re-decided here.
+ */
+export function databaseTableNodesFromModel(scope, shape, origin) {
+    if (shape.table === null)
+        return [];
+    const schema = shape.schema ?? DEFAULT_MODEL_SCHEMA;
+    const nodes = [];
+    const tableId = nodeId(scope, "DATABASE_TABLE", tableQsp(schema, shape.table), null);
+    nodes.push({
+        id: tableId,
+        type: "DATABASE_TABLE",
+        name: shape.table,
+        file: origin.file,
+        range: { startLine: origin.line, endLine: origin.line },
+        language: null,
+        producedBy: origin.producedBy,
+        resolution: origin.resolution,
+        attrs: { name: shape.table, schema },
+    });
+    for (const field of shape.fields) {
+        const columnName = field.columnName ?? field.name;
+        const columnId = nodeId(scope, "DATABASE_COLUMN", tableQsp(schema, shape.table, columnName), null);
+        nodes.push({
+            id: columnId,
+            type: "DATABASE_COLUMN",
+            name: `${shape.table}.${columnName}`,
+            file: origin.file,
+            range: { startLine: origin.line, endLine: origin.line },
+            language: null,
+            producedBy: origin.producedBy,
+            resolution: origin.resolution,
+            attrs: { name: columnName, nullable: field.nullable },
+        });
+    }
+    return nodes;
+}
+//# sourceMappingURL=model-tables.js.map

package/dist/model-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-tables.js","sourceRoot":"","sources":["../src/model-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAsB,MAAM,eAAe,CAAC;AAGrE,kGAAkG;AAClG,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AA6C7C;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,KAAoB,EACpB,KAAsB,EACtB,MAAwB;IAExB,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,oBAAoB,CAAC;IAEpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IACrF,KAAK,CAAC,IAAI,CAAC;QACT,EAAE,EAAE,OAAO;QACX,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,KAAK,CAAC,KAAK;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE;QACvD,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE;KACrC,CAAC,CAAC;IAEH,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC;QAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC,CAAC;QACnG,KAAK,CAAC,IAAI,CAAC;YACT,EAAE,EAAE,QAAQ;YACZ,IAAI,EAAE,iBAAiB;YACvB,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,IAAI,UAAU,EAAE;YACpC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE;YACvD,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;SACtD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/normalise.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The Normaliser — the only door into the graph.
+ *
+ * Everything an adapter emits passes through here before anything is written.
+ * It exists because of one ordering rule in the build plan: **the Normaliser
+ * comes before the writer.** Build the writer first and "reject at the boundary"
+ * silently becomes "clean up in SQL", which is unrecoverable — once a bad edge
+ * is in the store, a dropped bad edge and a missing good one look identical, and
+ * §11B.6 recall has no denominator.
+ *
+ * Two rules govern the whole file:
+ *
+ *   1. **Drop and log, never repair.** A repair changes what an adapter claimed
+ *      without telling anyone. The one exception is confidence, which is clamped
+ *      *down* to a per-resolution ceiling and recorded — lowering a claim cannot
+ *      manufacture a fact, and every clamp appears in the result.
+ *   2. **Trust nothing.** Adapters live in a different repo, on a different
+ *      release cadence (DEC-001), and are third-party as far as this package is
+ *      concerned. TypeScript types do not survive that boundary at runtime, so
+ *      the input is `unknown` and every field is checked structurally.
+ *
+ * This package has zero dependencies, so it cannot see the store. The "edge
+ * references a node that does not exist" check therefore takes a `nodeExists`
+ * predicate: the caller supplies the store lookup, and the IR boundary stays
+ * dependency-free.
+ */
+import type { IRBatch, ResolutionLevel } from "./ir.ts";
+/**
+ * Every way a batch, node, edge or reference can be turned away.
+ *
+ * Typed rather than free-text because these are counted, not just printed:
+ * §20.2's "not analysable" category and §11B.6's recall denominator are both
+ * aggregates over this list. A rejection whose reason is a sentence cannot be
+ * aggregated.
+ */
+export declare const REJECTION_CODES: readonly ["BATCH_MALFORMED", "BATCH_FIELD_INVALID", "BATCH_SOURCE_FILES_EMPTY", "UNKNOWN_NODE_TYPE", "UNKNOWN_EDGE_TYPE", "MALFORMED_NODE_ID", "DUPLICATE_NODE_ID", "EMPTY_NAME", "MALFORMED_PRODUCED_BY", "PRODUCED_BY_MISMATCH", "RESOLUTION_OUT_OF_RANGE", "RESOLUTION_EXCEEDS_BATCH", "R4_WITHOUT_OBSERVED_RUN", "OBSERVED_RUN_WITHOUT_R4", "CONFIDENCE_INVALID", "ABSOLUTE_PATH", "NON_PORTABLE_PATH", "FILE_OUTSIDE_SOURCE_FILES", "MISSING_FILE", "FILE_ON_FILELESS_TYPE", "RANGE_WITHOUT_FILE", "INVALID_RANGE", "MALFORMED_SKIPPED_FILE", "FILE_IN_SOURCE_AND_SKIPPED", "LANGUAGE_ON_JOIN_NODE", "UNKNOWN_WORKSPACE", "MALFORMED_ATTRS", "MALFORMED_UNRESOLVED_REF", "DANGLING_EDGE_ENDPOINT", "EDGE_ENDPOINT_DROPPED"];
+export type RejectionCode = (typeof REJECTION_CODES)[number];
+export interface Rejection {
+    readonly code: RejectionCode;
+    readonly scope: "batch" | "node" | "edge" | "unresolved";
+    /** Node id, `from→to:TYPE` for an edge, or the repo for a batch. Enough to find it. */
+    readonly subject: string;
+    readonly detail: string;
+}
+/** A confidence value lowered to its resolution's ceiling. Never raised. */
+export interface Clamp {
+    readonly subject: string;
+    readonly resolution: ResolutionLevel;
+    readonly from: number;
+    readonly to: number;
+}
+export interface NormaliseResult {
+    /** `null` when the envelope itself was rejected — nothing in it can be trusted. */
+    readonly batch: IRBatch | null;
+    readonly rejections: readonly Rejection[];
+    readonly clamps: readonly Clamp[];
+}
+/**
+ * The maximum confidence an edge may claim at each resolution level.
+ *
+ * **The numbers for R0–R2 are provisional.** Architecture §32 item 13 lists
+ * `EdgeConfidence` per resolution level as open *tuning*, to be set "once two
+ * adapters exist and can be compared" — which is Step 14 of this build, not
+ * Step 5. Only two of the five values are actually pinned by the architecture:
+ * §12.4 states 1.0 for R3 and R4.
+ *
+ * What is NOT provisional is the shape, and that is what the tests assert:
+ * monotonically non-decreasing in resolution, never above 1.0, and 1.0 exactly
+ * at R3 and R4. Tuning the middle three later cannot violate any of those, so
+ * measuring them later does not invalidate anything built on this now.
+ *
+ * Override via `NormaliseOptions.confidenceCeilings` rather than editing here —
+ * the accuracy benchmark (§11B.6) will want to sweep them.
+ */
+export declare const DEFAULT_CONFIDENCE_CEILINGS: Readonly<Record<ResolutionLevel, number>>;
+export interface NormaliseOptions {
+    /**
+     * Does a node with this id already exist in the store? An edge may legally
+     * point at a node written by an earlier batch — a call from this file into one
+     * that did not change is the normal case, not an error.
+     *
+     * Omitted means "the batch is the whole world", which is what the fake
+     * adapters and the conformance harness want.
+     */
+    readonly nodeExists?: (id: string) => boolean;
+    readonly confidenceCeilings?: Readonly<Record<ResolutionLevel, number>>;
+    /**
+     * The workspace ids this run was configured to know about (DEC-054).
+     *
+     * A workspace id must be byte-identical in every repository that shares it, and
+     * the failure when it is not has no symptoms: `billing-platform` here and
+     * `billing_platform` there produces a graph that is structurally perfect,
+     * internally consistent, and joins nothing. Zero joins, zero errors, zero
+     * warnings.
+     *
+     * So an unrecognised workspace is treated as a typo rather than as a new
+     * workspace, and the batch is rejected whole — its workspace-scoped ids were
+     * computed under a scope no other repository will ever produce, which makes
+     * every one of them wrong rather than merely unmatched.
+     *
+     * Omitted means "accept any", which is what a single-repo run and the
+     * conformance harness want.
+     */
+    readonly knownWorkspaces?: readonly string[];
+}
+/**
+ * Validate and normalise one `IRBatch`.
+ *
+ * Never throws on bad input — a malformed batch is a result, not an exception,
+ * because a run over 40 adapters must report all of them rather than die on the
+ * first. It throws only on programmer error in the options.
+ */
+export declare function normaliseBatch(input: unknown, options?: NormaliseOptions): NormaliseResult;
+//# sourceMappingURL=normalise.d.ts.map

package/dist/normalise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalise.d.ts","sourceRoot":"","sources":["../src/normalise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EACV,OAAO,EAIP,eAAe,EAGhB,MAAM,SAAS,CAAC;AAQjB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,ksBAwClB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAC;IACzD,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,4EAA4E;AAC5E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;CACnC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAMjF,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAqED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAkO9F"}