@twistezo/ai-review-council 1.2.0 → 1.3.0

package/README.md

@@ -12,21 +12,21 @@ Changes: [CHANGELOG.md](CHANGELOG.md). Internals: [ARCHITECTURE.md](ARCHITECTURE
 ## Run
 
 ```bash
+# install
 npm install -g @twistezo/ai-review-council
-```
 
-```bash
-# every option is optional and skips its wizard question
+# run; every option is optional and skips its wizard question
 ai-review-council --dir ~/projects/my-app --lang pl --scope uncommitted --reviewers 2
-```
 
-Without installing: `npx @twistezo/ai-review-council`.
+# or run without installing
+npx @twistezo/ai-review-council
+```
 
 | Option | Value | Default |
 |---|---|---|
 | `-d, --dir` | folder inside a Git repository | asked |
 | `-l, --lang` | `en`, `pl` | asked, `en` |
-| `-s, --scope` | `uncommitted`, or a commit hash: changes after it, uncommitted included | asked |
+| `-s, --scope` | `uncommitted`; `full`: the entire codebase, every file as new; or a commit hash: changes after it, uncommitted included | asked |
 | `-r, --reviewers` | 1 to 6 | asked |
 | `-t, --timeout` | minutes per agent, 1 to 120 | `10` |
 
@@ -61,29 +61,33 @@ A new review type needs a file in both folders and an entry in `reviewTypes` in
 ## Develop
 
 ```bash
+# install dependencies
 npm install
-```
 
-```bash
-# same options as the installed command
+# run from source; same options as the installed command
 npm run dev -- --dir ~/projects/my-app
-```
 
-```bash
+# tests, typecheck, build into `dist/`
 npm test
-```
-
-```bash
 npm run typecheck
-```
-
-```bash
 npm run build
 ```
 
-Release: bump the version in `package.json` and `package-lock.json`, add its `CHANGELOG.md` section, then commit, tag and push. A GitHub release for the tag publishes it to npm ([`publish.yml`](.github/workflows/publish.yml)):
+Release: a GitHub release for the tag publishes the version to npm ([`publish.yml`](.github/workflows/publish.yml)).
 
 ```bash
-# notes: the version's CHANGELOG section
-VERSION=1.2.0 && gh release create "v$VERSION" --title "v$VERSION" --notes "$(awk -v v="## $VERSION " '/^## [0-9]/{p=index($0, v)==1} p' CHANGELOG.md)"
+# version to release; add its section to CHANGELOG.md first
+VERSION=1.2.1
+
+# bump package.json and package-lock.json, no Git commit or tag
+npm version "$VERSION" --no-git-tag-version
+
+# commit, tag and push
+git add CHANGELOG.md package.json package-lock.json
+git commit -m "Release v$VERSION"
+git tag "v$VERSION"
+git push origin main "v$VERSION"
+
+# GitHub release with the version's CHANGELOG section as notes; CI publishes to npm
+gh release create "v$VERSION" --title "v$VERSION" --notes "$(awk -v v="## $VERSION " '/^## [0-9]/{p=index($0, v)==1} p' CHANGELOG.md)"
 ```

package/dist/cli-options.js

@@ -7,7 +7,8 @@ export const usage = `Usage: ai-review-council [options]
 Options:
   -d, --dir <path>     Project folder to review; skips the folder step
   -l, --lang <code>    Report language: ${reportLanguages.join(', ')}; skips the language step
-  -s, --scope <value>  uncommitted, or a commit hash to review the changes after it; skips the scope step
+  -s, --scope <value>  uncommitted, full for the entire codebase, or a commit hash to review the changes after it;
+                       skips the scope step
   -r, --reviewers <n>  Number of reviewers, 1 to ${maxReviewers}; skips the count question
   -t, --timeout <min>  Minutes each agent may run before it fails (default ${defaultTimeoutMinutes}, max ${maxTimeoutMinutes})
   -h, --help           Show this help`;
@@ -25,6 +26,7 @@ const readRawOptions = (args) => parseArgs({
     allowPositionals: false,
 }).values;
 const uncommittedScope = 'uncommitted';
+const fullScope = 'full';
 const reviewerCountSchema = z.number().int().min(1).max(maxReviewers);
 const parseScope = (value) => {
     if (value === undefined) {
@@ -34,6 +36,9 @@ const parseScope = (value) => {
     if (trimmed.toLowerCase() === uncommittedScope) {
         return { kind: 'uncommitted' };
     }
+    if (trimmed.toLowerCase() === fullScope) {
+        return { kind: 'full' };
+    }
     return isCommitHashFormat(trimmed) ? { kind: 'since-commit', commitRef: trimmed } : 'invalid';
 };
 export const parseCliOptions = (args) => {
@@ -53,7 +58,7 @@ export const parseCliOptions = (args) => {
     }
     const scope = parseScope(values.scope);
     if (scope === 'invalid') {
-        return { ok: false, error: 'The --scope option needs `uncommitted` or a commit hash (4 to 40 hexadecimal characters).' };
+        return { ok: false, error: 'The --scope option needs `uncommitted`, `full` or a commit hash (4 to 40 hexadecimal characters).' };
     }
     const reviewerCount = values.reviewers === undefined ? null : reviewerCountSchema.safeParse(Number(values.reviewers));
     if (reviewerCount !== null && !reviewerCount.success) {

package/dist/domain/review-session.js

@@ -37,10 +37,13 @@ const commitInfoSchema = z.object({
     hash: z.string().length(40),
     subject: z.string(),
 });
-const reviewScopeKinds = ['uncommitted', 'since-commit'];
+const reviewScopeKinds = ['uncommitted', 'since-commit', 'full'];
 const reviewScopeSchema = z.object({
     kind: z.enum(reviewScopeKinds),
+    // the commit the review starts from; HEAD for `full`
     base: commitInfoSchema,
+    // what the diff is taken against: the base commit, or Git's empty tree for `full`, so every file shows as added
+    diffBase: z.string().min(1),
     changedFiles: z.array(changedFileSchema).min(1),
     // paths of likely secret files left out of the review
     excludedFiles: z.array(z.string().min(1)),

package/dist/git/git-repository.js

@@ -44,6 +44,11 @@ export const createGitRepository = (run) => {
         },
         resolveCommit,
         isInHeadHistory: async (root, hash) => (await git(root, ['merge-base', '--is-ancestor', hash, 'HEAD'])) !== null,
+        readEmptyTreeHash: async (root) => {
+            // Hashing nothing as a tree gives the empty tree, also in SHA-256 repositories.
+            const output = await git(root, ['hash-object', '-t', 'tree', '/dev/null']);
+            return output === null ? null : output.trim();
+        },
         listChangedFiles: async (root, baseHash) => {
             // `git diff <base>` compares the base with the working tree: staged and unstaged changes.
             const [diffOutput, untrackedOutput] = await Promise.all([

package/dist/review/review-messages.js

@@ -9,15 +9,23 @@ const changeLabels = {
     untracked: 'new, not in the diff: read it in full',
 };
 const describeFile = (file) => `- ${file.previousPath === null ? file.path : `${file.previousPath} -> ${file.path}`} (${changeLabels[file.change]})`;
+const describeRange = (scope) => {
+    const base = `${scope.base.hash.slice(0, 7)} ${scope.base.subject}`.trim();
+    switch (scope.kind) {
+        case 'uncommitted':
+            return `Uncommitted changes against ${base}.`;
+        case 'since-commit':
+            return `Everything changed after ${base}, up to the current files with uncommitted changes. The base commit itself is not part of the change.`;
+        case 'full':
+            return `The entire codebase at ${base}, uncommitted changes included. Every file is part of the change and shows as added in the diff.`;
+    }
+};
 const scopeSection = (session, diffPath) => {
     const { repository, scope } = session;
-    const base = `${scope.base.hash.slice(0, 7)} ${scope.base.subject}`.trim();
     const lines = [
         '## Scope',
         `Repository: ${repository.root} (${repository.branch === null ? 'detached HEAD' : `branch ${repository.branch}`})`,
-        scope.kind === 'uncommitted'
-            ? `Uncommitted changes against ${base}.`
-            : `Everything changed after ${base}, up to the current files with uncommitted changes. The base commit itself is not part of the change.`,
+        describeRange(scope),
         `Diff of tracked changes: ${diffPath}`,
         `Changed files (${scope.changedFiles.length}):`,
         ...scope.changedFiles.map(describeFile),

package/dist/review/review-workspace.js

@@ -35,7 +35,7 @@ export const createWorkspacePreparer = (git) => async (repositoryRoot, scope) =>
     activeDirectories.add(directory);
     const diffPath = path.join(directory, 'change.diff');
     try {
-        await writeFile(diffPath, await git.readDiff(repositoryRoot, scope.base.hash, trackedDiffPaths(scope)));
+        await writeFile(diffPath, await git.readDiff(repositoryRoot, scope.diffBase, trackedDiffPaths(scope)));
     }
     catch (error) {
         await removeDirectory(directory);

package/dist/scope/build-review-scope.js

@@ -1,7 +1,17 @@
 import { isCommitHashFormat } from '../git/git-repository.js';
 import { partitionReviewFiles } from './excluded-files.js';
+const nothingToReview = (request, base) => {
+    switch (request.kind) {
+        case 'uncommitted':
+            return 'There are no uncommitted changes to review.';
+        case 'since-commit':
+            return `There are no changes after ${base.hash.slice(0, 7)} to review.`;
+        case 'full':
+            return 'There are no files to review.';
+    }
+};
 export const buildReviewScope = async (git, root, request) => {
-    const ref = request.kind === 'uncommitted' ? 'HEAD' : request.commitRef.trim();
+    const ref = request.kind === 'since-commit' ? request.commitRef.trim() : 'HEAD';
     if (request.kind === 'since-commit' && !isCommitHashFormat(ref)) {
         return { ok: false, error: 'Enter a commit hash: 4 to 40 hexadecimal characters.' };
     }
@@ -16,14 +26,14 @@ export const buildReviewScope = async (git, root, request) => {
             error: `Commit ${base.hash.slice(0, 7)} is not in the history of the current branch. Pick one from \`git log\`.`,
         };
     }
-    const { included, excluded } = partitionReviewFiles(await git.listChangedFiles(root, base.hash));
+    // The entire codebase is diffed against no files at all, so every file is new.
+    const diffBase = request.kind === 'full' ? await git.readEmptyTreeHash(root) : base.hash;
+    if (diffBase === null) {
+        return { ok: false, error: 'Git could not read the empty tree to compare the codebase with.' };
+    }
+    const { included, excluded } = partitionReviewFiles(await git.listChangedFiles(root, diffBase));
     if (included.length === 0) {
-        return {
-            ok: false,
-            error: request.kind === 'uncommitted'
-                ? 'There are no uncommitted changes to review.'
-                : `There are no changes after ${base.hash.slice(0, 7)} to review.`,
-        };
+        return { ok: false, error: nothingToReview(request, base) };
     }
-    return { ok: true, scope: { kind: request.kind, base, changedFiles: included, excludedFiles: excluded } };
+    return { ok: true, scope: { kind: request.kind, base, diffBase, changedFiles: included, excludedFiles: excluded } };
 };

package/dist/ui/describe-scope.js

@@ -1,8 +1,15 @@
-export const describeScope = (scope) => {
+const describeRange = (scope) => {
     const base = scope.base.hash.slice(0, 7);
-    const range = scope.kind === 'uncommitted'
-        ? `uncommitted changes on ${base}`
-        : `changes after ${base} ${scope.base.subject}, uncommitted included`;
+    switch (scope.kind) {
+        case 'uncommitted':
+            return `uncommitted changes on ${base}`;
+        case 'since-commit':
+            return `changes after ${base} ${scope.base.subject}, uncommitted included`;
+        case 'full':
+            return `entire codebase on ${base}, uncommitted included`;
+    }
+};
+export const describeScope = (scope) => {
     const excluded = scope.excludedFiles.length === 0 ? '' : `, ${scope.excludedFiles.length} likely secret file(s) excluded`;
-    return `${range} (${scope.changedFiles.length} files${excluded})`;
+    return `${describeRange(scope)} (${scope.changedFiles.length} files${excluded})`;
 };

package/dist/ui/steps/scope-step.js

@@ -9,6 +9,7 @@ import { theme } from '../theme.js';
 const kindLabels = {
     uncommitted: 'Uncommitted only',
     'since-commit': 'Since commit',
+    full: 'Entire codebase',
 };
 const hints = {
     kind: '↑↓ row · Enter confirm',
@@ -20,7 +21,7 @@ export const ScopeStep = ({ git, repository, initialKind, preset, onSubmit, onPr
     const [commitRef, setCommitRef] = useState(preset?.kind === 'since-commit' ? preset.commitRef : '');
     const [error, setError] = useState(null);
     const load = async (request) => {
-        const previousView = request.kind === 'uncommitted' ? 'kind' : 'commit';
+        const previousView = request.kind === 'since-commit' ? 'commit' : 'kind';
         setView('loading');
         setError(null);
         try {
@@ -56,9 +57,10 @@ export const ScopeStep = ({ git, repository, initialKind, preset, onSubmit, onPr
     return (_jsxs(StepFrame, { title: "Review scope", hints: hints[view], onBack: goBack, children: [view === 'kind' && (_jsx(SelectList, { items: [
                     { key: 'uncommitted', label: kindLabels.uncommitted },
                     { key: 'since-commit', label: kindLabels['since-commit'] },
+                    { key: 'full', label: kindLabels.full },
                 ], initialKey: initialKind, onSelect: (key) => {
-                    if (key === 'uncommitted') {
-                        void load({ kind: 'uncommitted' });
+                    if (key === 'uncommitted' || key === 'full') {
+                        void load({ kind: key });
                     }
                     else {
                         setError(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twistezo/ai-review-council",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Terminal app that runs independent Codex and Claude Code reviewers and merges their results",
   "license": "MIT",
   "keywords": [