@descryy/ir 0.1.0

package/dist/vocabulary.js

@@ -0,0 +1,150 @@
+/**
+ * The canonical graph vocabulary: 15 node types, 15 edge types.
+ *
+ * FROZEN. See DEC-003. Adding a type multiplies traversal, ranking, storage and
+ * governance work — new capabilities are new *queries* over these edges, not new
+ * types. Extending either list requires a decision entry in DECISIONS.md, and the
+ * arity tests in test/vocabulary.test.ts will fail until the counts there are
+ * deliberately updated, which makes the change visible in review.
+ *
+ * Declared as `as const` arrays with derived unions rather than TS enums:
+ * enums are not erasable syntax and Node's type stripping cannot run them
+ * (tsconfig `erasableSyntaxOnly` enforces this).
+ */
+export const NODE_TYPES = [
+    "FILE",
+    "FUNCTION",
+    "CLASS",
+    "MODULE",
+    "API_ENDPOINT",
+    "API_ROUTE",
+    "DATABASE_TABLE",
+    "DATABASE_COLUMN",
+    "MODEL",
+    "DTO",
+    "COMPONENT",
+    "PAGE",
+    "TEST_CASE",
+    "INCIDENT",
+    "FIX_PATTERN",
+];
+export const EDGE_TYPES = [
+    "CALLS",
+    "IMPORTS",
+    "READS",
+    "WRITES",
+    "RETURNS",
+    "IMPLEMENTS",
+    "INHERITS",
+    "USES_API",
+    "SERVES_API",
+    /**
+     * A structural dependency on a type declaration — DEC-061.
+     *
+     * `A --USES_TYPE--> B` means A's *shape or signature* names B, so a change to
+     * B's shape may break A. It covers:
+     *
+     *     interface -> interface        a field's declared type
+     *     interface -> type alias       likewise
+     *     class     -> interface        a member's declared type
+     *     function  -> type             a parameter's type
+     *     function  -> type             a return type
+     *     any       -> type             a generic argument or constraint
+     *
+     * Spelled out because an edge whose meaning each adapter guesses at is worse
+     * than no edge: two adapters disagreeing here makes every threshold above them
+     * language-dependent.
+     *
+     * **It is not `READS`**, which is runtime consumption of a member — a type can
+     * be named in a signature without a single value ever being read. **It is not
+     * `PROPAGATES_TO`**, which is data lineage. **It is not `INHERITS`/
+     * `IMPLEMENTS`**, which are subtyping: a field of type `X` is not a subtype
+     * of `X`.
+     *
+     * It exists because none of the other 14 can express it at *symbol*
+     * granularity. `IMPORTS` is module-to-module and knows only that one file
+     * depends on another, which is file-level blast radius — the thing
+     * symbol-level analysis is supposed to beat.
+     */
+    "USES_TYPE",
+    "PROPAGATES_TO",
+    "TESTS",
+    "FIXED_BY",
+    "CHANGES_WITH",
+    "INCIDENT_CORRELATED",
+];
+const NODE_TYPE_SET = new Set(NODE_TYPES);
+const EDGE_TYPE_SET = new Set(EDGE_TYPES);
+export function isNodeType(value) {
+    return NODE_TYPE_SET.has(value);
+}
+export function isEdgeType(value) {
+    return EDGE_TYPE_SET.has(value);
+}
+/**
+ * Node types that have no source file and no line range.
+ *
+ * `API_ENDPOINT` is the cross-language join node — it is written by two adapters
+ * that never share a line of code, so it belongs to neither file. `INCIDENT` and
+ * `FIX_PATTERN` come from git history rather than from source.
+ *
+ * See DEC-014: architecture §11A.4 typed `file` and `range` as required, which
+ * made the join node unrepresentable.
+ */
+export const FILELESS_NODE_TYPES = [
+    "API_ENDPOINT",
+    "INCIDENT",
+    "FIX_PATTERN",
+];
+const FILELESS_SET = new Set(FILELESS_NODE_TYPES);
+export function isFilelessNodeType(type) {
+    return FILELESS_SET.has(type);
+}
+/**
+ * Node types that are a **declared type** — something a reference can name and a
+ * value can be an instance of.
+ *
+ * `MODEL` and `DTO` are not alternatives to `CLASS`; they are a `CLASS` that a
+ * framework extractor found extra evidence about. An ORM model is still a type:
+ * it is still imported, still named in annotations, still inherited from, still
+ * returned. The extra evidence is a persistence mapping or a transport boundary,
+ * and it changes what the node *means*, not what it *is*.
+ *
+ * This predicate exists because every adapter writes `type === "CLASS"` to ask
+ * "is this a type?", and there were twenty-one such sites across two adapters
+ * before the first framework extractor landed. Promoting one class to `MODEL`
+ * silently withdrew its `USES_TYPE`, `INHERITS` and `RETURNS` edges at every one
+ * of them — a recall collapse with no error, no rejection and no ledger row,
+ * which is the failure mode rule 7 exists to forbid.
+ *
+ * It is a query over the frozen vocabulary, not an extension of it. See DEC-093.
+ */
+export const TYPE_LIKE_NODE_TYPES = ["CLASS", "MODEL", "DTO"];
+const TYPE_LIKE_SET = new Set(TYPE_LIKE_NODE_TYPES);
+export function isTypeLikeNodeType(type) {
+    return TYPE_LIKE_SET.has(type);
+}
+/**
+ * Node types that are a **callable declaration** — something a call site can
+ * reach and a call graph can traverse.
+ *
+ * The same relationship `TYPE_LIKE_NODE_TYPES` describes, one row down. A React
+ * component is a function that a framework calls; `<OrderPage />` is a call in
+ * every sense a call graph cares about, which is the argument this codebase
+ * already made when it decided `post = (…) => …` is a method. `PAGE` is a
+ * component with a route attached and is callable for the same reason.
+ *
+ * `TEST_CASE` is deliberately absent. It is callable, but every site that
+ * distinguishes it does so because a call *inside* a test is coverage rather
+ * than a call-graph edge — folding it in here would erase that distinction at
+ * exactly the sites that exist to make it.
+ *
+ * See DEC-093, and the note there about what promotion costs when a kind check
+ * is written as an equality.
+ */
+export const CALLABLE_NODE_TYPES = ["FUNCTION", "COMPONENT", "PAGE"];
+const CALLABLE_SET = new Set(CALLABLE_NODE_TYPES);
+export function isCallableNodeType(type) {
+    return CALLABLE_SET.has(type);
+}
+//# sourceMappingURL=vocabulary.js.map

package/dist/vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../src/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM;IACN,UAAU;IACV,OAAO;IACP,QAAQ;IACR,cAAc;IACd,WAAW;IACX,gBAAgB;IAChB,iBAAiB;IACjB,OAAO;IACP,KAAK;IACL,WAAW;IACX,MAAM;IACN,WAAW;IACX,UAAU;IACV,aAAa;CACL,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO;IACP,SAAS;IACT,OAAO;IACP,QAAQ;IACR,SAAS;IACT,YAAY;IACZ,UAAU;IACV,UAAU;IACV,YAAY;IACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,WAAW;IACX,eAAe;IACf,OAAO;IACP,UAAU;IACV,cAAc;IACd,qBAAqB;CACb,CAAC;AAKX,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;AAC/D,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;AAE/D,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,cAAc;IACd,UAAU;IACV,aAAa;CACyB,CAAC;AAEzC,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAEvE,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAwC,CAAC;AAErG,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAEzE,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAwC,CAAC;AAE5G,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAEvE,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@descryy/ir",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Canonical IR, graph vocabulary, node identity, Normaliser, adapter contracts, conformance harness. Zero runtime dependencies by design.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {}
+}