@descryy/adapter-common 0.1.0

package/dist/discover.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ *
+ * 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.
+ */
+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.
+ */
+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.
+ */
+export interface DiscoverOptions {
+    /**
+     * Called once with every directory name `.gitignore` excluded, so the count
+     * reaches the report rather than vanishing into the walk.
+     */
+    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.
+     */
+    readonly onNestedCheckout?: (repoRelativeDir: string) => void;
+}
+export declare function discover(root: string, globs: readonly string[], options?: DiscoverOptions): string[];
+/** Repo-relative, forward-slashed. Absolute paths are rejected by the Normaliser. */
+export declare function toRepoRelative(root: string, absolute: string): string;
+//# sourceMappingURL=discover.d.ts.map

package/dist/discover.d.ts.map

@@ -0,0 +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"}

package/dist/discover.js

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, sep } from "node:path";
+/**
+ * Directories never worth walking. Skipped before `readdir`, not filtered after.
+ *
+ * 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.
+ */
+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.
+ *
+ * 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.
+ */
+export function ignoredDirectories(root) {
+    const names = new Set();
+    const file = join(root, ".gitignore");
+    if (!existsSync(file))
+        return names;
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return names;
+    }
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        // A negation flips a rule this reader cannot model, so the safe response is
+        // to interpret nothing from this file's remaining ambiguity rather than to
+        // guess which side of it a directory falls on.
+        if (line === "" || line.startsWith("#") || line.startsWith("!"))
+            continue;
+        const name = line.replace(/^\//, "").replace(/\/$/, "");
+        if (name === "" || name.includes("/") || /[*?[\]]/.test(name))
+            continue;
+        names.add(name);
+    }
+    return names;
+}
+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.
+ */
+export function globToRegExp(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i += 1) {
+        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`.
+                const slash = glob[i + 2] === "/";
+                out += slash ? "(?:[^/]+/)*" : ".*";
+                i += slash ? 2 : 1;
+                continue;
+            }
+            out += "[^/]*";
+            continue;
+        }
+        out += char === "?" ? "[^/]" : escape(char);
+    }
+    return new RegExp(`^${out}$`);
+}
+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.
+ */
+function isNestedCheckout(dir) {
+    return existsSync(join(dir, ".git"));
+}
+export function discover(root, globs, options = {}) {
+    const found = [];
+    const ignored = ignoredDirectories(root);
+    if (ignored.size > 0)
+        options.onIgnored?.([...ignored].sort());
+    const walk = (dir, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            // An unreadable directory is a disclosed gap, not a crash. `parseFiles`
+            // must succeed at R0 whatever the environment looks like.
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name.startsWith(".") || SKIP.has(entry.name))
+                continue;
+            if (entry.isDirectory() && ignored.has(entry.name))
+                continue;
+            const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (isNestedCheckout(join(dir, entry.name))) {
+                    options.onNestedCheckout?.(relative);
+                    continue;
+                }
+                walk(join(dir, entry.name), relative);
+            }
+            else if (entry.isFile() && matchesAny(relative, globs))
+                found.push(relative);
+        }
+    };
+    walk(root, "");
+    return found.sort();
+}
+/** Repo-relative, forward-slashed. Absolute paths are rejected by the Normaliser. */
+export function toRepoRelative(root, absolute) {
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    const stripped = absolute.startsWith(prefix) ? absolute.slice(prefix.length) : absolute;
+    return stripped.split(sep).join("/");
+}
+//# sourceMappingURL=discover.js.map

package/dist/discover.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared adapter infrastructure.
+ *
+ * Everything here is language-blind on purpose. It sits in this repository
+ * rather than in `@descryy/ir` because it is about reading a working copy —
+ * directories, globs, path shapes — which is an adapter concern and not part of
+ * the IR contract. The engine never calls it.
+ */
+export { discover, globToRegExp, ignoredDirectories, matchesAny, toRepoRelative } from "./discover.ts";
+export type { DiscoverOptions } from "./discover.ts";
+export { isolateFile } from "./isolate.ts";
+export type { Isolated, IsolatedFailure } from "./isolate.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Shared adapter infrastructure.
+ *
+ * Everything here is language-blind on purpose. It sits in this repository
+ * rather than in `@descryy/ir` because it is about reading a working copy —
+ * directories, globs, path shapes — which is an adapter concern and not part of
+ * the IR contract. The engine never calls it.
+ */
+export { discover, globToRegExp, ignoredDirectories, matchesAny, toRepoRelative } from "./discover.js";
+export { isolateFile } from "./isolate.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/isolate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Per-file isolation for the work that happens *after* a file parses.
+ *
+ * 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.
+ */
+/** A file the adapter parsed but could not finish, and why. */
+export interface IsolatedFailure {
+    readonly file: string;
+    /** The underlying error message, not a restatement of a reason code. */
+    readonly detail: string;
+}
+export type Isolated<T> = {
+    readonly value: T;
+    readonly failure: undefined;
+} | {
+    readonly value: undefined;
+    readonly failure: IsolatedFailure;
+};
+/**
+ * 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.
+ *
+ * **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.
+ */
+export declare function isolateFile<T>(file: string, step: () => T): Isolated<T>;
+//# sourceMappingURL=isolate.d.ts.map

package/dist/isolate.d.ts.map

@@ -0,0 +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"}

package/dist/isolate.js

@@ -0,0 +1,49 @@
+/**
+ * Per-file isolation for the work that happens *after* a file parses.
+ *
+ * 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.
+ */
+/**
+ * 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.
+ *
+ * **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.
+ */
+export function isolateFile(file, step) {
+    try {
+        return { value: step(), failure: undefined };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        return {
+            value: undefined,
+            failure: { file, detail: error instanceof Error ? error.message : String(error) },
+        };
+    }
+}
+//# sourceMappingURL=isolate.js.map

package/dist/isolate.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@descryy/adapter-common",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared adapter infrastructure: file discovery, glob matching, path normalisation. No language knowledge.",
+  "license": "UNLICENSED",
+  "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": {}
+}