@anureo/code-review 0.0.0-stage → 0.3.0

package/src/schema.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/** Internal structural schema for one analysis assignment; validatePlan checks source scope,
+ * canonical ownership and ID limits after structured output parsing. Unknown fields are rejected. */
+export const moduleSchema = z.strictObject({
+    /** Exact selection identity; validatePlan rejects duplicates and IDs over 256 UTF-8 bytes. */
+    id: z.string().min(1),
+    name: z.string().min(1),
+    /** Module responsibilities passed to the angle agent with the source assignment. */
+    description: z.string().min(1),
+    /** Nonempty source list relative to the review directory; aliases are normalized by validatePlan. */
+    files: z.array(z.string().min(1)).min(1),
+});
+/** Internal structured output contract submitted by analyzeModules; requires a nonempty plan
+ * and rejects unknown fields. Filesystem validity and ownership are checked by validatePlan. */
+export const modulePlanSchema = z.strictObject({
+    /** Analysis overview retained in the plan and printed by formatReport. */
+    summary: z.string().min(1),
+    modules: z.array(moduleSchema).min(1),
+});
+/** Severity values accepted for Finding.severity.
+ * The findings schema and review prompt both derive their vocabulary from this list. */
+export const findingSeverities = ['P0', 'P1', 'P2', 'P3'];
+/** Internal finding shape used by reviewOutputSchema. Rejects unknown fields; validateFindings
+ * separately checks canonical module ownership and inclusive ranges against current source text. */
+export const findingSchema = z.strictObject({
+    severity: z.enum(findingSeverities),
+    title: z.string().min(1),
+    body: z.string().min(1),
+    /** Actionable remedy text, retained for reporting and the optional fix task. */
+    suggestion: z.string().min(1),
+    /** Source path relative to the directory reviewed by the agent. */
+    file: z.string().min(1),
+    /** First source line, 1-based and inclusive. */
+    lineStart: z.number().int().min(1),
+    /** Last source line, inclusive; ordering and file bounds require validateFindings. */
+    lineEnd: z.number().int().min(1),
+});
+/** Internal output schema supplied by reviewAngle for review and verification agents.
+ * An empty findings array is valid. validateFindings checks source locations after parsing. */
+export const reviewOutputSchema = z.strictObject({ findings: z.array(findingSchema) });
+/** Internal output schema supplied by applyFix for the agent's result after editing sources.
+ * applyFix checks Git state and observed edits before applying a patch to the original tree. */
+export const fixResultSchema = z.strictObject({
+    summary: z.string().min(1),
+    /** Agent-reported paths. The field is required and may be empty. */
+    changedFiles: z.array(z.string().min(1)),
+});

package/src/validation.d.ts

@@ -0,0 +1,21 @@
+import type { Finding, ModulePlan, ReviewModule } from "./schema.js";
+/** Check the listed assignments in a schema-parsed plan and return a copy with canonical,
+ * slash-separated paths relative to cwd. Pass the canonical absolute review directory and
+ * absolute workflow storage path for the source view being checked. Duplicate or oversized IDs,
+ * duplicate file ownership, invalid paths and filesystem failures reject in traversal order.
+ *
+ * analyzeModules checks the agent's source view first and, in fix mode, checks the resulting
+ * assignments against the original tree before selecting modules. A rejection prevents dispatch. */
+export declare function validatePlan(cwd: string, plan: ModulePlan, workflowDirectory: string): Promise<ModulePlan>;
+/** Return copies of schema-parsed findings with canonical source paths, preserving order.
+ * Requires canonical absolute cwd, absolute workflow storage and a module from validatePlan.
+ * Checks ownership and inclusive ranges using one UTF-8 read per canonical file in this call,
+ * with no source lock.
+ * Invalid paths, ownership, ranges or filesystem failures reject. reviewAngle awaits the check
+ * inside withAgentWorktree before returning completed findings or recording failed coverage. */
+export declare function validateFindings(cwd: string, module: ReviewModule, findings: Finding[], workflowDirectory: string): Promise<Finding[]>;
+/** Invoke the supplied local validator once and await its value. A synchronous throw or rejection
+ * becomes REVIEW_VALIDATION_FAILED, with the original Error message or a generic message.
+ * analyzeModules and reviewAngle supply callbacks after the agent returns. Analysis propagates
+ * this failure, while reviewAngle records it as failed coverage. */
+export declare function validateOutput<T>(validate: () => Promise<T>): Promise<T>;

package/src/validation.js

@@ -0,0 +1,105 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { HarnessSdkError } from '@anureo/sdk';
+import { assertReviewablePath, isInsideDirectory } from "./paths.js";
+/** Check the listed assignments in a schema-parsed plan and return a copy with canonical,
+ * slash-separated paths relative to cwd. Pass the canonical absolute review directory and
+ * absolute workflow storage path for the source view being checked. Duplicate or oversized IDs,
+ * duplicate file ownership, invalid paths and filesystem failures reject in traversal order.
+ *
+ * analyzeModules checks the agent's source view first and, in fix mode, checks the resulting
+ * assignments against the original tree before selecting modules. A rejection prevents dispatch. */
+export async function validatePlan(cwd, plan, workflowDirectory) {
+    const claimedIds = new Set();
+    const claimedFiles = new Set();
+    const modules = [];
+    for (const module of plan.modules) {
+        claimModuleId(module.id, claimedIds);
+        const files = [];
+        for (const file of module.files) {
+            const canonicalFile = await resolveReviewableSourcePath(cwd, file, workflowDirectory);
+            claimSourceFile(canonicalFile, claimedFiles);
+            files.push(canonicalFile);
+        }
+        modules.push({ ...module, files });
+    }
+    return { ...plan, modules };
+}
+/** Return copies of schema-parsed findings with canonical source paths, preserving order.
+ * Requires canonical absolute cwd, absolute workflow storage and a module from validatePlan.
+ * Checks ownership and inclusive ranges using one UTF-8 read per canonical file in this call,
+ * with no source lock.
+ * Invalid paths, ownership, ranges or filesystem failures reject. reviewAngle awaits the check
+ * inside withAgentWorktree before returning completed findings or recording failed coverage. */
+export async function validateFindings(cwd, module, findings, workflowDirectory) {
+    const lineCounts = new Map();
+    const validated = [];
+    for (const finding of findings) {
+        const file = await resolveReviewableSourcePath(cwd, finding.file, workflowDirectory);
+        if (!module.files.includes(file))
+            throw new Error(`Finding is outside module ${module.id}: ${file}`);
+        let lines = lineCounts.get(file);
+        if (lines === undefined) {
+            const text = await readFile(resolve(cwd, file), 'utf8');
+            lines = countSourceLines(text);
+            lineCounts.set(file, lines);
+        }
+        assertFindingLocation(finding, file, lines);
+        validated.push({ ...finding, file });
+    }
+    return validated;
+}
+/** Invoke the supplied local validator once and await its value. A synchronous throw or rejection
+ * becomes REVIEW_VALIDATION_FAILED, with the original Error message or a generic message.
+ * analyzeModules and reviewAngle supply callbacks after the agent returns. Analysis propagates
+ * this failure, while reviewAngle records it as failed coverage. */
+export async function validateOutput(validate) {
+    try {
+        return await validate();
+    }
+    catch (cause) {
+        throw new HarnessSdkError('REVIEW_VALIDATION_FAILED', cause instanceof Error ? cause.message : 'Invalid review output');
+    }
+}
+/** Reserve the exact ID after checking uniqueness and the same 256-byte UTF-8 cap
+ * applied to caller-selected module IDs. */
+function claimModuleId(id, claimedIds) {
+    if (claimedIds.has(id))
+        throw new Error(`Duplicate module id: ${id}`);
+    if (Buffer.byteLength(id) > 256)
+        throw new Error(`Module id is too long (max 256 bytes): ${id.slice(0, 64)}`);
+    claimedIds.add(id);
+}
+/** Claim a canonical relative path in the plan-wide ownership set. Reject repeated claims
+ * within a module or across modules, including paths that resolved from different aliases. */
+function claimSourceFile(file, claimedFiles) {
+    if (claimedFiles.has(file))
+        throw new Error(`Source file assigned more than once: ${file}`);
+    claimedFiles.add(file);
+}
+/** Resolve one relative source path for both validators, rejecting storage, metadata, escapes,
+ * non-files and filesystem failures. Resolve symlinks before scope checks so aliases cannot
+ * disguise excluded targets; return the canonical path relative to cwd with '/' separators. */
+async function resolveReviewableSourcePath(cwd, file, workflowDirectory) {
+    if (isAbsolute(file))
+        throw new Error(`Expected a relative source path: ${file}`);
+    const absolute = await realpath(resolve(cwd, file));
+    await assertReviewablePath(cwd, absolute, workflowDirectory);
+    if (!isInsideDirectory(cwd, absolute) || !(await stat(absolute)).isFile()) {
+        throw new Error(`Source file is outside the review directory or is not a file: ${file}`);
+    }
+    return relative(cwd, absolute).split(sep).join('/');
+}
+/** Count addressable source lines across CRLF and single-character line terminators.
+ * A final terminator does not create an extra line; empty files have no valid finding location. */
+function countSourceLines(text) {
+    const segments = text.split(/\r\n|[\n\r\u2028\u2029]/u);
+    return text.length === 0 ? 0 : segments.length - (segments.at(-1) === '' ? 1 : 0);
+}
+/** Reject a schema-parsed finding unless its inclusive range fits the observed source line count.
+ * Keep the normalized path in the diagnostic, matching the finding returned on success. */
+function assertFindingLocation(finding, file, lines) {
+    if (finding.lineStart < 1 || finding.lineEnd < finding.lineStart || finding.lineEnd > lines) {
+        throw new Error(`Invalid finding location: ${file}:${finding.lineStart}-${finding.lineEnd}; expected 1 <= lineStart <= lineEnd <= ${lines}`);
+    }
+}

package/src/worktree.d.ts

@@ -0,0 +1,23 @@
+/** Internal checkout paths valid during the withAgentWorktree callback. */
+export interface AgentWorktree {
+    /** Absolute Git root of the detached checkout. */
+    root: string;
+    /** Absolute parent directory where applyFix stages its baseline and patch. */
+    scratch: string;
+}
+/** Run one agent operation and await its result and any checkout cleanup.
+ * Supply cwd and the workflow storage directory as absolute paths. If supplied, root must be
+ * the canonical Git root containing cwd.
+ * With a root, the callback receives a checkout-local cwd and any in-repository storage path
+ * is remapped for validation. Without a root, the callback receives the original paths and
+ * no checkout handle. Await all checkout access inside the callback, including patch staging.
+ *
+ * analyzeModules uses the returned plan before dispatching reviews. reviewAngle and applyFix
+ * report checkout rejections as failed angle or fix results, respectively.
+ * Setup or callback failures propagate even if cleanup also fails. Cleanup alone rejects with
+ * REVIEW_FIX_CLEANUP and can leave files behind, even after applyFix patches the original tree. */
+export declare function withAgentWorktree<T>(options: {
+    root?: string;
+    cwd: string;
+    directory: string;
+}, use: (cwd: string, directory: string, worktree?: AgentWorktree) => Promise<T>): Promise<T>;

package/src/worktree.js

@@ -0,0 +1,117 @@
+// Creates a private Git checkout of the current source for one agent session.
+import { copyFile, lstat, mkdir, mkdtemp, realpath, rm, readlink, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, relative, resolve } from 'node:path';
+import { HarnessSdkError } from '@anureo/sdk';
+import { reviewGit } from "./git.js";
+import { hasOperationalPathSegment, isInsideDirectory } from "./paths.js";
+/** Run one agent operation and await its result and any checkout cleanup.
+ * Supply cwd and the workflow storage directory as absolute paths. If supplied, root must be
+ * the canonical Git root containing cwd.
+ * With a root, the callback receives a checkout-local cwd and any in-repository storage path
+ * is remapped for validation. Without a root, the callback receives the original paths and
+ * no checkout handle. Await all checkout access inside the callback, including patch staging.
+ *
+ * analyzeModules uses the returned plan before dispatching reviews. reviewAngle and applyFix
+ * report checkout rejections as failed angle or fix results, respectively.
+ * Setup or callback failures propagate even if cleanup also fails. Cleanup alone rejects with
+ * REVIEW_FIX_CLEANUP and can leave files behind, even after applyFix patches the original tree. */
+export async function withAgentWorktree(options, use) {
+    const { root, cwd, directory } = options;
+    if (root === undefined)
+        return use(cwd, directory);
+    const scratch = await mkdtemp(resolve(await realpath(tmpdir()), 'anureo-review-'));
+    const checkout = resolve(scratch, 'checkout');
+    const worktree = { root: checkout, scratch };
+    let registered = false;
+    let failed = false;
+    try {
+        const head = await registerCheckout(root, worktree);
+        registered = true;
+        await reviewGit(checkout, 'read-tree', head);
+        await copySource(root, checkout, directory);
+        const localCwd = resolve(checkout, relative(root, cwd));
+        const localDirectory = isInsideDirectory(root, directory) ? resolve(checkout, relative(root, directory)) : directory;
+        await mkdir(localCwd, { recursive: true });
+        return await use(localCwd, localDirectory, worktree);
+    }
+    catch (cause) {
+        failed = true;
+        throw cause;
+    }
+    finally {
+        try {
+            if (registered)
+                await reviewGit(root, 'worktree', 'remove', '--force', checkout);
+            await rm(scratch, { recursive: true, force: true });
+        }
+        catch (cause) {
+            if (!failed)
+                throw new HarnessSdkError('REVIEW_FIX_CLEANUP', `Could not remove temporary worktree at ${checkout}`, false, false, { cause });
+            // A secondary cleanup failure must not hide a setup or callback failure.
+        }
+    }
+}
+/** Register a detached checkout with hooks disabled and return the baseline for its index.
+ * Fall back to an empty commit if HEAD lookup fails, including on an unborn branch. Reject on
+ * registration failure. withAgentWorktree owns index initialization, source copying and removal. */
+async function registerCheckout(root, worktree) {
+    const head = await reviewGit(root, 'rev-parse', '--verify', 'HEAD').then(value => value.trim(), () => emptyCommit(root, worktree.scratch));
+    await reviewGit(root, '-c', 'core.hooksPath=' + resolve(worktree.scratch, 'hooks'), 'worktree', 'add', '--detach', '--no-checkout', worktree.root, head);
+    return head;
+}
+/** Write a fallback tree and commit into the source repository's object store without updating
+ * refs. registerCheckout awaits the commit ID and propagates filesystem and Git failures. */
+async function emptyCommit(root, scratch) {
+    const empty = resolve(scratch, 'empty');
+    await writeFile(empty, '');
+    const tree = (await reviewGit(root, 'hash-object', '-w', '-t', 'tree', '--no-filters', empty)).trim();
+    return (await reviewGit(root, '-c', 'user.name=Anureo', '-c', 'user.email=anureo@localhost', '-c', 'commit.gpgSign=false', 'commit-tree', tree, '-m', 'Empty review baseline')).trim();
+}
+/** Copy current tracked and non-ignored untracked files before withAgentWorktree invokes its
+ * callback. Exclude operational paths and both the configured and resolved workflow storage
+ * paths. Reads are sequential and acquire no lock. Git or unexpected copy failures reject. */
+async function copySource(root, checkout, directory) {
+    const storage = await realpath(directory).catch(() => directory);
+    const files = new Set((await reviewGit(root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard')).split('\0'));
+    for (const file of files) {
+        if (!file || hasOperationalPathSegment(file.split('/')))
+            continue;
+        const source = resolve(root, file);
+        if (isInsideDirectory(storage, source) || isInsideDirectory(directory, source))
+            continue;
+        await copySourceEntry({ root, checkout, file, source });
+    }
+}
+/** Materialize regular files and symlinks with lexical targets inside root, rebasing links to
+ * the checkout. Treat ENOENT and ENOTDIR as absent entries because the index can still list
+ * deleted paths. Other copy failures propagate to copySource. */
+async function copySourceEntry({ root, checkout, file, source }) {
+    const parent = dirname(source);
+    try {
+        // Git can list old indexed children of a directory replaced by a symlink.
+        if (await realpath(parent) !== parent)
+            return;
+        const info = await lstat(source);
+        const target = resolve(checkout, file);
+        const targetParent = dirname(target);
+        if (info.isFile()) {
+            await mkdir(targetParent, { recursive: true });
+            await copyFile(source, target);
+        }
+        else if (info.isSymbolicLink()) {
+            const link = resolve(parent, await readlink(source));
+            if (!isInsideDirectory(root, link))
+                return;
+            await mkdir(targetParent, { recursive: true });
+            const localLink = relative(targetParent, resolve(checkout, relative(root, link))) || '.';
+            const type = await lstat(link).then(value => value.isDirectory() ? 'dir' : 'file', () => 'file');
+            await symlink(localLink, target, type);
+        }
+    }
+    catch (cause) {
+        const code = cause && typeof cause === 'object' && 'code' in cause ? String(cause.code) : undefined;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR')
+            throw cause;
+    }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.