@vantageos/backend-doctor 0.2.0 → 0.4.0

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"}`;
+}