docsgov 0.1.0

package/dist/codeq/signature.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { normalizeType, signaturesMatch } from "./signature.js";
+// WHY: overload identity (in Java/Go/TS) is by erased parameter types; the doc
+// author and the source may spell a type differently (whitespace, generic args,
+// varargs vs array). Matching MUST normalize both sides the same way or overload
+// disambiguation is brittle and rejects refs that should resolve. These cases
+// are the port of internal/codeq/signature_test.go and pin the normalization
+// rules that the language resolvers depend on.
+describe("normalizeType", () => {
+    // Each pair encodes one normalization rule the resolvers rely on.
+    const cases = {
+        "String[]": "String[]", // already canonical → unchanged
+        " String [ ] ": "String[]", // whitespace is dropped entirely
+        "List<String>": "List", // generic args erased to the base name
+        "Map<K, V>": "Map", // multi-arg generics erased, whitespace gone
+        "String...": "String[]", // varargs map to an array suffix
+        "java.util.List": "java.util.List", // qualified names preserved verbatim
+        int: "int", // primitives preserved verbatim
+    };
+    for (const [input, want] of Object.entries(cases)) {
+        it(`normalizes ${JSON.stringify(input)} → ${JSON.stringify(want)}`, () => {
+            expect(normalizeType(input)).toBe(want);
+        });
+    }
+    it("re-attaches an array suffix after erasing generics (List<String>[] → List[])", () => {
+        // WHY: a generic array's [] follows the closing '>'; erasing the generic
+        // must keep the arrayness or List<T>[] would wrongly match List.
+        expect(normalizeType("List<String>[]")).toBe("List[]");
+    });
+});
+describe("signaturesMatch", () => {
+    it("matches on a whitespace-only difference", () => {
+        expect(signaturesMatch(["String[]", "Integer"], ["String [ ]", "Integer"])).toBe(true);
+    });
+    it("matches after generic erasure (List<String> ~ List)", () => {
+        expect(signaturesMatch(["List<String>"], ["List"])).toBe(true);
+    });
+    it("matches zero-arg against zero-arg", () => {
+        // WHY: the "()" overload is a real, distinct overload — [] must match [].
+        expect(signaturesMatch([], [])).toBe(true);
+    });
+    it("rejects an arity mismatch", () => {
+        // WHY: arity is the first discriminator between overloads; (int) is not (int,int).
+        expect(signaturesMatch(["int"], ["int", "int"])).toBe(false);
+    });
+    it("rejects different types of equal arity", () => {
+        // WHY: matching is case/text sensitive after normalization — int is not long.
+        expect(signaturesMatch(["int"], ["long"])).toBe(false);
+    });
+});

package/dist/codeq/suggest.js

@@ -0,0 +1,96 @@
+// suggest.ts is the candidate-listing companion to the boolean Resolver oracle.
+//
+// The oracle (resolve) answers ONLY "does this ref exist?" — true/false. When it
+// returns false the check layer wants to help the author: which same-kind names
+// DO exist in the file (so a typo can become a "did you mean")? That is what a
+// Suggestion carries. Extraction needs tree-sitter, so it lives here behind the
+// codeq boundary; the check layer owns the ranking + wording (check/suggest.ts).
+//
+// This is BEST-EFFORT and has no Go analogue: the Go binary's oracle is boolean
+// only. The suggestion path is invoked solely on the not-found branch, so it
+// never affects whether a violation fires — only how it reads.
+import { nodeText, runQuery } from "./treesitter.js";
+/**
+ * refKind classifies a CodeRef the same way the resolvers' dispatch does, but
+ * only as far as suggestions care: a Member selector means we're after a member,
+ * else a Param selector means a parameter, else the top-level symbol. A bare
+ * symbol + signature (a Java/JS/TS constructor overload) stays "symbol" — its
+ * candidate space is the type names, and an exact-name match is suppressed by the
+ * ranker, so a pure signature mismatch yields no misleading suggestion.
+ */
+export function refKind(ref) {
+    if (ref.Member !== "") {
+        return "member";
+    }
+    if (ref.Param !== "") {
+        return "param";
+    }
+    return "symbol";
+}
+/**
+ * suggestFromExtractors computes a Suggestion for `ref` from a parsed tree using
+ * the language's extractors. The dispatch mirrors refKind:
+ *
+ *   member: list the owner's members. If the owner has none AND is not declared
+ *           at all, report ownerMissing instead (the type name is the typo).
+ *   param:  list the function's params, with the same owner-missing fallback.
+ *   symbol: list every top-level name.
+ *
+ * The owner-existence fallback uses symbolNames as the "is this declared?" oracle;
+ * a present-but-memberless owner therefore yields an empty candidate list rather
+ * than a false ownerMissing.
+ */
+export function suggestFromExtractors(root, ref, ex) {
+    if (ref.Member !== "") {
+        const members = ex.memberNames(root, ref.Symbol);
+        if (members.length > 0) {
+            return { kind: "member", candidates: members };
+        }
+        if (ex.symbolNames(root).includes(ref.Symbol)) {
+            return { kind: "member", candidates: [] };
+        }
+        return { kind: "member", ownerMissing: ref.Symbol, candidates: [] };
+    }
+    if (ref.Param !== "") {
+        const params = ex.paramNames(root, ref.Symbol);
+        if (params.length > 0) {
+            return { kind: "param", candidates: params };
+        }
+        if (ex.symbolNames(root).includes(ref.Symbol)) {
+            return { kind: "param", candidates: [] };
+        }
+        return { kind: "param", ownerMissing: ref.Symbol, candidates: [] };
+    }
+    return { kind: "symbol", candidates: ex.symbolNames(root) };
+}
+/**
+ * collectCapture returns the text of every `cap` capture across a query's
+ * matches — e.g. every declaration name. Shared by the language extractors,
+ * which use the SAME queries the oracle uses, so a candidate list is exactly the
+ * symbol space resolve() searched.
+ */
+export function collectCapture(root, query, cap) {
+    const out = [];
+    for (const m of runQuery(root, query)) {
+        const n = m.captures[cap];
+        if (n !== undefined) {
+            out.push(nodeText(n));
+        }
+    }
+    return out;
+}
+/**
+ * collectOwned returns the `nameCap` capture of every match whose `ownerCap`
+ * capture equals `want` — the members of a type, or the params of a function.
+ */
+export function collectOwned(root, query, want, ownerCap, nameCap) {
+    const out = [];
+    for (const m of runQuery(root, query)) {
+        const owner = m.captures[ownerCap];
+        const name = m.captures[nameCap];
+        if (owner !== undefined && name !== undefined && nodeText(owner) === want) {
+            out.push(nodeText(name));
+        }
+    }
+    return out;
+}

package/dist/codeq/treesitter.js

@@ -0,0 +1,122 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { Language, Node, Parser, Query } from "web-tree-sitter";
+// treesitter.ts is the ONLY module that imports web-tree-sitter. It insulates
+// the resolvers from the binding: resolver code is identical regardless of which
+// tree-sitter binding sits underneath. It exposes:
+//   - initParser()         — one-time process-wide Parser.init (idempotent)
+//   - loadGrammar(name)    — async, cached Language loader reading vendored wasm
+//   - compileQuery(lang,src) — compile once, reuse (mirrors Go's mustQuery vars)
+//   - runQuery(root, q)    — binding-neutral match shape (no cursor API leak)
+//   - parseTree(parser,src)— parse + null-guard
+//   - nodeText(n)          — n.text (UTF-16 correct; no []byte math)
+//
+// Re-export the binding's value/type names so resolvers import them from HERE,
+// keeping the web-tree-sitter import surface in one file.
+export { Language, Node, Parser };
+// Vendored wasm files live alongside this module in ./grammars/. They were
+// copied once from the upstream tree-sitter-* npm packages at vendor time (see
+// the port notes); those packages are NOT runtime deps.
+const WASM_FILE = {
+    go: "tree-sitter-go.wasm",
+    java: "tree-sitter-java.wasm",
+    javascript: "tree-sitter-javascript.wasm",
+    typescript: "tree-sitter-typescript.wasm",
+    tsx: "tree-sitter-tsx.wasm",
+};
+// One-time Parser.init guard. Parser.init() must run exactly once process-wide
+// before any Language.load / parse. Cache the Promise so concurrent callers
+// share the single init.
+let initPromise;
+/** initParser runs Parser.init() exactly once process-wide. Idempotent. */
+export function initParser() {
+    if (initPromise === undefined) {
+        initPromise = Parser.init();
+    }
+    return initPromise;
+}
+// Cache loaded Language objects by grammar name so each wasm is read+loaded once.
+const languageCache = new Map();
+/**
+ * loadGrammar loads (and caches) the Language for a vendored grammar. It runs
+ * initParser() first, then reads the wasm bytes and Language.load()s them.
+ * Concurrent calls for the same grammar share one load.
+ */
+export function loadGrammar(name) {
+    const cached = languageCache.get(name);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const p = (async () => {
+        await initParser();
+        const wasmPath = fileURLToPath(new URL(`./grammars/${WASM_FILE[name]}`, import.meta.url));
+        const bytes = await readFile(wasmPath);
+        return Language.load(bytes);
+    })();
+    languageCache.set(name, p);
+    p.catch(() => {
+        // Evict a failed load so a retry is possible (mirrors the cache.ts policy).
+        if (languageCache.get(name) === p) {
+            languageCache.delete(name);
+        }
+    });
+    return p;
+}
+/**
+ * compileQuery compiles a tree-sitter S-expression query against a language.
+ * THROWS on a bad query — this mirrors Go's mustQuery panic: a hard-coded query
+ * literal that fails to compile is a programming error, surfaced at resolver
+ * construction time. Compile once and reuse the returned Query across trees
+ * (parse/matches are read-only on the Query), mirroring Go's package-level
+ * mustQuery vars / per-grammar buildTSQueries.
+ */
+export function compileQuery(language, src) {
+    // new Query throws on a syntax error in src; let it propagate (= the panic).
+    return new Query(language, src);
+}
+/**
+ * runQuery runs `query` over `root` and returns an array of binding-neutral
+ * match views. Each view groups captures by name so resolver code never touches
+ * the binding's capture-array shape. `captures[name]` is the FIRST node captured
+ * under that name in the match; `all[name]` is every node under that name.
+ *
+ * web-tree-sitter's query.matches returns a plain array (no cursor / NextMatch /
+ * CaptureNameForId); each capture object carries .name and .node directly. We
+ * normalise that here so the cursor-vs-array difference between bindings never
+ * leaks into resolvers.
+ */
+export function runQuery(root, query) {
+    const matches = query.matches(root);
+    const out = [];
+    for (const m of matches) {
+        const captures = {};
+        const all = {};
+        for (const c of m.captures) {
+            if (!(c.name in captures)) {
+                captures[c.name] = c.node;
+            }
+            (all[c.name] ??= []).push(c.node);
+        }
+        out.push({ captures, all, patternIndex: m.patternIndex });
+    }
+    return out;
+}
+/**
+ * parseTree parses `src` with `parser` and returns the root Node, or throws if
+ * the parser produced no tree (parse() returns null when no language is set —
+ * a programming error here, since callers set the language first).
+ *
+ * Note: this does NOT check rootNode.hasError; that maps to ParseFailedError and
+ * is the resolver's call (it owns the file path for the error message).
+ */
+export function parseTree(parser, src) {
+    const tree = parser.parse(src);
+    if (tree === null) {
+        throw new Error("codeq: parser produced no tree (no language set)");
+    }
+    return tree.rootNode;
+}
+/** nodeText returns a node's source text. UTF-16 correct — no []byte slicing. */
+export function nodeText(n) {
+    return n.text;
+}

package/dist/codeq/treesitter.test.js

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { Parser, compileQuery, loadGrammar, nodeText, parseTree, runQuery, } from "./treesitter.js";
+// WHY: the treesitter helper is the seam every language resolver builds on. If
+// loadGrammar can't read a vendored wasm, compileQuery doesn't surface a bad
+// query, or runQuery's capture-grouping is wrong, EVERY resolver is broken in a
+// way no resolver test would localise. These tests pin: (1) a vendored grammar
+// loads and parses real source, (2) the SAME S-expression query text from the Go
+// package runs verbatim and yields the expected named captures, (3) a bad query
+// throws (the mustQuery-panic contract resolvers rely on), (4) the binding's
+// UTF-16 offsets don't corrupt nodeText, and (5) .ts and .tsx are distinct langs.
+// One shared parser is fine across tests: parse() is sync post-init, and each
+// parse returns its own tree. We set the language per test.
+function parserFor(lang) {
+    const p = new Parser();
+    p.setLanguage(lang);
+    return p;
+}
+describe("treesitter helper", () => {
+    it("loads the Go grammar and parses a sample without errors", async () => {
+        const go = await loadGrammar("go");
+        const root = parseTree(parserFor(go), "package pkg\nfunc Bar() {}\ntype T struct{}\n");
+        // A clean parse of valid Go must not report ERROR nodes — this is what the
+        // resolver maps to ParseFailedError, so a false positive here would reject
+        // valid source.
+        expect(root.hasError).toBe(false);
+        expect(root.type).toBe("source_file");
+    });
+    it("runs the verbatim Go symbol query and returns @name captures", async () => {
+        const go = await loadGrammar("go");
+        // This is the exact goSymbolQuery text from internal/codeq/go_queries.go —
+        // proving the node-type names match the upstream wasm grammar so the Go
+        // queries port verbatim (a core assumption of the whole port).
+        const q = compileQuery(go, `
+(function_declaration name: (identifier) @name)
+(type_declaration (type_spec name: (type_identifier) @name))
+(var_declaration (var_spec name: (identifier) @name))
+(const_declaration (const_spec name: (identifier) @name))
+`);
+        try {
+            const root = parseTree(parserFor(go), "package pkg\nfunc Bar() {}\ntype Baz struct{}\nvar Qux = 1\nconst K = 2\n");
+            const names = runQuery(root, q)
+                .map((m) => m.captures["name"])
+                .filter((n) => n !== undefined)
+                .map(nodeText)
+                .sort();
+            // All four top-level declaration kinds must be captured by @name.
+            expect(names).toEqual(["Bar", "Baz", "K", "Qux"]);
+        }
+        finally {
+            q.delete();
+        }
+    });
+    it("groups multi-capture matches: captures has first, all has every node", async () => {
+        const go = await loadGrammar("go");
+        // The Go member query yields TWO captures per match (@owner and @name); this
+        // verifies runQuery's per-name grouping that resolvers depend on.
+        const q = compileQuery(go, `(method_declaration receiver: (parameter_list (parameter_declaration type: (type_identifier) @owner)) name: (field_identifier) @name)`);
+        try {
+            const root = parseTree(parserFor(go), "package pkg\ntype T struct{}\nfunc (t T) Do() {}\n");
+            const matches = runQuery(root, q);
+            expect(matches).toHaveLength(1);
+            const m = matches[0];
+            expect(m).toBeDefined();
+            expect(nodeText(m.captures["owner"])).toBe("T");
+            expect(nodeText(m.captures["name"])).toBe("Do");
+            // all[name] is an array even for a single capture.
+            expect(m.all["name"]).toHaveLength(1);
+        }
+        finally {
+            q.delete();
+        }
+    });
+    it("throws on a syntactically invalid query (mustQuery-panic contract)", async () => {
+        const go = await loadGrammar("go");
+        // A hard-coded bad query is a programming error; compileQuery must throw so
+        // resolver construction fails loudly rather than silently matching nothing.
+        expect(() => compileQuery(go, "(this is not a valid query")).toThrow();
+    });
+    it("reports hasError on invalid source (the ParseFailedError trigger)", async () => {
+        const go = await loadGrammar("go");
+        // Invalid Go yields ERROR nodes, NOT a parse() null/throw — the resolver
+        // checks hasError to decide ParseFailedError, so this must be true here.
+        const root = parseTree(parserFor(go), "package pkg\nfunc Bar( {{{ \n");
+        expect(root.hasError).toBe(true);
+    });
+    it("returns UTF-16-correct text via nodeText (no byte-offset corruption)", async () => {
+        const go = await loadGrammar("go");
+        // A multibyte identifier comment would desync []byte offsets; node.text is
+        // UTF-16 native, so nodeText must return the identifier intact even with a
+        // non-ASCII string literal earlier in the file.
+        const root = parseTree(parserFor(go), 'package pkg\nvar S = "café→ünïcödé"\nfunc Função() {}\n');
+        const q = compileQuery(go, `(function_declaration name: (identifier) @name)`);
+        try {
+            const names = runQuery(root, q).map((m) => nodeText(m.captures["name"]));
+            expect(names).toEqual(["Função"]);
+        }
+        finally {
+            q.delete();
+        }
+    });
+    it("loads .ts and .tsx as DISTINCT languages", async () => {
+        // WHY: a Query compiled for typescript cannot run on a tsx tree and vice
+        // versa; the dispatch routes .ts→typescript and .tsx→tsx. Confirm they are
+        // not the same object so per-grammar query sets stay separate.
+        const [ts, tsx] = await Promise.all([
+            loadGrammar("typescript"),
+            loadGrammar("tsx"),
+        ]);
+        expect(ts).not.toBe(tsx);
+    });
+    it("caches the loaded Language (same grammar → same object)", async () => {
+        // WHY: loadGrammar must read+load each wasm once (Go caches the Language at
+        // package init); a second call must return the cached Language, not reload.
+        const a = await loadGrammar("java");
+        const b = await loadGrammar("java");
+        expect(a).toBe(b);
+    });
+});

package/dist/config/config.js

@@ -0,0 +1,74 @@
+// Port of internal/config/config.go.
+//
+// Document-config / manifest YAML types and their loader. YAML field spellings
+// are preserved exactly ("boundary", "source"). Validation/parse failures
+// throw; the parsed Config is returned data.
+import { parse as parseYaml } from "yaml";
+/**
+ * decodeScope turns a parsed YAML value (the value under `code:`/`doc:`/`api:`)
+ * into a Scope. A null value (present-but-empty section) yields an empty Scope,
+ * matching Go's "decode null into zero-value struct" behaviour. Non-list
+ * boundary/source values are coerced/ignored the way yaml.v3 leaves the field
+ * at its zero value when the node is absent.
+ */
+function decodeScope(value) {
+    const scope = { boundary: [], source: [] };
+    if (value === null || value === undefined) {
+        return scope;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return scope;
+    }
+    const rec = value;
+    scope.boundary = toStringArray(rec["boundary"]);
+    scope.source = toStringArray(rec["source"]);
+    return scope;
+}
+/** toStringArray coerces a YAML sequence node into a string[] (empty if absent). */
+function toStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((item) => String(item));
+}
+/**
+ * loadConfig reads .docgov/docgov.yaml from fsys and returns the parsed Config.
+ *
+ * A missing file propagates a NotExistError (the CLI maps this to its exit code
+ * in a later stage). A malformed YAML file throws a descriptive error. No
+ * section defaults are applied: absent sections remain undefined.
+ *
+ * The custom decoding distinguishes "key present with null value" (yields a
+ * non-undefined empty Scope) from "key absent" (leaves the Scope undefined),
+ * matching the Go UnmarshalYAML implementation. Unknown top-level keys are
+ * silently ignored.
+ */
+export async function loadConfig(fsys) {
+    // readFile throws NotExistError for a missing file; let it propagate.
+    const data = await fsys.readFile(".docgov/docgov.yaml");
+    const text = new TextDecoder().decode(data);
+    // parseYaml throws on malformed YAML (descriptive error); let it propagate.
+    const parsed = parseYaml(text);
+    const cfg = {};
+    // An empty/null document is valid — no sections → all undefined.
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return cfg;
+    }
+    const root = parsed;
+    for (const key of Object.keys(root)) {
+        const scope = decodeScope(root[key]);
+        switch (key) {
+            case "code":
+                cfg.Code = scope;
+                break;
+            case "doc":
+                cfg.Doc = scope;
+                break;
+            case "api":
+                cfg.API = scope;
+                break;
+            // Unknown top-level keys are silently ignored per the plan.
+        }
+    }
+    return cfg;
+}

package/dist/config/config.test.js

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { loadConfig } from "./config.js";
+import { isNotExist, MapFS } from "./fs.js";
+describe("loadConfig", () => {
+    // All three sections must load when present — this is the happy path the
+    // whole check pipeline depends on.
+    it("loads code, doc, and api scopes with their exact glob lists", async () => {
+        const fsys = new MapFS({
+            ".docgov/docgov.yaml": `
+code:
+  boundary: [docs/**]
+  source:   [internal/**, cmd/**]
+doc:
+  boundary: [docs/**]
+api:
+  boundary: [docs/api/contract/**]
+  source:   [docs/api/openapi/**]
+`,
+        });
+        const cfg = await loadConfig(fsys);
+        expect(cfg.Code).toBeDefined();
+        expect(cfg.Doc).toBeDefined();
+        expect(cfg.API).toBeDefined();
+        expect(cfg.Code?.boundary).toEqual(["docs/**"]);
+        expect(cfg.Code?.source).toEqual(["internal/**", "cmd/**"]);
+        expect(cfg.Doc?.boundary).toEqual(["docs/**"]);
+        expect(cfg.API?.boundary).toEqual(["docs/api/contract/**"]);
+        expect(cfg.API?.source).toEqual(["docs/api/openapi/**"]);
+    });
+    // An absent section must stay undefined so the pipeline can skip that guard
+    // entirely (undefined vs defined is the "is this guard configured?" signal).
+    it("leaves absent sections undefined", async () => {
+        const fsys = new MapFS({
+            ".docgov/docgov.yaml": `
+doc:
+  boundary: [docs/**]
+`,
+        });
+        const cfg = await loadConfig(fsys);
+        expect(cfg.Code).toBeUndefined();
+        expect(cfg.API).toBeUndefined();
+        expect(cfg.Doc).toBeDefined();
+        expect(cfg.Doc?.boundary).toEqual(["docs/**"]);
+    });
+    // A present-but-empty `code:` key must yield a DEFINED scope with empty
+    // arrays — this is the load-bearing distinction between "omitted" (skip the
+    // guard) and "explicitly configured but empty" (run the guard, match nothing).
+    it("yields a defined empty scope for a present-but-null section", async () => {
+        const fsys = new MapFS({
+            ".docgov/docgov.yaml": `
+code:
+`,
+        });
+        const cfg = await loadConfig(fsys);
+        expect(cfg.Code).toBeDefined();
+        expect(cfg.Code?.boundary).toEqual([]);
+        expect(cfg.Code?.source).toEqual([]);
+    });
+    // A missing config file must propagate a not-exist error so the CLI can map
+    // it to its dedicated exit code rather than crashing opaquely.
+    it("throws a not-exist error when the config file is missing", async () => {
+        const fsys = new MapFS({});
+        let thrown;
+        try {
+            await loadConfig(fsys);
+        }
+        catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBeDefined();
+        expect(isNotExist(thrown)).toBe(true);
+    });
+    // Malformed YAML must throw — a silently-empty config would let governed
+    // docs go unchecked.
+    it("throws on malformed YAML", async () => {
+        const fsys = new MapFS({
+            ".docgov/docgov.yaml": `
+code: {boundary: [not closed
+`,
+        });
+        await expect(loadConfig(fsys)).rejects.toThrow();
+    });
+    // Unknown top-level keys are silently ignored (forward-compat per the plan).
+    it("silently ignores unknown top-level keys", async () => {
+        const fsys = new MapFS({
+            ".docgov/docgov.yaml": `
+future:
+  boundary: [x/**]
+doc:
+  boundary: [docs/**]
+`,
+        });
+        const cfg = await loadConfig(fsys);
+        expect(cfg.Doc?.boundary).toEqual(["docs/**"]);
+        expect(cfg.Code).toBeUndefined();
+        expect(cfg.API).toBeUndefined();
+    });
+});

package/dist/config/fs.js

@@ -0,0 +1,116 @@
+// Filesystem abstraction for the config package.
+//
+// FS RECONCILIATION (minimize-docgov port): the config package and the repo
+// package originally carried two different FS abstractions — config's was
+// synchronous (readFile + walk), repo's is asynchronous (readFile + readDir +
+// sub). The check orchestrator composes both, so they are unified here onto
+// repo's ASYNC FS: config re-exports repo's `FS`/`DirEntry`/`isNotExist`, and
+// `MapFS` (config's in-memory test FS) now implements that async interface.
+//
+// All paths are forward-slash ("/") relative paths, following the io/fs
+// convention. There is no leading "/" and no "." prefix ("." is the root).
+export { isNotExist } from "../repo/fs.js";
+/**
+ * NotExistError is the TS analogue of Go's fs.ErrNotExist. LoadConfig
+ * propagates it for a missing file so the CLI can map it to its dedicated exit
+ * code (the same way the Go code relies on errors.Is(err, fs.ErrNotExist)).
+ *
+ * Its `code` is set to "ENOENT" so repo's {@link isNotExist} (which keys on the
+ * Node error code) recognises it too — keeping a single not-exist predicate
+ * across the unified FS.
+ */
+export class NotExistError extends Error {
+    /** Node-style error code so the shared isNotExist predicate matches. */
+    code = "ENOENT";
+    constructor(path) {
+        super(`file does not exist: ${path}`);
+        this.name = "NotExistError";
+    }
+}
+/** A directory entry of {@link MapFS}, implementing repo's DirEntry. */
+class MapDirEntry {
+    entryName;
+    dir;
+    constructor(entryName, dir) {
+        this.entryName = entryName;
+        this.dir = dir;
+    }
+    name() {
+        return this.entryName;
+    }
+    isDir() {
+        return this.dir;
+    }
+}
+/**
+ * MapFS is an in-memory FS keyed by file path, mirroring testing/fstest.MapFS.
+ * It implements repo's async {@link FS} so config (and the check orchestrator)
+ * can drive it the same way they drive a real on-disk repo. Directory entries
+ * are synthesised from the file paths' parent segments.
+ */
+export class MapFS {
+    files;
+    /** Slash-path of the subtree this view is rooted at ("" for the real root). */
+    root;
+    constructor(files, root = "") {
+        this.files = new Map();
+        for (const [name, data] of Object.entries(files)) {
+            this.files.set(name, typeof data === "string" ? new TextEncoder().encode(data) : data);
+        }
+        this.root = root;
+    }
+    /** Joins a name onto this view's root, normalising the "." root. */
+    resolve(name) {
+        const rel = name === "." || name === "" ? "" : name;
+        if (this.root === "") {
+            return rel;
+        }
+        return rel === "" ? this.root : `${this.root}/${rel}`;
+    }
+    async readFile(name) {
+        const key = this.resolve(name);
+        const data = this.files.get(key);
+        if (data === undefined) {
+            throw new NotExistError(key);
+        }
+        return data;
+    }
+    async readDir(name) {
+        const dir = this.resolve(name);
+        const prefix = dir === "" ? "" : `${dir}/`;
+        const childNames = new Map(); // name -> isDir
+        let dirExists = dir === "";
+        for (const filePath of this.files.keys()) {
+            if (dir !== "" && filePath === dir) {
+                // A file path that equals the requested dir means it's not a directory.
+                continue;
+            }
+            if (!filePath.startsWith(prefix)) {
+                continue;
+            }
+            dirExists = true;
+            const rest = filePath.slice(prefix.length);
+            const slash = rest.indexOf("/");
+            if (slash < 0) {
+                childNames.set(rest, false);
+            }
+            else {
+                const childDir = rest.slice(0, slash);
+                if (!childNames.has(childDir)) {
+                    childNames.set(childDir, true);
+                }
+            }
+        }
+        if (!dirExists) {
+            throw new NotExistError(dir);
+        }
+        return [...childNames].map(([n, isDir]) => new MapDirEntry(n, isDir));
+    }
+    sub(name) {
+        const dir = this.resolve(name);
+        const view = new MapFS({}, dir);
+        // Share the same backing map so the sub-view reads the same files.
+        view.files = this.files;
+        return view;
+    }
+}