Respect (linguist|gitlab)-generated in .gitattributes (#115)

This PR adds support for `.gitattributes` files being able to either
consider a file as generated, or remove a typically generated file (i.e
in folders such as `out`) from being considered as generated. This is
complimentary to the existing path-based heuristics.

Both negation (`-linguist-generated`) and a `false` value
(`linguist-generated=false`) are supported.

`git check-attr --source=` is used but if the Git version is older than
2.40, when [the `--source` option was
introduced](https://github.blog/open-source/git/highlights-from-git-2-40/#:~:text=While%20we%E2%80%99re%20talking%20about%20scripting),
it will fall-back to the previous method of generating an index first
with `git read-tree`.

Files marked as generated are collapsed by default and given a small
`Generated` badge:

<img width="3211" height="390" alt="image"
src="https://github.com/user-attachments/assets/4224a9e1-5c81-4ee5-acd5-46cff95de674"
/>

The walkthrough agent will group these generated files in the final
support section but if they are deemed to be behaviourally important, it
may still be included in a named section.

Author: KianNH

bin/walkthrough-guide.md

@@ -39,8 +39,10 @@ choose.
 - **`support[]`** — changed hunks that should stay off the main path. Use it for generated files,
   lockfiles, snapshots, docs-only changes, and repeated mechanical edits unless they are essential
   to review. Codiff adds any omitted live-diff hunks to support. Generated-like files are one
-  synthetic hunk per changed section; never split them, but keep behavior-relevant snapshots or
-  artifacts on the main path.
+  synthetic hunk per changed section; never split them, use `reason: "Generated files"` for
+  generated-only support items so they render together, but keep behavior-relevant snapshots or
+  artifacts on the main path. Codiff also recognizes `linguist-generated` and `gitlab-generated`
+  attributes from `.gitattributes`.
 - **`changeType?` / `commitNote?`** — optional commit composer metadata for committable
   walkthroughs.
 - **`commit?`** — for working-tree walkthroughs, include `title` and `body` when there is enough

core/App.css

@@ -2713,6 +2713,7 @@ html[data-codiff-platform='darwin'] .sidebar {
 
 .codiff-status-badge,
 .codiff-section-badge,
+.codiff-generated-badge,
 .codiff-line-count,
 .codiff-file-comment-button,
 .codiff-load-button,
@@ -2726,13 +2727,19 @@ html[data-codiff-platform='darwin'] .sidebar {
 
 .codiff-status-badge,
 .codiff-section-badge,
+.codiff-generated-badge,
 .codiff-line-count {
   background: rgb(127 127 127 / 0.11);
   color: var(--muted);
   padding: 5px 9px;
   white-space: nowrap;
 }
 
+.codiff-generated-badge {
+  background: color-mix(in srgb, var(--sidebar-ref) 15%, transparent);
+  color: var(--sidebar-ref);
+}
+
 .codiff-line-count {
   display: inline-flex;
   font-family: var(--font-mono);

core/App.tsx

@@ -70,6 +70,7 @@ import {
 } from './lib/diff.ts';
 import { compactPath, fuzzyMatches, sortFiles } from './lib/files.ts';
 import { isNativeInputTarget } from './lib/keyboard.ts';
+import { isGeneratedWalkthroughFile } from './lib/narrative-walkthrough-diff.js';
 import { buildCommitModel, buildGenericCommitModel } from './lib/narrative-walkthrough.ts';
 import {
   consumeReloadSelection,
@@ -228,6 +229,7 @@ const getReloadSourceForLaunch = (
 
 export default function App() {
   const [collapsed, setCollapsed] = useState<Set<string>>(() => new Set());
+  const [expandedGenerated, setExpandedGenerated] = useState<Set<string>>(() => new Set());
   const [activeDiffSearchMatchIndex, setActiveDiffSearchMatchIndex] = useState(0);
   const [diffSearchFocusRequest, setDiffSearchFocusRequest] = useState(0);
   const [diffSearchQuery, setDiffSearchQuery] = useState('');
@@ -301,6 +303,7 @@ export default function App() {
   const stateRef = useRef<RepositoryState | null>(null);
   const activeReviewCommandTargetRef = useRef<ReviewCommandTarget | null>(null);
   const collapsedRef = useRef<Set<string>>(new Set());
+  const expandedGeneratedRef = useRef<Set<string>>(new Set());
   const preferencesRef = useRef<CodiffPreferences>(defaultPreferences);
   const reviewCommentsRef = useRef<ReadonlyArray<ReviewComment>>([]);
   const selectedPathRef = useRef<string | null>(null);
@@ -558,6 +561,13 @@ export default function App() {
         }
         return next;
       });
+      if (nextViewed) {
+        setExpandedGenerated((current) => {
+          const next = new Set(current);
+          next.delete(file.path);
+          return next;
+        });
+      }
       bumpItemVersion(file.path);
     },
     [bumpItemVersion],
@@ -571,6 +581,7 @@ export default function App() {
 
     sourceSessionsRef.current.set(getSourceKey(currentState.source), {
       collapsed: new Set(collapsedRef.current),
+      expandedGenerated: new Set(expandedGeneratedRef.current),
       narrativeWalkthrough: narrativeWalkthroughRef.current,
       reviewComments: reviewCommentsRef.current,
       selectedPath: selectedPathRef.current,
@@ -733,6 +744,7 @@ export default function App() {
       setState(orderedState);
       setLoadError(null);
       setCollapsed(getCollapsedViewedPaths(orderedState.files, nextViewed));
+      setExpandedGenerated(new Set());
       setItemVersionByKey({});
       setFocusCommentId(null);
       setFocusCommentRequest(0);
@@ -1026,6 +1038,7 @@ export default function App() {
           setReviewComments(getReviewCommentsFromState(orderedState));
           setViewed(nextViewed);
           setCollapsed(getCollapsedViewedPaths(orderedState.files, nextViewed));
+          setExpandedGenerated(new Set());
           setLoadError(null);
         })
         .catch((error: unknown) => {
@@ -1097,6 +1110,10 @@ export default function App() {
     collapsedRef.current = collapsed;
   }, [collapsed]);
 
+  useEffect(() => {
+    expandedGeneratedRef.current = expandedGenerated;
+  }, [expandedGenerated]);
+
   useEffect(() => {
     reviewCommentsRef.current = reviewComments;
   }, [reviewComments]);
@@ -1601,11 +1618,13 @@ export default function App() {
               : (orderedState.files[0]?.path ?? null);
           const nextCollapsed =
             session?.collapsed ?? getCollapsedViewedPaths(orderedState.files, nextViewed);
+          const nextExpandedGenerated = session?.expandedGenerated ?? new Set<string>();
 
           stateGenerationRef.current += 1;
           setState(orderedState);
           setHistorySource(getHistorySource(orderedState.source) ?? historySource);
           setCollapsed(new Set(nextCollapsed));
+          setExpandedGenerated(new Set(nextExpandedGenerated));
           setItemVersionByKey({});
           setReviewComments(session?.reviewComments ?? getReviewCommentsFromState(orderedState));
           setReloadDeltaPaths(new Set());
@@ -1814,6 +1833,13 @@ export default function App() {
       });
 
       setCollapsed((current) => updateReviewIdentityCollapsed(current, reviewIdentity, isViewed));
+      if (!isViewed) {
+        setExpandedGenerated((current) => {
+          const next = new Set(current);
+          next.delete(reviewIdentity.key);
+          return next;
+        });
+      }
       bumpItemVersion(reviewIdentity.key);
     },
     [bumpItemVersion],
@@ -2028,6 +2054,15 @@ export default function App() {
         }
         return next;
       });
+      setExpandedGenerated((current) => {
+        const next = new Set(current);
+        if (isCollapsed && isGeneratedWalkthroughFile(file)) {
+          next.add(reviewKey);
+        } else {
+          next.delete(reviewKey);
+        }
+        return next;
+      });
       bumpItemVersion(reviewKey);
     },
     [bumpItemVersion],
@@ -2542,6 +2577,7 @@ export default function App() {
     commitMetadata,
     diffLineHeight,
     diffStyle,
+    expandedGenerated,
     focusCommentId,
     focusCommentRequest,
     gitIdentity,

core/SharedWalkthroughApp.tsx

@@ -62,7 +62,7 @@ import {
 } from './lib/diff.ts';
 import { compactPath, fileTreeSort, fuzzyMatches, sortFiles, statusForTree } from './lib/files.ts';
 import { isNativeInputTarget } from './lib/keyboard.ts';
-import { isGeneratedWalkthroughPath } from './lib/narrative-walkthrough-diff.js';
+import { isGeneratedWalkthroughFile } from './lib/narrative-walkthrough-diff.js';
 import {
   getCommentKey,
   getReviewCommentsFromState,
@@ -1051,6 +1051,7 @@ function ReviewSurface({
   );
   const keymap = useMemo(() => createDefaultConfig().keymap, []);
   const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set());
+  const [expandedGenerated, setExpandedGenerated] = useState<ReadonlySet<string>>(() => new Set());
   const [fileSearchQuery, setFileSearchQuery] = useState('');
   const [itemVersionByKey, setItemVersionByKey] = useState<Record<string, number>>({});
   const [selectedPath, setSelectedPath] = useState<string | null>(
@@ -1140,9 +1141,7 @@ function ReviewSurface({
       ? selectedPath
       : (visibleFiles[0]?.path ?? null);
   const initialMarkdownPreviewSectionIds = useMemo(() => {
-    const nonGeneratedFiles = snapshot.files.filter(
-      (file) => !isGeneratedWalkthroughPath(file.path),
-    );
+    const nonGeneratedFiles = snapshot.files.filter((file) => !isGeneratedWalkthroughFile(file));
     if (
       nonGeneratedFiles.length === 0 ||
       !nonGeneratedFiles.every((file) => isMarkdownFilePath(file.path))
@@ -1611,7 +1610,7 @@ function ReviewSurface({
   }, []);
 
   const toggleCollapsed = useCallback(
-    (_file: ChangedFile, isCollapsed: boolean, reviewKey: string) => {
+    (file: ChangedFile, isCollapsed: boolean, reviewKey: string) => {
       setCollapsed((current) => {
         const next = new Set(current);
         if (isCollapsed) {
@@ -1621,6 +1620,15 @@ function ReviewSurface({
         }
         return next;
       });
+      setExpandedGenerated((current) => {
+        const next = new Set(current);
+        if (isCollapsed && isGeneratedWalkthroughFile(file)) {
+          next.add(reviewKey);
+        } else {
+          next.delete(reviewKey);
+        }
+        return next;
+      });
       bumpItemVersion(reviewKey);
     },
     [bumpItemVersion],
@@ -1629,6 +1637,13 @@ function ReviewSurface({
     (_file: ChangedFile, isViewed: boolean, reviewIdentity: ReviewIdentity) => {
       setViewed((current) => updateReviewIdentityViewed(current, reviewIdentity, isViewed));
       setCollapsed((current) => updateReviewIdentityCollapsed(current, reviewIdentity, isViewed));
+      if (!isViewed) {
+        setExpandedGenerated((current) => {
+          const next = new Set(current);
+          next.delete(reviewIdentity.key);
+          return next;
+        });
+      }
       bumpItemVersion(reviewIdentity.key);
     },
     [bumpItemVersion],
@@ -1685,6 +1700,7 @@ function ReviewSurface({
     diffLineHeight,
     diffStyle: snapshot.preferences.diffStyle,
     disableWorkerPool: true,
+    expandedGenerated,
     focusCommentId,
     focusCommentRequest,
     gitIdentity,

core/__tests__/ReviewCodeView-scroll.test.tsx

@@ -125,6 +125,53 @@ const createLoadedMarkdownFile = (contents: string, fingerprint: string) => {
   };
 };
 
+test('generated files are collapsed by default and can be explicitly expanded per review', async () => {
+  const file = createChangedFile('src/__generated__/api.ts');
+  const reviewKey = 'walkthrough:generated-api';
+  const blocks: ReadonlyArray<ReviewDiffBlock> = [
+    {
+      file,
+      id: reviewKey,
+      reviewIdentity: {
+        fingerprint: file.fingerprint,
+        key: reviewKey,
+      },
+    },
+  ];
+  const view = await renderReact(<ReviewCodeViewHarness blocks={blocks} files={[]} />);
+
+  try {
+    await waitFor(() => {
+      expect(
+        view.container.querySelector('[aria-label="Expand file"]')?.getAttribute('aria-expanded'),
+      ).toBe('false');
+      expect(view.container.querySelector('.codiff-generated-badge')?.textContent).toBe(
+        'Generated',
+      );
+    });
+
+    await view.rerender(
+      <ReviewCodeViewHarness
+        blocks={blocks}
+        expandedGenerated={new Set([reviewKey])}
+        files={[]}
+        itemVersionByKey={{ [reviewKey]: 1 }}
+      />,
+    );
+
+    await waitFor(() => {
+      expect(
+        view.container.querySelector('[aria-label="Collapse file"]')?.getAttribute('aria-expanded'),
+      ).toBe('true');
+      expect(view.container.querySelector('.codiff-generated-badge')?.textContent).toBe(
+        'Generated',
+      );
+    });
+  } finally {
+    await view.cleanup();
+  }
+});
+
 test('switching edited Markdown back to a diff flushes and refreshes it first', async () => {
   const order: Array<string> = [];
   const initialFile = createLoadedMarkdownFile('# Edited\n', 'plan.md:initial');

core/__tests__/SharedWalkthroughApp.test.tsx

@@ -207,7 +207,10 @@ test('shared walkthroughs switch between walkthrough and tree review modes', asy
 
 test('shared walkthroughs initially preview Markdown when other files are generated', async () => {
   const file = createMarkdownFile();
-  const generatedFile = createChangedFile('src/__generated__/api.ts');
+  const generatedFile = {
+    ...createChangedFile('src/api.ts'),
+    generated: true,
+  };
   const source = { type: 'working-tree' } as const;
   const walkthrough = {
     agent: 'codex',