feat: add file limit to structure tool

[carlos-alm]

Summary

• Add a global file limit (default 25) to the structure tool so per-file listings are capped across all directories, reducing token usage from 12k+ to a manageable size
• Directory-level summaries always appear; when files are suppressed, a warning recommends --full or narrowing with --directory
• Add full boolean to MCP tool schema and --full CLI flag to bypass the limit

Test plan

• npm test -- tests/integration/structure.test.js — 16 tests pass (3 new)
• npm test — full suite passes (519 tests)
• npm run lint — clean
• node src/cli.js structure — shows max 25 files with warning if exceeded
• node src/cli.js structure --full — shows all files, no warning
• node src/cli.js structure --directory src --depth 1 — narrowed scope

[claude]

Claude finished @carlos-alm's task —— View job

---

Code Review Complete ✅

Todo List

• Read all changed files to understand the implementation
• Phase 1: Root cause analysis - understand the problem
• Phase 2: Check for configuration changes and test integrity
• Phase 3: Review code quality and implementation details
• Phase 4: Provide final assessment and recommendation

Root Cause Analysis

Problem Being Solved: The structure tool was generating excessive token usage (12k+ tokens) when showing all files without limits, making it impractical for AI agents and potentially causing issues with LLM context windows.

Why This Approach: Adding a configurable file limit (default 25) with a --full override flag is a sensible approach. It balances usability with comprehensive information by always showing directory summaries while limiting per-file listings. The warning message provides clear guidance on how to see all files when needed.

Risk Assessment: LOW RISK - This is a pure enhancement that doesn't modify existing behavior for users who explicitly want full output.

Configuration Changes Review

✅ No problematic configuration changes detected

• No linting rules relaxed
• No test coverage thresholds lowered
• No build configuration modifications
• No TypeScript strict mode changes

Test Integrity Assessment

✅ Test quality maintained

• 3 new tests added specifically for the file limit functionality (lines 136-161 in structure.test.js)
• Tests properly verify the core functionality:
  • Truncation triggers with warning when limit exceeded
  • full: true bypasses limit without warning
  • No truncation when files are within limit
• All existing tests continue to pass
• Test assertions are appropriate and thorough

Code Quality Review

Implementation Quality: EXCELLENT

structure.js:334 - Clean parameterization with fileLimit defaulting to 25
structure.js:409-434 - Well-implemented global file limiting logic:

• Correctly calculates total files across all directories
• Properly truncates files per directory while respecting the global limit
• Returns helpful metadata (suppressed, warning) for user feedback

cli.js:505 - Proper CLI integration with --full flag
mcp.js:274-277 - Correct MCP tool schema update with full parameter and clear description

Positive Aspects:

1. Backward compatible: Default behavior changes, but --full preserves original functionality
2. Clear user feedback: Warning message is informative and actionable
3. Consistent API: Both CLI and MCP interfaces support the new functionality
4. Appropriate defaults: 25 files is a reasonable balance for most use cases
5. Clean separation: File limiting logic is well-contained and doesn't affect other functionality

Minor Observations:

1. Performance: File limit is applied after database queries, but this is fine for the expected scale
2. Algorithm: Files are distributed fairly across directories rather than preferencing high-value directories (acceptable design choice)

Security & Performance

✅ No security concerns
✅ Performance impact minimal - logic runs after DB queries complete
✅ No injection risks - no user input processed unsafely

Final Assessment

## Root Cause Analysis
**Problem Being Solved**: Structure tool token usage exceeded 12k+ tokens, creating UX issues for AI agents
**Why This Approach**: File limit with override provides balanced solution - always show directory structure, limit per-file details by default
**Risk Assessment**: LOW RISK - Pure enhancement, backward compatible with --full flag

## Critical Concerns
None identified. This is a well-implemented feature enhancement.

## Final Recommendation
- Rating: ⭐⭐⭐⭐☆ (4/5)
- Action: **APPROVE**
- Reasoning: Solid implementation addressing a real usability issue. Clean code, appropriate tests, good UX with actionable warning messages. Only missing the 5th star due to the simple nature of the feature rather than exceptional complexity/innovation.

---

[greptile-apps]

Greptile Summary

Adds a configurable file limit to the structure tool (default 25 files) to reduce token usage from 12k+ to manageable levels. Directory summaries always display; when the limit is exceeded, per-file listings are truncated and a warning message directs users to --full or --directory filtering.

Key changes:

• structureData now accepts full (boolean) and fileLimit (number, default 25) options
• File truncation logic iterates directories in sort order, showing files until the limit is reached
• When truncated, returns suppressed count and warning message in the response object
• CLI adds --full flag to bypass the limit
• MCP tool schema adds full: boolean property (default false)
• Comprehensive test coverage for truncation, full mode, and under-limit scenarios
• Unrelated: hardens CI benchmark workflow with npm caching and npm ci --prefer-offline --no-audit --no-fund to prevent transient installation failures

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Clean implementation with comprehensive test coverage (3 new tests, all passing), clear documentation updates, and backward-compatible defaults. The truncation logic is straightforward and well-tested. The unrelated CI hardening changes follow GitHub Actions best practices.
• No files require special attention

Important Files Changed

Filename	Overview
.github/workflows/benchmark.yml	Hardens CI dependency installation with npm caching and npm ci flags to prevent transient failures
src/structure.js	Implements global file limit (default 25) with truncation logic and warning message for token reduction
src/cli.js	Adds --full flag to structure command and passes it to structureData
src/mcp.js	Adds full boolean to MCP tool schema with default false and passes it to structureData handler
tests/integration/structure.test.js	Adds 3 tests covering file limit truncation, full mode bypass, and no-truncation scenarios

_{Last reviewed commit: 2c565fa}

[greptile-apps]

_{5 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}