@vantageos/backend-doctor 0.1.0

package/dist/tally.js

@@ -0,0 +1,152 @@
+// The machine TALLY + the severity-mapped VERDICT. This closes the eyeballed-
+// distribution defect (k1790pj53tx4djwfrkhq8v5kp58cn4mh): no human ever counts
+// rows again. Two prior hand-typed distributions (57/40/16/2, 69/60/17/4) were
+// both wrong — the tally is DERIVED here, never typed.
+//
+// TALLY GRANULARITY — the printed tally is over RULES, not over RESULTS. Some
+// rules emit more than one DetectorResult (oracle per-row predicates reduced to
+// one result today, and live/static halves in later waves); the rule-level state
+// is the WORST state across that rule's results (non-conforming > could-not-judge
+// > absent > present), because that is what maps to a verdict. The CLI prints the
+// result count too, so the two numbers are never confused.
+import { computeExitCode } from "@vantageos/mcp-doctor";
+import { deriveRuleIds } from "./coverage.js";
+import { deriveSeverityMap } from "./severity.js";
+/** The four states, in worst-first order — the reduction picks the worst. */
+const STATE_RANK = {
+    "non-conforming": 3,
+    "could-not-judge": 2,
+    absent: 1,
+    present: 0,
+};
+const ALL_STATES = ["present", "non-conforming", "could-not-judge", "absent"];
+/** Extract the ruleId (`R-N`) a result belongs to, from its leading id token. */
+export function ruleIdOf(result) {
+    const m = /^(R-\d+)\b/.exec(result.id);
+    if (!m)
+        throw new Error(`ruleIdOf: result id ${JSON.stringify(result.id)} carries no R-N tag`);
+    return m[1];
+}
+/**
+ * Reduce the engine's DetectorResults to a rule-level tally. Asserts the four
+ * state counts sum to the rule total (the derive-never-type invariant) and that
+ * every rule the standard defines is present in the results.
+ */
+export function tally(results, ruleIds = deriveRuleIds()) {
+    const ruleState = new Map();
+    for (const r of results) {
+        const id = ruleIdOf(r);
+        const prev = ruleState.get(id);
+        if (prev === undefined || STATE_RANK[r.state] > STATE_RANK[prev])
+            ruleState.set(id, r.state);
+    }
+    const byState = {
+        present: 0,
+        "non-conforming": 0,
+        "could-not-judge": 0,
+        absent: 0,
+    };
+    for (const s of ruleState.values())
+        byState[s] += 1;
+    const ruleTotal = ruleState.size;
+    const sum = ALL_STATES.reduce((a, s) => a + byState[s], 0);
+    if (sum !== ruleTotal) {
+        throw new Error(`tally: state counts ${JSON.stringify(byState)} sum ${sum} != rule total ${ruleTotal}`);
+    }
+    const missing = ruleIds.filter((id) => !ruleState.has(id));
+    if (missing.length > 0) {
+        throw new Error(`tally: rules in the standard with no result: ${missing.join(", ")}`);
+    }
+    if (ruleTotal !== ruleIds.length) {
+        throw new Error(`tally: ${ruleTotal} rules tallied != ${ruleIds.length} derived rules`);
+    }
+    return { byState, ruleTotal, resultTotal: results.length, ruleState };
+}
+function emptyBySeverity() {
+    return { critical: [], "major-high": [], major: [], minor: [] };
+}
+/**
+ * Map the tally to react-doctor's verdict shape, severity DERIVED from the
+ * standard. Verdict rules (major = major-high + major combined for the gate):
+ *   0 critical + 0 major violations                 -> approve
+ *   0 critical + 1..5 major violations              -> revise recommended
+ *   0 critical + >5 major violations                -> revise mandatory
+ *   >=1 critical violation                          -> revise mandatory (NO bypass)
+ * ABSTENTIONS: a could-not-judge is a human verdict owed. Any abstention blocks
+ * "approve" (the outcome becomes at least revise-recommended); an abstention on a
+ * CRITICAL rule can never be silently approved and is reported first.
+ *
+ * EXIT CODE preserves the engine's honesty:
+ *   >=1 critical OR revise-mandatory                -> 1 (a violation IS wrong)
+ *   1..5 major violations (revise-recommended)      -> 1 (hard violations exist)
+ *   no hard violation, abstention owed              -> 2 (not looked = never a clean 0)
+ *   approve                                         -> 0
+ * We cross-check against the engine's computeExitCode and never print "approve"
+ * on an exit that means abstention.
+ */
+export function verdict(t, results, severity = deriveSeverityMap()) {
+    const violations = emptyBySeverity();
+    const abstentions = emptyBySeverity();
+    for (const [ruleId, state] of t.ruleState) {
+        const sev = severity.get(ruleId);
+        if (sev === undefined)
+            throw new Error(`verdict: no severity for ${ruleId} — severity map incomplete`);
+        if (state === "non-conforming")
+            violations[sev].push(ruleId);
+        else if (state === "could-not-judge")
+            abstentions[sev].push(ruleId);
+    }
+    const criticalViolations = violations.critical.length;
+    const majorViolations = violations["major-high"].length + violations.major.length;
+    const criticalAbstentions = abstentions.critical.length;
+    const abstentionTotal = abstentions.critical.length +
+        abstentions["major-high"].length +
+        abstentions.major.length +
+        abstentions.minor.length;
+    let outcome;
+    let exitCode;
+    if (criticalViolations >= 1 || majorViolations > 5) {
+        outcome = "revise-mandatory";
+        exitCode = 1;
+    }
+    else if (majorViolations >= 1) {
+        outcome = "revise-recommended";
+        exitCode = 1; // hard violations present — a caller must not read a clean 0
+    }
+    else if (abstentionTotal > 0) {
+        // no hard violation, but a human verdict is owed (critical abstention first)
+        outcome = "revise-recommended";
+        exitCode = 2;
+    }
+    else {
+        outcome = "approve";
+        exitCode = 0;
+    }
+    const engineExitCode = computeExitCode(results);
+    const criticalNote = criticalViolations > 0
+        ? `${criticalViolations} CRITICAL violation(s) — revise mandatory, NO bypass.`
+        : criticalAbstentions > 0
+            ? `${criticalAbstentions} CRITICAL abstention(s) — a human verdict is owed; approve is blocked.`
+            : "no critical violation or abstention.";
+    const summary = `VERDICT: ${outcome} (exit ${exitCode}) — ${criticalNote} ` +
+        `major violations=${majorViolations}, abstentions=${abstentionTotal} ` +
+        `(critical=${criticalAbstentions}). engine exit=${engineExitCode}.`;
+    return {
+        outcome,
+        exitCode,
+        violations,
+        abstentions,
+        criticalViolations,
+        majorViolations,
+        criticalAbstentions,
+        engineExitCode,
+        summary,
+    };
+}
+/** The one-line machine tally string the CLI prints. */
+export function tallyLine(t) {
+    return (`TALLY (by rule, ${t.ruleTotal} rules from ${t.resultTotal} results): ` +
+        `present=${t.byState.present} non-conforming=${t.byState["non-conforming"]} ` +
+        `could-not-judge=${t.byState["could-not-judge"]} absent=${t.byState.absent} ` +
+        `| sum=${t.byState.present + t.byState["non-conforming"] + t.byState["could-not-judge"] + t.byState.absent} == ${t.ruleTotal}`);
+}

package/dist/trigger.d.ts

@@ -0,0 +1,47 @@
+export declare const REFERENCE_WORKFLOW_REL = ".github/reference/backend-doctor.reference.yml";
+/**
+ * A gitignore/GitHub-Actions style path filter. `include` are the backend-path
+ * shapes that MUST trigger a run; `exclude` are carve-outs that must NOT (a
+ * test-only, generated, or docs diff under an included tree). GitHub Actions
+ * `paths:` supports `!` negation, so this exact shape renders 1:1 into a workflow.
+ */
+export interface PathFilter {
+    include: string[];
+    exclude: string[];
+}
+/**
+ * THE glob set — derived from the real Convex backend layout above. Each entry
+ * carries the shape it encodes so a reader can see nothing is accidental.
+ */
+export declare const BACKEND_PATH_FILTER: PathFilter;
+/**
+ * Convert a GitHub-Actions/gitignore-style glob to an anchored RegExp.
+ *   `**` matches any characters including `/` (crosses directories).
+ *   `*`  matches any characters except `/` (within a single segment).
+ *   `?`  matches a single character except `/`.
+ * Everything else is matched literally.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+/**
+ * The core decision: does `path` count as a backend change under `filter`?
+ * A path fires iff it matches an include glob AND no exclude glob.
+ */
+export declare function pathIsBackend(path: string, filter?: PathFilter): boolean;
+/**
+ * THE TRIGGER. Given the changed paths of a diff (e.g. `git diff --name-only`),
+ * decide whether backend-doctor must run.
+ *
+ * NEUTER GUARD: an empty include set is a vacuous matcher — it would fire on
+ * NOTHING (or, in the mirror disease, a "match everything" default fires on ALL
+ * paths). Either is the same bug as a scope returning empty. We throw loudly
+ * rather than silently degrade, so a broken filter is a RED test, never a
+ * cron-with-extra-steps or a rubber-stamp.
+ */
+export declare function shouldRun(changedPaths: string[], filter?: PathFilter): boolean;
+/**
+ * Render the shared glob set as a GitHub Actions `paths:` YAML block (2-space
+ * child indent under `paths:`). The reference workflow embeds the OUTPUT of this
+ * shape so the workflow filter and the matcher can never drift — one source.
+ * Excludes are emitted as `!`-negated entries, which GitHub `paths:` honours.
+ */
+export declare function renderWorkflowPaths(filter?: PathFilter, indent?: string): string;

package/dist/trigger.js

@@ -0,0 +1,143 @@
+// D6 — THE PATH-TRIGGER. Decides, given a list of changed paths, whether
+// backend-doctor MUST run. The backend-path shapes are DERIVED from what a
+// Convex backend actually IS (grounded against the real /root/coding/vantage-memory
+// layout, read-only):
+//
+//   SHAPE (a) SCHEMA      — convex/schema.ts (the defineSchema file).
+//   SHAPE (b) FUNCTION    — convex/**/*.ts queries/mutations/actions (e.g.
+//                           convex/tasks.ts, convex/http.ts, convex/lib/*.ts).
+//   SHAPE (c) INDEX       — index definitions are `defineTable(...).index(...)`
+//                           calls that live INSIDE the schema file (108 of them
+//                           in VP's convex/schema.ts). So an index change IS a
+//                           schema-file change — covered by shape (a)'s glob.
+//   SHAPE (d) DEPLOY CFG  — convex.json (when present), package.json (the convex
+//                           deploy scripts / convex dependency), and the Convex
+//                           deploy/test workflows under .github/workflows
+//                           (VP ships .github/workflows/vitest-convex.yml).
+//
+// ONE SOURCE OF TRUTH: BACKEND_PATH_FILTER below is the ONLY place the globs
+// live. src/trigger.ts (this matcher) and the reference workflow both derive
+// their path filter from it — a path moving here moves BOTH (the workflow's
+// `paths:` block is generated by renderWorkflowPaths()). A matcher and a
+// workflow filter that drift is the skew defect; sharing the source closes it.
+//
+// The reference workflow lives OUTSIDE .github/workflows/ (GitHub Actions runs
+// everything under that directory regardless of a file's own "not installed"
+// header — PR #8). Its path is a constant HERE, so a test that reads it resolves
+// the path from one place rather than typing the literal a second time (which is
+// exactly the skew that broke when the file moved).
+export const REFERENCE_WORKFLOW_REL = ".github/reference/backend-doctor.reference.yml";
+/**
+ * THE glob set — derived from the real Convex backend layout above. Each entry
+ * carries the shape it encodes so a reader can see nothing is accidental.
+ */
+export const BACKEND_PATH_FILTER = {
+    include: [
+        // SHAPE (a) SCHEMA — explicit even though convex/** covers it, so the
+        // schema shape is visible; SHAPE (c) INDEX rides on this file.
+        "convex/schema.ts",
+        // SHAPE (b) FUNCTION — every query/mutation/action file, nested too.
+        "convex/**",
+        // SHAPE (d) DEPLOY CFG — convex project config (when present) + the npm
+        // manifest that carries the convex dependency and deploy scripts.
+        "convex.json",
+        "package.json",
+        // SHAPE (d) DEPLOY CFG — the Convex deploy / test workflows.
+        ".github/workflows/*convex*.yml",
+        ".github/workflows/*deploy*.yml",
+    ],
+    exclude: [
+        // A test-only diff under convex/ does not change the deployed backend.
+        "convex/**/*.test.ts",
+        // Convex codegen output is derived, never hand-edited.
+        "convex/_generated/**",
+        // A docs-only file living under convex/ is not a backend change.
+        "convex/**/*.md",
+    ],
+};
+/**
+ * Convert a GitHub-Actions/gitignore-style glob to an anchored RegExp.
+ *   `**` matches any characters including `/` (crosses directories).
+ *   `*`  matches any characters except `/` (within a single segment).
+ *   `?`  matches a single character except `/`.
+ * Everything else is matched literally.
+ */
+export function globToRegExp(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                // `**/` matches zero or more directory segments (so `convex/**/*.md`
+                // also matches `convex/README.md`); a bare `**` matches anything.
+                if (glob[i + 2] === "/") {
+                    out += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    out += ".*";
+                    i++;
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else if ("\\^$.|+()[]{}".includes(c)) {
+            out += `\\${c}`;
+        }
+        else {
+            out += c;
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+/** Normalise a path: strip a leading `./` and any leading `/`. */
+function normalise(p) {
+    return p.replace(/^\.\//, "").replace(/^\/+/, "");
+}
+/** Does a single path match any glob in the list? */
+function matchesAny(path, globs) {
+    return globs.some((g) => globToRegExp(g).test(path));
+}
+/**
+ * The core decision: does `path` count as a backend change under `filter`?
+ * A path fires iff it matches an include glob AND no exclude glob.
+ */
+export function pathIsBackend(path, filter = BACKEND_PATH_FILTER) {
+    const p = normalise(path);
+    return matchesAny(p, filter.include) && !matchesAny(p, filter.exclude);
+}
+/**
+ * THE TRIGGER. Given the changed paths of a diff (e.g. `git diff --name-only`),
+ * decide whether backend-doctor must run.
+ *
+ * NEUTER GUARD: an empty include set is a vacuous matcher — it would fire on
+ * NOTHING (or, in the mirror disease, a "match everything" default fires on ALL
+ * paths). Either is the same bug as a scope returning empty. We throw loudly
+ * rather than silently degrade, so a broken filter is a RED test, never a
+ * cron-with-extra-steps or a rubber-stamp.
+ */
+export function shouldRun(changedPaths, filter = BACKEND_PATH_FILTER) {
+    if (!filter.include || filter.include.length === 0) {
+        throw new Error("shouldRun: BACKEND_PATH_FILTER.include is EMPTY — a vacuous matcher would " +
+            "never fire (or, mirrored, fire on everything). Refusing to run a filter with no backend shapes.");
+    }
+    return changedPaths.some((p) => pathIsBackend(p, filter));
+}
+/**
+ * Render the shared glob set as a GitHub Actions `paths:` YAML block (2-space
+ * child indent under `paths:`). The reference workflow embeds the OUTPUT of this
+ * shape so the workflow filter and the matcher can never drift — one source.
+ * Excludes are emitted as `!`-negated entries, which GitHub `paths:` honours.
+ */
+export function renderWorkflowPaths(filter = BACKEND_PATH_FILTER, indent = "      ") {
+    const lines = [
+        ...filter.include.map((g) => `${indent}- "${g}"`),
+        ...filter.exclude.map((g) => `${indent}- "!${g}"`),
+    ];
+    return lines.join("\n");
+}