git-reviewer 2.14.1 → 2.15.0

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-379-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-415-brightgreen.svg)](test/)
 [![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen.svg)](package.json)
 
 **English** · [简体中文](docs/README.zh-CN.md) · [日本語](docs/README.ja.md)
@@ -79,7 +79,9 @@ git reviewer export [repository] [--format json|prompt]
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --no-intro    Open the review without the first-run help
       --staged      Review only staged changes (HEAD vs index)
+      --no-untracked Review tracked working-tree changes only
   -f, --format <f>  Export format: json (default) or prompt
   -h, --help        Show help
   -v, --version     Show the version
@@ -103,6 +105,19 @@ changes. As with the default view, reload after changing what is staged. Saved c
 are shared between views and may refer to code outside the current comparison;
 check their anchors before applying them.
 
+Wholly untracked directories with more than 200 files appear as one directory
+row with a file count and no diff. Smaller directories stay reviewable file by
+file. Tracked changes are always listed individually, and `.gitignore` still
+applies. The scope note names any folded directories and their counts.
+The headline counts individual files separately from folded folders and the
+files inside them. Tracked changes appear first; reloading keeps your selection.
+
+Use `git reviewer --no-untracked` to exclude all untracked files. If there are
+no tracked working-tree changes, the view stays empty instead of loading the
+last commit. Staged and commit comparisons keep their usual behavior.
+Saved reviews and exports retain this tracked-only scope. The text review and
+agent prompt explain the exclusion; older comments remain shared between views.
+
 ### When you are not standing in a repository
 
 The page opens on a picker rather than on an empty box:
@@ -388,6 +403,48 @@ The UI is a client of this; nothing is hidden from you.
 | `POST /api/submit-review` | Render the saved comments to a review file |
 | `DELETE /api/cleanup/:repoId` | End the session; files on disk are untouched |
 
+### POST request bodies
+
+`POST /api/load-repo` opens a repository. `repoPath` is required; choose a comparison or staged changes:
+
+```json
+{"repoPath":"/home/you/work/api","base":"main","head":"feature"}
+```
+
+To review a commit range, use `"commits": {"from":"abc123","to":"def456"}` instead of `base`/`head`. To review staged changes, use `"staged": true` without comparison fields. `head` is optional when using `base`.
+
+For tracked working-tree changes only, send `"untracked": false`. It defaults
+to `true`. Folded directory entries carry `directory: true` and `fileCount`;
+they have no file diff.
+
+`POST /api/save-comments` persists comments for an open session:
+
+```json
+{
+  "repoId": "<repoId returned by load-repo>",
+  "comments": [
+    {
+      "file": "src/app.js",
+      "line": 12,
+      "lineContent": "const value = 1;",
+      "text": "Consider renaming this variable.",
+      "selectedText": "const value",
+      "followUps": [{"text":"Please also update its uses.","timestamp":"2026-01-01T00:00:00.000Z"}]
+    }
+  ]
+}
+```
+
+Each comment requires `file` (non-empty string), `line` (positive integer), and `text` (non-empty string). `lineContent`, `selectedText`, and `followUps` are optional.
+
+`POST /api/submit-review` renders the previously saved comments:
+
+```json
+{"repoId":"<repoId returned by load-repo>"}
+```
+
+The startup `--json` output does not include `repoId`: no session exists at startup. A client obtains its own `repoId` by calling `POST /api/load-repo`.
+
 A `repoId` is a random per-session handle, not a path. Requests that resolve
 outside the opened repository are refused, and a path that names nothing gets a
 404.
@@ -410,7 +467,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 379 tests
+npm test              # 415 tests
 npm run test:watch
 npm run test:coverage
 ```

package/bin/reviewer.js

@@ -92,6 +92,9 @@ async function exportReview(options) {
       error instanceof NoMatchingCommentsError ||
       error instanceof ReviewOwnershipError
     ) {
+      if (repoPath === given && error instanceof NoReviewError && !(await repoRoot(given))) {
+        throw new UsageError(`${given} is not inside a git repository, and no review is saved for it.`);
+      }
       throw new UsageError(error.message);
     }
     throw error;
@@ -250,13 +253,34 @@ async function main() {
     options.port ?? (Number(process.env.PORT) || DEFAULT_PORT),
     { onReviewSubmitted, handoff: handingOff, onIdle }
   );
-  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath, options.staged);
+  const port = server.address().port;
+  const url = buildUrl(
+    `http://${DEFAULT_HOST}:${port}`,
+    repoPath,
+    options.staged,
+    options.noIntro,
+    options.untracked
+  );
 
-  note(`\n  Code Reviewer  ${url}`);
-  if (repoPath) note(`  reviewing      ${repoPath}`);
-  note(handingOff
-    ? '\n  Submit the review in the browser and it will be written here.\n'
-    : '\n  Close the tab when you are done, or press Ctrl+C.\n');
+  if (options.json) {
+    // One machine-readable line instead of the banner, so an agent can read
+    // the URL without a regex that breaks the day the banner is reworded.
+    // stderr, like everything else here: stdout is reserved for the review.
+    // No repoId: none exists yet. The page creates one via POST /api/load-repo.
+    note(JSON.stringify({
+      url,
+      port,
+      repository: repoPath,
+      pid: process.pid,
+      version
+    }));
+  } else {
+    note(`\n  Code Reviewer  ${url}`);
+    if (repoPath) note(`  reviewing      ${repoPath}`);
+    note(handingOff
+      ? '\n  Submit the review in the browser and it will be written here.\n'
+      : '\n  Close the tab when you are done, or press Ctrl+C.\n');
+  }
 
   if (options.open && !(await openInBrowser(url))) {
     note('  Could not open a browser — open the URL above yourself.\n');

package/lib/agent.js

@@ -23,6 +23,7 @@ const SCHEMA = 'code-review/v1';
  * @property {string} generatedAt ISO 8601
  * @property {{path: string, name: string, head: string|null, branch: string|null}} repository
  * @property {'working'|'staged'|'lastCommit'|'range'|null} mode
+ * @property {boolean} [untracked] false when the working comparison excluded untracked files
  * @property {{comments: number, files: number}} summary
  * @property {AgentComment[]} comments
  */
@@ -48,9 +49,10 @@ const SCHEMA = 'code-review/v1';
  * @param {string|null} [args.head] the commit the review was written against
  * @param {string|null} [args.branch]
  * @param {string|null} [args.mode]
+ * @param {boolean} [args.untracked]
  * @returns {ReviewDocument}
  */
-function buildReviewDocument({ repoPath, comments, generatedAt, head = null, branch = null, mode = null, range = null }) {
+function buildReviewDocument({ repoPath, comments, generatedAt, head = null, branch = null, mode = null, range = null, untracked }) {
   const grouped = groupByFile(comments);
 
   return {
@@ -63,6 +65,9 @@ function buildReviewDocument({ repoPath, comments, generatedAt, head = null, bra
       branch
     },
     mode,
+    // Older saves say nothing about untracked files. Only record an explicit
+    // exclusion in a working comparison; other scopes do not use this flag.
+    ...(mode === 'working' && untracked === false ? { untracked: false } : {}),
     // Omitted rather than null when there is no range, so `"range" in
     // document` is a meaningful test -- the same rule the optional comment
     // fields follow. A `working` review has no range and never will.
@@ -198,10 +203,15 @@ function toAgentComment(comment, id) {
  * @param {ReviewDocument} document
  * @returns {string|null}
  */
-function describeScope({ repository, mode, range }) {
+function describeScope({ repository, mode, range, untracked }) {
   const at = repository.head ? ` (${repository.head})` : '';
 
   if (mode === 'working') {
+    if (untracked === false) {
+      return `Comparison: tracked changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}. ` +
+        'Untracked files are excluded from this comparison. Saved comments are shared between review views ' +
+        'and may refer to changes outside this comparison; check their anchors before applying them.';
+    }
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
@@ -322,4 +332,4 @@ function formatPrompt(document) {
   return `${lines.join('\n')}`;
 }
 
-module.exports = { buildReviewDocument, filterReviewDocument, formatPrompt, SCHEMA };
+module.exports = { buildReviewDocument, filterReviewDocument, formatPrompt, describeScope, SCHEMA };

package/lib/changes.js

@@ -12,8 +12,14 @@
  * @typedef {object} ChangedFile
  * @property {string} path repo-relative path
  * @property {'A'|'M'|'D'|'R'|'B'} status
+ * @property {boolean} [directory] a folded, wholly untracked directory
+ * @property {number} [fileCount] untracked files represented by that directory
  */
 
+// Keep a new source folder reviewable file by file, while hundreds of
+// untracked files take one row instead of pushing tracked edits off screen.
+const UNTRACKED_DIRECTORY_LIMIT = 200;
+
 /**
  * Unquotes git's octal-escaped, C-quoted filename strings (e.g. "\"caf\\303\\251.txt\"" -> "café.txt").
  *
@@ -136,30 +142,101 @@ function parseCommitFilePath(raw) {
  * most- to least-specific for that reason.
  *
  * @param {import('simple-git').StatusResult} status
+ * @param {string[]} [untrackedDirectories] directory entries from Git's normal untracked status
  * @returns {ChangedFile[]}
  */
-function collectWorkingChanges(status) {
+function collectWorkingChanges(status, untrackedDirectories = []) {
+  const directories = new Set(untrackedDirectories.map(unquoteGitPath).filter(p => p?.endsWith('/')));
+  const directoryOf = new Map();
+  const counts = new Map();
+
+  for (const rawPath of status?.not_added ?? []) {
+    const filePath = unquoteGitPath(rawPath);
+    if (!filePath || directoryOf.has(filePath)) continue;
+    // Check path components, not every directory against every file. The
+    // trailing slash also keeps output/ separate from output-neighbor/.
+    for (let slash = filePath.indexOf('/'); slash !== -1; slash = filePath.indexOf('/', slash + 1)) {
+      const directory = filePath.slice(0, slash + 1);
+      if (!directories.has(directory)) continue;
+      directoryOf.set(filePath, directory);
+      counts.set(directory, (counts.get(directory) ?? 0) + 1);
+      break;
+    }
+  }
+
   const buckets = [
     [status?.renamed ?? [], 'R'],
     [status?.deleted ?? [], 'D'],
     [status?.created ?? [], 'A'],
-    [status?.not_added ?? [], 'A'],
+    [status?.not_added ?? [], 'A', true],
     [status?.modified ?? [], 'M']
   ];
 
   const seen = new Map();
+  const untrackedPaths = new Set();
 
-  for (const [files, letter] of buckets) {
+  for (const [files, letter, untracked] of buckets) {
     for (const entry of files) {
       // `renamed` holds `{ from, to }`; every other bucket holds plain strings.
       const rawPath = typeof entry === 'string' ? entry : entry?.to;
       const filePath = unquoteGitPath(rawPath);
       if (!filePath || seen.has(filePath)) continue;
+      const directory = untracked ? directoryOf.get(filePath) : null;
+      const fileCount = counts.get(directory) ?? 0;
+      if (fileCount > UNTRACKED_DIRECTORY_LIMIT) {
+        if (!seen.has(directory)) {
+          seen.set(directory, { path: directory, status: 'A', directory: true, fileCount });
+          untrackedPaths.add(directory);
+        }
+        continue;
+      }
       seen.set(filePath, { path: filePath, status: letter });
+      if (untracked) untrackedPaths.add(filePath);
     }
   }
 
-  return [...seen.values()];
+  // Put tracked edits on screen first without changing status precedence.
+  // The source bucket matters: a staged addition also has status A.
+  const files = [...seen.values()];
+  return [
+    ...files.filter(file => !untrackedPaths.has(file.path)),
+    ...files.filter(file => untrackedPaths.has(file.path))
+  ];
+}
+
+/**
+ * Git's normal status identifies wholly untracked directories; its all
+ * status supplies the files to count and keep individually in small ones.
+ * Turning untracked files off must avoid enumerating them in the first place.
+ * @param {import('simple-git').SimpleGit} git
+ * @param {boolean} [untracked]
+ * @returns {Promise<ChangedFile[]>}
+ */
+async function collectWorkingTreeChanges(git, untracked = true) {
+  if (!untracked) return collectWorkingChanges(await git.status(['--untracked-files=no']));
+  const status = await git.status(['--untracked-files=normal']);
+  const directories = (status.not_added ?? []).filter(p => unquoteGitPath(p).endsWith('/'));
+  if (!directories.length) return collectWorkingChanges(status);
+  return collectWorkingChanges(await git.status(['--untracked-files=all']), directories);
+}
+
+/** Explain the visible rows and the files represented by folded directories. */
+function describeWorkingChanges(files, untracked = true) {
+  const directories = files.filter(file => file.directory);
+  const count = files.length - directories.length;
+  const headline = `Found ${count} changed file${count === 1 ? '' : 's'}`;
+  if (!untracked) {
+    const changes = count ? headline : 'No tracked changes';
+    return `${changes} — untracked files hidden`;
+  }
+  const total = directories.reduce((sum, file) => sum + file.fileCount, 0);
+  const summary = directories.length
+    ? `; ${directories.length} folder${directories.length === 1 ? '' : 's'} folded (${total.toLocaleString('en-US')} untracked files)`
+    : '';
+  const folded = directories.map(file =>
+    `${file.path} holds ${file.fileCount.toLocaleString('en-US')} untracked files; individual files are not listed.`
+  ).join(' ');
+  return headline + summary + (folded ? `. ${folded}` : '');
 }
 
 /**
@@ -287,6 +364,8 @@ async function collectStagedChanges(git) {
 module.exports = {
   collectStagedChanges,
   collectWorkingChanges,
+  collectWorkingTreeChanges,
+  describeWorkingChanges,
   collectCommitChanges,
   classifyCommitFile,
   unquoteGitPath,

package/lib/cli.js

@@ -43,7 +43,10 @@ Options:
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --no-intro    Open the review without the first-run help
+      --no-untracked Exclude untracked files from working directory reviews
       --staged      Review only staged changes (HEAD vs index)
+      --json        Print one JSON line on stderr at startup instead of the banner
   -f, --format <f>  Export format: json (default) or prompt
       --file <path> Export comments for one repo-relative file
   -h, --help        Show this help
@@ -84,7 +87,10 @@ class UsageError extends Error {
  * @property {string|null} repoPath absolute path, or null when not given
  * @property {number|null} port explicit port, or null to use the default
  * @property {boolean} open whether to launch a browser
+ * @property {boolean} noIntro skip the first-run help dialog
  * @property {boolean} staged whether to review only the index
+ * @property {boolean} untracked whether to include untracked files
+ * @property {boolean} json whether to print the startup info as one JSON line
  * @property {'json'|'prompt'} format for `export`
  * @property {string|null} file repo-relative file to export, or all files
  * @property {boolean} help
@@ -106,7 +112,10 @@ function parseArgs(argv, cwd = process.cwd()) {
     repoPath: null,
     port: null,
     open: true,
+    noIntro: false,
     staged: false,
+    untracked: true,
+    json: false,
     format: 'json',
     file: null,
     help: false,
@@ -141,10 +150,22 @@ function parseArgs(argv, cwd = process.cwd()) {
         options.open = false;
         break;
 
+      case '--no-intro':
+        options.noIntro = true;
+        break;
+
       case '--staged':
         options.staged = true;
         break;
 
+      case '--no-untracked':
+        options.untracked = false;
+        break;
+
+      case '--json':
+        options.json = true;
+        break;
+
       case '-p':
       case '--port': {
         const value = rest[++i];
@@ -211,7 +232,16 @@ function parseArgs(argv, cwd = process.cwd()) {
   if (options.staged && options.command !== 'serve') {
     throw new UsageError('--staged is only valid when serving a review');
   }
+  if (options.noIntro && options.command !== 'serve') {
+    throw new UsageError('--no-intro is only valid when serving a review');
+  }
+  if (!options.untracked && options.command !== 'serve') {
+    throw new UsageError('--no-untracked is only valid when serving a review');
+  }
 
+  if (options.json && options.command !== 'serve') {
+    throw new UsageError('--json is only valid when serving a review');
+  }
   return options;
 }
 
@@ -261,21 +291,28 @@ function parseFile(value, flag) {
  * @param {string} origin e.g. http://127.0.0.1:4500
  * @param {string|null} repoPath
  * @param {boolean} [staged]
+ * @param {boolean} [noIntro] add intro=0 so a fresh browser skips the first-run help
+ * @param {boolean} [untracked] include untracked files in working directory reviews
  * @returns {string}
  */
-function buildUrl(origin, repoPath, staged = false) {
-  if (!repoPath) return staged ? `${origin}/?staged=1` : origin;
-
-  // Slashes are left as slashes. They are legal in a query value -- RFC 3986
-  // has `query = *( pchar / "/" / "?" )` -- and encoding them turns the most
-  // prominent line the command prints into %2F soup:
-  //
-  //   before  http://127.0.0.1:4500/?repo=%2FUsers%2Fyou%2Fwork%2Fapi
-  //   after   http://127.0.0.1:4500/?repo=/Users/you/work/api
-  //
-  // Everything else stays encoded, including the characters that would
-  // otherwise end the query and take the rest of the path with them.
-  return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}${staged ? '&staged=1' : ''}`;
+function buildUrl(origin, repoPath, staged = false, noIntro = false, untracked = true) {
+  const params = [];
+  if (repoPath) {
+    // Slashes are left as slashes. They are legal in a query value -- RFC 3986
+    // has `query = *( pchar / "/" / "?" )` -- and encoding them turns the most
+    // prominent line the command prints into %2F soup:
+    //
+    //   before  http://127.0.0.1:4500/?repo=%2FUsers%2Fyou%2Fwork%2Fapi
+    //   after   http://127.0.0.1:4500/?repo=/Users/you/work/api
+    //
+    // Everything else stays encoded, including the characters that would
+    // otherwise end the query and take the rest of the path with them.
+    params.push(`repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}`);
+  }
+  if (staged) params.push('staged=1');
+  if (noIntro) params.push('intro=0');
+  if (!untracked) params.push('untracked=0');
+  return params.length === 0 ? origin : `${origin}/?${params.join('&')}`;
 }
 
 /**

package/lib/export.js

@@ -100,7 +100,7 @@ async function readGitPosition(repoPath) {
  *   records a different repository than the one asked for
  */
 async function loadReviewDocument(reviewsDir, repoPath, { file = null } = {}) {
-  const { comments, mode, range } = await readSavedComments(reviewsDir, repoPath);
+  const { comments, mode, range, untracked } = await readSavedComments(reviewsDir, repoPath);
 
   if (comments.length === 0) throw new NoReviewError(repoPath);
 
@@ -121,7 +121,7 @@ async function loadReviewDocument(reviewsDir, repoPath, { file = null } = {}) {
   // same object reference when no filter is given. `test/agent.test.js`
   // asserts that identity with `assert.equal`.
   const document = filterReviewDocument(
-    buildReviewDocument({ repoPath, comments, generatedAt: new Date(), head, branch, mode, range }),
+    buildReviewDocument({ repoPath, comments, generatedAt: new Date(), head, branch, mode, range, untracked }),
     { file }
   );
 

package/lib/review.js

@@ -124,13 +124,15 @@ function reviewFilename(repoPath, generatedAt) {
  * @param {string} args.repoPath repository the review covers
  * @param {import('./comments').Comment[]} args.comments
  * @param {Date} args.generatedAt
+ * @param {string|null} [args.scope] an explanation of an explicitly restricted comparison
  * @returns {string}
  */
-function formatReview({ repoPath, comments, generatedAt }) {
+function formatReview({ repoPath, comments, generatedAt, scope = null }) {
   const sections = [
     '# Code Review\n',
     `Repository: ${repoPath}`,
     `Generated: ${generatedAt.toISOString()}`,
+    ...(scope ? [scope] : []),
     `Total Comments: ${comments.length}\n`
   ];
 

package/lib/sessions.js

@@ -35,7 +35,7 @@ class SessionStore {
    */
   constructor(generateId = () => crypto.randomBytes(8).toString('hex')) {
     this.generateId = generateId;
-    /** @type {Map<string, {repoPath: string, mode: ReviewMode, range: ReviewRange|null}>} */
+    /** @type {Map<string, {repoPath: string, mode: ReviewMode, range: ReviewRange|null, untracked?: boolean}>} */
     this.sessions = new Map();
   }
 
@@ -43,17 +43,21 @@ class SessionStore {
    * @param {string} repoPath absolute path of the opened repository
    * @param {ReviewMode} mode
    * @param {ReviewRange|null} [range] the two refs, for a commit-based review
+   * @param {boolean} [untracked] whether a working comparison includes untracked files
    * @returns {string} the new session id
    */
-  create(repoPath, mode, range = null) {
+  create(repoPath, mode, range = null, untracked = true) {
     const repoId = this.generateId();
-    this.sessions.set(repoId, { repoPath, mode, range });
+    this.sessions.set(repoId, {
+      repoPath, mode, range,
+      ...(mode === 'working' && untracked === false ? { untracked: false } : {})
+    });
     return repoId;
   }
 
   /**
    * @param {string} repoId
-   * @returns {{repoPath: string, mode: ReviewMode, range: ReviewRange|null}|undefined}
+   * @returns {{repoPath: string, mode: ReviewMode, range: ReviewRange|null, untracked?: boolean}|undefined}
    */
   get(repoId) {
     return this.sessions.get(repoId);

package/lib/store.js

@@ -74,7 +74,7 @@ async function readJson(file) {
  *
  * @param {string} reviewsDir
  * @param {string} repoPath
- * @returns {Promise<{comments: object[], mode: string|null, range: object|null, adopted: boolean}>}
+ * @returns {Promise<{comments: object[], mode: string|null, range: object|null, untracked?: boolean, adopted: boolean}>}
  *   `mode` is null for a file written before it was recorded -- there is
  *   nothing on disk that says what was compared, and guessing would be
  *   worse than admitting it.
@@ -90,7 +90,11 @@ async function readSavedComments(reviewsDir, repoPath) {
     if (!belongsTo(saved.repoPath, repoPath)) {
       throw new ReviewOwnershipError(repoPath, saved.repoPath);
     }
-    return { comments: saved.comments ?? [], mode: saved.mode ?? null, range: saved.range ?? null, adopted: false };
+    return {
+      comments: saved.comments ?? [], mode: saved.mode ?? null, range: saved.range ?? null,
+      ...(saved.mode === 'working' && saved.untracked === false ? { untracked: false } : {}),
+      adopted: false
+    };
   }
 
   const legacyName = legacyCommentsFilename(repoPath);
@@ -110,7 +114,11 @@ async function readSavedComments(reviewsDir, repoPath) {
     /* the comments are already in hand; renaming is housekeeping */
   }
 
-  return { comments: legacy.comments ?? [], mode: legacy.mode ?? null, range: legacy.range ?? null, adopted: true };
+  return {
+    comments: legacy.comments ?? [], mode: legacy.mode ?? null, range: legacy.range ?? null,
+    ...(legacy.mode === 'working' && legacy.untracked === false ? { untracked: false } : {}),
+    adopted: true
+  };
 }
 
 module.exports = { readSavedComments, ReviewOwnershipError, belongsTo };

package/man/git-reviewer.1

@@ -9,6 +9,7 @@ git-reviewer, reviewer \- review local git changes in your browser, and hand the
 .RB [ \-p
 .IR port ]
 .RB [ \-\-no\-open ]
+.RB [ \-\-no\-untracked ]
 .br
 .B git reviewer export
 .RI [ repository ]
@@ -51,10 +52,20 @@ Port to listen on. The default is 4500; if it is taken, a free one is used.
 .B \-\-no\-open
 Print the address instead of opening a browser.
 .TP
+.B \-\-no\-intro
+Open the review without the first-run help. The ? button still opens it.
+The page is told with
+.B intro=0
+in the URL.
+.TP
 .B \-\-staged
 Review only staged changes, comparing HEAD with the index. Unstaged edits are
 excluded, and an empty index comparison does not fall back to the last commit.
 .TP
+.B \-\-no\-untracked
+Exclude untracked files from working directory reviews. Tracked changes remain
+reviewable. This option is only valid when serving a review.
+.TP
 .BR \-f ", " \-\-format " \fIjson\fR|\fIprompt\fR"
 Export format. The default is json.
 .TP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-reviewer",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "description": "Review your coding agent's changes like a pull request — locally, with inline comments and threaded follow-ups, then hand the marked-up review back to the agent",
   "author": "Dheeraj Jha",
   "license": "MIT",

package/public/app.js

@@ -3,6 +3,7 @@
 // In Electron, this will be the random port Electron assigned
 const API_BASE = `${window.location.origin}/api`;
 const stagedByDefault = new URLSearchParams(window.location.search).get('staged') === '1';
+const untrackedByDefault = new URLSearchParams(window.location.search).get('untracked') !== '0';
 
 let currentRepoId = null;
 let currentFiles = [];
@@ -495,8 +496,15 @@ function renderScope(data) {
   } else {
     label.append(data.mode === 'staged' ? 'Staged changes' : 'Uncommitted changes');
     if (branch) label.append(' on ', strong(branch));
-    meta.textContent = plural(data.files.length, 'file') + ' changed';
-    setNote(data.mode === 'staged' ? 'The diff excludes unstaged changes. Saved comments are shared between views and may refer to other code; check their anchors.' : null);
+    const folders = data.files.filter(file => file.directory);
+    const foldedFiles = folders.reduce((sum, file) => sum + file.fileCount, 0);
+    meta.textContent = plural(data.files.length - folders.length, 'file') + ' changed' + (folders.length
+      ? `; ${plural(folders.length, 'folder')} folded (${foldedFiles.toLocaleString('en-US')} untracked files)`
+      : '');
+    setNote(data.mode === 'staged'
+      ? 'The diff excludes unstaged changes. Saved comments are shared between views and may refer to other code; check their anchors.'
+      : data.files.some(file => file.directory) ? data.message
+        : data.untracked === false ? 'Untracked files are excluded.' : null);
   }
 
   row.classList.add('hidden');
@@ -782,7 +790,7 @@ async function loadRepo(scope = {}) {
       body: JSON.stringify(
         scope.commits ? { repoPath, commits: scope.commits }
           : scope.base ? { repoPath, base: scope.base, ...(scope.head ? { head: scope.head } : {}) }
-            : { repoPath, staged: stagedByDefault }
+            : { repoPath, staged: stagedByDefault, ...(untrackedByDefault ? {} : { untracked: false }) }
       )
     });
 
@@ -818,13 +826,13 @@ async function loadRepo(scope = {}) {
       // `message`, and the scope bar above is still showing how many commits
       // that covers -- so this is information, not an error, and it must not
       // be dressed as one.
-      if (data.mode === 'range' || data.mode === 'staged') {
+      if (data.mode === 'range' || data.mode === 'staged' || data.untracked === false) {
         // The scope bar is already explaining this; a status line repeating
         // it underneath is two bars saying one thing.
         clearStatus();
         hidePicker();
         displayFiles([]);
-        showEmptyFileList(data.mode === 'staged' ? 'No staged changes.' : data.range?.kind !== 'commits'
+        showEmptyFileList(data.mode === 'staged' ? 'No staged changes.' : data.mode === 'working' ? 'No tracked changes.' : data.range?.kind !== 'commits'
           ? 'No files differ between these two.'
           : data.range.first === data.range.last
             ? 'This commit changes no files.'
@@ -882,7 +890,8 @@ async function loadRepo(scope = {}) {
     // repository does not move you off what you were reading.
     if (currentFiles.length > 0) {
       const previous = currentFiles.findIndex(file => file.path === currentFile);
-      const opening = previous === -1 ? 0 : previous;
+      const firstFile = currentFiles.findIndex(file => !file.directory);
+      const opening = previous === -1 ? Math.max(0, firstFile) : previous;
 
       loadFile(currentFiles[opening].path, opening);
       offerHelpOnce();
@@ -927,7 +936,7 @@ function displayFiles(files) {
   filesList.innerHTML = files.map((fileObj, index) => {
     const file = fileObj.path;
     const status = fileObj.status;
-    const parts = file.split('/');
+    const parts = (fileObj.directory ? file.slice(0, -1) : file).split('/');
     const filename = parts[parts.length - 1];
     const path = parts.slice(0, -1).join('/');
 
@@ -936,9 +945,10 @@ function displayFiles(files) {
     // both halves are escaped going in. They were not, and a name is chosen by
     // whatever repository is open: markup in one was drawn as markup, without
     // anyone clicking anything.
-    const displayText = path
+    let displayText = path
       ? `${escapeHtml(path)}/<span class="filename">${escapeHtml(filename)}</span>`
       : `<span class="filename">${escapeHtml(filename)}</span>`;
+    if (fileObj.directory) displayText = `<bdi dir="ltr">${displayText}/</bdi>`;
     const statusClass = fileStatusClass(status);
     // One letter is git's vocabulary, not everyone's. The name rides along as
     // a tooltip and as the accessible label, so "D" is never the only thing
@@ -959,11 +969,16 @@ function displayFiles(files) {
     // true, and re-rendering the list is what loses the selected row.
     return `<div class="file-item" onclick="openFileAt(${Number(index)})" title="${escapeHtml(file)}">
       ${statusBadge}<span class="file-path-text">${displayText}</span>
+      ${fileObj.directory ? `<span class="file-fold-count">${Number(fileObj.fileCount).toLocaleString('en-US')} files</span>` : ''}
       <span class="file-comment-count" data-file-index="${Number(index)}" hidden></span>
     </div>`;
   }).join('');
 
-  fileCount.textContent = `${files.length} file${files.length !== 1 ? 's' : ''}`;
+  const folders = files.filter(file => file.directory).length;
+  const individualFiles = files.length - folders;
+  fileCount.textContent = `${individualFiles} file${individualFiles !== 1 ? 's' : ''}` + (folders
+    ? ` · ${folders} folder${folders !== 1 ? 's' : ''}`
+    : '');
   sidebar.classList.remove('hidden');
   resizeHandle.classList.remove('hidden');
   submitBtn.classList.remove('hidden');
@@ -991,6 +1006,7 @@ function openFileAt(index) {
 // Load file content
 async function loadFile(filePath, index) {
   if (!currentRepoId) return Promise.resolve();
+  const repoId = currentRepoId;
 
   currentFile = filePath;
   currentFileIndex = index; // Track for keyboard navigation
@@ -1007,9 +1023,30 @@ async function loadFile(filePath, index) {
     }
   });
 
+  const file = currentFiles[index];
+  const fullContextButton = document.querySelector('.full-context-btn');
+  if (fullContextButton) fullContextButton.disabled = !!file?.directory;
+  if (file?.directory) {
+    // A folded row describes a directory; there is no file or diff to fetch.
+    currentDiffLines = [];
+    document.getElementById('currentFile').textContent = filePath;
+    const section = document.getElementById('codeSection');
+    section.classList.remove('hidden');
+    section.style.display = 'block';
+    document.getElementById('codeViewer').innerHTML =
+      `<div class="binary-notice">${Number(file.fileCount).toLocaleString('en-US')} untracked files` +
+      '<span>This directory is folded because it contains more than 200 files. ' +
+      'Individual files and diffs are not shown. Add generated output to .gitignore to exclude it from future reviews.</span></div>';
+    updateFullContextButton();
+    return;
+  }
+
   try {
-    const response = await fetch(`${API_BASE}/file/${currentRepoId}/${filePath}`);
+    const response = await fetch(`${API_BASE}/file/${repoId}/${filePath}`);
     const data = await response.json();
+    // A directory can be selected while a previous file request is in flight.
+    // Its no-diff pane must not be replaced with that file's editable lines.
+    if (currentRepoId !== repoId || currentFile !== filePath) return;
 
     if (!response.ok) {
       throw new Error(data.error || 'Failed to load file');
@@ -1076,6 +1113,7 @@ async function loadFile(filePath, index) {
     return Promise.resolve();
 
   } catch (error) {
+    if (currentRepoId !== repoId || currentFile !== filePath) return;
     showStatus(`Error loading file: ${error.message}`, 'error');
     return Promise.reject(error);
   }
@@ -1956,6 +1994,9 @@ let storedFullFileLines = null;
 // Toggle between full context and diff-only view
 async function showFullContext() {
   if (!currentRepoId || !currentFile) return;
+  if (currentFiles.some(file => file.path === currentFile && file.directory)) return;
+  const repoId = currentRepoId;
+  const filePath = currentFile;
 
   if (isFullContextMode) {
     // Switch back to diff view
@@ -1965,8 +2006,9 @@ async function showFullContext() {
   } else {
     // Switch to full context
     try {
-      const response = await fetch(`${API_BASE}/file-full/${currentRepoId}/${currentFile}`);
+      const response = await fetch(`${API_BASE}/file-full/${repoId}/${filePath}`);
       const data = await response.json();
+      if (currentRepoId !== repoId || currentFile !== filePath) return;
 
       if (!response.ok) {
         throw new Error(data.error || 'Failed to load full file content');
@@ -1978,6 +2020,7 @@ async function showFullContext() {
       updateFullContextButton();
 
     } catch (error) {
+      if (currentRepoId !== repoId || currentFile !== filePath) return;
       showStatus(`Error loading full context: ${error.message}`, 'error');
     }
   }
@@ -2842,6 +2885,23 @@ function closeHelp() {
   document.getElementById('helpModal').classList.add('hidden');
 }
 
+/**
+ * Whether the first-run help should open on its own.
+ *
+ * `intro=0` is an explicit no, for an automation that starts from a fresh
+ * browser every time. Otherwise the dialog opens once per browser, until it
+ * has been seen. Asking for it with the ? button does not come through here.
+ *
+ * @param {string} search location.search, with or without the leading ?
+ * @param {boolean} seen
+ * @returns {boolean}
+ */
+function shouldOfferHelp(search, seen) {
+  // The same reader the page uses for `repo` and `staged`.
+  if (new URLSearchParams(search || '').get('intro') === '0') return false;
+  return !seen;
+}
+
 /**
  * Offer it unprompted the first time, once a repository is actually on screen.
  *
@@ -2849,7 +2909,7 @@ function closeHelp() {
  * would be the first thing between somebody and the tool they just started.
  */
 function offerHelpOnce() {
-  if (helpWasSeen()) return;
+  if (!shouldOfferHelp(window.location.search, helpWasSeen())) return;
   openHelp();
 }
 

package/public/style.css

@@ -211,6 +211,12 @@ button:disabled {
   flex-shrink: 0;
 }
 
+.file-fold-count {
+  flex-shrink: 0;
+  font-size: 11px;
+  color: #6a737d;
+}
+
 .file-status-added {
   background: #28a745;
   color: white;

package/server.js

@@ -12,11 +12,11 @@ const {
   resolveRepoFile,
   PathEscapeError
 } = require('./lib/paths');
-const { collectWorkingChanges, collectStagedChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
+const { collectWorkingTreeChanges, describeWorkingChanges, collectStagedChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
 const { SessionStore } = require('./lib/sessions');
 const { normalizeComments } = require('./lib/comments');
 const { formatReview, reviewFilename, commentsFilename } = require('./lib/review');
-const { buildReviewDocument } = require('./lib/agent');
+const { buildReviewDocument, describeScope } = require('./lib/agent');
 const { readSavedComments, ReviewOwnershipError } = require('./lib/store');
 const { repoRoot } = require('./lib/repo');
 const { browse } = require('./lib/browse');
@@ -838,7 +838,10 @@ function createApp(options = {}) {
       // Resolve to the root of the working tree before anything is keyed on
       // this path. A subdirectory passes `checkIsRepo()` quite happily and
       // then produces a file list whose diffs are all empty; see lib/repo.js.
-      const { base, head, commits: run, staged = false } = req.body ?? {};
+      const { base, head, commits: run, staged = false, untracked = true } = req.body ?? {};
+      if (typeof untracked !== 'boolean') {
+        return res.status(400).json({ error: 'The untracked option must be a boolean.' });
+      }
       if (typeof staged !== 'boolean' || (staged && (base != null || head != null || run != null))) {
         return res.status(400).json({ error: 'Choose staged changes or a commit comparison, not both.' });
       }
@@ -887,12 +890,14 @@ function createApp(options = {}) {
         mode = 'range';
         message = describeRange(range, files.length);
       } else {
-        files = collectWorkingChanges(await git.status());
+        files = await collectWorkingTreeChanges(git, untracked);
         mode = 'working';
-        message = `Found ${files.length} changed file(s)`;
+        message = describeWorkingChanges(files, untracked);
 
         // A clean tree has nothing to review, so fall back to the last commit.
-        if (files.length === 0) {
+        // Hiding untracked files is an explicit working-tree scope. An empty
+        // tracked review must not silently become a review of committed work.
+        if (files.length === 0 && untracked) {
           try {
             const lastCommit = await resolveRange(git, 'HEAD~1', 'HEAD');
             const commitFiles = await collectRangeChanges(git, lastCommit);
@@ -910,7 +915,10 @@ function createApp(options = {}) {
         }
       }
 
-      const repoId = sessions.create(root, mode, range);
+      const repoId = sessions.create(root, mode, range, untracked);
+      sessions.get(repoId).foldedDirectories = new Map(
+        files.filter(file => file.directory).map(file => [file.path, file.fileCount])
+      );
       // stderr, not stdout. `reviewer | claude -p ...` puts the finished
       // review on stdout, and anything else written there lands in the middle
       // of it. Progress is for the person watching; stdout is for the pipe.
@@ -925,7 +933,7 @@ function createApp(options = {}) {
 
       // `repoPath` in the response is the resolved root, not what was asked
       // for, so the page can show which repository it actually opened.
-      res.json({ repoId, files, repoPath: root, mode, range, message });
+      res.json({ repoId, files, repoPath: root, mode, range, message, untracked });
     } catch (error) {
       console.error('Load repo error:', error);
       res.status(500).json({ error: error.message });
@@ -946,6 +954,10 @@ function createApp(options = {}) {
       // works because of statement order is not a containment check.
       resolveRepoFile(session.repoPath, filePath);
 
+      if (session.foldedDirectories?.has(filePath)) {
+        return res.json({ filePath, directory: true, fileCount: session.foldedDirectories.get(filePath), binary: false, diffLines: [] });
+      }
+
       const git = gitFactory(session.repoPath);
       const diffText = await diffForFile(git, session, filePath);
 
@@ -978,6 +990,11 @@ function createApp(options = {}) {
       const session = requireSession(res, repoId);
       if (!session) return;
 
+      resolveRepoFile(session.repoPath, filePath);
+      if (session.foldedDirectories?.has(filePath)) {
+        return res.json({ filePath, directory: true, fileCount: session.foldedDirectories.get(filePath), lines: [] });
+      }
+
       const content = await readFileForMode(session, filePath);
       res.json({ filePath, lines: content.split('\n') });
     } catch (error) {
@@ -1018,6 +1035,7 @@ function createApp(options = {}) {
         lastUpdated: new Date().toISOString(),
         mode: session.mode,
         range: session.range,
+        ...(session.untracked === false ? { untracked: false } : {}),
         comments: normalized
       };
 
@@ -1066,7 +1084,6 @@ function createApp(options = {}) {
       }
 
       const generatedAt = new Date();
-      const reviewContent = formatReview({ repoPath: session.repoPath, comments, generatedAt });
       const filename = reviewFilename(session.repoPath, generatedAt);
 
       // The commit is worth recording for anything acting on the review later:
@@ -1082,7 +1099,12 @@ function createApp(options = {}) {
         head,
         branch,
         mode: session.mode,
-        range: session.range
+        range: session.range,
+        untracked: session.untracked
+      });
+      const reviewContent = formatReview({
+        repoPath: session.repoPath, comments, generatedAt,
+        scope: document.untracked === false ? describeScope(document) : null
       });
       const documentFilename = filename.replace(/\.txt$/, '.json');