docsgov 0.1.0

package/dist/check/run.js

@@ -0,0 +1,391 @@
+// Port of internal/check/run.go — the three-pass Run pipeline (Stage 5 of
+// minimize-docgov) and the {{api:…}} qualifier dispatch from apitokens' caller.
+//
+// run() runs three independent passes (code, doc, api) over the scopes declared
+// in cfg. Only present (non-undefined) sections are executed. Violations are
+// collected from all passes and returned sorted by (file, line) for
+// determinism. Only operational errors (FS walk failures, etc.) reject.
+//
+// FS RECONCILIATION: this is the integration point. config and repo now share
+// repo's ASYNC FS (see config/fs.ts), so run() — and every pass — is async.
+import { parse as parseSpec } from "../apispec/index.js";
+import { inScope, walkMarkdown } from "../config/index.js";
+import { parseApiRef } from "../guard/api/index.js";
+import { parseCodeRef } from "../guard/code/index.js";
+import { MalformedRefError as ApiMalformedRefError } from "../guard/api/errors.js";
+import { MalformedRefError as CodeMalformedRefError } from "../guard/code/errors.js";
+import { isNotExist } from "../repo/index.js";
+import { Rules } from "../violation/index.js";
+import { checkDocLinks } from "./doclinks.js";
+import { suggestionSuffix } from "./suggest.js";
+import { iterApiTokens, iterCodeTokens } from "./tokens.js";
+/**
+ * run executes three independent guard passes (code, doc, api) as configured in
+ * cfg, collecting all violations. Passes for absent sections are skipped.
+ * Returns violations sorted by (file, line). Only operational errors (FS walk
+ * failures, etc.) reject.
+ */
+export async function run(cfg, r, resolver) {
+    const fsys = r.fs();
+    let vs = [];
+    if (cfg.Code !== undefined) {
+        vs = vs.concat(await runCodePass(cfg.Code, fsys, resolver));
+    }
+    if (cfg.Doc !== undefined) {
+        vs = vs.concat(await runDocPass(cfg.Doc, fsys));
+    }
+    if (cfg.API !== undefined) {
+        vs = vs.concat(await runAPIPass(cfg.API, fsys));
+    }
+    vs.sort((a, b) => {
+        if (a.file !== b.file) {
+            return a.file < b.file ? -1 : 1;
+        }
+        return a.line - b.line;
+    });
+    return vs;
+}
+/** decodeBytes turns raw file bytes into a string (CRLF already normalised by repo). */
+function decodeBytes(data) {
+    return new TextDecoder().decode(data);
+}
+/**
+ * runCodePass executes the code guard pass over all .md files in scope.boundary.
+ * For each {{code:…}} token: parse it, check the path is under scope.source, then
+ * resolve it. No status/sigil gating.
+ */
+async function runCodePass(scope, fsys, resolver) {
+    const files = await walkMarkdown(fsys, scope.boundary);
+    const vs = [];
+    for (const file of files) {
+        let src;
+        try {
+            src = decodeBytes(await fsys.readFile(file));
+        }
+        catch (err) {
+            vs.push({
+                rule: Rules.guardCode,
+                file,
+                line: 0,
+                sectionID: "",
+                expected: "",
+                actual: "",
+                message: "cannot read file: " + errMsg(err),
+            });
+            continue;
+        }
+        for (const loc of iterCodeTokens(src)) {
+            const v = await checkCodeToken(file, loc, scope.source, fsys, resolver);
+            if (v !== null) {
+                vs.push(v);
+            }
+        }
+    }
+    return vs;
+}
+/**
+ * checkCodeToken evaluates one code token: parse, source-check, resolve. Returns
+ * null when the token passes all checks.
+ */
+async function checkCodeToken(file, loc, source, fsys, resolver) {
+    let ref;
+    try {
+        ref = parseCodeRef(loc.token);
+    }
+    catch (err) {
+        if (err instanceof CodeMalformedRefError) {
+            return {
+                rule: Rules.guardCode,
+                file,
+                line: loc.line,
+                sectionID: "",
+                expected: "",
+                actual: loc.token,
+                message: "malformed code ref: " + err.message,
+            };
+        }
+        throw err;
+    }
+    if (!inScope(source, ref.Path)) {
+        return {
+            rule: Rules.guardCode,
+            file,
+            line: loc.line,
+            sectionID: "",
+            expected: "under code.source",
+            actual: loc.token,
+            message: "ref points outside source",
+        };
+    }
+    let found;
+    try {
+        found = await resolver.resolve(fsys, ref);
+    }
+    catch (err) {
+        return {
+            rule: Rules.guardCode,
+            file,
+            line: loc.line,
+            sectionID: "",
+            expected: "",
+            actual: loc.token,
+            message: "resolver error: " + errMsg(err),
+        };
+    }
+    if (!found) {
+        let message = "referenced symbol not found";
+        // Best-effort "did you mean": never let a suggestion fault drop the
+        // violation itself — the base message must always survive.
+        if (resolver.suggest !== undefined) {
+            try {
+                message += suggestionSuffix(ref, await resolver.suggest(fsys, ref));
+            }
+            catch {
+                // keep the base message
+            }
+        }
+        return {
+            rule: Rules.guardCode,
+            file,
+            line: loc.line,
+            sectionID: "",
+            expected: "symbol exists",
+            actual: loc.token,
+            message,
+        };
+    }
+    return null;
+}
+/**
+ * runDocPass executes the doc existence pass over all .md files in
+ * scope.boundary. It collects every link and image destination from the mdast
+ * tree, then applies the existence algorithm (URL/fragment skip, absolute
+ * reject, escape reject, existence check).
+ */
+async function runDocPass(scope, fsys) {
+    const files = await walkMarkdown(fsys, scope.boundary);
+    const vs = [];
+    for (const file of files) {
+        let src;
+        try {
+            src = decodeBytes(await fsys.readFile(file));
+        }
+        catch (err) {
+            vs.push({
+                rule: Rules.guardDocs,
+                file,
+                line: 0,
+                sectionID: "",
+                expected: "",
+                actual: "",
+                message: "cannot read file: " + errMsg(err),
+            });
+            continue;
+        }
+        const fv = await checkDocLinks(file, src, fsys);
+        for (const v of fv) {
+            vs.push(v);
+        }
+    }
+    return vs;
+}
+/**
+ * runAPIPass executes the api guard pass:
+ *  1. Load all .json specs under scope.source.
+ *  2. For each .md in scope.boundary, scan {{api:…}} tokens and validate.
+ */
+async function runAPIPass(scope, fsys) {
+    const { specs, specVs } = await loadAPISpecs(scope.source, fsys);
+    // If there were spec-load violations but some specs loaded, continue checking.
+    // If no specs loaded at all (and no load error), add a zero-spec violation.
+    const vs = [...specVs];
+    if (specs.length === 0 && specVs.length === 0) {
+        vs.push({
+            rule: Rules.guardAPI,
+            file: "",
+            line: 0,
+            sectionID: "",
+            expected: "",
+            actual: "",
+            message: "no OpenAPI spec found under api.source",
+        });
+        // Without specs we can still scan tokens for malformed-ref errors.
+    }
+    const files = await walkMarkdown(fsys, scope.boundary);
+    for (const file of files) {
+        let src;
+        try {
+            src = decodeBytes(await fsys.readFile(file));
+        }
+        catch (err) {
+            vs.push({
+                rule: Rules.guardAPI,
+                file,
+                line: 0,
+                sectionID: "",
+                expected: "",
+                actual: "",
+                message: "cannot read file: " + errMsg(err),
+            });
+            continue;
+        }
+        for (const loc of iterApiTokens(src)) {
+            for (const v of checkAPIToken(file, loc, specs)) {
+                vs.push(v);
+            }
+        }
+    }
+    return vs;
+}
+/**
+ * loadAPISpecs enumerates every .json file under source patterns, loads each,
+ * and returns the loaded specs plus any per-file load violations.
+ */
+async function loadAPISpecs(source, fsys) {
+    const specs = [];
+    const specVs = [];
+    // Collect every .json path in the tree (slash paths), then filter by scope.
+    const jsonPaths = [];
+    async function descend(dirSlash) {
+        let entries;
+        try {
+            entries = await fsys.readDir(dirSlash === "" ? "." : dirSlash);
+        }
+        catch (err) {
+            if (isNotExist(err)) {
+                return;
+            }
+            throw err;
+        }
+        for (const entry of entries) {
+            const childSlash = dirSlash === "" ? entry.name() : `${dirSlash}/${entry.name()}`;
+            if (entry.isDir()) {
+                await descend(childSlash);
+                continue;
+            }
+            if (childSlash.endsWith(".json")) {
+                jsonPaths.push(childSlash);
+            }
+        }
+    }
+    await descend("");
+    for (const p of jsonPaths) {
+        if (!inScope(source, p)) {
+            continue;
+        }
+        let s;
+        try {
+            const data = decodeBytes(await fsys.readFile(p));
+            s = parseSpec(data, p);
+        }
+        catch (err) {
+            specVs.push({
+                rule: Rules.guardAPI,
+                file: p,
+                line: 0,
+                sectionID: "",
+                expected: "",
+                actual: "",
+                message: errMsg(err),
+            });
+            continue;
+        }
+        specs.push(s);
+    }
+    return { specs, specVs };
+}
+/**
+ * checkAPIToken validates one {{api:…}} token against the loaded specs. Returns
+ * one violation when: malformed, operation missing, or qualifier not satisfied.
+ */
+function checkAPIToken(file, loc, specs) {
+    let ref;
+    try {
+        ref = parseApiRef(loc.token);
+    }
+    catch (err) {
+        if (err instanceof ApiMalformedRefError) {
+            return [
+                {
+                    rule: Rules.guardAPI,
+                    file,
+                    line: loc.line,
+                    sectionID: "",
+                    expected: "",
+                    actual: loc.token,
+                    message: "malformed api ref: " + err.message,
+                },
+            ];
+        }
+        throw err;
+    }
+    // Check that at least one spec has the operation.
+    let opFound = false;
+    for (const s of specs) {
+        if (s.hasOperation(ref.Method, ref.Path)) {
+            opFound = true;
+            break;
+        }
+    }
+    if (!opFound) {
+        return [
+            {
+                rule: Rules.guardAPI,
+                file,
+                line: loc.line,
+                sectionID: "",
+                expected: "",
+                actual: loc.token,
+                message: `operation ${ref.Method} ${ref.Path} not found in spec`,
+            },
+        ];
+    }
+    // No qualifier — operation existence is sufficient.
+    if (ref.Qualifier === null) {
+        return [];
+    }
+    // Qualifier dispatch: pass if ANY spec satisfies it.
+    const name = ref.Qualifier.Path.join(".");
+    let satisfied = false;
+    for (const s of specs) {
+        if (qualifierSatisfied(s, ref, name)) {
+            satisfied = true;
+            break;
+        }
+    }
+    if (!satisfied) {
+        return [
+            {
+                rule: Rules.guardAPI,
+                file,
+                line: loc.line,
+                sectionID: "",
+                expected: "",
+                actual: loc.token,
+                message: `${ref.Qualifier.Kind} ${name} not found on ${ref.Method} ${ref.Path}`,
+            },
+        ];
+    }
+    return [];
+}
+/** qualifierSatisfied checks whether the given spec satisfies the qualifier on ref. */
+function qualifierSatisfied(s, ref, name) {
+    const q = ref.Qualifier;
+    if (q === null) {
+        return false;
+    }
+    switch (q.Kind) {
+        case "param":
+            return s.hasParam(ref.Method, ref.Path, name);
+        case "header":
+            return s.hasHeader(ref.Method, ref.Path, name);
+        case "body":
+            return s.hasBodyField(ref.Method, ref.Path, q.Path);
+        case "response":
+            return s.hasResponseField(ref.Method, ref.Path, q.Path);
+    }
+    return false;
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}