@vantageos/backend-doctor 0.2.0 → 0.3.0

package/dist/rule-class.js

@@ -0,0 +1,218 @@
+// The GATE CLASS of every rule — mechanical or judgement — and the one count the
+// deploy gate refuses on: `mechanical_violations`.
+//
+// The vantage-peers deploy hook (`enforce-backend-doctor-before-deploy.py`) reads
+// `qa/backend-doctor-<sha>.json` and refuses ONLY on mechanical non-conformance,
+// never on a judgement/process rule. This module is where that distinction is made,
+// and it is made from DATA, never from TS logic:
+//
+//   - the per-rule class lives in the sidecar `fixtures/rule-classes-<pin>.json`
+//     (one entry per numbered rule plus CR-1, each with a one-phrase basis);
+//   - every R- entry is CROSS-CHECKED against the pinned standard's own build kind
+//     (the section 15 "Build kind" column, and the `*kind:*` token of a Detector spec
+//     for a rule the table does not list — R-50/R-51), through the sidecar's
+//     `standard_kind_to_class` vocabulary (`process` -> judgement);
+//   - a rule with no entry, an entry outside the two classes, an entry with no
+//     basis, a rule the standard gives no build kind, or a sidecar class that
+//     DISAGREES with the standard is UNCLASSIFIED — a could-not-judge. It is never
+//     defaulted to either class; the count it would feed becomes `null`.
+//
+// COUNT GRANULARITY — by RULE, the same granularity as the TALLY and the VERDICT
+// line: a rule whose reduced state is `non-conforming` is one violation, however
+// many sites it names. CR-1 (doctor-owned, outside the pinned rule set) counts as
+// one rule.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { STANDARD_SHA, VENDORED_STANDARD_PATH } from "./coverage.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export const RULE_CLASS_PATH = join(here, "..", "fixtures", "rule-classes-2825122.json");
+const GATE_CLASSES = new Set(["mechanical", "judgement"]);
+export function loadRuleClassFile(path = RULE_CLASS_PATH) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/**
+ * The build kind the PINNED STANDARD itself states per rule: every row of the
+ * section 15 table (`| R-N | mechanical|judgement|process | … |`), then, for a rule the
+ * table does not list, the `*kind:* <word>` token inside that rule's own text (up
+ * to the next rule definition). A rule the standard classifies nowhere is absent
+ * from the map — classifyRules reports it as unclassified.
+ */
+export function parseStandardKinds(path = VENDORED_STANDARD_PATH) {
+    const blob = readFileSync(path, "utf8");
+    const out = new Map();
+    const start = blob.indexOf("## 15. Build column");
+    if (start !== -1) {
+        const after = blob.indexOf("\n## ", start + 1);
+        const section = blob.slice(start, after === -1 ? undefined : after);
+        for (const line of section.split("\n")) {
+            const m = /^\|\s*(R-\d+)\s*\|\s*(mechanical|judgement|process)\s*\|/.exec(line);
+            if (m)
+                out.set(m[1], m[2]);
+        }
+    }
+    // Detector-spec `*kind:*` for rules outside the table (none at 2825122: the table lists all 52; kept for a future rule defined outside it).
+    const lines = blob.split("\n");
+    let current;
+    for (const line of lines) {
+        const def = /^\*\*(R-\d+)\b/.exec(line);
+        if (def)
+            current = def[1];
+        if (current === undefined || out.has(current))
+            continue;
+        const k = /\*kind:\*\s*(mechanical|judgement|process)\b/.exec(line);
+        if (k)
+            out.set(current, k[1]);
+    }
+    return out;
+}
+/**
+ * Place every id in exactly one class, or name it unclassified with its reason.
+ * `ids` is the derived rule set PLUS the doctor-owned ids (CR-1). An R- id is
+ * cross-checked against the standard; a non-R id (CR-1) is not in the standard and
+ * stands on the sidecar alone.
+ */
+export function classifyRules(ids, file = loadRuleClassFile(), standardKinds = parseStandardKinds(), standardSha = STANDARD_SHA) {
+    const classOf = new Map();
+    const basisOf = new Map();
+    const unclassified = [];
+    const pinMismatch = file.standard_sha !== standardSha
+        ? `sidecar is pinned to standard ${String(file.standard_sha).slice(0, 12)}, the instrument to ${standardSha.slice(0, 12)}`
+        : undefined;
+    for (const id of ids) {
+        if (pinMismatch) {
+            unclassified.push({ id, reason: pinMismatch });
+            continue;
+        }
+        const entry = file.rules?.[id];
+        if (entry === undefined) {
+            unclassified.push({ id, reason: "no class in the sidecar" });
+            continue;
+        }
+        if (!GATE_CLASSES.has(entry.class)) {
+            unclassified.push({
+                id,
+                reason: `sidecar class ${JSON.stringify(entry.class)} is neither mechanical nor judgement`,
+            });
+            continue;
+        }
+        if (typeof entry.basis !== "string" || entry.basis.trim() === "") {
+            unclassified.push({
+                id,
+                reason: "sidecar class carries no basis phrase",
+            });
+            continue;
+        }
+        if (/^R-\d+$/.test(id)) {
+            const kind = standardKinds.get(id);
+            if (kind === undefined) {
+                unclassified.push({
+                    id,
+                    reason: "the pinned standard states no build kind for this rule",
+                });
+                continue;
+            }
+            const expected = file.standard_kind_to_class?.[kind];
+            if (expected !== entry.class) {
+                unclassified.push({
+                    id,
+                    reason: `sidecar says ${entry.class}, the pinned standard says ${kind} (-> ${expected ?? "no mapping"}) — CONFLICT`,
+                });
+                continue;
+            }
+        }
+        classOf.set(id, entry.class);
+        basisOf.set(id, entry.basis);
+    }
+    const wanted = new Set(ids);
+    const stale = Object.keys(file.rules ?? {}).filter((id) => !wanted.has(id));
+    return { classOf, basisOf, unclassified, stale };
+}
+const byRuleId = (a, b) => {
+    const prefix = (s) => s.replace(/\d+$/, "");
+    const n = (s) => Number(/\d+$/.exec(s)?.[0] ?? 0);
+    return prefix(a).localeCompare(prefix(b)) || n(a) - n(b);
+};
+/**
+ * Count the non-conforming rules whose class is mechanical. The count is `null`
+ * — never 0 — when any rule is unclassified (its violation, present or future,
+ * could be mechanical) or when the instrument names a self-defect that voids the
+ * run (`instrumentDefects`, e.g. incomplete coverage or a dirty judged tree).
+ */
+export function countMechanical(ruleState, classification, instrumentDefects = []) {
+    const out = {
+        count: null,
+        mechanicalViolations: [],
+        judgementViolations: [],
+        mechanicalAbstentions: [],
+        judgementAbstentions: [],
+        unclassified: classification.unclassified,
+        cannotCertify: [...instrumentDefects],
+    };
+    const unclassifiedIds = new Set(classification.unclassified.map((u) => u.id));
+    for (const [id, state] of ruleState) {
+        const cls = classification.classOf.get(id);
+        if (cls === undefined) {
+            if (!unclassifiedIds.has(id)) {
+                out.unclassified = [
+                    ...out.unclassified,
+                    {
+                        id,
+                        reason: "a result exists for a rule the classification never saw",
+                    },
+                ];
+                unclassifiedIds.add(id);
+            }
+            continue;
+        }
+        if (state === "non-conforming") {
+            (cls === "mechanical"
+                ? out.mechanicalViolations
+                : out.judgementViolations).push(id);
+        }
+        else if (state === "could-not-judge") {
+            (cls === "mechanical"
+                ? out.mechanicalAbstentions
+                : out.judgementAbstentions).push(id);
+        }
+    }
+    for (const list of [
+        out.mechanicalViolations,
+        out.judgementViolations,
+        out.mechanicalAbstentions,
+        out.judgementAbstentions,
+    ])
+        list.sort(byRuleId);
+    if (out.unclassified.length > 0) {
+        out.cannotCertify.push(`${out.unclassified.length} rule(s) unclassified: ${out.unclassified.map((u) => `${u.id} (${u.reason})`).join("; ")}`);
+    }
+    if (out.cannotCertify.length === 0)
+        out.count = out.mechanicalViolations.length;
+    return out;
+}
+/** The human line printed next to the VERDICT line. */
+export function mechanicalLine(m) {
+    const head = m.count === null
+        ? "MECHANICAL VIOLATIONS: COULD-NOT-JUDGE (no count certified; the evidence file records null)"
+        : `MECHANICAL VIOLATIONS: ${m.count}`;
+    const list = (ids) => (ids.length ? ids.join(", ") : "none");
+    const lines = [
+        `${head} — mechanical [${list(m.mechanicalViolations)}]; judgement violations (printed, not counted) [${list(m.judgementViolations)}]; abstentions (not violations, not 0): mechanical [${list(m.mechanicalAbstentions)}], judgement [${list(m.judgementAbstentions)}]`,
+    ];
+    for (const why of m.cannotCertify)
+        lines.push(`  CANNOT CERTIFY: ${why}`);
+    return lines.join("\n");
+}
+export function buildEvidence(e) {
+    return {
+        sha: e.sha,
+        cli_commit: e.cli_commit,
+        convex_path: e.convex_path,
+        exit_code: e.exit_code,
+        checked: e.checked,
+        total: e.total,
+        mechanical_violations: e.mechanical_violations,
+        mechanical_rule_counts: e.mechanical_rule_counts,
+        mechanical_rule_module_counts: e.mechanical_rule_module_counts,
+    };
+}

package/dist/tally.d.ts

@@ -23,7 +23,7 @@ export interface Verdict {
     exitCode: number;
     /** non-conforming rules bucketed by severity. */
     violations: Record<Severity, string[]>;
-    /** could-not-judge rules bucketed by severity — abstentions, a human owes a verdict. */
+    /** could-not-judge rules bucketed by severity — abstentions: the instrument did not decide, and each names why. A disposition-only abstention is retired (k179jnhx); see the ABSTENTIONS note below for what remains. */
     abstentions: Record<Severity, string[]>;
     /** derived counts the wording turns on. */
     criticalViolations: number;
@@ -40,14 +40,22 @@ export interface Verdict {
  *   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.
+ * ABSTENTIONS: a could-not-judge means the instrument did NOT decide, and says
+ * why. Task k179jnhx retired judgement as an acceptance kind: a rule whose
+ * DISPOSITION used to wait on a person now decides on a written justification
+ * token's PRESENCE. What still abstains is named per rule, never relabelled:
+ * an unreadable input (unparseable file, unreachable tree, absent oracle), a
+ * rule with no detector yet (pinned NOT_MECHANICALLY_CHECKABLE), a population
+ * the source cannot decide statically, or a recorded marker claim the standard
+ * itself sends to a reviewer (R-51's write-contract marker).
+ * Any abstention still 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)
+ *   no hard violation, input unreadable somewhere   -> 2 (not read = never a clean 0)
  *   approve                                         -> 0
  * We cross-check against the engine's computeExitCode and never print "approve"
  * on an exit that means abstention.

package/dist/tally.js

@@ -71,14 +71,22 @@ function emptyBySeverity() {
  *   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.
+ * ABSTENTIONS: a could-not-judge means the instrument did NOT decide, and says
+ * why. Task k179jnhx retired judgement as an acceptance kind: a rule whose
+ * DISPOSITION used to wait on a person now decides on a written justification
+ * token's PRESENCE. What still abstains is named per rule, never relabelled:
+ * an unreadable input (unparseable file, unreachable tree, absent oracle), a
+ * rule with no detector yet (pinned NOT_MECHANICALLY_CHECKABLE), a population
+ * the source cannot decide statically, or a recorded marker claim the standard
+ * itself sends to a reviewer (R-51's write-contract marker).
+ * Any abstention still 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)
+ *   no hard violation, input unreadable somewhere   -> 2 (not read = never a clean 0)
  *   approve                                         -> 0
  * We cross-check against the engine's computeExitCode and never print "approve"
  * on an exit that means abstention.
@@ -113,7 +121,7 @@ export function verdict(t, results, severity = deriveSeverityMap()) {
         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)
+        // no hard violation, but some input could not be READ (critical abstention first)
         outcome = "revise-recommended";
         exitCode = 2;
     }
@@ -125,7 +133,7 @@ export function verdict(t, results, severity = deriveSeverityMap()) {
     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.`
+            ? `${criticalAbstentions} CRITICAL abstention(s) — not decided (each rule names why); approve is blocked.`
             : "no critical violation or abstention.";
     const summary = `VERDICT: ${outcome} (exit ${exitCode}) — ${criticalNote} ` +
         `major violations=${majorViolations}, abstentions=${abstentionTotal} ` +

package/dist/violation-count.d.ts

@@ -0,0 +1,48 @@
+import type { DetectorResult } from "./engine-types.js";
+import type { MechanicalCount } from "./rule-class.js";
+export interface ViolationCount {
+    /** the non-conforming count the verdict line prints. */
+    count: number;
+    /**
+     * per module (see moduleOf) — present for a site-based count, absent for a
+     * row- or finding-based one; the values always sum to `count`.
+     */
+    modules?: Record<string, number>;
+}
+/** Attach `c` to `r` and return `r` (so a producer can `return withCount({...}, c)`). */
+export declare function withCount<R extends DetectorResult>(r: R, c: ViolationCount): R;
+export declare function countOf(r: DetectorResult): ViolationCount | undefined;
+/**
+ * The module a site's file belongs to. A convex/ file is its basename without
+ * extension (`convex/tasks.ts` -> `tasks`, `convex/lib/auth.ts` -> `auth`). A file
+ * outside convex/ (R-53 also reads `mcp-server/src`) keeps its path without
+ * extension (`mcp-server/src/tools.ts` -> `mcp-server/src/tools`): it can never
+ * collide with a convex basename, and every site has a module, so the split
+ * always sums to the count.
+ */
+export declare function moduleOf(rel: string): string;
+/** A site-based count: one item per site, split by module. */
+export declare function siteCount(sites: readonly {
+    rel: string;
+}[]): ViolationCount;
+/** A row- or finding-based count: no file, so no module split. */
+export declare function itemCount(n: number): ViolationCount;
+/** Sum the counts of several non-conforming results of one rule (merged halves). */
+export declare function sumCounts(parts: readonly (ViolationCount | undefined)[]): ViolationCount | undefined;
+export interface MechanicalRuleCounts {
+    /** red mechanical rule id -> its non-conforming count; null when not certifiable. */
+    counts: Record<string, number> | null;
+    /** red mechanical rule id -> module -> count, for site-based rules. */
+    moduleCounts: Record<string, Record<string, number>> | null;
+    /** red mechanical rules with no attached count (the reason `counts` is null). */
+    uncounted: string[];
+}
+/**
+ * One entry per rule in `mech.mechanicalViolations`: the sum of the attached
+ * counts of that rule's non-conforming results (the tally reduces a rule to its
+ * worst result; when several results of a rule are red, each one's items are
+ * printed and counted). Null when `mech.count` is null or any red rule is uncounted.
+ */
+export declare function mechanicalRuleCounts(results: readonly DetectorResult[], mech: MechanicalCount): MechanicalRuleCounts;
+/** The human line printed under MECHANICAL VIOLATIONS. */
+export declare function mechanicalRuleCountsLine(m: MechanicalRuleCounts): string;

package/dist/violation-count.js

@@ -0,0 +1,94 @@
+const COUNTS = new WeakMap();
+/** Attach `c` to `r` and return `r` (so a producer can `return withCount({...}, c)`). */
+export function withCount(r, c) {
+    COUNTS.set(r, c);
+    return r;
+}
+export function countOf(r) {
+    return COUNTS.get(r);
+}
+/**
+ * The module a site's file belongs to. A convex/ file is its basename without
+ * extension (`convex/tasks.ts` -> `tasks`, `convex/lib/auth.ts` -> `auth`). A file
+ * outside convex/ (R-53 also reads `mcp-server/src`) keeps its path without
+ * extension (`mcp-server/src/tools.ts` -> `mcp-server/src/tools`): it can never
+ * collide with a convex basename, and every site has a module, so the split
+ * always sums to the count.
+ */
+export function moduleOf(rel) {
+    const noExt = (p) => p.replace(/\.[^./]+$/, "");
+    if (/(^|\/)convex\//.test(rel))
+        return noExt(rel.split("/").pop() ?? rel);
+    return noExt(rel.replace(/^\.\//, ""));
+}
+/** A site-based count: one item per site, split by module. */
+export function siteCount(sites) {
+    const modules = {};
+    for (const s of sites) {
+        const m = moduleOf(s.rel);
+        modules[m] = (modules[m] ?? 0) + 1;
+    }
+    return { count: sites.length, modules: sortKeys(modules) };
+}
+/** A row- or finding-based count: no file, so no module split. */
+export function itemCount(n) {
+    return { count: n };
+}
+/** Sum the counts of several non-conforming results of one rule (merged halves). */
+export function sumCounts(parts) {
+    if (parts.length === 0 || parts.some((p) => p === undefined))
+        return undefined;
+    let count = 0;
+    let modules = {};
+    for (const p of parts) {
+        count += p.count;
+        if (p.modules === undefined || modules === undefined)
+            modules = undefined;
+        else
+            for (const [k, v] of Object.entries(p.modules))
+                modules[k] = (modules[k] ?? 0) + v;
+    }
+    return modules === undefined
+        ? { count }
+        : { count, modules: sortKeys(modules) };
+}
+function sortKeys(o) {
+    return Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
+}
+const ruleOf = (r) => /^((?:R|CR)-\d+)\b/.exec(r.id)?.[1];
+/**
+ * One entry per rule in `mech.mechanicalViolations`: the sum of the attached
+ * counts of that rule's non-conforming results (the tally reduces a rule to its
+ * worst result; when several results of a rule are red, each one's items are
+ * printed and counted). Null when `mech.count` is null or any red rule is uncounted.
+ */
+export function mechanicalRuleCounts(results, mech) {
+    if (mech.count === null)
+        return { counts: null, moduleCounts: null, uncounted: [] };
+    const counts = {};
+    const moduleCounts = {};
+    const uncounted = [];
+    for (const id of mech.mechanicalViolations) {
+        const red = results.filter((r) => ruleOf(r) === id && r.state === "non-conforming");
+        const c = sumCounts(red.map(countOf));
+        if (c === undefined) {
+            uncounted.push(id);
+            continue;
+        }
+        counts[id] = c.count;
+        if (c.modules !== undefined)
+            moduleCounts[id] = c.modules;
+    }
+    if (uncounted.length > 0)
+        return { counts: null, moduleCounts: null, uncounted };
+    return { counts, moduleCounts, uncounted };
+}
+/** The human line printed under MECHANICAL VIOLATIONS. */
+export function mechanicalRuleCountsLine(m) {
+    if (m.counts === null)
+        return m.uncounted.length > 0
+            ? `MECHANICAL RULE COUNTS: COULD-NOT-JUDGE — no count attached for ${m.uncounted.join(", ")} (the evidence file records null)`
+            : "MECHANICAL RULE COUNTS: COULD-NOT-JUDGE (the mechanical count is not certified; the evidence file records null)";
+    const entries = Object.entries(m.counts);
+    return `MECHANICAL RULE COUNTS: ${entries.length ? entries.map(([id, n]) => `${id} ${n}`).join(", ") : "none"}`;
+}