@phamvuhoang/otto-core 0.30.0 → 0.32.0

package/dist/verification-evidence.js

@@ -0,0 +1,184 @@
+/**
+ * Verification evidence validation + relocation (issue #181 P24, re-review).
+ *
+ * The pure {@link isValidArtifactReference} checks an artifact reference's *shape*
+ * only. This impure layer, run at finalize against the real workspace + git,
+ * answers whether the cited proof actually **exists** — a source `file:line` whose
+ * file is present and whose line is in bounds, or a commit SHA present in git —
+ * and **relocates** scratch file artifacts (screenshots, transcripts the verify
+ * stage wrote under `.otto-tmp/`) into the durable run bundle with bundle-relative
+ * paths. Both close re-review gaps: agent-cited proof that doesn't exist no longer
+ * earns coverage, and a malicious/absolute/`..` path can neither be counted nor
+ * copied out of the workspace.
+ *
+ * INERT outside a `--verify` finalize; pure-ish (fs reads + copies into the
+ * bundle, git injected for testability).
+ */
+import { copyFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { basename, isAbsolute, join, sep } from "node:path";
+import { runReportDir } from "./run-report.js";
+import { BUNDLE_ARTIFACT_PREFIX, isValidArtifactReference, } from "./verification-matrix.js";
+const SHA_RE = /^[0-9a-f]{7,40}$/i;
+const FILE_LINE_RE = /^(.+?):(\d+)(?:-(\d+))?$/;
+/**
+ * Real on-disk path of `file` iff it resolves to a regular file **inside** the
+ * workspace — rejecting `..` traversal, absolute escapes, and symlinks that point
+ * outside (realpath is compared against the workspace's realpath). Null otherwise.
+ */
+function safeWorkspaceFile(file, workspaceDir) {
+    if (/(?:^|[\\/])\.\.(?:[\\/]|$)/.test(file))
+        return null; // traversal
+    const abs = isAbsolute(file) ? file : join(workspaceDir, file);
+    let realWs;
+    let real;
+    try {
+        realWs = realpathSync(workspaceDir);
+    }
+    catch {
+        return null;
+    }
+    try {
+        real = realpathSync(abs);
+    }
+    catch {
+        return null; // does not exist
+    }
+    if (real !== realWs && !real.startsWith(realWs + sep))
+        return null; // escaped
+    try {
+        if (!statSync(real).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return real;
+}
+/**
+ * Whether an artifact reference points to evidence that actually exists: a commit
+ * SHA present in git, or a file inside the workspace whose cited line range is in
+ * bounds. Syntactically-invalid refs / URLs / traversal are rejected first.
+ */
+export function artifactReferenceExists(ref, workspaceDir, deps) {
+    const r = ref.trim();
+    if (!isValidArtifactReference(r))
+        return false;
+    if (SHA_RE.test(r))
+        return deps.commitExists(r);
+    const m = FILE_LINE_RE.exec(r);
+    const file = m ? m[1] : r;
+    const real = safeWorkspaceFile(file, workspaceDir);
+    if (!real)
+        return false;
+    if (m) {
+        const start = Number(m[2]);
+        const end = m[3] ? Number(m[3]) : start;
+        if (start < 1 || end < start)
+            return false;
+        let lineCount;
+        try {
+            lineCount = readFileSync(real, "utf8").split("\n").length;
+        }
+        catch {
+            return false;
+        }
+        if (end > lineCount)
+            return false;
+    }
+    return true;
+}
+/**
+ * Validate every entry's artifact against the filesystem/git (setting
+ * `artifactExists`), and relocate any **scratch file** artifact (a plain path,
+ * inside the workspace, that is not a `file:line`/SHA reference) into the run
+ * bundle at `.otto/runs/<run-id>/verification/` with a bundle-relative path, so
+ * the persisted report's links resolve and the files are durable. Source
+ * `file:line` references and commit SHAs are durable already and left untouched;
+ * a path that escapes the workspace is neither counted nor copied.
+ */
+export function validateVerificationEvidence(entries, opts) {
+    const { workspaceDir, runId, commitExists } = opts;
+    let counter = 0;
+    let scratchRoot = null;
+    try {
+        scratchRoot = realpathSync(join(workspaceDir, ".otto-tmp"));
+    }
+    catch {
+        scratchRoot = null; // no scratch dir ⇒ nothing to relocate
+    }
+    // The physical run-bundle verification dir. Ensure the bundle dir exists, then
+    // realpath it (stripping any symlinks ABOVE it) and require it to stay inside
+    // the workspace; the copy destination is then this exact physical dir, and the
+    // `verification/` component itself must not be a symlink (checked per copy).
+    let destDir = null;
+    try {
+        const bundlePath = runReportDir(workspaceDir, runId);
+        mkdirSync(bundlePath, { recursive: true });
+        const bundleReal = realpathSync(bundlePath);
+        const wsReal = realpathSync(workspaceDir);
+        if (bundleReal === wsReal || bundleReal.startsWith(wsReal + sep)) {
+            destDir = join(bundleReal, "verification");
+        }
+    }
+    catch {
+        destDir = null;
+    }
+    const relocateScratch = (p) => {
+        const keep = { path: p, bundled: false };
+        if (FILE_LINE_RE.test(p) || SHA_RE.test(p))
+            return keep; // a reference, not a file
+        const real = safeWorkspaceFile(p, workspaceDir);
+        // Only relocate scratch artifacts the verify stage wrote under `.otto-tmp/`
+        // — never an arbitrary in-repo or host file (#181 re-review).
+        if (!real ||
+            !destDir ||
+            !scratchRoot ||
+            (real !== scratchRoot && !real.startsWith(scratchRoot + sep))) {
+            return keep;
+        }
+        try {
+            mkdirSync(destDir, { recursive: true });
+            // The destination must be the *physical* bundle verification dir: reject a
+            // symlinked `verification/` (which could redirect the copy into a source
+            // dir even while staying inside the workspace) by requiring its realpath to
+            // equal the path itself (#181 boundary review).
+            if (lstatSync(destDir).isSymbolicLink())
+                return keep;
+            if (realpathSync(destDir) !== destDir)
+                return keep;
+            const safe = `${counter++}-${basename(p)}`
+                .replace(/[^\w.-]+/g, "-")
+                .slice(0, 100);
+            const target = join(destDir, safe);
+            // Reject a pre-existing symlink at the target — copyFileSync would follow it.
+            try {
+                if (lstatSync(target).isSymbolicLink())
+                    return keep;
+            }
+            catch {
+                // absent target is the expected case
+            }
+            copyFileSync(real, target);
+            return { path: `${BUNDLE_ARTIFACT_PREFIX}${safe}`, bundled: true };
+        }
+        catch {
+            return keep; // best-effort: never fail finalize over a copy
+        }
+    };
+    return entries.map((e) => {
+        const next = { ...e };
+        if (e.artifactPath !== undefined) {
+            next.artifactExists = artifactReferenceExists(e.artifactPath, workspaceDir, { commitExists });
+            const r = relocateScratch(e.artifactPath);
+            next.artifactPath = r.path;
+            next.artifactBundled = r.bundled;
+        }
+        if (e.beforePath !== undefined) {
+            const r = relocateScratch(e.beforePath);
+            next.beforePath = r.path;
+            next.beforeBundled = r.bundled;
+        }
+        return next;
+    });
+}
+//# sourceMappingURL=verification-evidence.js.map

package/dist/verification-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-evidence.js","sourceRoot":"","sources":["../src/verification-evidence.ts"],"names":[],"mappings":"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"}

package/dist/verification-matrix.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Verification matrix (issue #181 P24, slice 1 — "make verification provable").
+ *
+ * A pure data model + scorer for the roadmap's verification-artifact matrix:
+ * each requirement (a plan task / acceptance criterion) paired with HOW it was
+ * checked, the concrete artifact that proves it (a `file:line`, a commit SHA, a
+ * command transcript, a screenshot path), the result, and a confidence. Today
+ * the `verify` stage emits this as free-form DONE/GAP/DEFERRED prose; P24 turns
+ * it into a structured matrix a maintainer can scan, and a "verification
+ * gallery" a non-engineer can accept/reject from.
+ *
+ * This slice is the substrate — the type, a summary scorer (counts, artifact
+ * coverage, an overall verdict), and a formatter that renders the matrix and
+ * surfaces failures / unproven requirements as explicit risks rather than
+ * burying them in logs. INERT on the loop: nothing here runs a stage or changes
+ * behavior; later P24 slices populate it from the verify stage and fold it into
+ * run reports + `otto-inspect`. Mirrors how the plan/context/report rubrics
+ * shipped pure-then-wired.
+ */
+/** How a requirement was checked. */
+export type VerificationMethod = "test" | "command" | "visual" | "inspection" | "manual";
+/** The outcome of checking a requirement. */
+export type VerificationResult = "pass" | "fail" | "partial" | "deferred";
+/** How much the evidence supports the result. */
+export type VerificationConfidence = "high" | "medium" | "low";
+/** One row of the verification matrix: a requirement and how it was proven. */
+export type VerificationEntry = {
+    /** The requirement / plan task / acceptance criterion being verified. */
+    requirement: string;
+    method: VerificationMethod;
+    /** The concrete check: the command run, the assertion, or the visual checked. */
+    check: string;
+    /** Pointer to the proving artifact: `file:line`, a commit SHA, a transcript or
+     *  screenshot path. Absent ⇒ the requirement is asserted but not artifact-backed.
+     *  For a `visual` before/after entry this is the **after** screenshot. */
+    artifactPath?: string;
+    /** For a `visual` entry, the optional **before** screenshot path, paired with
+     *  `artifactPath` (the after) for a before/after comparison. */
+    beforePath?: string;
+    /** Set by the loop's filesystem/git validation (issue #181 re-review): whether
+     *  `artifactPath` actually resolves to an existing file (with in-bounds line)
+     *  or a commit present in git. `false` ⇒ the cited proof does not exist and the
+     *  requirement is not counted as covered. Never read from agent JSON. */
+    artifactExists?: boolean;
+    /** Set true ONLY by the impure layer when `artifactPath` was actually copied
+     *  into the physical run bundle (issue #181 boundary review). Embedding trusts
+     *  this flag, not a string prefix the agent could spoof. Never read from agent JSON. */
+    artifactBundled?: boolean;
+    /** Set true ONLY by the impure layer when `beforePath` was copied into the
+     *  physical run bundle. Never read from agent JSON. */
+    beforeBundled?: boolean;
+    result: VerificationResult;
+    confidence: VerificationConfidence;
+    note?: string;
+};
+/**
+ * Whether a string is a *typed*, durable artifact reference that actually proves
+ * something — a `file:line` (or `file:line-range`), a path with a separator or a
+ * file extension (a transcript / screenshot / source file), or a 7–40 char commit
+ * SHA. A bare command (`node --test`), prose (`read the code`), or a placeholder
+ * (`TODO`) is NOT proof and returns false, so the coverage signal can't be earned
+ * by an unverifiable string (#181 review). Pure.
+ */
+export declare function isValidArtifactReference(ref: string): boolean;
+export type VerificationParseResult = {
+    /** Valid entries kept. */
+    entries: VerificationEntry[];
+    /** Rows present in the JSON array that were rejected as malformed. */
+    dropped: number;
+    /** False when the input was not parseable JSON or not an array. */
+    parsed: boolean;
+};
+/**
+ * Parse an agent-emitted verification matrix (a JSON `VerificationEntry[]`,
+ * e.g. the `.otto-tmp/verify-matrix.json` the verify stage writes), keeping the
+ * parse diagnostics so a malformed/partial matrix is reported, not silently
+ * dropped (#181 review). Tolerant: never throws, drops any entry missing a
+ * non-empty `requirement` or carrying an unknown `method`/`result`, defaults an
+ * absent/invalid `confidence` to `medium`, and counts each dropped row. Non-array
+ * / malformed JSON ⇒ `{ entries: [], dropped: 0, parsed: false }`. Pure.
+ */
+export declare function parseVerificationMatrixWithDiagnostics(raw: string): VerificationParseResult;
+/** Parse a verification matrix into valid entries (diagnostics discarded). Pure. */
+export declare function parseVerificationMatrix(raw: string): VerificationEntry[];
+export type VerificationSummary = {
+    total: number;
+    pass: number;
+    fail: number;
+    partial: number;
+    deferred: number;
+    /** Entries carrying a concrete artifact path. */
+    withArtifact: number;
+    /** Artifact-backed share of the *verifiable* (non-deferred) requirements, 0..1. */
+    coverage: number;
+    /**
+     * Overall verdict:
+     * - `empty` — nothing to verify.
+     * - `gaps` — at least one requirement failed.
+     * - `unproven` — no failures, but no verifiable requirement is artifact-backed.
+     * - `partial` — no failures, some but not all verifiable requirements proven.
+     * - `verified` — no failures and every verifiable requirement is artifact-backed.
+     */
+    verdict: "empty" | "gaps" | "unproven" | "partial" | "verified";
+};
+/** Tally a verification matrix into counts, artifact coverage, and a verdict. Pure. */
+export declare function summarizeVerification(entries: VerificationEntry[]): VerificationSummary;
+export type VerificationCoverageGate = {
+    /** True iff no requirement failed, every verifiable one is artifact-backed, and
+     *  no matrix rows were dropped during parsing. */
+    passed: boolean;
+    /** Artifact-backed share of the verifiable requirements, 0..1. */
+    coverage: number;
+    /** Verifiable requirements asserted without a valid proving artifact. */
+    unproven: string[];
+    /** Requirements that failed verification. */
+    failed: string[];
+    /** Requirements left `partial` — checked but not fully passing. */
+    incomplete: string[];
+    /** Malformed matrix rows dropped during parsing — unknown, unverified requirements. */
+    dropped: number;
+};
+/**
+ * Score a verification matrix against the roadmap's coverage bar (P24): every
+ * verifiable requirement must carry a valid artifact, none may fail, none may be
+ * left partial, and no rows may have been dropped during parsing. `dropped` rows
+ * are unknown requirements that cannot be assumed proven, so any drop FAILs the
+ * gate (#181 re-review). The `unproven`/`failed`/`incomplete` lists + `dropped`
+ * are exactly why the gate did not pass. Pure.
+ */
+export declare function scoreVerificationCoverage(entries: VerificationEntry[], dropped?: number): VerificationCoverageGate;
+/**
+ * Render the verification-coverage gate as a report block (mirrors the emit-time
+ * legibility gate): a PASS/FAIL verdict, the artifact-backed coverage, and — on
+ * FAIL — the unproven/failed requirements plus how to clear them. Empty string
+ * for an empty matrix, so a run with no verification adds no gate. Pure.
+ */
+export declare function formatVerificationCoverageGate(entries: VerificationEntry[], dropped?: number): string;
+/** Path prefix of artifacts relocated into the run bundle (see
+ *  `verification-evidence.ts`); only these resolve relative to report.md. */
+export declare const BUNDLE_ARTIFACT_PREFIX = "verification/";
+/**
+ * Render the visual evidence (P24 visual half) as a markdown "Screenshot
+ * Evidence" section that *embeds* each `visual` entry's captured screenshot —
+ * a single image, or a before → after pair — so a non-engineer reading the run
+ * report sees the proof, not just a path. Only artifacts the impure layer actually
+ * **copied into the bundle** (`artifactBundled`/`beforeBundled`) and that are
+ * images are embedded; a visual check the environment could not render, or any
+ * unbundled/spoofed path, is left to the coverage gate to flag, never emitted as
+ * an image. Empty string when no embeddable visual evidence exists. Pure.
+ */
+export declare function formatVisualEvidence(entries: VerificationEntry[]): string;
+/**
+ * Render a verification matrix as a scannable report: a header verdict line, one
+ * row per requirement (mark · method · requirement · artifact), and an explicit
+ * **Risks** section listing every failed or unproven requirement so a reader
+ * cannot miss them. Pure.
+ */
+export declare function formatVerificationMatrix(entries: VerificationEntry[]): string;
+//# sourceMappingURL=verification-matrix.d.ts.map

package/dist/verification-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-matrix.d.ts","sourceRoot":"","sources":["../src/verification-matrix.ts"],"names":[],"mappings":"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"}