Skip to content

feat: rule-text cache keys, actionable findings, nested configs, and --rule - #90

Merged
nekomeowww merged 6 commits into
alint-dev:mainfrom
arvinxx:fix/dx-rule-cache-config-scope-and-rule-filter
Sep 28, 2026
Merged

nekomeowww merged 6 commits into
alint-dev:mainfrom
arvinxx:fix/dx-rule-cache-config-scope-and-rule-filter

Conversation

@arvinxx

@arvinxx arvinxx commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #91 — four DX problems reported by a team running alint on 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.

Report Fix
Editing a rule did not invalidate its cached findings A declarative rule declares its own cache key: instruction, reviewed file scope, and built-in agent version
A clean target still produced a finding Findings that only assert the target is correct are dropped, and the schema asks for an empty array
Rule scope could only be written in the root config Nested alint.config.* are discovered and scoped to the directory that declares them
No way to debug a single rule alint --rule <id|glob> runs only the rules a filter names

fix(config): declarative rules key their own cache

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 left the cache fingerprint equal, so the next run replayed the previous findings as cache hits without running the rule at all. The only workaround was rm -rf .alintcache.

The preset now sets cacheKey from 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.

cacheKey was already in the rule DSL but undocumented for authors, so the README now covers it.

fix(config): only actionable findings are reported

Some 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, and basic-coding-agent's report tool says the same.

feat(core,cli): --rule

alint --rule docs/review-copy src
alint --rule 'docs/*' src
alint --rule docs/review-copy,docs/naming src
alint --rule docs/review-copy --format json src

A 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 configs

Every alint.config.* below the repository root is loaded together with the root config, and each file is scoped to its directory:

// packages/app/alint.config.ts
export default defineConfig([
  {
    plugins: { app: appPlugin },
    rules: { 'app/layer-boundary': 'error' },
  },
])
  • files, directories, and ignores resolve against the declaring config's 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.
  • Discovery skips hidden directories, node_modules, and build output, and does not read a nested .env.
  • An explicit --config <path> pins one file and disables discovery.
  • All config files share one plugin alias namespace and one plugin lockfile, so alint plugin install installs what nested configs declare. Two files that bind one alias to different specifiers fail the load instead of silently resolving to one of them.
  • Project-scoped rules (onTargetProject) stay in the root config: the project target sits outside a nested item's base path.

Tests

  • Regression tests reproduce each report before the fix: the declarative cache test asserts a second run with a changed instruction calls the model again, and the finding test asserts a "No violations found." finding never reaches the reporter.
  • New suites: 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 in packages/config/src/config/load.test.ts and two CLI cases in cli.test.ts.
  • pnpm test:run — 116 files, 1289 passed, 1 skipped.
  • pnpm typecheck and pnpm exec eslint packages/*/src are clean.
  • pnpm docs:update regenerated the table of contents and packages/cli/README.md.

arvinxx and others added 6 commits September 28, 2026 09:42
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.
@nekomeowww
nekomeowww merged commit 1fcf435 into alint-dev:main Sep 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DX] Stale rule cache, no-issue findings, root-only configs, and no way to isolate one rule

2 participants