@descryy/adapter-common 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Descry
+
+All rights reserved.
+
+This software is proprietary and confidential. No license, express or
+implied, to use, copy, modify, merge, publish, distribute, sublicense, or
+sell copies of this software is granted without prior written permission
+from the copyright holder.

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

@@ -1,58 +1,41 @@
 /**
- * File discovery.
- *
- * Hand-rolled rather than a glob dependency. The patterns a corpus manifest
- * uses are `src/**` + extension, which is three regex constructs, and an adapter
- * that ships one dependency ships that dependency's transitive tree into every
- * install of a locally-installed developer tool.
+ * File discovery. Hand-rolled rather than a glob dependency: corpus manifests
+ * only need `src/**` + extension (three regex constructs), and a dependency
+ * here ships its whole transitive tree into every install of this tool.
  */
 /**
- * Directory patterns a repository's own `.gitignore` files exclude.
- *
- * **Deliberately only directories, and deliberately only unambiguous ones.** A
- * full gitignore implementation has negation, nesting, anchoring and precedence,
- * and every one of those is a way to exclude a file that is real source. The
- * asymmetry decides the design: a build directory wrongly walked costs parse
- * time and some junk nodes, while a source directory wrongly skipped removes
- * real code from the graph and *cannot be seen* in any recall measurement,
- * because the files never entered the denominator.
+ * Directory patterns a repository's own `.gitignore` excludes.
  *
- * So this reads the forms that can only mean a directory — `dist/`, `/build`,
- * `coverage` on its own line — and ignores globs, negations and anything with a
- * path separator inside it. What it declines to interpret is simply walked, as
- * before.
+ * Deliberately only directories, and only unambiguous ones (`dist/`, `/build`,
+ * `coverage` alone on a line — no globs, negation, or path separators). A full
+ * gitignore implementation has negation, nesting, anchoring and precedence,
+ * and each is a way to wrongly exclude real source; a wrongly-walked build dir
+ * just costs parse time, but a wrongly-skipped source dir removes code from
+ * the graph invisibly — it never enters the recall denominator. What this
+ * declines to interpret is simply walked, as before.
  */
 export declare function ignoredDirectories(root: string): ReadonlySet<string>;
 /**
- * Translate a glob to an anchored regular expression.
- *
- * Supports `**` (any number of path segments, including none), `*` (any run of
- * characters within one segment) and `?`. That is the whole surface the corpus
- * manifests use; anything more would be inventing requirements.
+ * Glob to anchored regex. Supports `**` (any path depth, incl. zero), `*`
+ * (any run within one segment) and `?` — the whole surface corpus manifests
+ * use; more would be inventing requirements.
  */
 export declare function globToRegExp(glob: string): RegExp;
 export declare function matchesAny(path: string, globs: readonly string[]): boolean;
 /**
  * Every file under `root` matching any glob, repo-relative and sorted.
  *
- * Sorted because batch contents must not depend on directory-entry order: the
- * engine asserts that ingesting the same repository twice produces a
- * byte-identical database, and an unsorted walk breaks that on a different
- * filesystem rather than on this one.
+ * Sorted so batch contents don't depend on directory-entry order: the engine
+ * asserts that ingesting the same repo twice is byte-identical, and an
+ * unsorted walk breaks that on a different filesystem, not this one.
  */
 export interface DiscoverOptions {
-    /**
-     * Called once with every directory name `.gitignore` excluded, so the count
-     * reaches the report rather than vanishing into the walk.
-     */
+    /** Called once with every directory `.gitignore` excluded, so the count reaches the report. */
     readonly onIgnored?: (names: readonly string[]) => void;
     /**
-     * Called for each nested checkout skipped, repo-relative.
-     *
-     * Surfaced rather than logged: a repository that contains three worktrees of
-     * itself is a fact the report has to be able to state, because the difference
-     * between "we analysed 1,087 files" and "we analysed 1,087 of 4,300" is the
-     * difference between a result and a misleading one.
+     * Called for each nested checkout skipped, repo-relative. Surfaced rather
+     * than logged — "analysed 1,087 files" and "analysed 1,087 of 4,300" are
+     * different claims, and the report must be able to state which one is true.
      */
     readonly onNestedCheckout?: (repoRelativeDir: string) => void;
 }

package/dist/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAqBpE;AAMD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBjD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE1E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IACxD;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D;AAiBD,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,eAAoB,GAC5B,MAAM,EAAE,CA+BV;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrE"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAqBpE;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBjD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE1E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D;AAcD,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,eAAoB,GAC5B,MAAM,EAAE,CA+BV;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrE"}

package/dist/discover.js

@@ -1,39 +1,28 @@
 /**
- * File discovery.
- *
- * Hand-rolled rather than a glob dependency. The patterns a corpus manifest
- * uses are `src/**` + extension, which is three regex constructs, and an adapter
- * that ships one dependency ships that dependency's transitive tree into every
- * install of a locally-installed developer tool.
+ * File discovery. Hand-rolled rather than a glob dependency: corpus manifests
+ * only need `src/**` + extension (three regex constructs), and a dependency
+ * here ships its whole transitive tree into every install of this tool.
  */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, sep } from "node:path";
 /**
- * Directories never worth walking. Skipped before `readdir`, not filtered after.
+ * Directories never worth walking, skipped before `readdir`.
  *
- * This list is a **floor, not the policy.** It is a guess about where build
- * output lives, and a guess is exactly what `.gitignore` exists to replace: the
- * repository has already declared which of its files are not source, and the
- * standing rule is that where the project will tell you, you never infer. So the
- * list stays for repositories with no `.gitignore` and for `.git` itself, and
- * `ignoredDirectories` reads the declaration on top of it.
+ * A **floor, not the policy**: a guess about build output, kept only for repos
+ * with no `.gitignore` (and for `.git` itself). Where the project declares its
+ * own exclusions, `ignoredDirectories` reads that instead of guessing.
  */
 const SKIP = new Set(["node_modules", ".git", "dist", "build", "out", "coverage", ".next"]);
 /**
- * Directory patterns a repository's own `.gitignore` files exclude.
- *
- * **Deliberately only directories, and deliberately only unambiguous ones.** A
- * full gitignore implementation has negation, nesting, anchoring and precedence,
- * and every one of those is a way to exclude a file that is real source. The
- * asymmetry decides the design: a build directory wrongly walked costs parse
- * time and some junk nodes, while a source directory wrongly skipped removes
- * real code from the graph and *cannot be seen* in any recall measurement,
- * because the files never entered the denominator.
+ * Directory patterns a repository's own `.gitignore` excludes.
  *
- * So this reads the forms that can only mean a directory — `dist/`, `/build`,
- * `coverage` on its own line — and ignores globs, negations and anything with a
- * path separator inside it. What it declines to interpret is simply walked, as
- * before.
+ * Deliberately only directories, and only unambiguous ones (`dist/`, `/build`,
+ * `coverage` alone on a line — no globs, negation, or path separators). A full
+ * gitignore implementation has negation, nesting, anchoring and precedence,
+ * and each is a way to wrongly exclude real source; a wrongly-walked build dir
+ * just costs parse time, but a wrongly-skipped source dir removes code from
+ * the graph invisibly — it never enters the recall denominator. What this
+ * declines to interpret is simply walked, as before.
  */
 export function ignoredDirectories(root) {
     const names = new Set();
@@ -65,11 +54,9 @@ function escape(literal) {
     return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /**
- * Translate a glob to an anchored regular expression.
- *
- * Supports `**` (any number of path segments, including none), `*` (any run of
- * characters within one segment) and `?`. That is the whole surface the corpus
- * manifests use; anything more would be inventing requirements.
+ * Glob to anchored regex. Supports `**` (any path depth, incl. zero), `*`
+ * (any run within one segment) and `?` — the whole surface corpus manifests
+ * use; more would be inventing requirements.
  */
 export function globToRegExp(glob) {
     let out = "";
@@ -77,8 +64,7 @@ export function globToRegExp(glob) {
         const char = glob[i];
         if (char === "*") {
             if (glob[i + 1] === "*") {
-                // `**/` collapses to "any depth, including zero segments" so that
-                // `src/**/*.ts` matches `src/money.ts` as well as `src/ui/Page.ts`.
+                // `**/` = any depth incl. zero, so `src/**/*.ts` matches `src/money.ts` too.
                 const slash = glob[i + 2] === "/";
                 out += slash ? "(?:[^/]+/)*" : ".*";
                 i += slash ? 2 : 1;
@@ -95,15 +81,12 @@ export function matchesAny(path, globs) {
     return globs.some((glob) => globToRegExp(glob).test(path));
 }
 /**
- * A directory holding its own `.git` is a different repository — a submodule, a
- * vendored checkout, or a `git worktree`. It is skipped for the same reason
- * `node_modules` is, plus a sharper one: node identity is
- * `hash(repo, kind, path)` (DEC-011), so analysing a nested checkout as part of
- * its parent stamps the parent's repo id onto another repository's symbols.
- *
- * Found on real code. One repository contained three worktrees of itself, each
- * with the same `package.json` name — 6,309 of 8,902 emitted nodes were exact
- * identity collisions with their own copies.
+ * A directory holding its own `.git` is a different repo (submodule, vendored
+ * checkout, worktree) and is skipped: node identity is `hash(repo, kind,
+ * path)` (DEC-011), so analysing it as part of the parent stamps the parent's
+ * repo id onto another repo's symbols. Measured on real code — one repo with
+ * three worktrees of itself produced 6,309 of 8,902 emitted nodes as exact
+ * identity collisions.
  */
 function isNestedCheckout(dir) {
     return existsSync(join(dir, ".git"));

package/dist/discover.js.map

@@ -1 +1 @@
-{"version":3,"file":"discover.js","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"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"}

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

@@ -1,25 +1,16 @@
 /**
- * Per-file isolation for the work that happens *after* a file parses.
+ * Per-file isolation for the work *after* a file parses. Read/parse errors are
+ * already isolated (`unreadable`, `too-large`, `parseText`'s caught failure);
+ * the unguarded step is walking a parsed tree into an adapter's per-file unit,
+ * which indexes children and assumes shapes a grammar can decline to produce —
+ * a throw there takes the whole pass down, not just one file (real failure
+ * mode: `Cannot read properties of undefined (reading 'length')`, worst when
+ * a developer is analysing the file they just half-finished writing).
  *
- * Reading and parsing are already isolated everywhere: a read error becomes an
- * `unreadable` skip, an oversized file a `too-large` one, and `parseText` catches
- * the grammar and hands back a failure rather than throwing. The step nothing
- * guards is the one in between — walking a parsed tree into an adapter's own
- * per-file unit. That code indexes children, reads `.length`, and assumes shapes
- * a real grammar can decline to produce, and a throw there does not degrade one
- * file: it takes the whole pass down, along with every file that had already
- * succeeded.
- *
- * That failure mode is not hypothetical. `Cannot read properties of undefined
- * (reading 'length')` is exactly its shape, and it fires hardest at the worst
- * moment — a developer analysing code they just wrote is analysing the file most
- * likely to be half-finished.
- *
- * The vocabulary does not grow to accommodate this. A step that throws is a file
- * we could not finish reading, disclosed through `skippedFiles` with reason
- * `other` and the real error message as its detail — the same route
- * `adapter-go` already uses for a file it can see but cannot place in a module.
- * `SkipReason` stays at four values.
+ * The vocabulary doesn't grow for this: a throw becomes a `skippedFiles` entry
+ * with reason `other` and the real error as detail — same route `adapter-go`
+ * uses for a file it can see but can't place in a module. `SkipReason` stays
+ * at four values.
  */
 /** A file the adapter parsed but could not finish, and why. */
 export interface IsolatedFailure {
@@ -37,14 +28,13 @@ export type Isolated<T> = {
 /**
  * Run one file's step, converting a throw into a disclosed skip for that file.
  *
- * Deliberately synchronous. Every adapter's per-file walk is synchronous over an
- * already-parsed tree, and an async signature here would invite a caller to move
- * I/O inside the boundary, where a partially-written unit is much harder to
- * reason about than a partially-read directory.
+ * Deliberately synchronous — every adapter's per-file walk is synchronous over
+ * an already-parsed tree, and async here would invite I/O inside the boundary,
+ * where a partially-written unit is harder to reason about than a
+ * partially-read directory.
  *
- * **An abort is re-thrown.** A cancelled run is not a corpus of broken files, and
- * recording it as one would turn a single deliberate stop into a per-file
- * disclosure about the repository for every file that had not been reached yet.
+ * An abort is re-thrown: a cancelled run isn't a corpus of broken files, and
+ * recording it as one would misreport every file not yet reached as broken.
  */
 export declare function isolateFile<T>(file: string, step: () => T): Isolated<T>;
 //# sourceMappingURL=isolate.d.ts.map

package/dist/isolate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isolate.d.ts","sourceRoot":"","sources":["../src/isolate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,IAClB;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAUvE"}
+{"version":3,"file":"isolate.d.ts","sourceRoot":"","sources":["../src/isolate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,IAClB;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAUvE"}

package/dist/isolate.js

@@ -1,37 +1,27 @@
 /**
- * Per-file isolation for the work that happens *after* a file parses.
+ * Per-file isolation for the work *after* a file parses. Read/parse errors are
+ * already isolated (`unreadable`, `too-large`, `parseText`'s caught failure);
+ * the unguarded step is walking a parsed tree into an adapter's per-file unit,
+ * which indexes children and assumes shapes a grammar can decline to produce —
+ * a throw there takes the whole pass down, not just one file (real failure
+ * mode: `Cannot read properties of undefined (reading 'length')`, worst when
+ * a developer is analysing the file they just half-finished writing).
  *
- * Reading and parsing are already isolated everywhere: a read error becomes an
- * `unreadable` skip, an oversized file a `too-large` one, and `parseText` catches
- * the grammar and hands back a failure rather than throwing. The step nothing
- * guards is the one in between — walking a parsed tree into an adapter's own
- * per-file unit. That code indexes children, reads `.length`, and assumes shapes
- * a real grammar can decline to produce, and a throw there does not degrade one
- * file: it takes the whole pass down, along with every file that had already
- * succeeded.
- *
- * That failure mode is not hypothetical. `Cannot read properties of undefined
- * (reading 'length')` is exactly its shape, and it fires hardest at the worst
- * moment — a developer analysing code they just wrote is analysing the file most
- * likely to be half-finished.
- *
- * The vocabulary does not grow to accommodate this. A step that throws is a file
- * we could not finish reading, disclosed through `skippedFiles` with reason
- * `other` and the real error message as its detail — the same route
- * `adapter-go` already uses for a file it can see but cannot place in a module.
- * `SkipReason` stays at four values.
+ * The vocabulary doesn't grow for this: a throw becomes a `skippedFiles` entry
+ * with reason `other` and the real error as detail — same route `adapter-go`
+ * uses for a file it can see but can't place in a module. `SkipReason` stays
+ * at four values.
  */
 /**
  * Run one file's step, converting a throw into a disclosed skip for that file.
  *
- * Deliberately synchronous. Every adapter's per-file walk is synchronous over an
- * already-parsed tree, and an async signature here would invite a caller to move
- * I/O inside the boundary, where a partially-written unit is much harder to
- * reason about than a partially-read directory.
+ * Deliberately synchronous — every adapter's per-file walk is synchronous over
+ * an already-parsed tree, and async here would invite I/O inside the boundary,
+ * where a partially-written unit is harder to reason about than a
+ * partially-read directory.
  *
- * **An abort is re-thrown.** A cancelled run is not a corpus of broken files, and
- * recording it as one would turn a single deliberate stop into a per-file
- * disclosure about the repository for every file that had not been reached yet.
+ * An abort is re-thrown: a cancelled run isn't a corpus of broken files, and
+ * recording it as one would misreport every file not yet reached as broken.
  */
 export function isolateFile(file, step) {
     try {

package/dist/isolate.js.map

@@ -1 +1 @@
-{"version":3,"file":"isolate.js","sourceRoot":"","sources":["../src/isolate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAaH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAI,IAAY,EAAE,IAAa;IACxD,IAAI,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY;YAAE,MAAM,KAAK,CAAC;QACvE,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;SAClF,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"isolate.js","sourceRoot":"","sources":["../src/isolate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAI,IAAY,EAAE,IAAa;IACxD,IAAI,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY;YAAE,MAAM,KAAK,CAAC;QACvE,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;SAClF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@descryy/adapter-common",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Shared adapter infrastructure: file discovery, glob matching, path normalisation. No language knowledge.",
   "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/descryhq-wq/descry-adapters.git",
+    "directory": "packages/adapter-common"
+  },
+  "bugs": {
+    "url": "https://github.com/descryhq-wq/descry-adapters/issues"
+  },
+  "homepage": "https://github.com/descryhq-wq/descry-adapters#readme",
   "engines": {
     "node": ">=22.5"
   },