feat: Ability to whitelist only specific model patterns (#289)

[mbkloster]

Implements #289

Adds a new parameter which, if given, restricts models annotated to match a given set of patterns.

I added both an integration spec and a (much simpler) unit test to this, but let me know if there are patterns or approaches you'd like to see tested separately. I was able to verify that this works on the sample project in this repo.

[drwl]

Sorry for the delay on this. I have looked at the PR a few times and it does make sense. I just need to take some time on how to best handle this, since it seems like there's demand for being able to filter models/files to annotate (allow list) as well as filter to ignore (deny list).

@OdenTakashi do you have any thoughts on how we might want to handle this?

[OdenTakashi]

Thanks for opening this, @mbkloster!

it seems like there's demand for being able to filter models/files to annotate (allow list) as well as filter to ignore (deny list).

@drwl I agree — and given that PR #267 is already exploring the deny side, I've been thinking about how we might approach this:

• Option naming / approach: These two PRs feel complementary. PR Make it possible to filter files by Regexp #267 currently uses regex, but it might make sense to align on globs for both — it'd be consistent with existing flags like --additional-file-patterns, should cover both use-cases well, and could be easier to maintain. For naming, something like --include-file-patterns / --exclude-file-patterns (or --allow-file-patterns / --deny-file-patterns) might make the relationship immediately clear.
• Precedence: When both options are specified, it might be worth thinking through how they interact — one option could be: apply the allow/include side first (narrow the set), then the deny/exclude side (remove from that set), though curious if others have a different take.

Would love to hear your thoughts, @drwl

[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.

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