feat(output): Add --show-file-offsets option to annotate directory tree with line ranges

[nuthalapativarun]

Summary

Adds a --show-file-offsets CLI flag and output.showFileOffsets config option that annotates each file entry in the directory structure section with its line range in the output file:

<directory_structure>
src/
  components/
    DictCard.tsx [lines 142–219]
    DictManager.tsx [lines 221–283]
    Editor.tsx [lines 285–352]
  index.ts [lines 42–89]
</directory_structure>

This allows AI agents and users to jump directly to a specific file's content in the packed output without scanning the entire file, which is especially valuable for large repositories.

Closes #1367

Changes

• Add output.showFileOffsets: boolean config option (default: false) to config schema
• Add --show-file-offsets CLI flag
• Add src/core/output/fileOffsets.ts — scans rendered output for file block positions (supports XML, Markdown, and plain styles)
• Add generateTreeStringWithFileOffsets / generateTreeStringWithRootsAndFileOffsets to fileTreeGenerate.ts
• Implement two-pass rendering in generateOutput(): first pass discovers file line positions, second pass renders with annotations
• Add 10 unit tests covering offset computation for each style and tree annotation

Implementation Notes

Two-pass rendering: The directory tree is built before the output content is rendered, so file line positions are not available at tree-build time. The solution:

1. Render the output once (without annotations)
2. Scan the rendered string for file block start/end markers
3. Annotate the tree (same line count, only line content changes)
4. Re-render with the annotated tree

Because the tree section has the same number of lines in both passes (annotations extend line content but add no new lines), all file block positions remain stable between passes.

JSON output: Not annotated since JSON is structured and does not use a directory tree section.

Test Plan

• npm run lint passes
• npm run test passes (1125 tests)
• Unit tests for computeFileLineOffsets for XML, Markdown, plain, and JSON styles
• Unit tests for generateTreeStringWithFileOffsets with and without multi-root

---

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bb38796f-cc71-4d48-b85d-70165cce8cca

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added a new --show-file-offsets CLI flag that enables annotating each file in the directory structure output with line ranges indicating its position in the rendered repomix output file. The feature propagates through CLI options, configuration schema, and implements two-pass output rendering to compute file offsets before final tree generation.

Changes

Cohort / File(s)	Summary
CLI Option Definition src/cli/cliRun.ts, src/cli/types.ts, src/cli/actions/defaultAction.ts	Added --show-file-offsets CLI flag, extended CliOptions interface with showFileOffsets property, and propagated flag into cliConfig.output via conditional merge.
Configuration Schema src/config/configSchema.ts	Extended repomixConfigBaseSchema and repomixConfigDefaultSchema with optional output.showFileOffsets boolean field (defaults to false).
File Offset Utilities src/core/output/fileOffsets.ts	New module providing FileLineOffset interface, computeFileLineOffsets() to extract per-file line ranges from rendered output (supports xml, markdown, plain formats), and formatFileOffsetAnnotation() to format line-range strings.
File Tree Generation src/core/file/fileTreeGenerate.ts	Added treeToStringWithFileOffsets(), generateTreeStringWithFileOffsets(), and generateTreeStringWithRootsAndFileOffsets() to render directory trees with file-offset annotations appended to file entries.
Output Generation src/core/output/outputGenerate.ts	Refactored style selection into renderOutput() helper; added two-pass rendering logic when showFileOffsets is enabled—first pass computes offsets, second pass regenerates tree with annotations and re-renders output.
Test Configuration Updates tests/config/configSchema.test.ts, tests/core/metrics/calculateGitDiffMetrics.test.ts, tests/core/metrics/calculateGitLogMetrics.test.ts, tests/core/output/flagFullDirectoryStructure.test.ts, tests/core/output/outputStyles/jsonStyle.test.ts	Added showFileOffsets: false to mock configuration objects across multiple test suites.
New Test Suite tests/core/output/showFileOffsets.test.ts	Comprehensive test coverage for offset computation across output formats (xml, markdown, plain), tree string generation with annotations, and multi-root tree rendering behavior.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as CLI Engine
    participant Config as Config/Output
    participant Gen as Output Generator
    participant Tree as Tree Generator
    participant Offsets as Offset Computer

    User->>CLI: Run with --show-file-offsets
    CLI->>Config: Build config with showFileOffsets=true
    Config-->>Gen: Pass config
    
    Gen->>Gen: First Pass: Render output<br/>(tree without offsets)
    Gen->>Offsets: computeFileLineOffsets(output)
    Offsets-->>Gen: Record{filePath→{start,end}}
    
    Gen->>Tree: generateTreeString...<br/>WithFileOffsets(offsets)
    Tree->>Tree: Format each file entry<br/>with [lines X–Y]
    Tree-->>Gen: Annotated tree string
    
    Gen->>Gen: Second Pass:<br/>Re-render full output<br/>with annotated tree
    Gen-->>User: Output with file offsets<br/>in directory structure

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(tree): add multi-root directory labels #1024: The main PR's file-offset computation and tree-generation functions extend and call into multi-root tree-generation APIs that the retrieved PR introduces, with direct code-level dependencies.
• Add metadata-only output mode with --no-files flag #491: Both PRs modify the same CLI/config/output plumbing (cliRun.ts, CliOptions, configSchema, outputGenerate.ts) to propagate a new CLI flag and alter output-generation behavior through the same pipeline.
• feat(cli): Add CLI flags for controlling output sections and content processing #236: Both PRs update src/cli/actions/defaultAction.ts to add conditional propagation of new CLI output flags into cliConfig.output via object spread merge.

Suggested reviewers

• yamadashy

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main feature: adding a --show-file-offsets option to annotate the directory tree with line ranges.
Description check	✅ Passed	The description comprehensively covers the feature with a clear summary, implementation details, test plan, and the basic template checklist is acknowledged through test execution claims.
Linked Issues check	✅ Passed	All coding requirements from issue #1367 are met: the feature adds line offset annotations to directory tree entries, supports multiple output styles (XML, Markdown, plain), and correctly calculates line ranges for each file in the rendered output.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the feature objectives: CLI flag, config schema, offset computation, tree annotation, two-pass rendering, and comprehensive test coverage are all in scope for implementing the requested feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.

[devin-ai-integration]

🟡 Plain-text test uses 80-char separator instead of 64-char, defeating section-isolation testing

The plain-text offset test constructs its mock output with 80-character long separators ('='.repeat(80)) at lines 76, 78, 82, and 84, but the production code uses 64-character separators (PLAIN_LONG_SEPARATOR = '='.repeat(64) at src/core/output/outputStyles/plainStyle.ts:1 and LONG_SEPARATOR = '='.repeat(64) at src/core/output/fileOffsets.ts:46,123). Because findFilesSectionStartLine compares prevLine === LONG_SEPARATOR (64 chars) against the test's 80-char string, the match fails and the function falls back to returning 1 (scan entire output). Similarly, the end-of-section detection (line === LONG_SEPARATOR) also never triggers, falling back to the last line. The test still passes because the file markers are found regardless, but it completely fails to validate the section-isolation logic that prevents false matches from file content containing marker strings.

Suggested change

	'================================================================================',
	'Directory Structure',
	'================================================================================',
	'src/',
	' foo.ts',
	'',
	'================================================================================',
	'Files',
	'================================================================================',
	'================================================================',
	'Directory Structure',
	'================================================================',
	'src/',
	' foo.ts',
	'',
	'================================================================',
	'Files',
	'================================================================',

---

Was this helpful? React with 👍 or 👎 to provide feedback.