Draft: Add read-only stub files feature

[lutzleonhardt]

Add Read-Only Stub Files Feature

📝 Draft PR: This PR is currently in the idea/prototype phase. Feedback is welcome!

⚠ Unit tests are pending: This proof of concept currently lacks unit tests, which will be added upon merge approval. The build may fail due to this.

see also Navigating Large Codebases: Aider's Read-Only Stub Solution for a deeper explanation

Overview

This PR adds support for read-only stub files, which show only the structural outline of source files rather than their full content. This helps reduce context window usage while maintaining awareness of code structure.

Key Changes

• Added new /read-only-stub command to add files as read-only stubs
• Files can be converted between editable, read-only, and read-only stub modes
• Stubs show function/class definitions without implementation details
• Updated token counting and context management to handle stub files
• Added support for stub files in save/load commands
• Improved file listing display to clearly indicate stub status

Implementation Details

• Added abs_read_only_stubs_fnames to track stub files
• Refactored file handling code to support three file states (editable, read-only, stub)
• Added stub file conversion logic in commands
• Updated UI to show "(stub)" indicator for stub files
• Reused existing repo map stub generation code for consistency

Testing

The changes have been tested for:

• Converting between file modes (editable ↔ read-only ↔ stub)
• Directory handling
• Token counting accuracy
• Save/load functionality
• UI display in both pretty and plain modes

Documentation

The new /read-only-stub command is self-documenting via the help system.

Related Issues

This feature helps address context window management for large codebases by providing a way to include structural information about files without their full content.

[CLAassistant]

All committers have signed the CLA.

[tomjuggler]

This will solve all of my problems with AI coding. I'm putting in my vote here for this upgrade - it can't come soon enough imo

[lutzleonhardt]

@tomjuggler I think this is not in the current scope and therefore will not be merged

[bitnom]

@lutzleonhardt I'm all over the place today with these comments man lol. sry, ugh...

I looked for a scope document or roadmap and couldn't find one. I have previously seen the maintainer make arguments for less automation, which this PR is not.

I like the feature. It seem reasonable to me. Managing aider context is often cumbersome and limiting. This PR makes it a little less cumbersome and a lot less limiting.

[Faolain]

This is extremely useful, is there anything here @paul-gauthier which would make this possible to be merged in or is there any reason why it wouldn't be?