@navels/neal 0.1.0

package/dist/neal/final-completion.js

@@ -0,0 +1,229 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getFinalCompletionContinueExecutionMax } from './config.js';
+import { getChangedFilesForRange, getCommitRange, getCommitSubjects, getDiffStatForRange, } from './git.js';
+import { toResidualReviewDebt } from './review-debt.js';
+import { buildScopeAccountingSummary, getCurrentScopeLabel } from './scopes.js';
+import { getDerivedPlanView, getFinalCompletionView } from './state-views.js';
+import { extractVerificationCommandResults, latestCommandResultPerCommand, summarizeVerificationCommandResults, } from './verification-events.js';
+function getEventsPath(runDir) {
+    return join(runDir, 'events.ndjson');
+}
+function summarizeChangedFiles(files) {
+    if (files.length === 0) {
+        return 'none';
+    }
+    const displayFiles = files.slice(0, 12);
+    const lines = displayFiles.map((file) => `- ${file}`);
+    if (files.length > displayFiles.length) {
+        lines.push(`- ...and ${files.length - displayFiles.length} more`);
+    }
+    return lines.join('\n');
+}
+function renderCompletedScopeSummary(scopes) {
+    if (scopes.length === 0) {
+        return 'No completed scopes recorded.';
+    }
+    return scopes
+        .map((scope) => {
+        const changedFiles = scope.changedFiles.length > 0
+            ? `${scope.changedFiles.length} file(s): ${scope.changedFiles.join(', ')}`
+            : 'no changed files';
+        const commit = scope.finalCommit ?? 'pending';
+        const parent = scope.derivedFromParentScope ? ` | parent ${scope.derivedFromParentScope}` : '';
+        const blocker = scope.blocker ? ` | blocker: ${scope.blocker}` : '';
+        const residualDebt = scope.residualReviewDebt?.length
+            ? ` | residual non-blocking debt: ${scope.residualReviewDebt
+                .map((item) => `${item.id} ${item.status}: ${item.claim}`)
+                .join('; ')}`
+            : '';
+        return `- Scope ${scope.number}: ${scope.result} (${scope.marker}) | commit ${commit}${parent} | ${changedFiles}${blocker}${residualDebt}`;
+    })
+        .join('\n');
+}
+function uniqueFiles(files) {
+    return [...new Set(files)];
+}
+function buildTerminalScopeRecord(state, terminalScope) {
+    const marker = (terminalScope.marker ?? state.lastScopeMarker ?? 'AUTONOMY_DONE');
+    const derivedPlan = getDerivedPlanView(state);
+    return {
+        number: getCurrentScopeLabel(state),
+        marker,
+        result: 'accepted',
+        baseCommit: state.baseCommit,
+        finalCommit: terminalScope.finalCommit,
+        summary: state.currentScopeProgressJustification?.milestoneTargeted ?? null,
+        commitSubject: terminalScope.commitSubject,
+        changedFiles: [...terminalScope.changedFiles],
+        reviewRounds: state.rounds.length,
+        findings: state.findings.length,
+        residualReviewDebt: toResidualReviewDebt(state.findings),
+        archivedReviewPath: terminalScope.archivedReviewPath,
+        blocker: null,
+        derivedFromParentScope: derivedPlan?.parentScopeNumber !== null && derivedPlan?.parentScopeNumber !== undefined
+            ? String(derivedPlan.parentScopeNumber)
+            : null,
+        replacedByDerivedPlanPath: null,
+    };
+}
+function mergeCompletedScopesWithTerminalScope(state, terminalScope) {
+    if (!terminalScope) {
+        return state.completedScopes;
+    }
+    const terminalRecord = buildTerminalScopeRecord(state, terminalScope);
+    return [
+        ...state.completedScopes.filter((scope) => scope.number !== terminalRecord.number),
+        terminalRecord,
+    ];
+}
+function toReferenceScope(scope) {
+    return {
+        number: scope.number,
+        finalCommit: scope.finalCommit,
+        commitSubject: scope.commitSubject,
+        changedFiles: [...scope.changedFiles],
+        archivedReviewPath: scope.archivedReviewPath,
+    };
+}
+function findLastNonEmptyImplementationScope(effectiveScopes, terminalScope, state) {
+    if (terminalScope && terminalScope.changedFiles.length > 0) {
+        return toReferenceScope(buildTerminalScopeRecord(state, terminalScope));
+    }
+    for (let index = effectiveScopes.length - 1; index >= 0; index -= 1) {
+        const scope = effectiveScopes[index];
+        if (scope?.result === 'accepted' && scope.changedFiles.length > 0) {
+            return toReferenceScope(scope);
+        }
+    }
+    return null;
+}
+async function loadVerificationCommandResults(runDir) {
+    try {
+        const content = await readFile(getEventsPath(runDir), 'utf8');
+        const events = content
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+        return extractVerificationCommandResults(events);
+    }
+    catch {
+        return [];
+    }
+}
+function collectResidualReviewDebt(scopes) {
+    return scopes.flatMap((scope) => scope.residualReviewDebt ?? []);
+}
+function summarizeResidualReviewDebt(scopes) {
+    const items = scopes.flatMap((scope) => (scope.residualReviewDebt ?? []).map((item) => ({
+        scope: scope.number,
+        ...item,
+    })));
+    if (items.length === 0) {
+        return 'No unresolved non-blocking review debt was recorded for accepted scopes.';
+    }
+    return items
+        .map((item) => {
+        const files = item.files.length > 0 ? item.files.join(', ') : 'n/a';
+        const disposition = item.coderDisposition ? ` | coder disposition: ${item.coderDisposition}` : '';
+        return `- Scope ${item.scope} ${item.id} (${item.status}) | files: ${files} | ${item.claim} | required: ${item.requiredAction}${disposition}`;
+    })
+        .join('\n');
+}
+async function loadAggregateReviewContext(state, finalCommit) {
+    const baseCommit = state.initialBaseCommit;
+    const headCommit = finalCommit;
+    const range = baseCommit && headCommit ? `${baseCommit}..${headCommit}` : null;
+    if (!baseCommit) {
+        return {
+            baseCommit,
+            headCommit,
+            range,
+            commitSubjects: [],
+            diffStat: '',
+            changedFiles: [],
+            unavailableReason: 'initialBaseCommit is unavailable, so the aggregate completion range cannot be computed.',
+        };
+    }
+    if (!headCommit) {
+        return {
+            baseCommit,
+            headCommit,
+            range,
+            commitSubjects: [],
+            diffStat: '',
+            changedFiles: [],
+            unavailableReason: 'finalCommit is unavailable, so the aggregate completion range cannot be computed.',
+        };
+    }
+    try {
+        const commits = await getCommitRange(state.cwd, baseCommit, headCommit);
+        const [commitSubjects, diffStat, changedFiles] = await Promise.all([
+            getCommitSubjects(state.cwd, commits),
+            getDiffStatForRange(state.cwd, baseCommit, headCommit),
+            getChangedFilesForRange(state.cwd, baseCommit, headCommit),
+        ]);
+        return {
+            baseCommit,
+            headCommit,
+            range,
+            commitSubjects,
+            diffStat,
+            changedFiles,
+            unavailableReason: null,
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error && error.message.trim() ? error.message.trim() : 'unknown git error';
+        return {
+            baseCommit,
+            headCommit,
+            range,
+            commitSubjects: [],
+            diffStat: '',
+            changedFiles: [],
+            unavailableReason: `Unable to read aggregate completion git context for ${range}: ${reason}`,
+        };
+    }
+}
+export async function buildFinalCompletionPacket(args) {
+    const terminalScope = args.terminalScope ?? null;
+    const finalCommit = terminalScope?.finalCommit ?? args.state.finalCommit;
+    const effectiveScopes = mergeCompletedScopesWithTerminalScope(args.state, terminalScope);
+    const allVerificationCommandResults = await loadVerificationCommandResults(args.state.runDir);
+    const verificationCommandResults = latestCommandResultPerCommand(allVerificationCommandResults);
+    const verificationCommands = verificationCommandResults.map((result) => result.command);
+    const scopeAccounting = buildScopeAccountingSummary(effectiveScopes);
+    const terminalChangedFiles = [...(terminalScope?.changedFiles ?? [])];
+    const planChangedFiles = uniqueFiles(effectiveScopes
+        .filter((scope) => scope.result === 'accepted')
+        .flatMap((scope) => scope.changedFiles));
+    const residualReviewDebt = collectResidualReviewDebt(effectiveScopes);
+    const aggregateReviewContext = await loadAggregateReviewContext(args.state, finalCommit);
+    const finalCompletion = getFinalCompletionView(args.state);
+    return {
+        planDoc: args.state.planDoc,
+        executionShape: args.state.executionShape,
+        currentScopeLabel: getCurrentScopeLabel(args.state),
+        finalCommit,
+        aggregateReviewContext,
+        completedScopeSummary: renderCompletedScopeSummary(effectiveScopes),
+        acceptedScopeCount: effectiveScopes.filter((scope) => scope.result === 'accepted').length,
+        blockedScopeCount: effectiveScopes.filter((scope) => scope.result === 'blocked').length,
+        scopeAccounting,
+        scopeAccountingSummary: scopeAccounting.summary,
+        verificationOnlyCompletion: terminalChangedFiles.length === 0 && args.state.createdCommits.length === 0,
+        terminalChangedFiles,
+        terminalChangedFilesSummary: summarizeChangedFiles(terminalChangedFiles),
+        planChangedFiles,
+        planChangedFilesSummary: summarizeChangedFiles(planChangedFiles),
+        residualReviewDebt,
+        residualReviewDebtSummary: summarizeResidualReviewDebt(effectiveScopes),
+        verificationCommands,
+        verificationCommandResults,
+        verificationSummary: summarizeVerificationCommandResults(verificationCommandResults),
+        lastNonEmptyImplementationScope: findLastNonEmptyImplementationScope(effectiveScopes, terminalScope, args.state),
+        continueExecutionCount: finalCompletion?.continueExecutionCount ?? 0,
+        continueExecutionMax: Math.max(0, getFinalCompletionContinueExecutionMax(args.state.cwd)),
+    };
+}

package/dist/neal/git.js

@@ -0,0 +1,339 @@
+import { execFile, spawn } from 'node:child_process';
+import { isAbsolute, resolve } from 'node:path';
+function runGit(args, cwd) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        execFile('git', args, { cwd }, (error, stdout, stderr) => {
+            if (error) {
+                rejectPromise(new Error(stderr.trim() || error.message));
+                return;
+            }
+            resolvePromise(stdout.trim());
+        });
+    });
+}
+function runGitOptionalConfig(args, cwd) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        execFile('git', args, { cwd }, (error, stdout, stderr) => {
+            if (!error) {
+                resolvePromise(stdout.trim());
+                return;
+            }
+            const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : null;
+            if (code === 1 && stdout.trim() === '' && stderr.trim() === '') {
+                resolvePromise(null);
+                return;
+            }
+            rejectPromise(new Error(stderr.trim() || error.message));
+        });
+    });
+}
+async function getBooleanGitConfig(cwd, key) {
+    const value = await runGitOptionalConfig(['config', '--bool', '--get', key], cwd);
+    if (value === null) {
+        return null;
+    }
+    return value === 'true';
+}
+function runGitWithInput(args, cwd, input) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('git', args, {
+            cwd,
+            shell: false,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', (error) => {
+            rejectPromise(new Error(stderr.trim() || error.message));
+        });
+        child.on('exit', (code, signal) => {
+            if (signal) {
+                rejectPromise(new Error(`git ${args.join(' ')} terminated by signal ${signal}`));
+                return;
+            }
+            if (code === 0) {
+                resolvePromise(stdout.trim());
+            }
+            else {
+                rejectPromise(new Error(stderr.trim() || `git ${args.join(' ')} exited with status ${code}`));
+            }
+        });
+        child.stdin.end(input);
+    });
+}
+function runGitWithInputStatus(args, cwd, input) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('git', args, {
+            cwd,
+            shell: false,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', (error) => {
+            rejectPromise(new Error(stderr.trim() || error.message));
+        });
+        child.on('exit', (code, signal) => {
+            resolvePromise({
+                stdout,
+                stderr,
+                code: code ?? 0,
+                signal,
+            });
+        });
+        child.stdin.end(input);
+    });
+}
+export async function getHeadCommit(cwd) {
+    return runGit(['rev-parse', 'HEAD'], cwd);
+}
+export async function getRepositoryRoot(cwd) {
+    return runGit(['rev-parse', '--show-toplevel'], cwd);
+}
+export async function tryGetRepositoryRoot(cwd) {
+    try {
+        const insideWorkTree = await runGit(['rev-parse', '--is-inside-work-tree'], cwd);
+        if (insideWorkTree !== 'true') {
+            return null;
+        }
+        return await getRepositoryRoot(cwd);
+    }
+    catch {
+        return null;
+    }
+}
+export async function getGitPath(cwd, path) {
+    const gitPath = await runGit(['rev-parse', '--git-path', path], cwd);
+    return isAbsolute(gitPath) ? gitPath : resolve(cwd, gitPath);
+}
+export async function getNealDirGitIgnoreStatus(cwd) {
+    const repoRoot = await tryGetRepositoryRoot(cwd);
+    if (repoRoot === null) {
+        return { kind: 'not_git' };
+    }
+    const ignoredPaths = await getIgnoredPaths(repoRoot, ['.neal/']);
+    if (ignoredPaths.includes('.neal/')) {
+        return { kind: 'ignored', repoRoot };
+    }
+    return {
+        kind: 'not_ignored',
+        repoRoot,
+        excludePath: await getGitPath(repoRoot, 'info/exclude'),
+    };
+}
+export async function assertGitRepositoryWithCommit(cwd, commandLabel) {
+    const repositoryMessage = `${commandLabel} requires a Git repository with at least one commit. ` +
+        'Run `git init` if needed, create an initial commit, then retry.';
+    const noInitialCommitMessage = `This repository has no commits yet. Create an initial commit before running \`${commandLabel}\`.`;
+    try {
+        const insideWorkTree = await runGit(['rev-parse', '--is-inside-work-tree'], cwd);
+        if (insideWorkTree !== 'true') {
+            throw new Error(repositoryMessage);
+        }
+    }
+    catch {
+        throw new Error(repositoryMessage);
+    }
+    try {
+        await runGit(['rev-parse', '--verify', 'HEAD^{commit}'], cwd);
+    }
+    catch {
+        throw new Error(noInitialCommitMessage);
+    }
+}
+export async function resolveCommitRef(cwd, ref) {
+    return runGit(['rev-parse', '--verify', `${ref}^{commit}`], cwd);
+}
+export async function isAncestorCommit(cwd, ancestor, descendant) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        execFile('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd }, (error, _stdout, stderr) => {
+            if (!error) {
+                resolvePromise(true);
+                return;
+            }
+            const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : null;
+            if (code === 1) {
+                resolvePromise(false);
+                return;
+            }
+            rejectPromise(new Error(stderr.trim() || error.message));
+        });
+    });
+}
+export async function getCommitRange(cwd, base, head) {
+    if (base === head) {
+        return [];
+    }
+    const output = await runGit(['rev-list', '--reverse', `${base}..${head}`], cwd);
+    return output ? output.split('\n').filter(Boolean) : [];
+}
+export async function getDiffStatForRange(cwd, base, head) {
+    if (base === head) {
+        return '';
+    }
+    return runGit(['diff', '--stat', `${base}..${head}`], cwd);
+}
+export async function getDiffForRange(cwd, base, head) {
+    if (base === head) {
+        return '';
+    }
+    return runGit(['diff', '--find-renames', `${base}..${head}`], cwd);
+}
+export async function getChangedFilesForRange(cwd, base, head) {
+    if (base === head) {
+        return [];
+    }
+    const output = await runGit(['diff', '--name-only', `${base}..${head}`], cwd);
+    return output ? output.split('\n').filter(Boolean) : [];
+}
+export async function commitTreePathExists(cwd, commit, path) {
+    const output = await runGit(['ls-tree', '--name-only', commit, '--', path], cwd);
+    return output.split('\n').filter(Boolean).includes(path);
+}
+export async function getIgnoredPaths(cwd, paths) {
+    if (paths.length === 0) {
+        return [];
+    }
+    const result = await runGitWithInputStatus(['check-ignore', '--no-index', '--stdin', '-z'], cwd, paths.join('\0') + '\0');
+    if (result.signal) {
+        throw new Error(`git check-ignore terminated by signal ${result.signal}`);
+    }
+    if (result.code === 1) {
+        return [];
+    }
+    if (result.code !== 0) {
+        throw new Error(result.stderr.trim() || `git check-ignore exited with status ${result.code}`);
+    }
+    return result.stdout.split('\0').filter(Boolean);
+}
+export async function dropIgnoredPathsFromCurrentCommitRange(cwd, baseCommit, headCommit) {
+    const changedFiles = await getChangedFilesForRange(cwd, baseCommit, headCommit);
+    const ignoredFiles = await getIgnoredPaths(cwd, changedFiles);
+    if (ignoredFiles.length === 0) {
+        return {
+            ignoredFiles: [],
+            headCommit,
+            createdReplacementCommit: false,
+        };
+    }
+    const currentHead = await getHeadCommit(cwd);
+    if (currentHead !== headCommit) {
+        throw new Error(`Cannot drop ignored files from commit range because HEAD moved from ${headCommit} to ${currentHead}`);
+    }
+    const replacementMessage = await getCommitMessage(cwd, headCommit);
+    await runGit(['reset', '--soft', baseCommit], cwd);
+    await runGit(['reset', '--', ...ignoredFiles], cwd);
+    const stagedFiles = await runGit(['diff', '--cached', '--name-only'], cwd);
+    if (!stagedFiles) {
+        return {
+            ignoredFiles,
+            headCommit: baseCommit,
+            createdReplacementCommit: false,
+        };
+    }
+    await runGitWithInput(['commit', '--no-verify', '-F', '-'], cwd, replacementMessage.endsWith('\n') ? replacementMessage : `${replacementMessage}\n`);
+    return {
+        ignoredFiles,
+        headCommit: await getHeadCommit(cwd),
+        createdReplacementCommit: true,
+    };
+}
+export async function assertNoIgnoredChangedFiles(cwd, changedFiles, context) {
+    const ignoredFiles = await getIgnoredPaths(cwd, changedFiles);
+    if (ignoredFiles.length === 0) {
+        return;
+    }
+    throw new Error([
+        `${context} would include ignored file(s), which Neal will not commit:`,
+        ...ignoredFiles.map((file) => `- ${file}`),
+        'Remove those files from the commit or change the ignore rules intentionally before continuing.',
+    ].join('\n'));
+}
+export async function getCommitSubjects(cwd, commits) {
+    if (commits.length === 0) {
+        return [];
+    }
+    const output = await runGit(['show', '--quiet', '--format=%H %s', ...commits], cwd);
+    return output ? output.split('\n').filter(Boolean) : [];
+}
+export async function getCommitMessage(cwd, commit) {
+    return runGit(['show', '--quiet', '--format=%B', commit], cwd);
+}
+export async function getWorktreeStatus(cwd, options = {}) {
+    const args = ['status', '--short'];
+    if (options.untrackedFiles === 'all') {
+        args.push('--untracked-files=all');
+    }
+    return runGit(args, cwd);
+}
+export async function stagePath(cwd, path) {
+    await runGit(['add', '--', path], cwd);
+}
+export async function getStagedChangedFiles(cwd) {
+    const output = await runGit(['diff', '--cached', '--name-only'], cwd);
+    return output ? output.split('\n').filter(Boolean) : [];
+}
+export async function getStagedDiff(cwd) {
+    return runGit(['diff', '--cached', '--binary'], cwd);
+}
+export async function commitStagedChanges(cwd, message) {
+    await runGitWithInput(['commit', '--no-verify', '-F', '-'], cwd, message.endsWith('\n') ? message : `${message}\n`);
+    return getHeadCommit(cwd);
+}
+export async function getUnstagedDiff(cwd) {
+    return runGit(['diff', '--binary'], cwd);
+}
+export async function getUntrackedFiles(cwd) {
+    const output = await runGit(['ls-files', '--others', '--exclude-standard'], cwd);
+    return output ? output.split('\n').filter(Boolean) : [];
+}
+export async function resetHard(cwd, target) {
+    await runGit(['reset', '--hard', target], cwd);
+}
+export async function restoreWorktreePaths(cwd, paths) {
+    if (paths.length === 0) {
+        return;
+    }
+    await runGit(['restore', '--staged', '--worktree', '--', ...paths], cwd);
+}
+export async function createSquashReplacementCommit(cwd, baseCommit, finalCommit, message) {
+    const args = ['commit-tree', `${finalCommit}^{tree}`, '-p', baseCommit];
+    if (await getBooleanGitConfig(cwd, 'commit.gpgsign')) {
+        args.push('-S');
+    }
+    args.push('-F', '-');
+    return runGitWithInput(args, cwd, message.endsWith('\n') ? message : `${message}\n`);
+}
+export async function rebaseCurrentBranchOnto(cwd, newBase, upstream) {
+    await runGit(['rebase', '--onto', newBase, upstream], cwd);
+}
+export async function cleanUntracked(cwd, excludedPaths = []) {
+    const args = ['clean', '-fd'];
+    for (const path of excludedPaths) {
+        args.push('-e', path);
+    }
+    await runGit(args, cwd);
+}
+export async function cleanUntrackedPaths(cwd, paths) {
+    if (paths.length === 0) {
+        return;
+    }
+    await runGit(['clean', '-fd', '--', ...paths], cwd);
+}
+export async function squashCommits(cwd, baseCommit, message) {
+    await runGit(['reset', '--soft', baseCommit], cwd);
+    await runGitWithInput(['commit', '--no-verify', '-F', '-'], cwd, message.endsWith('\n') ? message : `${message}\n`);
+    return getHeadCommit(cwd);
+}