Feature: File-Level Analysis Filtering for CI Optimization

[chief-nerd]

Problem Statement

When running custom_lint in CI/CD pipelines on pull requests, the tool currently analyzes entire packages even when only a few files have changed. This results in unnecessary analysis time and resource usage.

Example scenario:

• A PR changes 28 files across 2 packages
• Each package contains 125+ files
• custom_lint analyzes all 250+ files instead of just the 28 changed files
• Analysis takes ~2 minutes when it could potentially take 20-30 seconds

Proposed Solution

Add CLI support for analyzing specific files, similar to how dart analyze works:

# Analyze specific files only
dart run custom_lint lib/file1.dart lib/file2.dart test/file3.dart

# Or via stdin for large file lists
echo "lib/file1.dart\nlib/file2.dart" | dart run custom_lint --stdin-files

Use Case

This feature is particularly valuable for:

1. CI/CD PR checks - Only lint changed files in pull requests
2. Pre-commit hooks - Only lint staged files
3. IDE integrations - Faster feedback on file save
4. Incremental analysis - Large monorepos with frequent small changes

Current Workaround Limitations

The existing LintRule.filesToAnalyze property filters which files to analyze within a package, but:

• ❌ Cannot limit analysis to specific file paths
• ❌ Only supports glob patterns for file matching
• ❌ Still requires analyzing the entire package structure
• ❌ No way to pass explicit file list via CLI

Using dart analyze as a fallback:

• ❌ Doesn't run custom lint rules
• ❌ Loses the value of custom_lint entirely

Proposed API

CLI Option

dart run custom_lint --files lib/a.dart,lib/b.dart,test/c.dart

stdin Support (for large file lists)

dart run custom_lint --stdin-files < changed_files.txt

Environment Variable (current melos pattern)

CUSTOM_LINT_FILES="lib/a.dart,lib/b.dart" dart run custom_lint

Implementation Notes

This would likely require:

1. Extending the CLI argument parser to accept file paths
2. Modifying CustomLintWorkspace.fromPaths() to support explicit file filtering
3. Ensuring analysis context still loads necessary package dependencies
4. Maintaining compatibility with existing glob-based filtering

Benefits

• ⚡ Faster CI/CD - 60-90% reduction in analysis time for small PRs
• 💰 Cost savings - Reduced compute time in cloud CI runners
• ✅ Better DX - Faster feedback loops for developers
• 🎯 Targeted analysis - Only analyze what changed

Related Issues

• This would complement the existing --watch mode for hot-reload
• Similar to how dart analyze and ESLint support file-specific analysis
• Aligns with incremental analysis patterns in other linters

Environment

• Tested on custom_lint version: 0.8.0
• Flutter monorepo with Melos
• Current workaround: Package-based filtering (sub-optimal) -- better than nothing

[mj-hd]

you can pass the file list to filesToAnalyze via Platform.environment as a workaround, I found this hack while working on #363.

[chief-nerd]

@mj-hd Thanks for the suggestion!
I dug through the upstream invertase/dart_custom_lint repo — especially client.dart and the code paths where filesToAnalyze is determined. Turns out the runner only respects the glob patterns returned by each plugin and the analyzer context roots; there’s no hook that reads a file list from the environment (or the CLI) that we could tap into from CI. So even if we prepared a list of changed files on our side, the client would still ignore it.

Long story short: I couldn’t find any env-variable override or similar entry point in custom_lint ...

[mj-hd]

@chief-nerd Sorry, my workaround only works when you're using a custom rule that you created. If you can modify the rule, you can override filesToAnalyze to read Platform.environment (because the CLI client and the plugin server share the same environment variables).