Repository navigation
feat: rule-text cache keys, actionable findings, nested configs, and --rule - #90
Merged
nekomeowww merged 6 commits intoSep 28, 2026
Conversation
Two ways a declarative rule reported results the current rule would not
produce.
A declarative rule is built by a shared factory, so the rule source the run
engine hashes is identical for every declarative rule: nothing in it says
which instruction the preset sends to the model. Editing `instruction` in
`rule.alint.toml` therefore left the cache fingerprint equal and the next run
replayed the previous findings as cache hits, without running the rule at
all. The rule now declares its own cache key — instruction, reviewed file
scope, and a version of the built-in agent — so a changed rule text
invalidates what it cached. The versions are bumped when a preset's prompts
or reporting change.
A clean target also made some models answer with a finding that asserts
compliance ("No violations found."), at high confidence, which the reporter
rendered as a diagnostic whose remediation is to change nothing. Findings
that only state the target is correct are now dropped before reporting, on
the message alone so a real violation survives a suggestion that says
otherwise, and the schema descriptions ask for an empty array instead.
Compliance phrased with a negation ("is not compliant with the rule") still
reports, and the schema and preset instructions say so explicitly.
Calibrating a rule meant reading every other rule's findings out of a JSON
run, or writing a throwaway script around the output to isolate one rule and
count its hits across runs. `--rule` narrows the run instead:
alint --rule docs/review-copy src
alint --rule 'docs/*' src
A pattern matches the configured rule id or the rule's own name, the flag is
repeatable and accepts a comma-separated list, and filtered rules are left
unplanned, so they never call a model. A filter that matches nothing fails
the run and lists the rule ids it did enable, because an empty run is
otherwise indistinguishable from a clean one.
Filtering keeps each surviving rule's enabled-registry position, so job order
and progress refs stay stable.
A rule that belongs to one package had to be registered as a directory plugin in the root config, and its scope repeated in the fixture runner root, the CI cache-key glob, the CI pathspec, and the tsconfig excludes. Missing one of those fail-silently steps dropped the rule from one tool while the others kept running it. Every `alint.config.*` below the repository root is now loaded with the root config, and each file is scoped to the directory that contains it: `files`, `directories`, and `ignores` resolve against that directory, and an item that declares no target patterns covers its whole subtree instead of reaching the repository. Discovery is depth-first, parents before children, so a deeper config overrides an outer one for its own directory the same way a later flat config item does. Discovery skips hidden directories, `node_modules`, and build output, and it does not read a nested `.env`. An explicit `--config` pins one file and disables discovery. Nested configs share the root plugin lockfile, so `alint plugin install` installs what they declare; two files binding one alias to different specifiers now fail the load instead of resolving to one of them. Project-scoped rules stay in the root config: the project target sits outside a nested item's base path. MSG2
The README gains a nested-config section, a --rule section, and the cacheKey paragraph rule authors need: a rule whose findings depend on an imported prompt or a preset's text declares those inputs, or its cached findings survive edits to that text.
The repository guide asks a regression test for a GitHub report to name the issue and link the report above the case.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #91 — four DX problems reported by a team running
alinton a large TypeScript monorepo, in the order they cost them time. The regression tests for each one name the issue and link it above the case.alint.config.*are discovered and scoped to the directory that declares themalint --rule <id|glob>runs only the rules a filter namesfix(config): declarative rules key their own cacheA declarative rule is built by a shared factory, so the rule source the run engine hashes is identical for every declarative rule — nothing in it says which instruction the preset sends to the model. Editing
instructioninrule.alint.tomlleft the cache fingerprint equal, so the next run replayed the previous findings as cache hits without running the rule at all. The only workaround wasrm -rf .alintcache.The preset now sets
cacheKeyfrom the rule definition (instruction,includeFiles,excludeFiles,builtInAgent, plus a per-agent version constant bumped when a preset's prompts or reporting change). Changing the rule text invalidates only that rule's entries; an unchanged rule still hits the cache.cacheKeywas already in the rule DSL but undocumented for authors, so the README now covers it.fix(config): only actionable findings are reportedSome models answer a compliant target with a finding that says so —
"No violations found."— at high confidence, so it renders as a diagnostic whose remediation is "change nothing". Findings whose message only asserts compliance are dropped before reporting. The judgement is made on the message alone, so a real violation survives a suggestion that says nothing else is needed, and negated compliance (The module is not compliant with the rule.) still reports. The schema descriptions now ask for an empty array instead, andbasic-coding-agent's report tool says the same.feat(core,cli):--rulealint --rule docs/review-copy src alint --rule 'docs/*' src alint --rule docs/review-copy,docs/naming src alint --rule docs/review-copy --format json srcA pattern matches the configured rule id (
plugin/rule) or the rule's own name. The flag is repeatable and accepts a comma-separated list. Filtered rules are left unplanned, so they never call a model. A filter that matches no enabled rule fails the run and lists the rule ids it did enable, because an empty filtered run reads exactly like a clean one.Surviving rules keep their enabled-registry position, so job order and progress refs stay stable.
feat(config): nested configsEvery
alint.config.*below the repository root is loaded together with the root config, and each file is scoped to its directory:files,directories, andignoresresolve against the declaring config's directory, and an item that declares no target patterns covers its whole subtree instead of reaching the repository.node_modules, and build output, and does not read a nested.env.--config <path>pins one file and disables discovery.alint plugin installinstalls what nested configs declare. Two files that bind one alias to different specifiers fail the load instead of silently resolving to one of them.onTargetProject) stay in the root config: the project target sits outside a nested item's base path.Tests
"No violations found."finding never reaches the reporter.packages/config/src/plugins/declarative/cache-key.test.ts,findings.test.ts,packages/core/src/core/rule-filter.test.ts,packages/cli/src/cli/commands/lint/rule-filter.test.ts, plus six nested-config cases inpackages/config/src/config/load.test.tsand two CLI cases incli.test.ts.pnpm test:run— 116 files, 1289 passed, 1 skipped.pnpm typecheckandpnpm exec eslint packages/*/srcare clean.pnpm docs:updateregenerated the table of contents andpackages/cli/README.md.