@descryy/adapter-common 0.2.0 → 0.3.0

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/index.d.ts

@@ -10,4 +10,5 @@ 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";
 //# 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"}

package/dist/index.js

@@ -8,4 +8,5 @@
  */
 export { discover, globToRegExp, ignoredDirectories, matchesAny, toRepoRelative } from "./discover.js";
 export { isolateFile } from "./isolate.js";
+export { extractOrDegrade, describeThrown } from "./degrade.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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descryy/adapter-common",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Shared adapter infrastructure: file discovery, glob matching, path normalisation. No language knowledge.",
   "license": "UNLICENSED",