@ttfw/envoi 1.0.0

package/dist/lib/judge.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Judge phase: Compute touched files from git diff.
+ *
+ * Provides functions to analyze git changes and categorize files
+ * for scope guardrail enforcement.
+ */
+import type { TaskScope, DiffLimits } from '../types/task.js';
+import type { ScopeConfig } from '../types/config.js';
+import type { ReportCode } from '../types/report.js';
+import type { BlastRadius } from '../types/report.js';
+/**
+ * Categorized list of files touched since a base commit.
+ */
+export interface TouchedFiles {
+    /** Files that were modified */
+    modified: string[];
+    /** Files that were added */
+    added: string[];
+    /** Files that were deleted */
+    deleted: string[];
+    /** Files that were renamed (with old and new paths) */
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Files that are untracked (new files not yet committed) */
+    untracked: string[];
+    /** Union of all file paths (excluding deleted files) */
+    all: string[];
+}
+/**
+ * Parsed result from git diff --name-status output.
+ */
+interface ParsedDiffStatus {
+    modified: string[];
+    added: string[];
+    deleted: string[];
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+/**
+ * Parses git diff --name-status output into categorized file lists.
+ *
+ * Git diff --name-status format:
+ * - M <path> - Modified
+ * - A <path> - Added
+ * - D <path> - Deleted
+ * - R<score> <old> <new> - Renamed (tab-separated, e.g., R100\told\tnew)
+ *
+ * This is a pure function that can be easily tested.
+ *
+ * @param output - Raw output from `git diff --name-status <base>...HEAD`
+ * @returns Object with categorized file lists
+ *
+ * @example
+ * ```typescript
+ * const diffOutput = 'M\tfile1.ts\nA\tfile2.ts\nR100\told.ts\tnew.ts\n';
+ * const result = parseGitDiffNameStatus(diffOutput);
+ * // result.modified = ['file1.ts']
+ * // result.added = ['file2.ts']
+ * // result.renamed = [{ from: 'old.ts', to: 'new.ts' }]
+ * ```
+ */
+export declare function parseGitDiffNameStatus(output: string): ParsedDiffStatus;
+/**
+ * Gets all files touched since a base commit using git diff --name-status
+ * and git status --porcelain.
+ *
+ * Combines:
+ * - Tracked file changes (modified, added, deleted, renamed) from git diff
+ * - Untracked files from git status
+ *
+ * @param baseCommit - The base commit SHA to diff against (e.g., 'main' or commit hash)
+ * @returns TouchedFiles object with categorized file lists
+ * @throws {Error} If git commands fail
+ *
+ * @example
+ * ```typescript
+ * const touched = getTouchedFiles('main');
+ * console.log(`Modified: ${touched.modified.length}`);
+ * console.log(`All files: ${touched.all.join(', ')}`);
+ * ```
+ */
+export declare function getTouchedFiles(baseCommit: string): TouchedFiles;
+/**
+ * Result of scope violation checking.
+ */
+export interface ScopeCheckResult {
+    /** True if no violations found */
+    ok: boolean;
+    /** Stop code if violation found, null otherwise */
+    stopCode: ReportCode | null;
+    /** List of file paths that caused the violation */
+    violatingFiles: string[];
+    /** Human-readable reason for the violation */
+    reason: string | null;
+}
+/**
+ * Checks touched files against scope rules and returns first violation or success.
+ *
+ * Checks are performed in priority order:
+ * 1. Runner-owned mutation (highest priority)
+ * 2. Forbidden globs
+ * 3. Outside allowed globs
+ * 4. New file when not allowed
+ * 5. Lockfile change when not allowed
+ *
+ * Returns the first violation found, or success if no violations.
+ *
+ * @param touched - TouchedFiles object with categorized file lists
+ * @param taskScope - Task scope configuration with allowed/forbidden globs and permissions
+ * @param scopeConfig - Scope configuration with lockfiles list
+ * @param runnerOwnedGlobs - Glob patterns for files owned by the runner
+ * @returns ScopeCheckResult with stopCode and violatingFiles
+ *
+ * @example
+ * ```typescript
+ * const result = checkScopeViolations(
+ *   { modified: ['src/utils.ts'], added: ['src/new.ts'], deleted: [], renamed: [], untracked: ['src/new.ts'], all: ['src/utils.ts', 'src/new.ts'] },
+ *   { allowed_globs: ['src/**'], forbidden_globs: ['*.key'], allow_new_files: false, allow_lockfile_changes: true },
+ *   { lockfiles: ['package-lock.json'], default_allowed_globs: [], default_forbidden_globs: [], default_allow_new_files: true, default_allow_lockfile_changes: false },
+ *   ['pilot/**']
+ * );
+ * if (!result.ok) {
+ *   console.error(`Violation: ${result.stopCode}`, result.violatingFiles);
+ * }
+ * ```
+ */
+export declare function checkScopeViolations(touched: TouchedFiles, taskScope: TaskScope, scopeConfig: ScopeConfig, runnerOwnedGlobs: string[]): ScopeCheckResult;
+/**
+ * Result of diff limits checking.
+ */
+export interface DiffCheckResult {
+    /** True if within limits, false if limits exceeded */
+    ok: boolean;
+    /** Stop code if limits exceeded, null otherwise */
+    stopCode: 'STOP_DIFF_TOO_LARGE' | null;
+    /** Blast radius metrics */
+    blastRadius: BlastRadius;
+    /** Human-readable reason for the violation */
+    reason: string | null;
+}
+/**
+ * Parses git diff --stat output to extract line counts.
+ *
+ * Git diff --stat format:
+ * - Individual file lines: " file.ts | N +++++" or " file.ts | N +++---"
+ * - Summary line: "N files changed, M insertions(+), K deletions(-)"
+ *
+ * This function extracts the summary line totals.
+ *
+ * @param output - Raw output from `git diff --stat <base>...HEAD`
+ * @returns Object with linesAdded and linesDeleted totals
+ *
+ * @example
+ * ```typescript
+ * const diffStat = ' file1.ts | 5 +++++\n file2.ts | 3 ---\n 2 files changed, 5 insertions(+), 3 deletions(-)';
+ * const result = parseGitDiffStat(diffStat);
+ * // result.linesAdded = 5
+ * // result.linesDeleted = 3
+ * ```
+ */
+export declare function parseGitDiffStat(output: string): {
+    linesAdded: number;
+    linesDeleted: number;
+};
+/**
+ * Computes blast radius metrics from git diff.
+ *
+ * Uses git diff --stat to get line counts and TouchedFiles to get file counts.
+ *
+ * @param baseCommit - The base commit SHA to diff against (e.g., 'main' or commit hash)
+ * @param touched - TouchedFiles object with categorized file lists
+ * @returns BlastRadius object with file and line counts
+ * @throws {Error} If git diff --stat command fails
+ *
+ * @example
+ * ```typescript
+ * const touched = getTouchedFiles('main');
+ * const blastRadius = computeBlastRadius('main', touched);
+ * console.log(`Files touched: ${blastRadius.files_touched}`);
+ * console.log(`Lines added: ${blastRadius.lines_added}`);
+ * ```
+ */
+export declare function computeBlastRadius(baseCommit: string, touched: TouchedFiles): BlastRadius;
+/**
+ * Checks blast radius against configured diff limits.
+ *
+ * Returns STOP_DIFF_TOO_LARGE if either limit is exceeded:
+ * - files_touched > max_files_touched
+ * - lines_changed (added + deleted) > max_lines_changed
+ *
+ * @param blastRadius - Blast radius metrics from computeBlastRadius
+ * @param limits - Diff limits configuration
+ * @returns DiffCheckResult with ok status and stopCode
+ *
+ * @example
+ * ```typescript
+ * const blastRadius = computeBlastRadius('main', touched);
+ * const result = checkDiffLimits(blastRadius, { max_files_touched: 10, max_lines_changed: 100 });
+ * if (!result.ok) {
+ *   console.error(`Violation: ${result.stopCode}`, result.reason);
+ * }
+ * ```
+ */
+export declare function checkDiffLimits(blastRadius: BlastRadius, limits: DiffLimits): DiffCheckResult;
+/**
+ * Result of HEAD-moved check (JUDGE phase).
+ * Detects if HEAD was moved externally during a tick (e.g. force push, external commit).
+ */
+export interface HeadCheckResult {
+    /** True if HEAD is still at expected commit or a descendant of it */
+    ok: boolean;
+    /** 'STOP_HEAD_MOVED' if HEAD was moved externally, null otherwise */
+    stopCode: 'STOP_HEAD_MOVED' | null;
+    /** The base commit we expected (stored at tick start) */
+    expectedHead: string;
+    /** Current HEAD commit SHA */
+    actualHead: string;
+    /** Human-readable reason when not ok */
+    reason: string | null;
+}
+/**
+ * Checks if HEAD is still at the expected commit (or a descendant of it).
+ *
+ * - If HEAD === expectedBaseCommit → ok (no changes yet).
+ * - If expectedBaseCommit is ancestor of HEAD → ok (builder made commits).
+ * - Otherwise → HEAD was moved externally (force push, external commit, branch switch) → STOP_HEAD_MOVED.
+ *
+ * @param expectedBaseCommit - The base commit SHA stored at tick start
+ * @returns HeadCheckResult with ok, stopCode, expectedHead, actualHead, reason
+ */
+export declare function checkHeadMoved(expectedBaseCommit: string): HeadCheckResult;
+export {};
+//# sourceMappingURL=judge.d.ts.map

package/dist/lib/judge.d.ts.map

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