jev-agent-tools 0.2.0 → 0.3.0

package/dist/tools/docs-check.js

@@ -1,16 +1,31 @@
 import { createAnalysisContext } from "../adapters/analysis-context.js";
 import { collectDocsInventory, docsDeclarationSearch, } from "../adapters/docs.js";
+import { resolveEvidenceContext, withEvidenceContext, } from "../adapters/evidence-context.js";
 import { collectUnits } from "../adapters/git.js";
 import { resolveBase } from "../adapters/git-base.js";
 import { shareGitInventory } from "../adapters/git-inventory.js";
-import { CHOICE_MAX_OPTIONS, DOCS_COLLECT_BUDGET_MS, DOCS_DISPLAY_MAX_SECTIONS, DOCS_MAX_SECTIONS, STATE_MAX_CHARS, } from "../constants.js";
+import { CHOICE_MAX_OPTIONS, DOCS_COLLECT_BUDGET_MS, DOCS_DISPLAY_MAX_SECTIONS, DOCS_MAX_SECTIONS, STATE_MAX_CHARS, TIMEOUT_MS, } from "../constants.js";
 import { collectDocsCandidates } from "../core/docs.js";
 import { buildEnvelope, } from "../core/output.js";
+import { known, } from "../core/result-report.js";
 import { prepareDocsCheck, readDocsJudgment, } from "../presets/docs.js";
 import { NOT_CONFIGURED } from "../texts/configuration.js";
+import { ReviewReport, reportMetrics } from "./review-report.js";
 /** Shared judgment seam: no guide delivery, rendering, or session answer recording. */
 export async function runDocsCheck(deps, input) {
     const started = performance.now();
+    const report = new ReviewReport();
+    const admission = input.evidenceContext
+        ? undefined
+        : await resolveEvidenceContext(input.cwd, undefined, {
+            exec: deps.exec,
+            signal: input.signal,
+            origin: deps.evidenceOrigin,
+        });
+    const evidenceContext = input.evidenceContext ?? admission?.context;
+    if (!evidenceContext)
+        throw new Error("Evidence context was not established");
+    evidenceContext.requestedBase = input.base ?? "HEAD";
     deps = { ...deps, exec: shareGitInventory(deps.exec) };
     const timeout = input.budgetMs === undefined
         ? undefined
@@ -31,7 +46,7 @@ export async function runDocsCheck(deps, input) {
     let budget;
     let sent = 0;
     let emptyBase;
-    const finish = (refusal) => {
+    const finish = (refusal, cause = "internal_error") => {
         if (unchecked.length > 5) {
             unjudged = {
                 count: unchecked.length,
@@ -96,7 +111,9 @@ export async function runDocsCheck(deps, input) {
                 !collection &&
                 !unchecked.length &&
                 !findings.length &&
-                emptyBase === undefined
+                emptyBase === undefined &&
+                report.items.size > 0 &&
+                [...report.items.values()].every((item) => item.treatment === "judged")
                 ? {
                     lines: [
                         {
@@ -110,12 +127,27 @@ export async function runDocsCheck(deps, input) {
             yield: {
                 calls: judgments.reduce((n, j) => n + (j.calls ?? 0), 0),
                 questions: judgments.reduce((n, j) => n + (j.questions ?? 0), 0),
-                costUsd: judgments.reduce((n, j) => n + (j.usage?.costUsd ?? 0), 0),
+                costUsd: judgments.length && judgments.every((j) => j.usage !== undefined)
+                    ? judgments.reduce((n, j) => n + (j.usage?.costUsd ?? 0), 0)
+                    : undefined,
                 cacheHits: judgments.reduce((n, j) => n + (j.cacheHits ?? 0), 0),
                 cacheRequests: judgments.reduce((n, j) => n + (j.cacheRequests ?? 0), 0),
                 elapsedMs: performance.now() - started,
             },
         });
+        report.diagnose("collection_omitted", "Existing documentation sentences only; missing documentation is not exhaustively detected (measured 2/45 obligations across 180 partial commits).", undefined, [], false);
+        if (emptyBase !== undefined)
+            report.diagnose("no_changed_units", `No changed units against ${emptyBase}`, emptyBase, [], false);
+        if (!refusal && emptyBase === undefined && !report.items.size)
+            report.diagnose("collection_empty", "No matching documentation sections were collected; this does not establish documentation completeness.", undefined, [], false);
+        if (refusal) {
+            report.refusal =
+                cause === "invalid_base" ||
+                    cause === "invalid_root" ||
+                    cause === "git_failure";
+            report.diagnose(cause, refusal);
+        }
+        const result = report.build("jev_check_diff", evidenceContext, reportMetrics(envelope));
         return {
             ok: !refusal,
             status: timeout?.aborted
@@ -128,37 +160,58 @@ export async function runDocsCheck(deps, input) {
             envelope,
             judgments,
             findings,
+            result,
             ...(collection ? { collection } : {}),
             ...(unjudged ? { unjudged } : {}),
         };
     };
     const client = deps.client;
     if (!client)
-        return finish(NOT_CONFIGURED);
+        return finish(NOT_CONFIGURED, "not_configured");
     const sessionRefusal = deps.runtime.session.refusal();
     if (sessionRefusal)
-        return finish(sessionRefusal);
+        return finish(sessionRefusal, "session_budget");
     try {
         const comparison = await resolveBase(deps.exec, input.cwd, input.base, signal);
         if (!comparison.ok)
-            return finish(comparison.error);
+            return finish(comparison.error, comparison.cause ?? "invalid_base");
         const base = comparison.base;
+        evidenceContext.resolvedBase = base;
         const analysis = await createAnalysisContext();
         const [collected, inventory] = await Promise.all([
             collectUnits(deps.exec, { cwd: input.cwd, base, signal }, analysis.parser),
             collectDocsInventory(deps.exec, input.cwd, signal),
         ]);
         if (!collected.ok)
-            return finish(collected.error);
+            return finish(collected.error, collected.cause ?? "git_failure");
         if (!inventory.ok)
-            return finish(inventory.error);
-        for (const limit of collected.limits)
+            return finish(inventory.error, inventory.cause ?? "file_unavailable");
+        const repositoryRoot = await deps.exec("git", ["rev-parse", "--show-toplevel"], { cwd: input.cwd, timeout: TIMEOUT_MS, signal });
+        if (!repositoryRoot.code &&
+            !repositoryRoot.killed &&
+            evidenceContext.effectiveRoot)
+            evidenceContext.effectiveRoot.path = repositoryRoot.stdout.trim();
+        for (const limit of collected.limits) {
+            report.diagnose(limit.kind === "secret_pattern"
+                ? "secret_pattern"
+                : "collection_omitted", limit.kind, limit.file);
             limitations.push({
                 fact: `${limit.file} : ${limit.kind}`,
                 next: "Read the complete change before concluding.",
             });
+        }
         if (!collected.units.length) {
             emptyBase = base;
+            report.inventories.push({
+                id: "changed-units",
+                kind: "units",
+                rules: ["Changed source units against resolved base"],
+                restrictions: [],
+                discovered: known(0),
+                considered: known(0),
+                scopeRestricted: false,
+                criteria: [],
+            });
             return finish();
         }
         const collectDeadline = performance.now() + DOCS_COLLECT_BUDGET_MS;
@@ -170,6 +223,38 @@ export async function runDocsCheck(deps, input) {
             lexical: analysis,
             shouldStop: () => performance.now() >= collectDeadline || !!signal?.aborted,
         });
+        report.inventories.push({
+            id: "docs-sections",
+            kind: "sections",
+            rules: [
+                "Tracked Markdown sections referring to changed declarations or static import closure",
+                `At most ${DOCS_MAX_SECTIONS} admitted sections`,
+            ],
+            restrictions: [],
+            discovered: known(candidates.candidates.length + candidates.omitted.length),
+            considered: known(candidates.candidates.length),
+            scopeRestricted: false,
+            criteria: [],
+        });
+        for (const candidate of candidates.candidates)
+            report.expect(`docs:${candidate.path}:${candidate.start}`, `${candidate.path} § ${candidate.heading}`, "section");
+        for (const candidate of candidates.omitted) {
+            const id = `docs:${candidate.path}:${candidate.start}`;
+            report.expect(id, `${candidate.path} § ${candidate.heading}`, "section");
+            report.diagnose("collection_omitted", "Section exceeds DOCS_MAX_SECTIONS", candidate.path, [id]);
+        }
+        for (const limit of candidates.limits) {
+            if (limit.kind === "collection_budget") {
+                report.missingWork = true;
+                report.diagnose("collection_omitted", limit.reason, limit.path, [], true, [...(limit.sections ?? [])]);
+            }
+            else
+                report.diagnose("dynamic_dependency", limit.reason, limit.path, [], false);
+        }
+        for (const limit of inventory.limits)
+            report.diagnose(limit.cause === "secret_pattern"
+                ? "secret_pattern"
+                : "collection_omitted", limit.reason, limit.path);
         for (const limit of inventory.limits)
             limitations.push({
                 fact: `${limit.path} : ${limit.reason}`,
@@ -211,27 +296,35 @@ export async function runDocsCheck(deps, input) {
             unchecked.push(`${omitted.path} § ${omitted.heading} (DOCS_MAX_SECTIONS)`);
         await Promise.all(candidates.candidates.map(async (candidate) => {
             const label = `${candidate.path} § ${candidate.heading}`;
+            const reportId = `docs:${candidate.path}:${candidate.start}`;
             if (candidate.units.some((unit) => unit.before === null && unit.after === null)) {
                 unchecked.push(`${label} (changed source unavailable)`);
+                report.diagnose("binary_or_non_utf8", "Changed source unavailable", label, [reportId]);
                 return;
             }
             if (budget?.kind === "session") {
                 unchecked.push(`${label} (${budget.message})`);
+                report.diagnose("session_budget", budget.message, label, [reportId]);
                 return;
             }
             const prepared = prepareDocsCheck(candidate);
-            if (JSON.stringify(prepared.state).length > STATE_MAX_CHARS ||
+            const state = withEvidenceContext(prepared.state, evidenceContext);
+            if (JSON.stringify(state).length > STATE_MAX_CHARS ||
                 candidate.sentences.length + 1 > CHOICE_MAX_OPTIONS) {
                 unchecked.push(`${label} (state or pointer too large)`);
+                report.diagnose("evidence_too_large", "Section state or sentence pointer exceeds limits", label, [reportId]);
                 return;
             }
             if (signal?.aborted) {
                 unchecked.push(`${label} (budget exceeded or canceled)`);
+                report.diagnose("cancelled", "Collection budget exceeded or check canceled", label, [reportId]);
                 return;
             }
-            const judgment = await client.judge(prepared.state, prepared.questions, {
+            const judgment = await client.judge(state, prepared.questions, {
                 signal,
+                groups: [["status", "sentence"]],
                 ...deps.runtime.session.requestGate(),
+                admissionCause: () => budget?.kind === "session" ? "session_budget" : "call_budget",
                 beforeRequest(questionCount) {
                     if (budget?.kind === "session")
                         return { ok: false, error: budget.message };
@@ -257,6 +350,22 @@ export async function runDocsCheck(deps, input) {
                 onUsage: (usage) => deps.runtime.session.recordUsage(usage),
             });
             judgments.push(judgment);
+            if (!judgment.ok)
+                report.failure(judgment, [reportId]);
+            else {
+                const status = judgment.answers.status;
+                const pointer = judgment.answers.sentence;
+                const finding = readDocsJudgment(candidate, judgment.answers);
+                const item = report.items.get(reportId);
+                if (finding && item)
+                    item.label = `${label} — ${finding.sentence ? JSON.stringify(finding.sentence.text) : "sentence not identified"} — after ${finding.units.map((unit) => `${unit.name} (${unit.file})`).join(", ")}`;
+                report.answer(reportId, status, { band: finding?.band ?? "verdict", reason: finding?.reason }, [
+                    pointer ?? {
+                        type: "unjudged",
+                        reason: "Required sentence pointer missing",
+                    },
+                ]);
+            }
             if (!judgment.ok) {
                 unchecked.push(`${label} (${judgment.error})`);
                 return;
@@ -293,7 +402,7 @@ export async function runDocsCheck(deps, input) {
     }
     catch (error) {
         if (signal?.aborted)
-            return finish(timeout?.aborted ? "Docs budget exceeded." : "Docs check canceled.");
+            return finish(timeout?.aborted ? "Docs budget exceeded." : "Docs check canceled.", "cancelled");
         throw error;
     }
 }