docsgov 0.1.0

package/dist/apispec/apispec.test.js

@@ -0,0 +1,444 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { load, parse } from "./apispec.js";
+import { SpecNotFoundError, SpecParseError } from "./errors.js";
+// Inline copy of internal/apispec/testdata/openapi.json. Covers normalisation,
+// requestBody descent, allOf/oneOf composition, and a $ref cycle.
+const OPENAPI = `{
+  "openapi": "3.1.0",
+  "info": { "title": "Test API", "version": "1.0.0" },
+  "paths": {
+    "/api/admin/teams": {
+      "get": {
+        "operationId": "listAdminTeams",
+        "parameters": [
+          { "name": "team_type",  "in": "query", "schema": { "type": "string" } },
+          { "name": "page_size",  "in": "query", "schema": { "type": "integer" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/AdminTeamsPage" }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createAdminTeam",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": { "req_field": { "type": "string" } }
+              }
+            }
+          }
+        },
+        "responses": { "201": { "description": "created" } }
+      }
+    },
+    "/api/admin/teams/{teamId}": {
+      "get": {
+        "operationId": "getAdminTeam",
+        "parameters": [
+          { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/TeamSummary" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/admin/items": {
+      "get": {
+        "operationId": "listAdminItems",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ItemsResult" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/admin/tree": {
+      "get": {
+        "operationId": "getAdminTree",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/TreeNode" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "AdminTeamsPage": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/TeamSummary" }
+          },
+          "next_page_token": { "type": "string" }
+        }
+      },
+      "TeamSummary": {
+        "type": "object",
+        "properties": {
+          "team_id":            { "type": "string" },
+          "team_key":           { "type": "string" },
+          "name":               { "type": "string" },
+          "team_type":          { "type": "string" },
+          "owner_user_id":      { "type": "string" },
+          "owner_display_name": { "type": "string" },
+          "member_count":       { "type": "integer" }
+        }
+      },
+      "Base": {
+        "type": "object",
+        "properties": { "base_field": { "type": "string" } }
+      },
+      "ItemsResult": {
+        "allOf": [
+          { "$ref": "#/components/schemas/Base" },
+          { "type": "object", "properties": { "extra": { "type": "string" } } },
+          { "oneOf": [
+              { "type": "object", "properties": { "variant_field": { "type": "string" } } }
+          ] }
+        ]
+      },
+      "TreeNode": {
+        "type": "object",
+        "properties": {
+          "node_id": { "type": "string" },
+          "label":   { "type": "string" },
+          "parent":  { "$ref": "#/components/schemas/TreeNode" }
+        }
+      }
+    }
+  }
+}`;
+// Inline copy of internal/apispec/testdata/nested.json. Covers param/header/body/
+// response queries through $ref, allOf, and array-items descent.
+const NESTED = `{
+  "openapi": "3.1.0",
+  "info": { "title": "Nested Test API", "version": "1.0.0" },
+  "paths": {
+    "/nested/{id}": {
+      "post": {
+        "operationId": "createNested",
+        "parameters": [
+          { "name": "id",     "in": "path",   "required": true, "schema": { "type": "string" } },
+          { "name": "lang",   "in": "query",  "schema": { "type": "string" } },
+          { "name": "X-Token","in": "header", "schema": { "type": "string" } }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/CreateBody" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "headers": {
+              "X-Trace": { "schema": { "type": "string" } }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "result": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Address": {
+        "type": "object",
+        "properties": {
+          "city":   { "type": "string" },
+          "street": { "type": "string" }
+        }
+      },
+      "Tag": {
+        "type": "object",
+        "properties": {
+          "name":  { "type": "string" },
+          "value": { "type": "string" }
+        }
+      },
+      "UserBase": {
+        "type": "object",
+        "properties": {
+          "email": { "type": "string" }
+        }
+      },
+      "UserFull": {
+        "allOf": [
+          { "$ref": "#/components/schemas/UserBase" },
+          {
+            "type": "object",
+            "properties": {
+              "address": { "$ref": "#/components/schemas/Address" },
+              "tags": {
+                "type": "array",
+                "items": { "$ref": "#/components/schemas/Tag" }
+              }
+            }
+          }
+        ]
+      },
+      "CreateBody": {
+        "type": "object",
+        "properties": {
+          "user": { "$ref": "#/components/schemas/UserFull" }
+        }
+      },
+      "SelfRef": {
+        "type": "object",
+        "properties": {
+          "self_id": { "type": "string" },
+          "child":   { "$ref": "#/components/schemas/SelfRef" }
+        }
+      }
+    }
+  }
+}`;
+function openapiSpec() {
+    return parse(OPENAPI, "openapi.json");
+}
+function nestedSpec() {
+    return parse(NESTED, "nested.json");
+}
+describe("hasOperation: path-template normalisation", () => {
+    // The guard must match a doc's {id} against the spec's {teamId}: operation
+    // existence keys on METHOD + normalised path, so var names are irrelevant.
+    test("exact method+path exists", () => {
+        expect(openapiSpec().hasOperation("GET", "/api/admin/teams")).toBe(true);
+    });
+    test("doc {id} normalises to spec {teamId}", () => {
+        expect(openapiSpec().hasOperation("GET", "/api/admin/teams/{id}")).toBe(true);
+    });
+    test("absent method on an existing path is false", () => {
+        expect(openapiSpec().hasOperation("DELETE", "/api/admin/teams")).toBe(false);
+    });
+    test("method is matched case-insensitively", () => {
+        expect(openapiSpec().hasOperation("get", "/api/admin/teams")).toBe(true);
+    });
+});
+describe("operationFields: contract field set", () => {
+    // The api guard checks {{api:...}} field references against the union of
+    // params + requestBody props + every response's props, walked recursively.
+    test("unions param names with response schema props (via $ref + array items)", () => {
+        const fields = openapiSpec().operationFields("GET", "/api/admin/teams");
+        expect(fields).toBeDefined();
+        for (const want of [
+            "team_type",
+            "page_size",
+            "items",
+            "next_page_token",
+            "team_id",
+            "owner_user_id",
+        ]) {
+            expect(fields?.has(want)).toBe(true);
+        }
+    });
+    test("does not invent fields that the contract never declares", () => {
+        expect(openapiSpec().operationFields("GET", "/api/admin/teams")?.has("does_not_exist")).toBe(false);
+    });
+    test("absent operation returns undefined (distinct from empty set)", () => {
+        expect(openapiSpec().operationFields("DELETE", "/api/admin/teams")).toBeUndefined();
+    });
+    // Exercises the requestBody.content.<media>.schema descent branch.
+    test("collects props from requestBody content schema", () => {
+        expect(openapiSpec().operationFields("POST", "/api/admin/teams")?.has("req_field")).toBe(true);
+    });
+    // allOf must contribute from every member (a $ref'd base + an inline object),
+    // and a nested oneOf branch must also be collected without breaking the walk.
+    test("resolves allOf members and nested oneOf branch", () => {
+        const fields = openapiSpec().operationFields("GET", "/api/admin/items");
+        expect(fields?.has("base_field")).toBe(true);
+        expect(fields?.has("extra")).toBe(true);
+        expect(fields?.has("variant_field")).toBe(true);
+    });
+    // A $ref cycle (TreeNode.parent -> TreeNode) must not infinite-loop; the
+    // visited-set lets collection terminate while still yielding direct props.
+    test("terminates on a $ref cycle and returns the node's own props", () => {
+        const fields = openapiSpec().operationFields("GET", "/api/admin/tree");
+        expect(fields?.has("node_id")).toBe(true);
+        expect(fields?.has("label")).toBe(true);
+    });
+});
+describe("hasParam: only path/query/cookie count", () => {
+    // The param facet of {{api:...}} addresses path/query/cookie params — headers
+    // and body fields are addressed by other facets and must not match here.
+    test("path param is a param", () => {
+        expect(nestedSpec().hasParam("POST", "/nested/{id}", "id")).toBe(true);
+    });
+    test("query param is a param", () => {
+        expect(nestedSpec().hasParam("POST", "/nested/{id}", "lang")).toBe(true);
+    });
+    test("header param is not a param", () => {
+        expect(nestedSpec().hasParam("POST", "/nested/{id}", "X-Token")).toBe(false);
+    });
+    test("a body-only name is not a param", () => {
+        expect(nestedSpec().hasParam("POST", "/nested/{id}", "email")).toBe(false);
+    });
+});
+describe("hasHeader: in:header params and response headers", () => {
+    // A header reference is satisfied either by an in:header parameter or by a
+    // response object's headers map.
+    test("in:header parameter matches", () => {
+        expect(nestedSpec().hasHeader("POST", "/nested/{id}", "X-Token")).toBe(true);
+    });
+    test("response headers map entry matches", () => {
+        expect(nestedSpec().hasHeader("POST", "/nested/{id}", "X-Trace")).toBe(true);
+    });
+    test("a body field name is not a header", () => {
+        expect(nestedSpec().hasHeader("POST", "/nested/{id}", "email")).toBe(false);
+    });
+});
+describe("hasBodyField: dotted path reachability in requestBody", () => {
+    // Body field references walk the request schema through $ref chains, allOf
+    // branches, and transparent array-items descent.
+    test("top-level field", () => {
+        expect(nestedSpec().hasBodyField("POST", "/nested/{id}", ["user"])).toBe(true);
+    });
+    test("reachable via $ref chain user -> UserFull(allOf) -> UserBase -> email", () => {
+        expect(nestedSpec().hasBodyField("POST", "/nested/{id}", ["user", "email"])).toBe(true);
+    });
+    test("deep nested user.address.city through $ref and allOf", () => {
+        expect(nestedSpec().hasBodyField("POST", "/nested/{id}", ["user", "address", "city"])).toBe(true);
+    });
+    // tags is an array; its items have a 'name' prop — array items are traversed
+    // without consuming a path segment.
+    test("array-items descent: user.tags.name", () => {
+        expect(nestedSpec().hasBodyField("POST", "/nested/{id}", ["user", "tags", "name"])).toBe(true);
+    });
+    test("bogus nested path is false", () => {
+        expect(nestedSpec().hasBodyField("POST", "/nested/{id}", ["user", "bogus"])).toBe(false);
+    });
+    test("a param-only name is not a body field", () => {
+        expect(nestedSpec().hasBodyField("POST", "/nested/{id}", ["lang"])).toBe(false);
+    });
+    // A self-referential schema must terminate for both a hit and a miss.
+    test("terminates on a $ref cycle (hit and miss)", () => {
+        const cycle = `{
+      "openapi": "3.1.0",
+      "info": {"title":"t","version":"1"},
+      "paths": {
+        "/cycle": {
+          "post": {
+            "requestBody": {
+              "content": {
+                "application/json": {
+                  "schema": {"$ref": "#/components/schemas/SelfRef"}
+                }
+              }
+            },
+            "responses": {"200": {"description": "ok"}}
+          }
+        }
+      },
+      "components": {
+        "schemas": {
+          "SelfRef": {
+            "type": "object",
+            "properties": {
+              "self_id": {"type": "string"},
+              "child":   {"$ref": "#/components/schemas/SelfRef"}
+            }
+          }
+        }
+      }
+    }`;
+        const s = parse(cycle, "cycle.json");
+        expect(s.hasBodyField("POST", "/cycle", ["self_id"])).toBe(true);
+        expect(s.hasBodyField("POST", "/cycle", ["nonexistent"])).toBe(false);
+    });
+});
+describe("hasResponseField: dotted path reachability in any response", () => {
+    test("top-level response field", () => {
+        expect(nestedSpec().hasResponseField("POST", "/nested/{id}", ["result"])).toBe(true);
+    });
+    test("a body-only field is not in the response schema", () => {
+        expect(nestedSpec().hasResponseField("POST", "/nested/{id}", ["email"])).toBe(false);
+    });
+});
+describe("load/parse error semantics", () => {
+    // I/O and parse failures are exceptional (thrown sentinels), unlike domain
+    // results which are returned data.
+    test("missing file throws SpecNotFoundError", async () => {
+        await expect(load(join(tmpdir(), "docgov-apispec-does-not-exist.json"))).rejects.toBeInstanceOf(SpecNotFoundError);
+    });
+    test("malformed syntax throws SpecParseError", () => {
+        expect(() => parse("{not json", "x.json")).toThrow(SpecParseError);
+    });
+    test("a non-object document throws SpecParseError", () => {
+        // YAML accepts a bare scalar; a spec must be a mapping at the top level.
+        expect(() => parse("42", "x.json")).toThrow(SpecParseError);
+    });
+});
+describe("load: reads YAML and JSON from disk", () => {
+    let dir;
+    beforeAll(async () => {
+        dir = await mkdtemp(join(tmpdir(), "docgov-apispec-"));
+    });
+    afterAll(async () => {
+        await rm(dir, { recursive: true, force: true });
+    });
+    // The guard accepts YAML specs too; load must parse YAML equivalently to JSON.
+    test("a YAML spec loads and queries like the JSON fixture", async () => {
+        const yamlSpec = `
+openapi: "3.1.0"
+info:
+  title: y
+  version: "1"
+paths:
+  /y/{id}:
+    get:
+      parameters:
+        - name: id
+          in: path
+      responses:
+        "200":
+          description: ok
+`;
+        const p = join(dir, "spec.yaml");
+        await writeFile(p, yamlSpec, "utf8");
+        const s = await load(p);
+        expect(s.hasOperation("GET", "/y/{anything}")).toBe(true);
+        expect(s.hasParam("GET", "/y/{id}", "id")).toBe(true);
+    });
+});

package/dist/apispec/errors.js

@@ -0,0 +1,17 @@
+// Sentinel error classes thrown by load/parse. These mirror Go's
+// ErrSpecNotFound and ErrSpecParse, which are wrapped exceptional conditions
+// (I/O and parse failures) — not domain results.
+/** Thrown by load when the spec file is not present. */
+export class SpecNotFoundError extends Error {
+    constructor(specPath) {
+        super(`apispec: spec not found: ${JSON.stringify(specPath)}`);
+        this.name = "SpecNotFoundError";
+    }
+}
+/** Thrown by load/parse when the spec file is not valid YAML/JSON (or not an object). */
+export class SpecParseError extends Error {
+    constructor(specPath, detail) {
+        super(`apispec: spec parse error: ${JSON.stringify(specPath)}: ${detail}`);
+        this.name = "SpecParseError";
+    }
+}

package/dist/apispec/index.js

@@ -0,0 +1,2 @@
+export { Spec, normalizePath, parse, load } from "./apispec.js";
+export { SpecNotFoundError, SpecParseError } from "./errors.js";

package/dist/check/doclinks.js

@@ -0,0 +1,167 @@
+// Port of internal/check/run_doclinks.go plus the doc-existence helpers that
+// live at the bottom of internal/check/run.go.
+//
+// The DOC guard: parse markdown, walk the mdast tree collecting every link and
+// image destination, and check each via the existence algorithm — skip external
+// URLs (http/https/mailto…) and pure "#fragment" anchors; reject absolute paths
+// and paths that escape the repo root; otherwise the destination must exist on
+// disk. A "#fragment" appended to a real file path is stripped, and the file is
+// still checked.
+//
+// The Go original walks the goldmark AST; this port walks the mdast tree
+// (remark-parse + remark-gfm). Line numbers come from the node's
+// position.start.line (mdast carries 1-indexed positions on every node), which
+// replaces Go's manual first-Text-descendant offset search and its inline-node
+// Lines() panic workaround.
+import * as posix from "node:path/posix";
+import { parseMarkdown } from "../dedup/mdsection/index.js";
+import { isNotExist } from "../repo/fs.js";
+import { Rules } from "../violation/index.js";
+/**
+ * checkDocLinks parses src as markdown, walks the mdast tree collecting all link
+ * and image destination strings, and checks each via checkDocLink. Line numbers
+ * come from each node's position.start.line.
+ */
+export async function checkDocLinks(file, src, fsys) {
+    const tree = parseMarkdown(src);
+    const vs = [];
+    const targets = [];
+    const visit = (n) => {
+        if (n.type === "link" || n.type === "image") {
+            const dest = n.url ?? "";
+            targets.push({ dest, line: n.position?.start.line ?? 1 });
+        }
+        const children = n.children;
+        if (children !== undefined) {
+            for (const c of children) {
+                visit(c);
+            }
+        }
+    };
+    visit(tree);
+    for (const t of targets) {
+        const v = await checkDocLink(file, t.dest, fsys, t.line);
+        if (v !== null) {
+            vs.push(v);
+        }
+    }
+    return vs;
+}
+/**
+ * runHasURLScheme returns true when target begins with a URL scheme like
+ * "http:", "https:", "mailto:", etc. Mirrors guard/docs.go.
+ */
+function runHasURLScheme(target) {
+    for (let i = 0; i < target.length; i++) {
+        const ch = target[i];
+        if (ch === ":" && i > 0) {
+            return true;
+        }
+        if (!runIsAlphanumOrPlus(ch)) {
+            return false;
+        }
+    }
+    return false;
+}
+function runIsAlphanumOrPlus(ch) {
+    return ((ch >= "a" && ch <= "z") ||
+        (ch >= "A" && ch <= "Z") ||
+        (ch >= "0" && ch <= "9") ||
+        ch === "+" ||
+        ch === "-" ||
+        ch === ".");
+}
+/** runIsPureFragment returns true when target is a bare "#..." reference. */
+function runIsPureFragment(target) {
+    return target.startsWith("#");
+}
+/** runStripFragment removes the #fragment suffix from target, if present. */
+function runStripFragment(target) {
+    const idx = target.indexOf("#");
+    if (idx >= 0) {
+        return target.slice(0, idx);
+    }
+    return target;
+}
+/** runEscapesRoot reports whether a cleaned repo-relative path escapes the root. */
+function runEscapesRoot(cleaned) {
+    return cleaned === ".." || cleaned.startsWith("../");
+}
+/**
+ * statExists reports whether repoRel resolves to an existing file OR directory
+ * on fsys. This mirrors Go's fs.Stat success (which is satisfied by both files
+ * and directories): a link target may legitimately be a directory. A genuinely
+ * missing path returns false; any other I/O fault propagates.
+ */
+async function statExists(fsys, repoRel) {
+    if (repoRel === "." || repoRel === "") {
+        return true; // the root always exists
+    }
+    const segments = repoRel.split("/");
+    const dir = segments.slice(0, -1).join("/");
+    const last = segments[segments.length - 1];
+    let entries;
+    try {
+        entries = await fsys.readDir(dir === "" ? "." : dir);
+    }
+    catch (err) {
+        if (isNotExist(err)) {
+            return false;
+        }
+        throw err;
+    }
+    return entries.some((e) => e.name() === last);
+}
+/**
+ * checkDocLink applies the existence algorithm for one link destination from
+ * file. Returns null when the link passes.
+ */
+async function checkDocLink(file, rawTarget, fsys, line) {
+    let target = rawTarget.trim();
+    if (target === "") {
+        return null;
+    }
+    if (runHasURLScheme(target) || runIsPureFragment(target)) {
+        return null;
+    }
+    target = runStripFragment(target);
+    if (target === "") {
+        return null;
+    }
+    if (posix.isAbsolute(target)) {
+        return {
+            rule: Rules.guardDocs,
+            file,
+            line,
+            sectionID: "",
+            expected: "",
+            actual: target,
+            message: "absolute path is not allowed",
+        };
+    }
+    // path.Clean(path.Join(path.Dir(file), target)) — posix throughout, slash paths.
+    const repoRel = posix.normalize(posix.join(posix.dirname(file), target));
+    if (runEscapesRoot(repoRel)) {
+        return {
+            rule: Rules.guardDocs,
+            file,
+            line,
+            sectionID: "",
+            expected: "",
+            actual: target,
+            message: "path escapes repo root",
+        };
+    }
+    if (!(await statExists(fsys, repoRel))) {
+        return {
+            rule: Rules.guardDocs,
+            file,
+            line,
+            sectionID: "",
+            expected: repoRel,
+            actual: "",
+            message: "referenced file does not exist",
+        };
+    }
+    return null;
+}

package/dist/check/index.js

@@ -0,0 +1,8 @@
+// Public surface of the check package — the guard orchestrator.
+//
+// run() discovers governed scopes from the loaded Config, walks markdown in
+// scope, and runs the code / doc / api guards over the repo, returning the
+// collected violation Records sorted by (file, line).
+export { run } from "./run.js";
+export { iterCodeTokens, iterApiTokens } from "./tokens.js";
+export { checkDocLinks } from "./doclinks.js";