Feature: Support generating subdirectory ruff.toml files with path-adjusted per-file-ignores

[Kilo59]

Title

Support generating subdirectory ruff.toml files with path-adjusted per-file-ignores

Problem

Ruff supports hierarchical configuration via extend, which is useful for having different linter thresholds in subdirectories (e.g., relaxed max-args in tests/). However, per-file-ignores patterns inherited via extend break because ruff resolves glob patterns relative to the config file's directory, not the original source.

Example

project/
├── pyproject.toml          # root config
│   [tool.ruff.lint.per-file-ignores]
│   "tests/**/*.py" = ["S101", "TC001", "TC002"]
│
└── tests/
    └── ruff.toml           # extends root, overrides max-args
        extend = "../pyproject.toml"
        [lint.pylint]
        max-args = 10

When ruff processes tests/ruff.toml, the inherited "tests/**/*.py" pattern resolves to tests/tests/**/*.py — matching nothing. The TC001/TC002 ignores silently stop applying, which changes isort's import classification and cascades into I001 sorting violations across every existing test file.

• This is a known ruff limitation: per-file-ignores have inconsistent behavior in symlinked directories astral-sh/ruff#6480.

Why extend-per-file-ignores doesn't fully solve it

Ruff shipped extend-per-file-ignores astral-sh/ruff#2558 which allows additive ignores. You can move the test ignores into tests/ruff.toml with "**/*.py" patterns. However, the TC001/TC002 ignores affect isort's import classification — adding them from a different config file changes the expected sort order for all existing test files, requiring a mass reformat of unrelated files.

The net result: there's no way to use a subdirectory ruff.toml for threshold overrides without either breaking per-file-ignores inheritance or causing import sorting churn across the entire test suite.

How ruff-sync could help

ruff-sync already handles merging upstream configs into local projects with path awareness. A natural extension would be generating subdirectory config files (like tests/ruff.toml) from a root config, with glob patterns automatically adjusted for the target directory.

Potential approaches

Option A: Path-rewriting on sync

When syncing a root config into a subdirectory ruff.toml, rewrite per-file-ignores patterns to be relative to the target directory. For example, "tests/**/*.py" in the root becomes "**/*.py" in tests/ruff.toml.

This could be a new command or flag:

# Generate tests/ruff.toml from root config with path-adjusted patterns
ruff-sync subdirectory tests/ --overrides tests/ruff-overrides.toml

Option B: Subdirectory config generation

A dedicated feature for generating subdirectory configs that:

1. Takes the root config as the base
2. Applies user-specified overrides (threshold changes, additional ignores)
3. Rewrites all glob patterns to be relative to the target directory
4. Outputs a self-contained ruff.toml that doesn't need extend

This avoids the extend path resolution bug entirely by producing a standalone config.

Option C: Exclude + extend-per-file-ignores coordination

When syncing, detect per-file-ignores patterns that reference the target subdirectory and automatically:

1. Exclude them from the parent sync (so they don't break via extend)
2. Add them to the child's extend-per-file-ignores with adjusted paths

Context

This came up while trying to set different pylint.max-args and mccabe.max-complexity thresholds for test files without disabling the rules entirely via per-file-ignores. The tests/ruff.toml approach is the documented way to do this, but it's broken in practice for any project that uses TC001/TC002 ignores on test files.

Related issues

• per-file-ignores have inconsistent behavior in symlinked directories astral-sh/ruff#6480 — per-file-ignores path resolution breaks with extend across directories (open)
• Ability to extend per-file-ignored astral-sh/ruff#2558 — extend-per-file-ignores feature request (closed, shipped)

[Kilo59]

I've been researching this issue and want to clarify exactly how Ruff's path resolution is behaving here, as the problem is actually slightly different than initially described.

I ran several tests against Ruff 0.15.11 to reproduce the behavior of extend and per-file-ignores.

It turns out that Ruff's extend behavior is actually working correctly when resolving paths. When tests/ruff.toml uses extend = "../pyproject.toml", Ruff evaluates the per-file-ignores defined in the base config (pyproject.toml) relative to the base config's directory.

This means that "tests/**/*.py" inherited via extend accurately resolves to <project_root>/tests/**/*.py and correctly matches test files!

So why does TC001/TC002 break isort classification when attempting to override settings in subdirectories?

The issue arises if you attempt to create a standalone or partially overridden tests/ruff.toml by migrating per-file-ignores into it. If you copy the per-file-ignores glob patterns directly into tests/ruff.toml (or use extend-per-file-ignores inside it), those patterns are now evaluated relative to tests/.

As a result, a pattern like "tests/**/*.py" explicitly defined inside tests/ruff.toml resolves to <project_root>/tests/tests/**/*.py, which matches nothing. This causes the TC001/TC002 ignores to stop applying, triggering cascading I001 sorting violations if you run ruff check --fix.

The Broader Vision for Standalone Configs

Despite the fact that native extend isn't fundamentally broken, the proposed feature is highly viable and solves several systemic challenges with Ruff's hierarchical configuration system.

Generating standalone subdirectory configs (Option B) solves major structural and DX issues beyond just TC001/TC002:

1. IDE Workspace Isolation: When a developer opens a subdirectory (e.g., project/tests/) as their workspace root in an editor, Ruff extensions often fail to resolve extend = "../pyproject.toml". A generated, self-contained ruff.toml guarantees the IDE will always apply the correct linting rules.
2. Overcoming Ruff's Inability to "Un-ignore" Rules: Ruff's extend behavior is purely additive for per-file-ignores. You cannot subtract an ignore inherited from a parent config. By generating a standalone config, ruff-sync can theoretically filter out conflicting ignores entirely, giving subdirectories true autonomy.
3. Monorepo & Microservice Isolation: In monorepos containing completely different environments (e.g., a Django backend vs ML pipelines), relying on nested extend chains causes plugin configurations to "leak" down the tree. Generating standalone configs allows teams to enforce baseline standards while keeping the actual configuration boundaries completely isolated and hermetic.
4. Explicit Discoverability: When a developer jumps into a subdirectory, a ruff.toml with just extend = "../pyproject.toml" obscures the linting reality. A generated standalone config acts as a single, explicit source of truth.

In short, replacing nested extend chains with explicitly generated standalone configs moves ruff-sync from just being a "sync tool" to being a true configuration compiler, generating isolated, robust config objects for any directory boundary.

Implementing Option B is a fantastic solution. If ruff-sync can generate a self-contained tests/ruff.toml that doesn't rely on extend inheritance, it must perform path-rewriting on the glob patterns (e.g., stripping the tests/ prefix) to maintain their semantic meaning. I'm excited to proceed with this direction!