@vantageos/backend-doctor 0.1.0

package/dist/detectors/standard/r41-frontier.js

@@ -0,0 +1,176 @@
+// R-41 — the ONE fully-mechanical rule of the nine: no human half. §18:
+// "every cited `S-`/`C-` frontier identifier resolves in the sibling document
+// (static, cross-document)." Prose (R-41): "every frontier statement names its
+// MCP sibling by identifier, and that identifier resolves in the sibling
+// document ... a frontier that names a sibling which does not exist in the
+// merged MCP standard is a dead pointer ... A dead pointer is a red, not a note."
+//
+// Unlike the four STANDARD-DOCUMENT detectors (which carry a delivery-gate/human
+// half and therefore return could-not-judge naming the sites a verdict is owed),
+// R-41 is DECIDABLE end-to-end from static text: it EXTRACTS every `S-`/`C-`/`E-`
+// /`A-` identifier CITED in the backend standard's §9 frontier statements, and
+// RESOLVES each against the DEFINED-id set of its sibling MCP-family document.
+//   - non-conforming — any cited id that does NOT resolve (a dead pointer).
+//   - present — every cited id resolves.
+// Never could-not-judge (no human half) UNLESS an input document is absent.
+//
+// THE DEFINITION FORM (the trap): ids are DEFINED as a NUMBERED LIST ITEM, never
+// a markdown heading — `8. **`S-8` — <title>.**`. A heading-anchored matcher
+// finds ZERO definitions while the ids appear in coverage tables — the exact
+// shape that reads as "cited but never defined". The enumerator matches the
+// numbered-item form. Independent enumeration reproduces S-27 + C-22 + E-6 + A-7
+// = 62 defined ids. The cited-id list is DERIVED from the real frontier text —
+// never hardcoded.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readStandard, STANDARD_FILE, toLines } from "./_doc.js";
+/** prefix → { the sibling fixture basename, its recorded upstream blob hash }.
+ * The blob hash is the PINS.txt record — a vendored document that cannot be
+ * hash-checked is an authority granted to oneself, so the hash travels here and
+ * the integrity test asserts `git hash-object` reproduces it. */
+export const SIBLING = {
+    S: {
+        file: "mcp-server-standard-a74a042b.md",
+        blob: "4f2c4caf95863f94657ac95b56d7149b2ed491bb",
+        label: "MCP server standard",
+    },
+    C: {
+        file: "mcp-standard-a74a042b.md",
+        blob: "94158d8923974be81c40a1e76ff60d5825474d08",
+        label: "MCP standard (trunk)",
+    },
+    E: {
+        file: "mcp-extension-standard-a74a042b.md",
+        blob: "40f7911af26bb2b99bfcf06026a270f739b3396c",
+        label: "MCP extension standard",
+    },
+    A: {
+        file: "mcp-app-standard-a74a042b.md",
+        blob: "1815e1d0dfd7d472704b7dea9e9d17537b3431f1",
+        label: "MCP App standard",
+    },
+};
+/** The pin all four siblings are fixed against. */
+export const SIBLING_PIN = "the four MCP-standard-family documents @ a74a042b53c71a095ab88b3073bd47728eeda814 (elpiarthera/ElPi-Corp) — S-/C-/E-/A- defined-id sets";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = join(HERE, "..", "..", "..", "fixtures");
+/** Absolute path of a sibling fixture. */
+export function siblingPath(prefix) {
+    return join(FIXTURES, SIBLING[prefix].file);
+}
+/** Read a sibling document's raw text. Injectable for tests (mutation bite). */
+export function readSibling(prefix) {
+    return readFileSync(siblingPath(prefix), "utf8");
+}
+/**
+ * Every id a sibling document DEFINES — matched by the NUMBERED-LIST-ITEM form
+ * `N. **`X-N` — title.**` (a heading- or `^\*\*`-anchored matcher finds zero).
+ * Returns the set for whatever prefix the file defines; the resolver only ever
+ * asks a file for its own prefix, so a single form suffices.
+ */
+export function definedIds(text) {
+    const ids = new Set();
+    for (const raw of text.split("\n")) {
+        const m = /^\d+\.\s+\*\*`?([SCEA]-\d+)`?/.exec(raw);
+        if (m)
+            ids.add(m[1]);
+    }
+    return ids;
+}
+/**
+ * Every `S-`/`C-`/`E-`/`A-` identifier CITED in a frontier statement of the
+ * backend standard — DERIVED from the real text by matching the citation form
+ * (a backtick-wrapped id on a line that opens `Frontier — MCP standard.`), never
+ * hardcoded. Deduped per id, keeping the first citing line as its site.
+ */
+export function citedIds(lines) {
+    const seen = new Set();
+    const out = [];
+    for (const l of lines) {
+        if (!/Frontier — MCP standard/.test(l.raw))
+            continue;
+        for (const m of l.raw.matchAll(/`([SCEA]-\d+)`/g)) {
+            const id = m[1];
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            out.push({ id, prefix: id[0], n: l.n });
+        }
+    }
+    return out;
+}
+/** Resolve every cited frontier id against its sibling's defined-id set.
+ * `standardText` and `siblingReader` are injectable for the mutation bite. */
+export function resolveFrontier(standardText = readStandard(), siblingReader = readSibling) {
+    const cited = citedIds(toLines(standardText));
+    const defined = {
+        S: definedIds(siblingReader("S")),
+        C: definedIds(siblingReader("C")),
+        E: definedIds(siblingReader("E")),
+        A: definedIds(siblingReader("A")),
+    };
+    const dead = [];
+    const resolved = [];
+    for (const c of cited) {
+        if (defined[c.prefix].has(c.id))
+            resolved.push(c);
+        else
+            dead.push(c);
+    }
+    return {
+        cited,
+        dead,
+        resolved,
+        definedCounts: {
+            S: defined.S.size,
+            C: defined.C.size,
+            E: defined.E.size,
+            A: defined.A.size,
+        },
+    };
+}
+const R41_ID = "R-41 every cited frontier id resolves in its MCP sibling";
+const R41_CHECK = "every `S-`/`C-`/`E-`/`A-` id cited in a §9 frontier statement resolves in its sibling MCP-family document (static, cross-document)";
+/** Build R-41's single DetectorResult from a resolution. Present when every
+ * cited id resolves; non-conforming on any dead pointer (a red, not a note);
+ * could-not-judge ONLY if an input yields no cited/defined ids at all (an
+ * absent input, not a clean bill). */
+export function decideR41(r) {
+    const site = (c) => `${STANDARD_FILE}:${c.n}`;
+    const counts = `defined[S=${r.definedCounts.S} C=${r.definedCounts.C} E=${r.definedCounts.E} A=${r.definedCounts.A}]`;
+    const citedList = r.cited.map((c) => `${c.id}@${site(c)}`).join("; ");
+    if (r.cited.length === 0) {
+        const reason = `R-41: no §9 frontier statement cited any S-/C-/E-/A- identifier in the vendored standard — the cross-document input is absent. NOT a clean bill.`;
+        return {
+            id: R41_ID,
+            anchor: `${STANDARD_FILE}:0`,
+            state: "could-not-judge",
+            verdict: reason,
+            reason,
+        };
+    }
+    if (r.dead.length > 0) {
+        const deadList = r.dead
+            .map((c) => `${c.id} (cited ${site(c)}) not defined in ${SIBLING[c.prefix].file}`)
+            .join("; ");
+        return {
+            id: R41_ID,
+            anchor: site(r.dead[0]),
+            state: "non-conforming",
+            verdict: `R-41: ${r.dead.length} DEAD POINTER(S) — a cited frontier id resolves to no definition in its sibling (a dead pointer is a red, not a note). ${counts} Dead: ${deadList}. Cited: ${citedList}.`,
+        };
+    }
+    return {
+        id: R41_ID,
+        anchor: site(r.cited[0]),
+        state: "present",
+        verdict: `R-41: all ${r.cited.length} cited frontier id(s) resolve in their sibling MCP-family document (${R41_CHECK}). ${counts} Sites: ${citedList}.`,
+    };
+}
+/** The R-41 detector — ignores the tree; reads the vendored standard + the four
+ * vendored siblings. Fully mechanical, no human half. */
+export const R41 = {
+    id: R41_ID,
+    run: () => decideR41(resolveFrontier()),
+};

package/dist/detectors/standard/r46-returns-validator.d.ts

@@ -0,0 +1,61 @@
+import type { Detector, DetectorResult, Tree } from "../../engine-types.js";
+/** The standard this detector is pinned against (the re-pinned instrument pin). */
+export declare const R46_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A716 R-46";
+type SrcFile = Tree["files"][number];
+/** A registrable entry — structurally mirrors registry.ts's RegistryEntry so the
+ * orchestrator owns the integration; we do NOT import registry.ts. */
+export interface StandardSourceDetectorEntry {
+    detector: Detector;
+    ruleId: string;
+    standardPin: string;
+}
+export declare function fileText(f: SrcFile): string;
+export declare function deriveSchemaFields(schemaText: string): Map<string, Set<string>>;
+export interface DocValidatorMatch {
+    exportName: string;
+    /** local const identifier that held this object literal, if any (disambiguates
+     * multiple document shapes from one export, e.g. a fields=lite|full union). */
+    alias: string | undefined;
+    table: string;
+    declaredKeys: Set<string>;
+    /** 1-based line of the v.object literal — the anchor. */
+    line: number;
+    /** 1-based line span of the enclosing export — where a projection reason lives. */
+    exportStartLine: number;
+    exportEndLine: number;
+}
+export declare function extractDocMatches(name: string, text: string): DocValidatorMatch[];
+export declare function projectionReason(rawLines: string[], startLine: number, endLine: number): string | undefined;
+export type Status = "COVERS" | "PROJECTION" | "MISSING";
+export interface InventoryEntry {
+    rel: string;
+    line: number;
+    label: string;
+    table: string;
+    status: Status;
+    missing: string[];
+    reason?: string;
+}
+export interface ParseFinding {
+    rel: string;
+    line: number;
+    note: string;
+}
+export interface Coverage {
+    inventory: InventoryEntry[];
+    /** files that could not be parsed / a validator whose table is not in schema. */
+    findings: ParseFinding[];
+    /** true iff a schema.ts was found and yielded at least one table. */
+    schemaFound: boolean;
+}
+/** Classify every document-returning validator in the target tree against the
+ * schema the target itself declares. */
+export declare function scanR46(files: SrcFile[]): Coverage;
+export declare function decideR46(cov: Coverage): DetectorResult;
+/** The R-46 detector — reads the TARGET tree the engine hands it (never the
+ * vendored standard, never the filesystem directly), derives the field set from
+ * that target's schema, and classifies every document-returning validator. */
+export declare const R46: Detector;
+/** In a form the orchestrator spreads into REGISTRY. */
+export declare const STANDARD_SOURCE_DETECTORS: StandardSourceDetectorEntry[];
+export {};