@descryy/adapter-common 0.2.0 → 0.3.1

package/dist/degrade.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The guard between "extraction gave up" and "this adapter is broken".
+ *
+ * Several adapters already refuse to return an empty graph over a non-empty
+ * repository: they build a filesystem-level graph — one node per file, nothing
+ * claimed about contents — plus one loud row saying the analysis failed rather
+ * than the repository being empty. That rule was earned, not designed: two real
+ * repositories came back with 0 nodes over ~18,000 files and a successful R0
+ * status, because a transport failure and an empty repository were
+ * indistinguishable downstream.
+ *
+ * Every one of those guards covered extraction **returning** nothing, and none
+ * covered it **throwing**. The two outcomes differ only in how the extractor
+ * gave up, and the thrown one is strictly worse for the reader: an exception
+ * out of `emit()` cannot be told apart from the adapter being broken for every
+ * repository, so the caller reports the whole language as not analysable. It
+ * fires exactly when someone is analysing code they just wrote — the worst
+ * possible moment for a tool trying to earn trust.
+ *
+ * ## Degrading is not swallowing
+ *
+ * The `degrade` callback an adapter supplies still says loudly that no graph was
+ * produced and that findings over the repository are unsupported. The only thing
+ * that changes is that the caller receives that sentence instead of a stack
+ * trace it has to interpret. A silent `catch` returning an empty extraction
+ * would be the exact failure these guards exist to prevent, arriving by a
+ * shorter route — so this helper cannot express that: it has no empty-result
+ * path, and an adapter with no degraded graph to fall back to must not call it.
+ *
+ * ## Language-blind, and it has to be
+ *
+ * Nothing here knows what a node is. `T` is the adapter's own extraction shape,
+ * and the disclosure text lives in the adapter's `degrade` callback, where the
+ * vocabulary for "module" or "compilation unit" belongs. This file only decides
+ * that a throw becomes a disclosure, and formats the cause.
+ */
+/**
+ * Run `extract`; on a throw, return `degrade(cause)` instead of propagating.
+ *
+ * `cause` names the thrown value's own type and message, because they are the
+ * cheapest real diagnosis available and the reader's alternative is reading the
+ * adapter's source. A non-`Error` throw is stringified rather than having
+ * `.message` read off it — doing that yields the literal text "undefined",
+ * which is a disclosure that names nothing.
+ */
+export declare function extractOrDegrade<T>(extract: () => T, degrade: (cause: string) => T): T;
+/** `Name: message` for an `Error`; an explicitly-labelled stringification otherwise. */
+export declare function describeThrown(error: unknown): string;
+//# sourceMappingURL=degrade.d.ts.map

package/dist/degrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degrade.d.ts","sourceRoot":"","sources":["../src/degrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,CAMtF;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD"}

package/dist/degrade.js

@@ -0,0 +1,60 @@
+/**
+ * The guard between "extraction gave up" and "this adapter is broken".
+ *
+ * Several adapters already refuse to return an empty graph over a non-empty
+ * repository: they build a filesystem-level graph — one node per file, nothing
+ * claimed about contents — plus one loud row saying the analysis failed rather
+ * than the repository being empty. That rule was earned, not designed: two real
+ * repositories came back with 0 nodes over ~18,000 files and a successful R0
+ * status, because a transport failure and an empty repository were
+ * indistinguishable downstream.
+ *
+ * Every one of those guards covered extraction **returning** nothing, and none
+ * covered it **throwing**. The two outcomes differ only in how the extractor
+ * gave up, and the thrown one is strictly worse for the reader: an exception
+ * out of `emit()` cannot be told apart from the adapter being broken for every
+ * repository, so the caller reports the whole language as not analysable. It
+ * fires exactly when someone is analysing code they just wrote — the worst
+ * possible moment for a tool trying to earn trust.
+ *
+ * ## Degrading is not swallowing
+ *
+ * The `degrade` callback an adapter supplies still says loudly that no graph was
+ * produced and that findings over the repository are unsupported. The only thing
+ * that changes is that the caller receives that sentence instead of a stack
+ * trace it has to interpret. A silent `catch` returning an empty extraction
+ * would be the exact failure these guards exist to prevent, arriving by a
+ * shorter route — so this helper cannot express that: it has no empty-result
+ * path, and an adapter with no degraded graph to fall back to must not call it.
+ *
+ * ## Language-blind, and it has to be
+ *
+ * Nothing here knows what a node is. `T` is the adapter's own extraction shape,
+ * and the disclosure text lives in the adapter's `degrade` callback, where the
+ * vocabulary for "module" or "compilation unit" belongs. This file only decides
+ * that a throw becomes a disclosure, and formats the cause.
+ */
+/**
+ * Run `extract`; on a throw, return `degrade(cause)` instead of propagating.
+ *
+ * `cause` names the thrown value's own type and message, because they are the
+ * cheapest real diagnosis available and the reader's alternative is reading the
+ * adapter's source. A non-`Error` throw is stringified rather than having
+ * `.message` read off it — doing that yields the literal text "undefined",
+ * which is a disclosure that names nothing.
+ */
+export function extractOrDegrade(extract, degrade) {
+    try {
+        return extract();
+    }
+    catch (error) {
+        return degrade(`extraction failed (${describeThrown(error)})`);
+    }
+}
+/** `Name: message` for an `Error`; an explicitly-labelled stringification otherwise. */
+export function describeThrown(error) {
+    if (error instanceof Error)
+        return `${error.name}: ${error.message}`;
+    return `a non-Error value was thrown: ${String(error)}`;
+}
+//# sourceMappingURL=degrade.js.map

package/dist/degrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degrade.js","sourceRoot":"","sources":["../src/degrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAI,OAAgB,EAAE,OAA6B;IACjF,IAAI,CAAC;QACH,OAAO,OAAO,EAAE,CAAC;IACnB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,sBAAsB,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACrE,OAAO,iCAAiC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC1D,CAAC"}

package/dist/file-node.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The shared, language-blind `FILE`-node minter.
+ *
+ * `FILE` is one of the fifteen canonical node types and was already real and
+ * populated before this file existed — `packages/core/src/sources/git/
+ * source.ts` in `descry-core` mints one per touched file, for `CHANGES_WITH`
+ * blast-radius edges, via `nodeId(scope, "FILE", fileQsp(path), null)`. No
+ * *adapter* had ever minted one; every adapter's own filesystem-level
+ * fallback used `MODULE` instead (see `adapter-python`'s `degradedGraph`).
+ *
+ * This helper exists so an adapter's degraded-extraction path can assert the
+ * one fact that survives a parse failure — the file exists — using the exact
+ * id computation the git-history producer already uses. Two `FILE` nodes for
+ * the same repo-relative path, one minted here and one minted by git
+ * history, hash to the same id and merge into one node rather than
+ * duplicate. `producedBy` is deliberately excluded from identity (it is not
+ * part of `nodeId`'s hash inputs) for the same reason: two adapters
+ * degrading on the same file must also merge, not fork.
+ *
+ * Filesystem-level only, per the product owner's ruling on
+ * `DEC-NEXT-degraded-graph-shape-for-adapters-without-one` (2026-09-15): a
+ * fallback "may assert filesystem-level facts... and nothing more." No
+ * language is guessed from the extension (DEC-026's reasoning, restated here
+ * for `FILE` the way `source.ts` already states it for its own).
+ */
+import { type IdentityScope, type IRNode } from "@descryy/ir";
+/**
+ * Mint a `FILE` node for one repo-relative path.
+ *
+ * `producedBy` names the caller for provenance only — it plays no part in
+ * the node's identity, so callers must not rely on it to keep two callers'
+ * nodes apart.
+ */
+export declare function fileNode(scope: IdentityScope, repoRelativePath: string, producedBy: string): IRNode;
+//# sourceMappingURL=file-node.d.ts.map

package/dist/file-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-node.d.ts","sourceRoot":"","sources":["../src/file-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAmB,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAenG"}

package/dist/file-node.js

@@ -0,0 +1,50 @@
+/**
+ * The shared, language-blind `FILE`-node minter.
+ *
+ * `FILE` is one of the fifteen canonical node types and was already real and
+ * populated before this file existed — `packages/core/src/sources/git/
+ * source.ts` in `descry-core` mints one per touched file, for `CHANGES_WITH`
+ * blast-radius edges, via `nodeId(scope, "FILE", fileQsp(path), null)`. No
+ * *adapter* had ever minted one; every adapter's own filesystem-level
+ * fallback used `MODULE` instead (see `adapter-python`'s `degradedGraph`).
+ *
+ * This helper exists so an adapter's degraded-extraction path can assert the
+ * one fact that survives a parse failure — the file exists — using the exact
+ * id computation the git-history producer already uses. Two `FILE` nodes for
+ * the same repo-relative path, one minted here and one minted by git
+ * history, hash to the same id and merge into one node rather than
+ * duplicate. `producedBy` is deliberately excluded from identity (it is not
+ * part of `nodeId`'s hash inputs) for the same reason: two adapters
+ * degrading on the same file must also merge, not fork.
+ *
+ * Filesystem-level only, per the product owner's ruling on
+ * `DEC-NEXT-degraded-graph-shape-for-adapters-without-one` (2026-09-15): a
+ * fallback "may assert filesystem-level facts... and nothing more." No
+ * language is guessed from the extension (DEC-026's reasoning, restated here
+ * for `FILE` the way `source.ts` already states it for its own).
+ */
+import { fileQsp, nodeId } from "@descryy/ir";
+/**
+ * Mint a `FILE` node for one repo-relative path.
+ *
+ * `producedBy` names the caller for provenance only — it plays no part in
+ * the node's identity, so callers must not rely on it to keep two callers'
+ * nodes apart.
+ */
+export function fileNode(scope, repoRelativePath, producedBy) {
+    return {
+        id: nodeId(scope, "FILE", fileQsp(repoRelativePath), null),
+        type: "FILE",
+        name: repoRelativePath.split("/").pop() ?? repoRelativePath,
+        file: repoRelativePath,
+        range: null,
+        // Guessing language from the extension would be a language decision made
+        // by a helper with no business making one — the same reasoning
+        // `source.ts` states for its own FILE nodes.
+        language: null,
+        producedBy,
+        resolution: 0,
+        attrs: { parsed: false },
+    };
+}
+//# sourceMappingURL=file-node.js.map

package/dist/file-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-node.js","sourceRoot":"","sources":["../src/file-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAmC,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAoB,EAAE,gBAAwB,EAAE,UAAkB;IACzF,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;QAC1D,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,gBAAgB;QAC3D,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,IAAI;QACX,yEAAyE;QACzE,+DAA+D;QAC/D,6CAA6C;QAC7C,QAAQ,EAAE,IAAI;QACd,UAAU;QACV,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;KACzB,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -10,4 +10,6 @@ export { discover, globToRegExp, ignoredDirectories, matchesAny, toRepoRelative
 export type { DiscoverOptions } from "./discover.ts";
 export { isolateFile } from "./isolate.ts";
 export type { Isolated, IsolatedFailure } from "./isolate.ts";
+export { extractOrDegrade, describeThrown } from "./degrade.ts";
+export { fileNode } from "./file-node.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvG,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvG,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -8,4 +8,6 @@
  */
 export { discover, globToRegExp, ignoredDirectories, matchesAny, toRepoRelative } from "./discover.js";
 export { isolateFile } from "./isolate.js";
+export { extractOrDegrade, describeThrown } from "./degrade.js";
+export { fileNode } from "./file-node.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEvG,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEvG,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descryy/adapter-common",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Shared adapter infrastructure: file discovery, glob matching, path normalisation. No language knowledge.",
   "license": "UNLICENSED",
@@ -32,5 +32,7 @@
   "scripts": {
     "build": "tsc -b"
   },
-  "dependencies": {}
+  "dependencies": {
+    "@descryy/ir": "0.10.0"
+  }
 }