@orangepro/orangepro-mcp 0.1.0

package/dist/local/pack/coverageReport.js

@@ -0,0 +1,192 @@
+import { LEDGER_SCHEMA_VERSION } from "../ledger.js";
+import { resolveCoverage } from "../score/coverage.js";
+import { rankRiskGaps } from "../score/risk.js";
+import { buildRtm } from "../rtm.js";
+/**
+ * Phase 5.2 — `COVERAGE_REPORT.md`, the human-readable third file of the
+ * 3-file contract (graph.html / COVERAGE_REPORT.md / graph.json). It states,
+ * auditably and in one place:
+ *  - dynamic Proven % over the DENOMINATOR behaviors;
+ *  - what the denominator is made of (Gate 3 composition line);
+ *  - import-resolution coverage (the 7 resolver axes) — unresolved imports are
+ *    test→source links the confirmer could not follow, so coverage can't be
+ *    proven across them;
+ *  - the graph schema version.
+ */
+const LAYER_ORDER = ["unit", "component", "integration", "api", "e2e", "manual", "unknown"];
+// The 7 resolver axes that matter for static-association defensibility, in
+// reading order; test→source is the gate axis.
+const AXIS_LABELS = [
+    { key: "test_to_source", label: "test → source (gate axis)" },
+    { key: "test_to_test", label: "test → test" },
+    { key: "test_internal", label: "test → internal" },
+    { key: "source_to_source", label: "source → source" },
+    { key: "barrel_terminal", label: "barrel → terminal" },
+    { key: "workspace_package", label: "workspace package" },
+    { key: "all_internal", label: "all internal" }
+];
+function emptyLedger() {
+    return { schema_version: LEDGER_SCHEMA_VERSION, records: [] };
+}
+export function renderCoverageReport(graph, ledger = emptyLedger()) {
+    const a = graph.analysis;
+    const lines = [];
+    lines.push("# Coverage Report");
+    lines.push("");
+    lines.push(`_Graph schema: ${graph.schema_version}_`);
+    lines.push(`_Generated: ${graph.updated_at || graph.created_at || "(unknown)"}_`);
+    lines.push("");
+    // ---- Public Proven + denominator: ONE atomic pair (shared with graph.html) ----
+    const { coverage: staticCov, denominator: comp } = resolveCoverage(graph);
+    const rtm = buildRtm(graph, ledger);
+    const s = rtm.summary;
+    lines.push("## Dynamic Proven");
+    lines.push("");
+    lines.push(`**${s.proven} of ${s.total} behaviors Proven (${s.coverage_pct}%)** — public Proven requires a closed dynamic targeted-proof ledger record. Static TESTED_BY/COVERS edges are Associated signal diagnostics, not proof.`);
+    const gate = a?.resolver_gate;
+    if (gate) {
+        lines.push("");
+        lines.push(gate.defensible
+            ? `Defensible for static association diagnostics: import resolution on the gate axis (test → source) is ${gate.pct ?? "?"}% (≥ ${gate.threshold_pct}%).`
+            : `⚠ Static association diagnostics are not defensible repo-wide: test → source resolution is ${gate.pct ?? "?"}% (< ${gate.threshold_pct}%) or the scan was truncated.`);
+    }
+    lines.push("");
+    lines.push("Static assertion candidates by test layer (diagnostic only — never counted as Proven):");
+    lines.push("");
+    lines.push("| layer | static candidate behaviors |");
+    lines.push("| --- | ---: |");
+    for (const l of LAYER_ORDER)
+        lines.push(`| ${l} | ${staticCov.by_layer[l]} |`);
+    lines.push("");
+    if (staticCov.confirmed > 0 && staticCov.unknown_count > 0) {
+        lines.push(`${staticCov.unknown_count} static candidate behavior(s) (${staticCov.unknown_pct}%) have an undetermined test layer.`);
+        lines.push("");
+    }
+    const runtime = a?.runtime_coverage;
+    lines.push("## Runtime coverage");
+    lines.push("");
+    if (runtime) {
+        lines.push(`**${runtime.covered_symbols} of ${runtime.total_eligible_symbols} eligible symbols runtime-covered (${runtime.covered_pct}%)** — measured from local coverage-tool output, not name matching and not assertion-level proof.`);
+        lines.push("");
+        lines.push("| language | covered / eligible | covered % | symbols with spans |");
+        lines.push("| --- | ---: | ---: | ---: |");
+        for (const [language, row] of Object.entries(runtime.by_language).sort(([a], [b]) => a.localeCompare(b))) {
+            lines.push(`| ${language} | ${row.covered} / ${row.eligible} | ${row.covered_pct}% | ${row.symbols_with_spans} |`);
+        }
+        lines.push("");
+        lines.push("Artifacts:");
+        lines.push("");
+        lines.push("| artifact | format | files | covered ranges |");
+        lines.push("| --- | --- | ---: | ---: |");
+        for (const artifact of runtime.artifacts) {
+            lines.push(`| ${escapeMd(artifact.path)} | ${artifact.format} | ${artifact.files} | ${artifact.covered_ranges} |`);
+        }
+        lines.push("");
+        if (runtime.skipped_artifacts?.length) {
+            lines.push("Skipped artifacts:");
+            lines.push("");
+            lines.push("| artifact | format | reason |");
+            lines.push("| --- | --- | --- |");
+            for (const artifact of runtime.skipped_artifacts) {
+                lines.push(`| ${escapeMd(artifact.path)} | ${artifact.format} | ${escapeMd(artifact.reason)} |`);
+            }
+            lines.push("");
+        }
+    }
+    else {
+        lines.push("No runtime coverage report was ingested. This report still shows dynamic Proven and static association diagnostics, but it does not claim actual executed coverage. Run `opro coverage .` for detected local coverage commands, or `opro analyze . --generate-coverage` where supported.");
+        lines.push("");
+    }
+    // ---- Denominator composition (Gate 3) — the SAME comp paired with cov above ----
+    const requirement = comp.requirement_template + comp.markdown_requirement;
+    lines.push("## Denominator");
+    lines.push("");
+    let compLine = `${comp.total} behaviors: ${comp.code_export} code_export, ${requirement} requirement`;
+    if (comp.excluded_test_inferred > 0)
+        compLine += `; ${comp.excluded_test_inferred} test-inferred excluded`;
+    if (comp.unattributed > 0)
+        compLine += `; ${comp.unattributed} unattributed`;
+    lines.push(compLine + ".");
+    lines.push("");
+    // Recomputed from nodes (comp), NOT read from persisted analysis — the
+    // disclosure is paired with the same graph the denominator was computed over.
+    // Complete accounting: total = counted + boilerplate + infra + generated + other (the
+    // buckets are disjoint and sum to every CodeSymbol node), so the "found" count
+    // is never a partial sum that drops non-callable consts / .d.ts / infra symbols.
+    const boilerplate = comp.excluded_boilerplate;
+    const infra = comp.excluded_infra;
+    const generated = comp.excluded_generated;
+    if (boilerplate > 0 || infra > 0 || generated > 0) {
+        const total = comp.code_symbols_total;
+        const other = Math.max(0, total - comp.code_export - boilerplate - infra - generated);
+        let line = `${total} code symbols found: ${comp.code_export} counted as behaviors`;
+        if (boilerplate > 0)
+            line += `, ${boilerplate} excluded as trivial accessors (getters/setters, toString/equals/hashCode, __repr__/__str__)`;
+        if (infra > 0)
+            line += `, ${infra} excluded as CI/test-infra (.github, e2e/playwright/cypress, fixtures/mocks)`;
+        if (generated > 0)
+            line += `, ${generated} excluded as generated code (Code generated ... DO NOT EDIT)`;
+        if (other > 0)
+            line += `, ${other} excluded as non-behavioral (type declarations, non-callable consts)`;
+        lines.push(line + ". Excluded symbols stay in the graph but carry no testable behavior, so counting them would distort coverage.");
+        lines.push("");
+    }
+    lines.push("Test-inferred behaviors (guessed from test describe-names) are inventoried but never counted — a test cannot prove its own requirement.");
+    lines.push("");
+    const riskGaps = rankRiskGaps(graph, { limit: 20 });
+    if (riskGaps.length > 0) {
+        lines.push("## Top gaps by risk");
+        lines.push("");
+        lines.push("Unconfirmed code behaviors ranked by structural impact and recent change activity. This is a prioritization list, not coverage proof.");
+        lines.push("");
+        lines.push("Risk score = Probability(1-10) × Impact(1-10) × DetectionDifficulty(1|5|10).");
+        lines.push("");
+        lines.push("| rank | behavior | file | risk | why |");
+        lines.push("| ---: | --- | --- | ---: | --- |");
+        riskGaps.forEach((g, i) => {
+            lines.push(`| ${i + 1} | ${escapeMd(g.title)} | ${escapeMd(g.file)} | ${g.risk_score} | ${escapeMd(g.reasons.join("; "))} |`);
+        });
+        lines.push("");
+    }
+    // ---- Import resolution (the 7 axes) ----
+    lines.push("## Import resolution");
+    lines.push("");
+    if (a?.resolver_metrics) {
+        const rm = a.resolver_metrics;
+        lines.push("Unresolved imports are links the confirmer cannot follow, so coverage can't be proven across them.");
+        lines.push("");
+        lines.push("| axis | resolved / eligible | resolved % | unresolved % |");
+        lines.push("| --- | ---: | ---: | ---: |");
+        for (const { key, label } of AXIS_LABELS) {
+            const m = rm[key];
+            if (!m)
+                continue;
+            const unresolved = m.n > 0 ? round1(100 - (m.resolved / m.n) * 100) : 0;
+            lines.push(`| ${label} | ${m.resolved} / ${m.n} | ${m.pct}% | ${unresolved}% |`);
+        }
+    }
+    else {
+        lines.push("_No TypeScript/JavaScript imports were scanned, so resolver metrics are not available._");
+    }
+    lines.push("");
+    const budget = a?.not_analyzed_due_to_budget;
+    if (a?.symbol_cap_hit || a?.files_cap_hit || budget) {
+        lines.push("## Caveats");
+        lines.push("");
+        if (budget) {
+            lines.push(`- ⚠ PARTIAL SCAN: the analyze budget (${budget.budget_ms}ms) stopped after ${budget.elapsed_ms}ms with ${budget.files_not_analyzed} file(s) NOT analyzed. The denominator is incomplete, so the Dynamic Proven headline is a partial view. Raise \`ORANGEPRO_MAX_ANALYZE_MS\` or scope with \`--base\`.`);
+        }
+        if (a?.symbol_cap_hit)
+            lines.push("- Symbol cap hit: some code symbols were omitted; the denominator understates the repo, so Dynamic Proven reads low. Raise `ORANGEPRO_MAX_SYMBOLS`.");
+        if (a?.files_cap_hit)
+            lines.push("- File cap hit: not all files were scanned; coverage measured an unknown fraction of the repo. Raise `ORANGEPRO_MAX_FILES`.");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function round1(n) {
+    return Math.round(n * 10) / 10;
+}
+function escapeMd(s) {
+    return s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}

package/dist/local/pack/exporter.js

@@ -0,0 +1,195 @@
+import { systemClock } from "../util/time.js";
+import { EVIDENCE_PACK_SCHEMA_VERSION } from "./schema.js";
+import { redactSecrets } from "../util/redact.js";
+/**
+ * A generated test's `body` is model output that can paraphrase the fed test
+ * source. The exported pack is the metadata-only IP boundary, so by default the
+ * body is NOT embedded — it stays in the local workspace graph. It is included
+ * only when `include_generated_bodies` is explicitly set. (This is distinct from
+ * the deferred raw-source-snippets policy, which never crosses the boundary.)
+ */
+const BODY_OMITTED = "[omitted: metadata-only export — generated test body kept local; set include_generated_bodies to embed]";
+/**
+ * Build a strict, promotion-ready evidence pack from a local graph + score.
+ *
+ * The pack is the IP boundary: only metadata, provenance, and grounding cross
+ * it. Prompt text, scoring weights, traversal traces, and raw source NEVER do.
+ * The strict `evidencePackSchema` enforces this — extra keys would be rejected —
+ * so this builder deliberately constructs minimal, shape-exact objects.
+ *
+ * Everything is built immutably: input graph/nodes/edges are never mutated.
+ */
+export function buildPack(graph, score, opts, clock) {
+    const now = (clock ?? systemClock)();
+    const pack = {
+        schema_version: EVIDENCE_PACK_SCHEMA_VERSION,
+        created_at: now,
+        workspace: {
+            name: graph.workspace.name,
+            root_hash: graph.workspace.root_hash,
+            source_upload_policy: graph.workspace.source_upload_policy
+        },
+        sources: graph.sources.map(toSource),
+        entities: graph.nodes.map(toEntity),
+        // IMPORTS edges are local resolver substrate (they feed coverage metrics and
+        // the structural confirmer), not promotion evidence: at monorepo scale they
+        // would dominate the pack for zero consumer value, so they stay local-only.
+        relationships: graph.edges.filter(isPackRelationshipEdge).map(toRelationship),
+        candidate_relationships: graph.candidate_edges.map(toCandidateRelationship),
+        quality_score: {
+            overall: score.overall,
+            band: score.band,
+            breakdown: {
+                behavior_anchors: score.breakdown.behavior_anchors,
+                acceptance_criteria: score.breakdown.acceptance_criteria,
+                provenance: score.breakdown.provenance,
+                interface_mapping: score.breakdown.interface_mapping,
+                validation_evidence: score.breakdown.validation_evidence,
+                known_regressions: score.breakdown.known_regressions
+            },
+            missing_evidence: [...score.missing_evidence]
+        },
+        generation_runs: graph.generation_runs.map((run) => toGenerationRun(run, graph.generated_tests, opts?.include_generated_bodies ?? false))
+    };
+    return pack;
+}
+function toSource(source) {
+    return {
+        source_scope_id: source.source_scope_id,
+        source_system: source.source_system,
+        source_type: source.source_type,
+        display_name: source.display_name,
+        content_hash: source.content_hash,
+        metadata: { ...source.metadata }
+    };
+}
+/** Map a node kind to the pack's snake_case entity_type. */
+function entityTypeOf(kind) {
+    switch (kind) {
+        case "AcceptanceCriterion":
+            return "acceptance_criterion";
+        case "CodeSymbol":
+            return "code_symbol";
+        case "ConfigFile":
+            return "config_file";
+        case "TestCase":
+            return "test_case";
+        case "UserFlow":
+            return "user_flow";
+        case "TenantStub":
+            return "tenant_stub";
+        case "BusinessRule":
+            return "business_rule";
+        case "SourceScope":
+            return "source_scope";
+        case "EvidenceItem":
+            return "evidence_item";
+        default:
+            return kind.toLowerCase();
+    }
+}
+/**
+ * Defense-in-depth secret scrub for any string crossing the pack boundary. Node
+ * properties are reviewed metadata (secret-redacted at ingest); re-redacting here
+ * makes the boundary's "no secrets" guarantee hold regardless of how a property
+ * was populated. Structure and non-secret text (e.g. acceptance criteria) are
+ * preserved — only secret patterns are replaced.
+ */
+function redactDeep(value) {
+    if (typeof value === "string")
+        return redactSecrets(value);
+    if (Array.isArray(value))
+        return value.map(redactDeep);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactDeep(v)]));
+    }
+    return value;
+}
+function toEntity(node) {
+    const properties = redactDeep({ ...node.properties });
+    if (node.content_hash !== undefined) {
+        properties.content_hash = node.content_hash;
+    }
+    return {
+        external_id: node.external_id,
+        entity_type: entityTypeOf(node.kind),
+        review_status: node.review_status,
+        confidence: node.confidence,
+        properties,
+        provenance: toProvenance(node.provenance)
+    };
+}
+/** Rebuild provenance into the strict shape, dropping any extra keys. */
+function toProvenance(provenance) {
+    const out = {
+        source_scope_id: provenance.source_scope_id
+    };
+    if (provenance.source_ref !== undefined)
+        out.source_ref = provenance.source_ref;
+    if (provenance.quote_hash !== undefined)
+        out.quote_hash = provenance.quote_hash;
+    if (provenance.detector !== undefined)
+        out.detector = provenance.detector;
+    return out;
+}
+function isPackRelationshipEdge(edge) {
+    return edge.relationship_type !== "IMPORTS" && edge.evidence_strength !== "framework-derived";
+}
+function proofReviewStatus(status) {
+    if (status === "ai_suggested") {
+        throw new Error("AI-suggested review status is not valid on hard/reviewed evidence-pack relationships.");
+    }
+    return status;
+}
+function toRelationship(edge) {
+    const rel = {
+        from_external_id: edge.from_external_id,
+        to_external_id: edge.to_external_id,
+        relationship_type: edge.relationship_type,
+        evidence_strength: edge.evidence_strength,
+        review_status: proofReviewStatus(edge.review_status),
+        provenance: toProvenance(edge.provenance)
+    };
+    if (edge.confidence !== undefined)
+        rel.confidence = edge.confidence;
+    return rel;
+}
+function toCandidateRelationship(edge) {
+    return {
+        from_external_id: edge.from_external_id,
+        to_external_id: edge.to_external_id,
+        relationship_type: edge.relationship_type,
+        evidence_strength: edge.evidence_strength,
+        // Reasons can carry repo-derived text (e.g. a resolved import specifier):
+        // redact for defense-in-depth parity with toEntity's redactDeep.
+        reason: redactSecrets(edge.reason),
+        confidence: edge.confidence
+    };
+}
+function toGenerationRun(run, allTests, includeBody) {
+    const tests = allTests.filter((t) => t.run_id === run.run_id).map((t) => toGeneratedTest(t, includeBody));
+    return {
+        run_id: run.run_id,
+        model_provider: run.model_provider,
+        model_name: run.model_name,
+        input_mode: run.input_mode,
+        prompt_version: run.prompt_version,
+        generated_tests: tests
+    };
+}
+function toGeneratedTest(test, includeBody) {
+    return {
+        title: test.title,
+        test_type: test.test_type,
+        framework_hint: test.framework_hint,
+        body: includeBody ? test.body : BODY_OMITTED,
+        bucket: test.bucket,
+        prompt_version: test.prompt_version,
+        grounding: {
+            entity_ids: [...test.grounding.entity_ids],
+            source_refs: [...test.grounding.source_refs],
+            weak_relationships_used: [...test.grounding.weak_relationships_used]
+        },
+        weak_evidence_used: test.weak_evidence_used
+    };
+}

package/dist/local/pack/schema.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+/**
+ * Evidence pack schema (`orangepro.local_evidence_pack.v0`).
+ *
+ * Objects are `.strict()` on purpose: unknown keys FAIL validation. This is the
+ * IP boundary in code form — prompt text, prompt templates, scoring weights,
+ * ranking traces, traversal traces, or raw source would all be rejected, so the
+ * pack stays "promotion-ready but not reverse-engineering-ready".
+ */
+export const EVIDENCE_PACK_SCHEMA_VERSION = "orangepro.local_evidence_pack.v0";
+const provenanceSchema = z
+    .object({
+    source_scope_id: z.string().min(1),
+    source_ref: z.string().optional(),
+    quote_hash: z.string().optional(),
+    detector: z.string().optional()
+})
+    .strict();
+const sourceSchema = z
+    .object({
+    source_scope_id: z.string().min(1),
+    source_system: z.string().min(1),
+    source_type: z.string().min(1),
+    display_name: z.string(),
+    content_hash: z.string(),
+    metadata: z.record(z.unknown())
+})
+    .strict();
+const entitySchema = z
+    .object({
+    external_id: z.string().min(1),
+    entity_type: z.string().min(1),
+    review_status: z.enum(["local_reviewed", "auto_detected", "inferred", "ai_suggested"]),
+    confidence: z.number().min(0).max(1),
+    properties: z.record(z.unknown()),
+    provenance: provenanceSchema
+})
+    .strict();
+const relationshipSchema = z
+    .object({
+    from_external_id: z.string().min(1),
+    to_external_id: z.string().min(1),
+    relationship_type: z.string().min(1),
+    evidence_strength: z.enum(["hard", "reviewed"]),
+    review_status: z.enum(["local_reviewed", "auto_detected", "inferred"]),
+    provenance: provenanceSchema,
+    confidence: z.number().min(0).max(1).optional()
+})
+    .strict();
+const candidateRelationshipSchema = z
+    .object({
+    from_external_id: z.string().min(1),
+    to_external_id: z.string().min(1),
+    relationship_type: z.string().min(1),
+    evidence_strength: z.enum(["candidate", "weak"]),
+    reason: z.string(),
+    confidence: z.number().min(0).max(1)
+})
+    .strict();
+const qualityScoreSchema = z
+    .object({
+    overall: z.number().min(0).max(100),
+    band: z.enum(["thin", "usable", "good", "strong"]),
+    breakdown: z
+        .object({
+        behavior_anchors: z.number().min(0).max(1),
+        acceptance_criteria: z.number().min(0).max(1),
+        provenance: z.number().min(0).max(1),
+        interface_mapping: z.number().min(0).max(1),
+        validation_evidence: z.number().min(0).max(1),
+        known_regressions: z.number().min(0).max(1)
+    })
+        .strict(),
+    missing_evidence: z.array(z.string())
+})
+    .strict();
+const groundingSchema = z
+    .object({
+    entity_ids: z.array(z.string()),
+    source_refs: z.array(z.string()),
+    weak_relationships_used: z.array(z.string())
+})
+    .strict();
+const generatedTestSchema = z
+    .object({
+    title: z.string().min(1),
+    test_type: z.string().min(1),
+    framework_hint: z.string(),
+    body: z.string(),
+    grounding: groundingSchema,
+    weak_evidence_used: z.boolean(),
+    // Optional per-artifact prompt lineage; old packs only carry this on the run.
+    prompt_version: z.string().optional(),
+    // Optional local scenario bucket (backward-compatible: old packs omit it).
+    bucket: z
+        .enum(["happy_path", "validation_error", "edge_case", "integration_flow", "security_privacy", "regression"])
+        .optional()
+})
+    .strict();
+const generationRunSchema = z
+    .object({
+    run_id: z.string().min(1),
+    model_provider: z.string(),
+    model_name: z.string(),
+    input_mode: z.enum(["graph_grounded", "raw_prompt"]),
+    prompt_version: z.string(),
+    generated_tests: z.array(generatedTestSchema)
+})
+    .strict();
+export const evidencePackSchema = z
+    .object({
+    schema_version: z.literal(EVIDENCE_PACK_SCHEMA_VERSION),
+    created_at: z.string(),
+    workspace: z
+        .object({
+        name: z.string(),
+        root_hash: z.string(),
+        source_upload_policy: z.enum(["metadata_only", "include_sources"])
+    })
+        .strict(),
+    sources: z.array(sourceSchema),
+    entities: z.array(entitySchema),
+    relationships: z.array(relationshipSchema),
+    candidate_relationships: z.array(candidateRelationshipSchema),
+    quality_score: qualityScoreSchema,
+    generation_runs: z.array(generationRunSchema)
+})
+    .strict();

package/dist/local/pack/summary.js

@@ -0,0 +1,127 @@
+/**
+ * Render an evidence pack as a human-readable Markdown summary.
+ *
+ * This is a trust artifact: it explains *what* evidence backs the pack and the
+ * generated tests WITHOUT exposing how anything was scored or prompted. It
+ * deliberately omits scoring weights, prompt text, and traversal traces — only
+ * the metadata already present in the pack is rendered.
+ */
+export function packToMarkdown(pack, analysis) {
+    const lines = [];
+    lines.push("# OrangePro Local Evidence Pack");
+    lines.push("");
+    lines.push(`- Created at: ${pack.created_at}`);
+    lines.push(`- Workspace: ${pack.workspace.name}`);
+    lines.push(`- Source upload policy: ${pack.workspace.source_upload_policy}`);
+    lines.push("");
+    if (analysis) {
+        // Phase 5.3: COVERAGE_REPORT.md is the SINGLE source of coverage truth
+        // (dynamic Proven %, denominator composition, resolver metrics). The pack defers
+        // to it and only surfaces completeness caveats that affect THIS pack — no
+        // competing coverage numbers live here.
+        lines.push("## Coverage");
+        lines.push("");
+        lines.push("Dynamic Proven, static association diagnostics, the denominator composition, and import-resolution metrics live in `COVERAGE_REPORT.md` (the 3-file contract: graph.html / COVERAGE_REPORT.md / graph.json). This pack does not restate them.");
+        if (analysis.flows_truncated > 0) {
+            lines.push(`- ⚠ Truncated: ${analysis.flows_truncated} test file(s) exceeded the inferred-behavior cap and are not represented. Raise ORANGEPRO_MAX_FLOWS to include them.`);
+        }
+        if (analysis.symbol_cap_hit) {
+            lines.push("- ⚠ Code-symbol extraction cap was reached; some symbols are omitted (the denominator understates the repo). Raise ORANGEPRO_MAX_SYMBOLS.");
+        }
+        if (analysis.not_analyzed_due_to_budget) {
+            const b = analysis.not_analyzed_due_to_budget;
+            lines.push(`- ⚠ PARTIAL SCAN: the analyze budget (${b.budget_ms}ms) stopped with ${b.files_not_analyzed} file(s) NOT analyzed — this pack came from a partial graph; coverage is a floor, not complete. Raise ORANGEPRO_MAX_ANALYZE_MS or scope with --base.`);
+        }
+        lines.push("");
+    }
+    lines.push("## Quality score");
+    lines.push("");
+    lines.push(`Overall: ${pack.quality_score.overall}/100 (band: ${pack.quality_score.band})`);
+    lines.push("");
+    for (const [dimension, value] of Object.entries(pack.quality_score.breakdown)) {
+        lines.push(`- ${labelDimension(dimension)}: ${formatFraction(value)}`);
+    }
+    lines.push("");
+    lines.push("## Why the score is not higher");
+    lines.push("");
+    if (pack.quality_score.missing_evidence.length === 0) {
+        lines.push("- No outstanding evidence gaps reported.");
+    }
+    else {
+        for (const item of pack.quality_score.missing_evidence) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Sources");
+    lines.push("");
+    if (pack.sources.length === 0) {
+        lines.push("- No sources recorded.");
+    }
+    else {
+        for (const source of pack.sources) {
+            lines.push(`- ${source.display_name} (${source.source_system} / ${source.source_type})`);
+        }
+    }
+    lines.push("");
+    lines.push("## Entities");
+    lines.push("");
+    lines.push(`Total entities: ${pack.entities.length}`);
+    lines.push("");
+    const counts = countByEntityType(pack.entities);
+    if (counts.length === 0) {
+        lines.push("- No entities recorded.");
+    }
+    else {
+        for (const { entity_type, count } of counts) {
+            lines.push(`- ${entity_type}: ${count}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Generated tests");
+    lines.push("");
+    const tests = pack.generation_runs.flatMap((run) => run.generated_tests);
+    if (tests.length === 0) {
+        lines.push("- No generated tests in this pack.");
+    }
+    else {
+        for (const test of tests) {
+            lines.push(`### ${test.title}`);
+            lines.push("");
+            if (test.bucket)
+                lines.push(`- Local bucket: ${test.bucket}`);
+            lines.push(`- Test type: ${test.test_type}`);
+            lines.push(`- Framework hint: ${test.framework_hint || "(none)"}`);
+            lines.push(`- Grounded by entities: ${formatList(test.grounding.entity_ids)}`);
+            lines.push(`- Source refs: ${formatList(test.grounding.source_refs)}`);
+            lines.push(`- Weak/candidate evidence used: ${test.weak_evidence_used ? "yes" : "no"}`);
+            lines.push("");
+        }
+    }
+    lines.push("## Provenance");
+    lines.push("");
+    lines.push("Every entity and relationship in this pack carries provenance (source scope, optional source reference and quote hash). The pack contains metadata, provenance, and grounding only — no raw source code, prompts, or scoring internals.");
+    lines.push("");
+    return lines.join("\n");
+}
+function labelDimension(dimension) {
+    return dimension
+        .split("_")
+        .map((part) => (part.length > 0 ? part[0].toUpperCase() + part.slice(1) : part))
+        .join(" ");
+}
+function formatFraction(value) {
+    return value.toFixed(2);
+}
+function formatList(values) {
+    return values.length > 0 ? values.join(", ") : "(none)";
+}
+function countByEntityType(entities) {
+    const counts = new Map();
+    for (const entity of entities) {
+        counts.set(entity.entity_type, (counts.get(entity.entity_type) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([entity_type, count]) => ({ entity_type, count }))
+        .sort((a, b) => a.entity_type.localeCompare(b.entity_type));
+}

package/dist/local/pack/validate.js

@@ -0,0 +1,25 @@
+import { evidencePackSchema } from "./schema.js";
+/** Validate an unknown object against the strict evidence-pack schema. */
+export function validatePack(obj) {
+    const result = evidencePackSchema.safeParse(obj);
+    if (result.success) {
+        return { valid: true, errors: [] };
+    }
+    return { valid: false, errors: result.error.issues.map(formatIssue) };
+}
+/** Parse JSON text then validate; reports a JSON error rather than throwing. */
+export function validatePackJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "invalid JSON";
+        return { valid: false, errors: [`<root>: invalid JSON (${message})`] };
+    }
+    return validatePack(parsed);
+}
+function formatIssue(issue) {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+    return `${path}: ${issue.message}`;
+}