@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/target.js

@@ -0,0 +1,173 @@
+// TARGET RESOLUTION — the run judges the same backend whichever path names it.
+//
+// The defect this closes: the engine's loadTree computes every file's `rel`
+// relative to the path the CLI was given, so the SAME repository produced two
+// different trees under the two documented invocations:
+//   - `backend-doctor <repo>/convex` → rels `messages.ts` (no `convex/` segment)
+//   - `backend-doctor <repo>`        → rels `convex/messages.ts`, PLUS every other
+//     `.ts` file in the repository, including archived copies such as
+//     `_archive-v0.2/<shell>/convex/*.ts` that a `(^|/)convex/` predicate then
+//     judged as live backend source.
+// Detectors keyed on the `convex/` prefix skipped every file in the first form and
+// over-counted in the second; R-36 looked for the lockfile beside `convex/`; CR-1
+// looked for `_generated/api.d.ts` beside the repository root. Measured on vCRM
+// d47a6d4: R-16 2 vs 50 violations, R-6 could-not-judge vs 19 violations.
+//
+// The fix is ONE normalisation at the entry, never a per-detector patch:
+//   repoRoot   nearest ancestor-or-self holding package.json or .git (a `convex`
+//              dir itself is never the repo root, even when it holds a package.json)
+//   convexDir  the `convex` segment the argument names, else <repoRoot>/convex
+//   scanRoots  convexDir and <repoRoot>/mcp-server/src (the two source surfaces the
+//              detectors' own predicates name), each loaded by the ENGINE's loader
+//   rel        relative to repoRoot, so every convex file carries `convex/`
+//   tree.root  repoRoot, so repository co-artifacts (lockfile, workflows) are found
+// Both invocations therefore reduce to the same (repoRoot, convexDir, files) triple.
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { runDoctor } from "@vantageos/mcp-doctor";
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function hasRepoMarker(dir) {
+    return existsSync(join(dir, "package.json")) || existsSync(join(dir, ".git"));
+}
+/** The `convex` dir the argument is (or sits inside), found walking UP from it and
+ * stopping at the first repository marker — so a repository that merely lives
+ * under some `/…/convex/…` host path is never mistaken for a convex dir. */
+function namedConvexDir(p) {
+    for (let dir = p;; dir = dirname(dir)) {
+        if (basename(dir) === "convex")
+            return dir;
+        if (hasRepoMarker(dir) || dirname(dir) === dir)
+            return undefined;
+    }
+}
+/** Resolve a CLI argument to the backend it names. Pure over the filesystem. */
+export function resolveTarget(arg) {
+    const input = resolve(arg);
+    const named = namedConvexDir(input);
+    const start = named ? dirname(named) : input;
+    let repoRoot = start;
+    let repoRootBy = "no marker (argument used as-is)";
+    for (let dir = start;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "package.json"))) {
+            repoRoot = dir;
+            repoRootBy = "package.json";
+            break;
+        }
+        if (existsSync(join(dir, ".git"))) {
+            repoRoot = dir;
+            repoRootBy = ".git";
+            break;
+        }
+        if (dirname(dir) === dir)
+            break;
+    }
+    const convexDir = named && isDir(named)
+        ? named
+        : isDir(join(repoRoot, "convex"))
+            ? join(repoRoot, "convex")
+            : undefined;
+    const scanRoots = [];
+    if (convexDir) {
+        scanRoots.push(convexDir);
+        const mcpSrc = join(repoRoot, "mcp-server", "src");
+        if (isDir(mcpSrc))
+            scanRoots.push(mcpSrc);
+    }
+    else {
+        // No convex dir anywhere: judge exactly what was named, never a guess.
+        scanRoots.push(input);
+    }
+    return { input, repoRoot, repoRootBy, convexDir, scanRoots };
+}
+/** Load one directory through the ENGINE's own loader (never a second traversal
+ * with its own skip list): a capture detector receives the tree runDoctor built. */
+function engineTree(root) {
+    let captured;
+    runDoctor(root, [
+        {
+            id: "target-capture",
+            run: (tree) => {
+                captured = tree;
+                return {
+                    id: "target-capture",
+                    anchor: root,
+                    state: "present",
+                    verdict: "captured",
+                };
+            },
+        },
+    ]);
+    if (captured === undefined) {
+        throw new Error(`backend-doctor: the engine loaded no tree for ${root} — refusing to judge a surface that was never read`);
+    }
+    return captured;
+}
+/** The ONE tree every detector judges: the scan roots' files, `rel` relative to
+ * the repository root, `root` = the repository root. */
+export function loadScopedTree(scope) {
+    const files = [];
+    let packageJson = null;
+    for (const root of scope.scanRoots) {
+        const t = engineTree(root);
+        packageJson ??= t.packageJson;
+        for (const f of t.files) {
+            const rel = relative(scope.repoRoot, f.path);
+            files.push({ ...f, rel: rel === "" ? basename(f.path) : rel });
+        }
+    }
+    return { root: scope.repoRoot, files, packageJson };
+}
+/** Files scanned per top-level directory (two segments under the repo root), so a
+ * reader sees WHAT was judged — an empty or surprising surface is visible. */
+export function coverageInventory(tree) {
+    const inv = new Map();
+    for (const f of tree.files) {
+        const parts = f.rel.split("/");
+        const key = parts.length > 2
+            ? `${parts[0]}/${parts[1]}`
+            : parts.length === 2
+                ? parts[0]
+                : ".";
+        inv.set(key, (inv.get(key) ?? 0) + 1);
+    }
+    return new Map([...inv.entries()].sort((a, b) => a[0].localeCompare(b[0])));
+}
+export function describeScope(scope, tree) {
+    const lines = [
+        `TARGET: ${scope.input}`,
+        `  repo root: ${scope.repoRoot} (by ${scope.repoRootBy})`,
+        `  convex dir: ${scope.convexDir ?? "NONE — no convex/ dir under the repo root; judging the argument as given"}`,
+        `COVERAGE INVENTORY (files scanned per dir, rel to repo root; ${tree.files.length} total):`,
+    ];
+    const inv = coverageInventory(tree);
+    if (inv.size === 0)
+        lines.push("  scanned NOTHING — every source rule below abstains on an empty scan");
+    for (const [dir, n] of inv)
+        lines.push(`  scanned ${dir}: ${n}`);
+    return lines.join("\n");
+}
+/** Wrap detectors so each judges the scoped tree instead of the engine's
+ * per-argument tree. runDoctor still owns the loud-fail contract. */
+export function onScopedTree(tree, detectors) {
+    return detectors.map((d) => ({ ...d, run: () => d.run(tree) }));
+}
+/** Absolute convex dir for a scoped tree (tree.root = repo root) or for a tree
+ * rooted AT a convex dir (direct detector tests). `prefix` is what the tree's
+ * rels carry in front of a convex-relative path. */
+export function convexRootOf(tree) {
+    if (existsSync(join(tree.root, "_generated")) ||
+        basename(tree.root) === "convex") {
+        return { dir: tree.root, prefix: "" };
+    }
+    const dir = join(tree.root, "convex");
+    if (isDir(dir))
+        return { dir, prefix: "convex/" };
+    return { dir: tree.root, prefix: "" };
+}

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