Proposal for handling additional file inclusions/exclusions

[drwl]

I have been thinking through this and the other issues. In the end, it would be great to move away from option flags towards an explicit structure for controlling what does and does not get annotated. Do let me know what you think. Note: I used AI to create the proposals. (Moved this from #300)

How I think the ideal pipeline could be:

The Pipeline

1. Model discovery    →  scan model_dir globs, find candidate .rb files
2. Model filter       →  whitelist OR exclusion (mutually exclusive) — PRs #267 and #300
                         ↓  surviving models
3. Related file       →  per model, expand to related files via patterns
   expansion             (additional_file_patterns, test/fixture/factory patterns, etc.)
                         ↓  combined set: models + related files
4. Related file       →  additional exclusions for step 3, for example if you want to exclude annotating tests for a specific model
   filtering
                         ↓  final set to annotate

These are two options for handling exclusion

Option A — Unified Exclusion

A single exclude_patterns option operates on the combined set (models + related files) after expansion. (This would happen at step 4)

# .annotaterb.yml

exclude_patterns:
  - "**/*.spec.rb"       # prevents spec files from being treated as models
  - "spec/billing/**/*"  # prevents billing-related specs from being annotated

How it works:

1. Model discovery finds all candidate files
2. Model-level whitelist or exclusion is applied (PRs Make it possible to filter files by Regexp #267/feat: Ability to whitelist only specific model patterns (#289) #300)
3. Related files are expanded per model
4. exclude_patterns is applied to the combined set — any file matching a pattern is dropped

Pros:

• Single concept and single config key — easy to explain and document
• Consistent: the same mechanism handles both model-level and related-file-level exclusion
• Familiar — similar to .gitignore semantics

Cons:

• Loses the distinction between "don't treat this as a model" and "don't annotate this related file" — both collapse into "don't touch this file"
• A pattern intended to exclude related files could unintentionally also exclude model files if written broadly
• Less explicit about which layer is being targeted

---

Option B — Separate Exclusion Options

Two distinct options target different layers of the pipeline explicitly.

# .annotaterb.yml

# Affects model discovery only — prevents files from being loaded as models
exclude_model_patterns:
  - "**/*.spec.rb"

# Affects related file annotation only — models are still processed, but
# matching related files are skipped
exclude_related_file_patterns:
  - "spec/billing/**/*"

How it works:

1. Model discovery finds all candidate files
2. exclude_model_patterns is applied — matching files are dropped before any model loading
3. Related files are expanded per surviving model
4. exclude_related_file_patterns is applied to the related file set only

Pros:

• Explicit — the user knows exactly which layer they are targeting
• exclude_model_patterns cleanly handles PR Make it possible to filter files by Regexp #267 (.spec.rb files in model directories)
• exclude_related_file_patterns cleanly complements the existing exclude_* boolean flags with pattern-based control
• No risk of a related-file pattern accidentally excluding a model file

Cons:

• Two options to learn and document instead of one
• User must understand the distinction between model discovery and related file annotation to use correctly
• Slightly more config verbosity