@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/scripts/lib/review-scope-advisory.js

@@ -0,0 +1,286 @@
+import { execFile } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { parseNameStatusPathCollection, parseStatusZPathCollection, parseStatusZPaths } from './review-scope-paths.js';
+const execFileAsync = promisify(execFile);
+const DEFAULT_LARGE_SCOPE_FILE_THRESHOLD = 25;
+const DEFAULT_LARGE_SCOPE_LINE_THRESHOLD = 1200;
+const REVIEW_LARGE_SCOPE_FILE_THRESHOLD_ENV_KEY = 'CODEX_REVIEW_LARGE_SCOPE_FILE_THRESHOLD';
+const REVIEW_LARGE_SCOPE_LINE_THRESHOLD_ENV_KEY = 'CODEX_REVIEW_LARGE_SCOPE_LINE_THRESHOLD';
+export const REVIEW_LARGE_SCOPE_OVERRIDE_REASON_ENV_KEY = 'CODEX_REVIEW_LARGE_SCOPE_OVERRIDE_REASON';
+const IGNORED_REVIEW_SCOPE_PREFIXES = ['.agent/task/', 'tasks/tasks-'];
+export async function collectReviewScopePaths(options, repoRoot) {
+    if (options.commit) {
+        const summary = await tryGit(['show', '--no-color', '--name-status', '--format=', options.commit], repoRoot);
+        return summary ? parseNameStatusPathCollection(summary) : { paths: [], renderedLines: [] };
+    }
+    if (options.base) {
+        const diff = await tryGit(['diff', '--no-color', '--name-status', `${options.base}...HEAD`], repoRoot);
+        return diff ? parseNameStatusPathCollection(diff) : { paths: [], renderedLines: [] };
+    }
+    const status = await tryGit(['status', '--porcelain=v1', '-z', '--untracked-files=all'], repoRoot);
+    return status ? parseStatusZPathCollection(status) : { paths: [], renderedLines: [] };
+}
+export function resolveEffectiveScopeMode(options) {
+    if (options.commit) {
+        return 'commit';
+    }
+    if (options.base) {
+        return 'base';
+    }
+    return 'uncommitted';
+}
+export function buildScopeNotes(options, scopePathCollection) {
+    const lines = [];
+    const scopePaths = scopePathCollection.paths;
+    const renderedScopeLines = scopePathCollection.renderedLines;
+    if (options.commit) {
+        lines.push(`Review scope hint: commit \`${options.commit}\``);
+    }
+    else if (options.base) {
+        lines.push(`Review scope hint: diff vs base \`${options.base}\``);
+    }
+    else {
+        lines.push('Review scope hint: uncommitted working tree changes (default).');
+    }
+    if (scopePaths.length > 0) {
+        lines.push('', `Review scope paths (${scopePaths.length}):`, '```', ...renderedScopeLines, '```');
+    }
+    else {
+        lines.push('', 'Review scope paths: unavailable or empty.');
+    }
+    return lines;
+}
+export async function assessReviewScope(options, repoRoot, env = process.env) {
+    const mode = resolveEffectiveScopeMode(options);
+    const fileThreshold = resolveLargeScopeFileThreshold(env);
+    const lineThreshold = resolveLargeScopeLineThreshold(env);
+    if (mode !== 'uncommitted') {
+        return {
+            mode,
+            changedFiles: null,
+            changedLines: null,
+            largeScope: false,
+            fileThreshold,
+            lineThreshold
+        };
+    }
+    const status = await tryGit(['status', '--porcelain=v1', '-z', '--untracked-files=all'], repoRoot);
+    const diff = await tryGit(['diff', '--numstat', '--no-renames'], repoRoot);
+    const cachedDiff = await tryGit(['diff', '--cached', '--numstat', '--no-renames'], repoRoot);
+    const untracked = await tryGit(['ls-files', '--others', '--exclude-standard', '-z'], repoRoot);
+    const untrackedPaths = untracked
+        ? parseNullDelimitedPaths(untracked).filter((filePath) => !isIgnoredReviewScopePath(filePath))
+        : [];
+    const untrackedLines = untrackedPaths.length > 0 ? await countWorkingTreeLines(untrackedPaths, repoRoot) : null;
+    const changedFiles = status
+        ? parseStatusZPaths(status).filter((filePath) => !isIgnoredReviewScopePath(filePath)).length
+        : null;
+    let changedLines = null;
+    if (diff || cachedDiff || untrackedLines !== null) {
+        changedLines = 0;
+        if (diff) {
+            changedLines += parseNumstatLineDelta(diff);
+        }
+        if (cachedDiff) {
+            changedLines += parseNumstatLineDelta(cachedDiff);
+        }
+        if (untrackedLines !== null) {
+            changedLines += untrackedLines;
+        }
+    }
+    const exceedsFileThreshold = changedFiles !== null && changedFiles >= fileThreshold;
+    const exceedsLineThreshold = changedLines !== null && changedLines >= lineThreshold;
+    return {
+        mode,
+        changedFiles,
+        changedLines,
+        largeScope: exceedsFileThreshold || exceedsLineThreshold,
+        fileThreshold,
+        lineThreshold
+    };
+}
+export function formatScopeMetrics(scope) {
+    const parts = [];
+    if (scope.changedFiles !== null) {
+        parts.push(`${scope.changedFiles} files`);
+    }
+    if (scope.changedLines !== null) {
+        parts.push(`${scope.changedLines} lines`);
+    }
+    if (parts.length === 0) {
+        return null;
+    }
+    return parts.join(', ');
+}
+export function logReviewScopeAssessment(scope, scopeMetrics, logger = console, overrideReason = null) {
+    if (scope.mode !== 'uncommitted') {
+        return;
+    }
+    if (scopeMetrics) {
+        logger.log(`[run-review] review scope metrics: ${scopeMetrics}.`);
+    }
+    else {
+        logger.log('[run-review] review scope metrics unavailable (git scope stats could not be resolved).');
+    }
+    if (!scope.largeScope) {
+        return;
+    }
+    const detail = scopeMetrics ?? 'metrics unavailable';
+    logger.warn(`[run-review] large uncommitted review scope detected (${detail}; thresholds: ${scope.fileThreshold} files / ${scope.lineThreshold} lines).`);
+    if (overrideReason) {
+        logger.warn(`[run-review] large uncommitted review scope override accepted via ${REVIEW_LARGE_SCOPE_OVERRIDE_REASON_ENV_KEY}: ${overrideReason}`);
+        return;
+    }
+    logger.warn(`[run-review] large uncommitted review scope now requires --base/--commit or ${REVIEW_LARGE_SCOPE_OVERRIDE_REASON_ENV_KEY} for an auditable override.`);
+}
+export function buildLargeScopeAdvisoryPromptLines(scope, scopeMetrics, overrideReason = null) {
+    if (scope.mode !== 'uncommitted' || !scope.largeScope) {
+        return [];
+    }
+    const detail = scopeMetrics ?? 'metrics unavailable';
+    const lines = [
+        `Scope advisory: large uncommitted diff detected (${detail}; thresholds: ${scope.fileThreshold} files / ${scope.lineThreshold} lines).`,
+    ];
+    if (overrideReason) {
+        lines.push(`Large-scope override recorded: ${overrideReason}`);
+    }
+    lines.push('Prioritize highest-risk findings first and report actionable issues early; avoid exhaustive low-signal traversal before surfacing initial findings.', 'If full coverage is incomplete, call out residual risk areas explicitly.');
+    return lines;
+}
+export function resolveLargeScopeOverrideReason(env = process.env) {
+    const reason = env[REVIEW_LARGE_SCOPE_OVERRIDE_REASON_ENV_KEY]?.trim();
+    return reason && reason.length > 0 ? reason : null;
+}
+export function getLargeScopeGateError(scope, scopeMetrics, overrideReason) {
+    if (scope.mode !== 'uncommitted' || !scope.largeScope || overrideReason) {
+        return null;
+    }
+    const detail = scopeMetrics ?? 'metrics unavailable';
+    return `large uncommitted review scope requires explicit scoping or override (${detail}; thresholds: ${scope.fileThreshold} files / ${scope.lineThreshold} lines). Rerun with --base <ref> or --commit <sha>, or set ${REVIEW_LARGE_SCOPE_OVERRIDE_REASON_ENV_KEY}=\"<reason>\" to record an auditable override.`;
+}
+function resolveLargeScopeFileThreshold(env) {
+    const configured = env[REVIEW_LARGE_SCOPE_FILE_THRESHOLD_ENV_KEY]?.trim();
+    if (!configured) {
+        return DEFAULT_LARGE_SCOPE_FILE_THRESHOLD;
+    }
+    const parsed = Number(configured);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${REVIEW_LARGE_SCOPE_FILE_THRESHOLD_ENV_KEY} must be a positive integer.`);
+    }
+    return parsed;
+}
+function resolveLargeScopeLineThreshold(env) {
+    const configured = env[REVIEW_LARGE_SCOPE_LINE_THRESHOLD_ENV_KEY]?.trim();
+    if (!configured) {
+        return DEFAULT_LARGE_SCOPE_LINE_THRESHOLD;
+    }
+    const parsed = Number(configured);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${REVIEW_LARGE_SCOPE_LINE_THRESHOLD_ENV_KEY} must be a positive integer.`);
+    }
+    return parsed;
+}
+function parseNumstatLineDelta(numstatOutput) {
+    let total = 0;
+    for (const rawLine of numstatOutput.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (!line) {
+            continue;
+        }
+        const [added, deleted, ...rest] = line.split(/\s+/u);
+        const filePath = rest.join(' ').trim();
+        if (!filePath || isIgnoredReviewScopePath(filePath)) {
+            continue;
+        }
+        const addCount = Number(added);
+        const delCount = Number(deleted);
+        total += Number.isFinite(addCount) ? addCount : 0;
+        total += Number.isFinite(delCount) ? delCount : 0;
+    }
+    return total;
+}
+function parseNullDelimitedPaths(raw) {
+    return raw.split('\u0000').filter((entry) => entry.length > 0);
+}
+function isIgnoredReviewScopePath(filePath) {
+    return IGNORED_REVIEW_SCOPE_PREFIXES.some((prefix) => filePath.startsWith(prefix));
+}
+async function countWorkingTreeFileLines(relativePath, repoRoot) {
+    const absolutePath = path.resolve(repoRoot, relativePath);
+    try {
+        const fileStat = await stat(absolutePath);
+        if (!fileStat.isFile()) {
+            return 0;
+        }
+    }
+    catch {
+        return 0;
+    }
+    return await new Promise((resolve) => {
+        const stream = createReadStream(absolutePath);
+        let sawData = false;
+        let sawBinaryByte = false;
+        let newlineCount = 0;
+        let lastByte = 0;
+        let settled = false;
+        const settle = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(value);
+        };
+        stream.once('error', () => settle(0));
+        stream.on('data', (chunk) => {
+            const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+            if (!buffer || buffer.length === 0) {
+                return;
+            }
+            sawData = true;
+            if (buffer.includes(0x00)) {
+                sawBinaryByte = true;
+                stream.destroy();
+                return;
+            }
+            for (const byte of buffer.values()) {
+                if (byte === 0x0a) {
+                    newlineCount += 1;
+                }
+            }
+            lastByte = buffer[buffer.length - 1] ?? lastByte;
+        });
+        stream.once('close', () => {
+            if (!sawData || sawBinaryByte) {
+                settle(0);
+            }
+        });
+        stream.once('end', () => {
+            if (!sawData || sawBinaryByte) {
+                settle(0);
+                return;
+            }
+            settle(newlineCount + (lastByte === 0x0a ? 0 : 1));
+        });
+    });
+}
+async function countWorkingTreeLines(paths, repoRoot) {
+    let total = 0;
+    for (const relativePath of paths) {
+        total += await countWorkingTreeFileLines(relativePath, repoRoot);
+    }
+    return total;
+}
+async function tryGit(args, repoRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', args, { maxBuffer: 1024 * 1024, cwd: repoRoot });
+        const trimmed = String(stdout ?? '').trimEnd();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export { REVIEW_LARGE_SCOPE_FILE_THRESHOLD_ENV_KEY, REVIEW_LARGE_SCOPE_LINE_THRESHOLD_ENV_KEY };

package/dist/scripts/lib/review-scope-paths.js

@@ -0,0 +1,123 @@
+function normalizeReviewScopePath(value) {
+    return value.trim().replace(/\\/gu, '/').replace(/^\.\//u, '');
+}
+function addNormalizedPath(paths, value) {
+    const normalized = normalizeReviewScopePath(value);
+    if (normalized) {
+        paths.add(normalized);
+    }
+}
+function formatScopePathForPrompt(value) {
+    if (value !== value.trim() || value.includes('\n') || value.includes('\r') || value.includes(' -> ')) {
+        return JSON.stringify(value);
+    }
+    return value;
+}
+function buildScopePathCollection(items) {
+    const paths = new Set();
+    const renderedLines = [];
+    for (const item of items) {
+        for (const value of item.pathValues) {
+            addNormalizedPath(paths, value);
+        }
+        renderedLines.push(item.renderedLine);
+    }
+    return {
+        paths: [...paths],
+        renderedLines
+    };
+}
+export function parseStatusZPathCollection(statusOutput) {
+    const items = [];
+    const entries = statusOutput.split('\0');
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index] ?? '';
+        if (entry.length < 3) {
+            continue;
+        }
+        const status = entry.slice(0, 2);
+        const currentPathRaw = entry.slice(3);
+        const currentPath = normalizeReviewScopePath(currentPathRaw);
+        if ((status.includes('R') || status.includes('C')) && index + 1 < entries.length) {
+            const sourcePathRaw = entries[index + 1] ?? '';
+            const sourcePath = normalizeReviewScopePath(sourcePathRaw);
+            if (sourcePath && currentPath) {
+                items.push({
+                    renderedLine: `${formatScopePathForPrompt(sourcePathRaw)} -> ${formatScopePathForPrompt(currentPathRaw)}`,
+                    pathValues: [currentPathRaw, sourcePathRaw]
+                });
+            }
+            else if (currentPath) {
+                items.push({
+                    renderedLine: formatScopePathForPrompt(currentPathRaw),
+                    pathValues: [currentPathRaw]
+                });
+            }
+            else if (sourcePath) {
+                items.push({
+                    renderedLine: formatScopePathForPrompt(sourcePathRaw),
+                    pathValues: [sourcePathRaw]
+                });
+            }
+            index += 1;
+            continue;
+        }
+        if (currentPath) {
+            items.push({
+                renderedLine: formatScopePathForPrompt(currentPathRaw),
+                pathValues: [currentPathRaw]
+            });
+        }
+    }
+    return buildScopePathCollection(items);
+}
+export function parseStatusZPaths(statusOutput) {
+    return parseStatusZPathCollection(statusOutput).paths;
+}
+export function parseNameStatusPathCollection(output) {
+    const items = [];
+    for (const rawLine of output.split(/\r?\n/u)) {
+        if (!rawLine.trim()) {
+            continue;
+        }
+        const fields = rawLine.split('\t').filter((entry) => entry.length > 0);
+        const status = fields[0] ?? '';
+        if (fields.length < 2) {
+            continue;
+        }
+        if ((status.startsWith('R') || status.startsWith('C')) && fields.length >= 3) {
+            const sourcePathRaw = fields[1] ?? '';
+            const destinationPathRaw = fields[2] ?? '';
+            const sourcePath = normalizeReviewScopePath(sourcePathRaw);
+            const destinationPath = normalizeReviewScopePath(destinationPathRaw);
+            if (sourcePath && destinationPath) {
+                items.push({
+                    renderedLine: `${formatScopePathForPrompt(sourcePathRaw)} -> ${formatScopePathForPrompt(destinationPathRaw)}`,
+                    pathValues: [sourcePathRaw, destinationPathRaw]
+                });
+            }
+            else if (sourcePath) {
+                items.push({
+                    renderedLine: formatScopePathForPrompt(sourcePathRaw),
+                    pathValues: [sourcePathRaw]
+                });
+            }
+            else if (destinationPath) {
+                items.push({
+                    renderedLine: formatScopePathForPrompt(destinationPathRaw),
+                    pathValues: [destinationPathRaw]
+                });
+            }
+            continue;
+        }
+        const pathRaw = fields[1] ?? '';
+        const path = normalizeReviewScopePath(pathRaw);
+        if (path) {
+            items.push({ renderedLine: formatScopePathForPrompt(pathRaw), pathValues: [pathRaw] });
+        }
+    }
+    return buildScopePathCollection(items);
+}
+export function parseNameStatusPaths(output) {
+    return parseNameStatusPathCollection(output).paths;
+}