@orangepro/orangepro-mcp 0.1.0

package/dist/local/score/risk.js

@@ -0,0 +1,362 @@
+import { execFileSync } from "node:child_process";
+const ENTRY_PATH_RE = /(^|\/)(routes?|controllers?|handlers?|jobs?|workers?|processors?|queues?|consumers?|subscribers?|listeners?|server|cmd)\//i;
+const ENTRY_FILE_RE = /(^|\/)[^/]*(controller|handler|route|router|job|processor|worker|queue|consumer|subscriber|listener|command|gateway)\.[^.\/]+$/i;
+const API_HANDLER_NAME_RE = /^(GET|POST|PUT|PATCH|DELETE|handle.*|handler|route|controller|endpoint)$/i;
+const ENTRY_NAME_RE = /(^|[.#])(main|serve|request|endpoint)/i;
+function symbolFile(n) {
+    if (typeof n.properties.file === "string")
+        return n.properties.file;
+    return n.external_id.replace(/^sym:/, "").split("#")[0];
+}
+function symbolTitle(n) {
+    return n.title ?? n.external_id.split("#")[1] ?? n.external_id;
+}
+function confirmedBehaviorIds(graph) {
+    const ids = new Set();
+    const nodeKinds = new Map(graph.nodes.map((n) => [n.external_id, n.kind]));
+    for (const e of graph.edges) {
+        if (e.evidence_strength !== "hard")
+            continue;
+        if (e.relationship_type !== "TESTED_BY" && e.relationship_type !== "COVERS")
+            continue;
+        if (nodeKinds.get(e.from_external_id) === "CodeSymbol" || nodeKinds.get(e.from_external_id) === "Requirement")
+            ids.add(e.from_external_id);
+        if (nodeKinds.get(e.to_external_id) === "CodeSymbol" || nodeKinds.get(e.to_external_id) === "Requirement")
+            ids.add(e.to_external_id);
+    }
+    return ids;
+}
+const GIT_CHURN_BATCH = 200;
+function gitChurn(root, files, window) {
+    const out = new Map();
+    if (!root || files.length === 0)
+        return out;
+    for (let i = 0; i < files.length; i += GIT_CHURN_BATCH) {
+        const batch = files.slice(i, i + GIT_CHURN_BATCH);
+        try {
+            const stdout = execFileSync("git", ["log", `--since=${window}`, "--numstat", "--", ...batch], {
+                cwd: root,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 4000,
+                maxBuffer: 2_000_000
+            });
+            for (const line of stdout.split("\n")) {
+                const m = line.match(/^(\d+|-)\s+(\d+|-)\s+(.+)$/);
+                if (!m)
+                    continue;
+                const adds = m[1] === "-" ? 0 : Number(m[1]);
+                const dels = m[2] === "-" ? 0 : Number(m[2]);
+                out.set(m[3], (out.get(m[3]) ?? 0) + adds + dels);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+function gitFirstCommitBatch(root, files) {
+    const out = new Map();
+    if (!root || files.length === 0)
+        return out;
+    for (let i = 0; i < files.length; i += GIT_CHURN_BATCH) {
+        const batch = files.slice(i, i + GIT_CHURN_BATCH);
+        try {
+            const stdout = execFileSync("git", ["log", "--diff-filter=A", "--reverse", "--format=format:%ct", "--name-only", "--", ...batch], {
+                cwd: root,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 4000,
+                maxBuffer: 2_000_000
+            });
+            let currentTs = 0;
+            for (const line of stdout.split("\n")) {
+                const trimmed = line.trim();
+                if (trimmed === "") {
+                    currentTs = 0;
+                    continue;
+                }
+                const ts = Number(trimmed);
+                if (!Number.isNaN(ts) && String(ts) === trimmed) {
+                    currentTs = ts;
+                    continue;
+                }
+                if (currentTs > 0 && !out.has(trimmed)) {
+                    out.set(trimmed, currentTs);
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+function countOutgoingCalls(symbolId, graph) {
+    const targets = new Set();
+    for (const e of graph.edges) {
+        if (e.relationship_type === "CALLS" && e.from_external_id === symbolId) {
+            targets.add(e.to_external_id);
+        }
+    }
+    return targets.size;
+}
+function isEntryPoint(node) {
+    const file = symbolFile(node);
+    const title = symbolTitle(node);
+    if (API_HANDLER_NAME_RE.test(title) && /(^|\/)api(s)?\//i.test(file))
+        return true;
+    return ENTRY_PATH_RE.test(file) || ENTRY_FILE_RE.test(file) || ENTRY_NAME_RE.test(`${file}#${title}`);
+}
+function isHttpRouteSymbol(node) {
+    return /^(GET|POST|PUT|PATCH|DELETE)$/i.test(symbolTitle(node)) && /(^|\/)api(s)?\//i.test(symbolFile(node));
+}
+function deriveRouteWeight(node) {
+    const file = symbolFile(node);
+    const title = symbolTitle(node);
+    const text = `${file} ${title}`;
+    const methodMatch = text.match(/\b(POST|GET|PUT|DELETE|PATCH)\b/i);
+    const method = methodMatch?.[1].toUpperCase() ?? "";
+    const isStore = /\/store\//i.test(file) || /\/store\b/i.test(file);
+    const isAdmin = /\/admin\//i.test(file) || /\/admin\b/i.test(file);
+    if (isHttpRouteSymbol(node) && isStore) {
+        if (method === "POST")
+            return 10;
+        if (method === "DELETE")
+            return 9;
+        if (method === "PUT")
+            return 8;
+        if (method === "GET")
+            return 5;
+        // default store route mutation-ish weight
+        return 7;
+    }
+    if (isHttpRouteSymbol(node) && isAdmin) {
+        if (method === "POST")
+            return 6;
+        if (method === "GET")
+            return 3;
+        return 5;
+    }
+    if (isEntryPoint(node))
+        return 4;
+    if (/(^|\/)(services?|controllers?|handlers?|modules?)\//i.test(file))
+        return 4;
+    return 2;
+}
+function deriveDataSensitivity(node) {
+    const text = `${node.external_id} ${symbolFile(node)} ${symbolTitle(node)}`.toLowerCase();
+    const tiers = [
+        [/payment|stripe|capture|refund|charge|billing/, 10],
+        [/auth|token|session|password|credential|jwt|oauth/, 9],
+        [/order|cart|checkout|invoice|transaction/, 7],
+        [/customer|user|account|profile|pii|gdpr/, 6],
+        [/notification|email|sms|webhook|push/, 3]
+    ];
+    for (const [re, weight] of tiers) {
+        if (re.test(text))
+            return weight;
+    }
+    return 1;
+}
+function getFlowDepth(node, graph) {
+    const entryIds = new Set(graph.nodes.filter((n) => n.kind === "CodeSymbol" && isEntryPoint(n)).map((n) => n.external_id));
+    if (entryIds.has(node.external_id))
+        return 0;
+    // BFS backward over CALLS edges to find nearest entry point.
+    const callers = new Map();
+    for (const e of graph.edges) {
+        if (e.relationship_type === "CALLS") {
+            const set = callers.get(e.to_external_id) ?? new Set();
+            set.add(e.from_external_id);
+            callers.set(e.to_external_id, set);
+        }
+    }
+    let depth = 0;
+    let frontier = new Set(callers.get(node.external_id) ?? []);
+    const seen = new Set(frontier);
+    while (frontier.size > 0 && depth < 6) {
+        depth++;
+        for (const id of frontier) {
+            if (entryIds.has(id))
+                return depth;
+        }
+        const next = new Set();
+        for (const id of frontier) {
+            for (const caller of callers.get(id) ?? []) {
+                if (!seen.has(caller)) {
+                    seen.add(caller);
+                    next.add(caller);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return depth >= 6 ? 6 : depth;
+}
+function complexityProxy(node) {
+    const start = typeof node.properties.start_line === "number" ? node.properties.start_line : 0;
+    const end = typeof node.properties.end_line === "number" ? node.properties.end_line : 0;
+    if (start > 0 && end >= start)
+        return end - start + 1;
+    return 0;
+}
+function normalizeScores(values) {
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    if (min === max) {
+        return values.map(() => 5);
+    }
+    return values.map((v) => 1 + ((v - min) / (max - min)) * 9);
+}
+const DETECTION_MAP = {
+    proven: 1,
+    associated: 5,
+    none: 10
+};
+const NEW_CODE_DAYS = 30;
+const NEW_CODE_SECONDS = NEW_CODE_DAYS * 24 * 60 * 60;
+function computeRawORS(node, graph, incomingRefs, gitChurn, fanOut, detectionTier, firstCommitTs, nowSec) {
+    const isNew = firstCommitTs > 0 && nowSec - firstCommitTs < NEW_CODE_SECONDS;
+    const complexity = complexityProxy(node);
+    const rawP = gitChurn * 0.35 + fanOut * 0.3 + (isNew ? 15 : 0) + complexity * 0.2;
+    const routeWeight = deriveRouteWeight(node);
+    const flowDepth = getFlowDepth(node, graph);
+    const flowPosition = Math.max(0, 5 - flowDepth);
+    const dataSensitivity = deriveDataSensitivity(node);
+    const rawI = incomingRefs * 0.3 + routeWeight * 0.3 + flowPosition * 0.2 + dataSensitivity * 0.2;
+    const d = DETECTION_MAP[detectionTier];
+    return { p: rawP, i: rawI, d };
+}
+function associatedBehaviorIds(graph, candidateIds) {
+    const ids = new Set();
+    for (const e of graph.candidate_edges ?? []) {
+        if (e.relationship_type !== "MAY_BE_TESTED_BY" && e.relationship_type !== "MAY_COVER" && e.relationship_type !== "MAY_RELATE_TO") {
+            continue;
+        }
+        // AI suggestions are useful prompts, but they are never evidence. Do not let them
+        // lower detection difficulty in "what to test first" rankings.
+        if (e.review_status === "ai_suggested")
+            continue;
+        if (candidateIds.has(e.from_external_id))
+            ids.add(e.from_external_id);
+        if (candidateIds.has(e.to_external_id))
+            ids.add(e.to_external_id);
+    }
+    return ids;
+}
+export function rankRiskGaps(graph, opts = {}) {
+    const limit = opts.limit ?? 20;
+    const confirmed = confirmedBehaviorIds(graph);
+    const symbols = graph.nodes.filter((n) => n.kind === "CodeSymbol" && n.denominator_eligible === true && !n.stale && !confirmed.has(n.external_id));
+    const symbolIds = new Set(symbols.map((s) => s.external_id));
+    const symbolsByFile = new Map();
+    for (const s of symbols) {
+        const file = symbolFile(s);
+        const list = symbolsByFile.get(file);
+        if (list)
+            list.push(s);
+        else
+            symbolsByFile.set(file, [s]);
+    }
+    const files = [...new Set(symbols.map(symbolFile))];
+    const churn = gitChurn(opts.repoRoot ?? graph.workspace.root, files, opts.churnWindow ?? "180 days ago");
+    const firstCommitTs = gitFirstCommitBatch(opts.repoRoot ?? graph.workspace.root, files);
+    const nowSec = Math.floor(Date.now() / 1000);
+    const incoming = new Map();
+    for (const e of graph.edges) {
+        if (e.relationship_type === "CALLS" && symbolIds.has(e.to_external_id)) {
+            incoming.set(e.to_external_id, (incoming.get(e.to_external_id) ?? 0) + 1);
+        }
+        else if (e.relationship_type === "IMPORTS") {
+            for (const s of symbolsByFile.get(e.to_external_id) ?? [])
+                incoming.set(s.external_id, (incoming.get(s.external_id) ?? 0) + 1);
+        }
+    }
+    const entryPoint = new Map(symbols.map((s) => [s.external_id, isEntryPoint(s)]));
+    const fanOut = new Map(symbols.map((s) => [s.external_id, countOutgoingCalls(s.external_id, graph)]));
+    const associated = associatedBehaviorIds(graph, symbolIds);
+    if (opts.legacy) {
+        return symbols
+            .map((s) => {
+            const file = symbolFile(s);
+            const incoming_refs = incoming.get(s.external_id) ?? 0;
+            const git_churn = churn.get(file) ?? 0;
+            const isEntry = entryPoint.get(s.external_id) ?? false;
+            const churnForScore = Math.min(git_churn, 500);
+            const score = Math.round((incoming_refs * 0.4 + churnForScore * 0.4 + (isEntry ? 20 : 0)) * 10) / 10;
+            const reasons = [
+                `${incoming_refs} incoming structural reference${incoming_refs === 1 ? "" : "s"}`,
+                `${git_churn} git churn line${git_churn === 1 ? "" : "s"} in 180 days${git_churn > 500 ? " (score capped at 500)" : ""}`
+            ];
+            if (isEntry)
+                reasons.push("near an API/route/handler entry point");
+            return { id: s.external_id, title: s.title || s.external_id, file, risk_score: score, incoming_refs, git_churn, entry_point: isEntry, reasons };
+        })
+            .sort((a, b) => b.risk_score - a.risk_score || b.incoming_refs - a.incoming_refs || b.git_churn - a.git_churn || a.id.localeCompare(b.id))
+            .slice(0, limit);
+    }
+    const rawScores = symbols.map((s) => {
+        const file = symbolFile(s);
+        const incoming_refs = incoming.get(s.external_id) ?? 0;
+        const git_churn = churn.get(file) ?? 0;
+        const fan_out = fanOut.get(s.external_id) ?? 0;
+        const ts = firstCommitTs.get(file) ?? 0;
+        const detectionTier = associated.has(s.external_id) ? "associated" : "none";
+        return computeRawORS(s, graph, incoming_refs, git_churn, fan_out, detectionTier, ts, nowSec);
+    });
+    const pScores = normalizeScores(rawScores.map((r) => r.p));
+    const iScores = normalizeScores(rawScores.map((r) => r.i));
+    return symbols
+        .map((s, idx) => {
+        const file = symbolFile(s);
+        const incoming_refs = incoming.get(s.external_id) ?? 0;
+        const git_churn = churn.get(file) ?? 0;
+        const fan_out = fanOut.get(s.external_id) ?? 0;
+        const isEntry = entryPoint.get(s.external_id) ?? false;
+        const route_weight = deriveRouteWeight(s);
+        const data_sensitivity = deriveDataSensitivity(s);
+        const flow_position = Math.max(0, 5 - getFlowDepth(s, graph));
+        const complexity_proxy = complexityProxy(s);
+        const firstTs = firstCommitTs.get(file) ?? 0;
+        const is_new_code = firstTs > 0 && nowSec - firstTs < NEW_CODE_SECONDS;
+        const p = Math.round(pScores[idx]);
+        const i = Math.round(iScores[idx]);
+        const d = rawScores[idx].d;
+        const detectionTier = associated.has(s.external_id) ? "associated" : "none";
+        const score = p * i * d;
+        const reasons = [
+            `ORS ${score} = P${p} × I${i} × D${d}`,
+            `${incoming_refs} incoming structural reference${incoming_refs === 1 ? "" : "s"}`,
+            `${git_churn} git churn line${git_churn === 1 ? "" : "s"} in 180 days`,
+            `route weight ${route_weight}, data sensitivity ${data_sensitivity}, fan-out ${fan_out}`
+        ];
+        if (isEntry)
+            reasons.push("near an API/route/handler entry point");
+        if (is_new_code)
+            reasons.push("new code (< 30 days)");
+        return {
+            id: s.external_id,
+            title: s.title || s.external_id,
+            file,
+            risk_score: score,
+            incoming_refs,
+            git_churn,
+            entry_point: isEntry,
+            reasons,
+            probability: p,
+            impact: i,
+            detection_difficulty: d,
+            fan_out,
+            route_weight,
+            data_sensitivity,
+            flow_position,
+            complexity_proxy,
+            is_new_code,
+            integration_signal: detectionTier
+        };
+    })
+        .sort((a, b) => b.risk_score - a.risk_score || b.incoming_refs - a.incoming_refs || b.git_churn - a.git_churn || a.id.localeCompare(b.id))
+        .slice(0, limit);
+}

package/dist/local/score/score.js

@@ -0,0 +1,182 @@
+import { denominatorBehaviors, denominatorComposition, nodesByKind } from "../graph/factories.js";
+/**
+ * Graph readiness score. This is a *readiness* signal, not a proof of test-lift.
+ *
+ * Internal scoring weights and the exact formula live here and are NEVER
+ * exported in the pack. Only the 0..1 per-dimension breakdown, the overall
+ * 0..100 score, the band, and plain-language missing-evidence are exposed.
+ */
+const WEIGHTS = {
+    behavior_anchors: 0.22,
+    acceptance_criteria: 0.2,
+    provenance: 0.15,
+    interface_mapping: 0.15,
+    validation_evidence: 0.18,
+    known_regressions: 0.1
+};
+const saturate = (count, target) => Math.max(0, Math.min(1, count / target));
+function bandFor(overall) {
+    if (overall >= 75)
+        return "strong";
+    if (overall >= 60)
+        return "good";
+    if (overall >= 40)
+        return "usable";
+    return "thin";
+}
+/**
+ * ONE O(edges) pass instead of O(behaviors × edges): the denominator can be
+ * tens of thousands of code exports (Mattermost: ~20k eligible over ~25k
+ * edges), and per-behavior linear scans made `opro score` multi-second.
+ */
+function buildEvidenceIndex(graph) {
+    const hardTested = new Set();
+    const acOwners = new Set();
+    for (const e of graph.edges) {
+        if (e.relationship_type === "TESTED_BY" || e.relationship_type === "COVERS") {
+            hardTested.add(e.from_external_id);
+            hardTested.add(e.to_external_id);
+        }
+        else if (e.relationship_type === "HAS_ACCEPTANCE_CRITERION") {
+            acOwners.add(e.from_external_id);
+        }
+    }
+    const weakTested = new Set();
+    const testLinkedFiles = new Set();
+    for (const e of graph.candidate_edges) {
+        if (e.relationship_type === "MAY_BE_TESTED_BY" || e.relationship_type === "MAY_COVER") {
+            weakTested.add(e.from_external_id);
+            weakTested.add(e.to_external_id);
+        }
+        else if (e.relationship_type === "MAY_RELATE_TO") {
+            testLinkedFiles.add(e.from_external_id);
+            testLinkedFiles.add(e.to_external_id);
+        }
+    }
+    return { hardTested, weakTested, testLinkedFiles, acOwners };
+}
+/**
+ * Test evidence for one behavior. Code exports get honest WEAK credit when a
+ * test resolved-imports their file (the Phase-2 MAY_RELATE_TO links) —
+ * symbol-level confirmation is Phase 4's job; without this interim credit,
+ * code-derived behaviors would be structurally uncoverable and a well-tested
+ * code-only repo would score "thin" no matter what.
+ */
+function evidenceFor(b, idx) {
+    if (idx.hardTested.has(b.external_id))
+        return "hard";
+    if (idx.weakTested.has(b.external_id))
+        return "weak";
+    if (b.behavior_source === "code_export") {
+        const file = typeof b.properties.file === "string" ? b.properties.file : "";
+        if (file && idx.testLinkedFiles.has(file))
+            return "weak";
+    }
+    return "none";
+}
+export function scoreGraph(graph) {
+    // Gate 3: the denominator is the SOLE basis for behavior counting here.
+    // Test-inferred flows are inventoried in the composition but contribute 0.
+    const behaviors = denominatorBehaviors(graph);
+    const denominator = denominatorComposition(graph);
+    const totalBehaviors = behaviors.length;
+    const strongBehaviors = behaviors.filter((b) => b.evidence_strength === "hard" || b.evidence_strength === "reviewed");
+    const weakBehaviors = behaviors.filter((b) => b.evidence_strength === "candidate" || b.evidence_strength === "weak");
+    const idx = buildEvidenceIndex(graph);
+    const explicitRequirements = denominator.requirement_template + denominator.markdown_requirement;
+    // behavior_anchors — code exports are "hard" evidence by construction, so a
+    // bare repo with six exported functions must NOT peg this at 1.0. The cap
+    // SCALES with explicit requirements rather than vanishing at the first one:
+    // two incidental markdown headings on a 1,400-export repo flipped this from
+    // 0.5-capped to a perfect score in live dogfooding (knife-edge).
+    let behaviorScore = saturate(strongBehaviors.length + weakBehaviors.length * 0.4, 6);
+    behaviorScore = Math.min(behaviorScore, 0.5 + 0.5 * saturate(explicitRequirements, 8));
+    // acceptance_criteria — ACs attach to REQUIREMENTS. Judging code exports for
+    // lacking ACs would zero this dim on any sizeable codebase; symbol-level
+    // coverage semantics arrive in Phase 4.
+    const acNodes = nodesByKind(graph, "AcceptanceCriterion").length;
+    const requirementBehaviors = behaviors.filter((b) => b.behavior_source === "requirement_template" || b.behavior_source === "markdown_requirement");
+    const behaviorsWithAc = requirementBehaviors.filter((b) => idx.acOwners.has(b.external_id)).length;
+    const acScore = requirementBehaviors.length === 0
+        ? saturate(acNodes, 4) * 0.5
+        : 0.7 * (behaviorsWithAc / requirementBehaviors.length) + 0.3 * saturate(acNodes, 4);
+    // provenance
+    const totalNodes = graph.nodes.length || 1;
+    const nodesWithRef = graph.nodes.filter((n) => Boolean(n.provenance?.source_ref)).length;
+    const provenanceScore = nodesWithRef / totalNodes;
+    // interface_mapping
+    const services = nodesByKind(graph, "Service");
+    const endpoints = nodesByKind(graph, "Endpoint");
+    const strongIface = [...services, ...endpoints].filter((n) => n.evidence_strength === "hard" || n.evidence_strength === "reviewed").length;
+    const weakIface = [...services, ...endpoints].filter((n) => n.evidence_strength === "candidate" || n.evidence_strength === "weak").length;
+    const ifaceEdges = graph.candidate_edges.filter((e) => e.relationship_type === "MAY_REQUIRE_INTERFACE").length;
+    const interfaceScore = saturate(strongIface + weakIface * 0.4 + ifaceEdges * 0.5, 5);
+    // validation_evidence
+    const testCaseCount = nodesByKind(graph, "TestCase").length;
+    const coveredBehaviors = behaviors.reduce((acc, b) => {
+        const ev = evidenceFor(b, idx);
+        return acc + (ev === "hard" ? 1 : ev === "weak" ? 0.5 : 0);
+    }, 0);
+    const coverageFrac = totalBehaviors === 0 ? 0 : coveredBehaviors / totalBehaviors;
+    const validationScore = 0.6 * coverageFrac + 0.4 * saturate(testCaseCount, 8);
+    // known_regressions
+    const incidents = nodesByKind(graph, "Incident").length;
+    const regressionScore = saturate(incidents, 3);
+    const breakdown = {
+        behavior_anchors: round2(behaviorScore),
+        acceptance_criteria: round2(acScore),
+        provenance: round2(provenanceScore),
+        interface_mapping: round2(interfaceScore),
+        validation_evidence: round2(validationScore),
+        known_regressions: round2(regressionScore)
+    };
+    const overall = Math.round(100 *
+        (WEIGHTS.behavior_anchors * breakdown.behavior_anchors +
+            WEIGHTS.acceptance_criteria * breakdown.acceptance_criteria +
+            WEIGHTS.provenance * breakdown.provenance +
+            WEIGHTS.interface_mapping * breakdown.interface_mapping +
+            WEIGHTS.validation_evidence * breakdown.validation_evidence +
+            WEIGHTS.known_regressions * breakdown.known_regressions));
+    const missing_evidence = missingEvidence(breakdown, denominator);
+    // A capped extraction means the denominator UNDERSTATES the repo's behavior
+    // surface — coverage % over a truncated denominator must say so.
+    if (graph.analysis?.symbol_cap_hit) {
+        missing_evidence.push("We hit the limit and only counted part of your code, so coverage looks lower than it really is. Raise ORANGEPRO_MAX_SYMBOLS and re-run `opro analyze .`.");
+    }
+    if (graph.analysis && graph.analysis.flows_truncated > 0) {
+        missing_evidence.push(`${graph.analysis.flows_truncated} test file(s) exceeded the inferred-behavior cap (${graph.analysis.max_inferred_flows}) and are not counted; raise ORANGEPRO_MAX_FLOWS to include them.`);
+    }
+    return { overall, band: bandFor(overall), breakdown, missing_evidence, denominator };
+}
+function missingEvidence(b, denominator) {
+    const out = [];
+    if (denominator.total === 0) {
+        out.push(denominator.excluded_test_inferred > 0
+            ? `Nothing to measure coverage against: we found ${denominator.excluded_test_inferred} behavior(s) guessed from test names, but those don't count (a test can't prove its own requirement). Add a requirements list (CSV/markdown) or analyze code that has functions/classes.`
+            : "Nothing to measure coverage against: no countable behaviors found. Add a requirements list (CSV/markdown) or analyze code that has functions/classes.");
+    }
+    // Keyed on the COMPOSITION, not evidence strength: code exports are "hard"
+    // by construction and used to permanently suppress this nudge on the exact
+    // repos it was written for (code-only, zero requirements).
+    const explicit = denominator.requirement_template + denominator.markdown_requirement;
+    if (denominator.total > 0 && explicit === 0) {
+        out.push("Add a few written requirements (we only found code and test names so far) — a short CSV/markdown list, or acceptance criteria.");
+    }
+    else if (explicit > 0 && explicit < 5 && denominator.code_export >= explicit * 20) {
+        out.push(`Only ${explicit} written requirement(s) for ${denominator.total} behaviors — add a requirements list so coverage reflects what the app should do, not just how much code exists.`);
+    }
+    if (b.acceptance_criteria < 0.5)
+        out.push("Add acceptance criteria so behaviors can be tested with concrete checks.");
+    if (b.interface_mapping < 0.4)
+        out.push("Add API/screen/service mapping (OpenAPI or route docs) for more specific tests.");
+    if (b.validation_evidence < 0.4)
+        out.push("Link existing tests or add manual QA steps so we can tell what's already covered.");
+    if (b.known_regressions < 0.2)
+        out.push("Add known bugs/incidents to enable targeted regression tests.");
+    if (b.provenance < 0.6)
+        out.push("Add source links so each behavior can be traced back to real code.");
+    return out;
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}

package/dist/local/types.js

@@ -0,0 +1 @@
+export {};

package/dist/local/util/hash.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+/** Content hash with the `sha256:` prefix used across graph + pack provenance. */
+export function hashString(input) {
+    return "sha256:" + createHash("sha256").update(input).digest("hex");
+}
+export function hashBuffer(buf) {
+    return "sha256:" + createHash("sha256").update(buf).digest("hex");
+}
+export function hashFile(absPath) {
+    return hashBuffer(readFileSync(absPath));
+}
+/** Short, stable, non-reversible digest for deriving node ids. */
+export function shortHash(input) {
+    return createHash("sha256").update(input).digest("hex").slice(0, 12);
+}

package/dist/local/util/ids.js

@@ -0,0 +1,16 @@
+import { shortHash } from "./hash.js";
+/**
+ * Deterministic internal node id. Stable across runs for the same (kind, key)
+ * so incremental updates can re-find and refresh existing nodes.
+ */
+export function stableId(kind, key) {
+    return `${kind}:${shortHash(`${kind}|${key}`)}`;
+}
+export function slugify(input) {
+    const slug = input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return slug || "item";
+}

package/dist/local/util/progress.js

@@ -0,0 +1,8 @@
+let reporter = null;
+export function setProgressReporter(fn) {
+    reporter = fn;
+}
+export function reportProgress(message, progress) {
+    if (reporter)
+        reporter(message, progress);
+}

package/dist/local/util/redact.js

@@ -0,0 +1,39 @@
+/**
+ * Secret redaction for any text that may surface in local reports or quote
+ * provenance. Privacy default is metadata-only; even when a source excerpt is
+ * read in-process for generation, obvious secrets are scrubbed first.
+ */
+const SECRET_PATTERNS = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "<redacted:private-key>"],
+    [/sk-ant-[A-Za-z0-9_-]{16,}/g, "<redacted:anthropic-key>"],
+    [/sk-[A-Za-z0-9]{20,}/g, "<redacted:openai-key>"],
+    [/ghp_[A-Za-z0-9]{20,}/g, "<redacted:github-token>"],
+    [/gho_[A-Za-z0-9]{20,}/g, "<redacted:github-token>"],
+    [/AKIA[0-9A-Z]{16}/g, "<redacted:aws-access-key>"],
+    [/xox[baprs]-[A-Za-z0-9-]{10,}/g, "<redacted:slack-token>"],
+    [/eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, "<redacted:jwt>"],
+    [/\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)\b\s*[:=]\s*["']?[^\s"']{8,}/gi, "<redacted:credential>"]
+];
+export function redactSecrets(text) {
+    let out = text;
+    for (const [pattern, replacement] of SECRET_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    return out;
+}
+export function redactSecretsPreservingLineCount(text) {
+    let out = text;
+    for (const [pattern, replacement] of SECRET_PATTERNS) {
+        out = out.replace(pattern, (match) => {
+            const newlineCount = match.match(/\r\n|\n|\r/g)?.length ?? 0;
+            return `${replacement}${"\n".repeat(newlineCount)}`;
+        });
+    }
+    return out;
+}
+export function containsSecret(text) {
+    return SECRET_PATTERNS.some(([pattern]) => {
+        pattern.lastIndex = 0;
+        return pattern.test(text);
+    });
+}

package/dist/local/util/time.js

@@ -0,0 +1 @@
+export const systemClock = () => new Date().toISOString();