Skip to content

refactor: restructure README/docs and split registry module#187

Merged
zeitlinger merged 9 commits intomainfrom
docs/split-and-v2-install
Apr 21, 2026
Merged

refactor: restructure README/docs and split registry module#187
zeitlinger merged 9 commits intomainfrom
docs/split-and-v2-install

Conversation

@zeitlinger
Copy link
Copy Markdown
Member

Summary

  • README dropped from 642 → 199 lines; per-linter details, CLI reference, and Why/Principles moved to docs/linters.md, docs/cli.md, docs/why.md.
  • Summary table name column now links to the matching detail section.
  • Install snippets use "github:grafana/flint" = "0.20.2" now that v2 is released; new Renovate custom manager keeps the README version fresh.
  • readme_linter_table_in_sync test generates summary into README and detail sections into docs/linters.md; UPDATE_README=1 cargo test readme_linter_table_in_sync still regenerates both.

Test plan

  • cargo test --bin flint readme_linter_table_in_sync green
  • mise run lint green
  • Rendered README on GitHub: summary table links resolve to docs/linters.md#<name>
  • Rendered docs/linters.md: Scope [file](#scopes) anchors still resolve to the Scopes section on the same page

README dropped from 642 to 199 lines. Per-linter details, CLI reference,
and Why/Principles moved to docs/linters.md, docs/cli.md, docs/why.md.
Summary table name column now links to the detail section.

Install snippets use `"github:grafana/flint" = "0.20.2"` now that v2 is
released; a new Renovate custom manager keeps the README version fresh.

Registry test generates into both files; `UPDATE_README=1 cargo test
readme_linter_table_in_sync` still regenerates.
Signed-off-by: Gregor Zeitlinger <[email protected]>
Use descriptive link text instead of bare file paths. renovate-deps
is no longer slow in the registry — update CLI flag description,
flint linters sample output, why.md principle bullet, and linters.md
scope note accordingly.
Signed-off-by: Gregor Zeitlinger <[email protected]>
src/registry.rs grew to 1173 lines. Split into a module directory
with focused files: types (struct + builder), checks (per-linter
constructors), obsolete (legacy key migration), mise (tool discovery
and activation), resolve (binary lookup), tests (unchanged). Public
API preserved via re-exports in mod.rs.
Signed-off-by: Gregor Zeitlinger <[email protected]>
@zeitlinger zeitlinger changed the title docs: slim README, split into docs/, use v0.20.2 install refactor: restructure README/docs and split registry module Apr 17, 2026
@zeitlinger zeitlinger marked this pull request as ready for review April 17, 2026 10:01
@zeitlinger zeitlinger requested a review from a team as a code owner April 17, 2026 10:01
Copilot AI review requested due to automatic review settings April 17, 2026 10:01
Bare `shfmt` resolves via aqua registry, which is broken in current
mise releases. `github:mvdan/sh` works and matches the key flint's
registry expects.
Signed-off-by: Gregor Zeitlinger <[email protected]>
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Refactors documentation structure and splits the linter registry implementation into smaller Rust modules to improve maintainability and keep generated docs in sync with the registry.

Changes:

  • Split the former monolithic src/registry.rs into src/registry/* modules (types, checks, mise parsing, obsolete keys, binary resolving) and updated tests accordingly.
  • Restructured docs by moving CLI/linters/principles content out of README.md into docs/*.md, with README linking to the new pages.
  • Added a Renovate custom manager to keep the README’s pinned flint version updated, and tracked it in the Renovate snapshot.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
src/registry/types.rs New registry types + builder-style API for defining checks.
src/registry/checks.rs New module containing built-in registry entries.
src/registry/mise.rs Reads mise.toml tools and determines check activation/version matching.
src/registry/resolve.rs Resolves executable names (incl. version-suffixed binaries) and PATH checks.
src/registry/obsolete.rs Centralizes obsolete mise tool key migrations.
src/registry/mod.rs Wires registry submodules and re-exports the public API.
src/registry/tests.rs Updates/extends registry tests and README/docs sync generation.
src/registry.rs (deleted) Removes the old monolithic registry implementation.
README.md Shrinks README; links out to docs/ and updates install snippets/table links.
docs/cli.md New CLI reference extracted from README.
docs/linters.md New per-linter detail page generated from the registry.
docs/why.md New background/principles doc extracted from README.
.github/renovate.json5 Adds Renovate regex manager for the README flint version pin.
.github/renovate-tracked-deps.json Tracks README flint version pin for renovate-deps.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread src/registry/checks.rs
Comment thread src/registry/types.rs Outdated
Comment thread docs/linters.md Outdated
Comment thread README.md
Comment thread README.md
Stacked on #187.

Two small migrations derived from the flint-v2 design todos:

### 1. `shfmt` → `github:mvdan/sh`

Bare `shfmt` resolves via aqua registry, which is broken in current
mise releases. `github:mvdan/sh` works (paired with the existing
`versioned_bin("shfmt_{version}")` wiring). Adds the mapping to
`OBSOLETE_KEYS` so `flint update` rewrites existing mise.toml files
non-interactively. Remove once
[jdx/mise#9191](jdx/mise#9191) ships
(v2026.4.17+) and #175 lands the bare `shfmt` restoration via
`aqua:mvdan/sh`.

### 2. Auto-add `node` prereq for `npm:` backend tools

npm-backed tools (prettier, biome, markdownlint-cli2, renovate) need
the `npm` command, which needs a Node.js runtime. Without an explicit
`node` entry, mise falls back to system node — may be absent, wrong
version, or drift across machines, breaking the "reproducible lint
environment" promise.

`flint init` and `flint update` now detect this and pin `node@lts`
via `mise use --pin` (resolves to a concrete version at write time).

## Test plan
- [ ] Unit tests pass (`cargo test --bin flint`)
- [ ] E2E tests pass (`cargo test --test e2e`)
- [ ] Run `flint update` on a repo with `npm:prettier` but no `node` →
adds node
- [ ] Run `flint update` on a repo with bare `shfmt` → rewritten to
`github:mvdan/sh`

---------

Signed-off-by: Gregor Zeitlinger <[email protected]>
zeitlinger added a commit that referenced this pull request Apr 18, 2026
Stacked on #187.

### Rust workflow steps

`flint init` now adds `Swatinem/rust-cache` and `rustup component add clippy
rustfmt` to `.github/workflows/lint.yml` when a Rust toolchain is detected in
`mise.toml`. The push trigger gets a comment explaining why we run on main
("warms the Rust cache so PR branches get a cache hit").

Also bumps the generated `mise-action` pin to v2026.4.16 to match flint's
own dogfood workflow.

### Markdownlint .yml migration

Switches the generated markdownlint config from `.markdownlint.jsonc` to
`.markdownlint.yml` for uniformity across consumer repos. Legacy variants
(`.markdownlint.{json,jsonc,yaml}` and `.markdownlint-cli2.*`) are replaced
on init. Only generated when editorconfig-checker is also selected, since
the file's comment points to editorconfig-checker for line-length.

### [tools] normalization

New `normalize_tools_section` sorts `mise.toml [tools]` alphabetically and
inserts a `# Linters` header. Toolchain keys (rust/go/dotnet/node) stay
above the header; lint-only binaries go below.

Toolchain detection is registry-driven: a new `Check::toolchain()` /
`Check::toolchain_components()` builder marks a mise_tool as a language
runtime. `toolchain_keys()` collects them at runtime, plus `node` (which
is added by `ensure_node_for_npm` outside the registry).

The old `mise_install_components: Option<&str>` field merges into
`toolchain: Option<Option<&str>>` — None = linter binary, Some(None) =
toolchain without components, Some(Some(c)) = toolchain with components.

### Idempotence fix

Before: first run generates `.github/workflows/lint.yml` but doesn't
detect actionlint (no workflow yaml existed at detect time). Second run
picks up the generated workflow → adds actionlint → non-idempotent.

Fix: when init is about to generate the workflow, synthesize the workflow
patterns into `present_patterns` so actionlint gets selected in the same
run. Covered by new `tests/cases/general/init-idempotent/` e2e case.

### Tests

- New e2e cases: `general/init-rust` (fresh rust project → full init),
  `general/init-idempotent` (fully-initialized repo → "No changes to apply")
- init-rust test uses a fake `mise` shell-script stub to deterministically
  pin tool versions, via the existing `[fake_bins]` harness feature
- Fixes a snapshot-writer bug in `write_test_toml` that was producing
  malformed test.toml (missing newlines, escape-processing strings)
- New unit tests for `normalize_tools_section`, markdownlint migration,
  rust workflow generation
Signed-off-by: Gregor Zeitlinger <[email protected]>
Copy link
Copy Markdown
Member

@martincostello martincostello left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check whether the Copilot comments need addressing, but otherwise LGTM.

…fix (#195)

## Summary
Stacked on #187. Three init improvements:

- **Rust workflow steps**: `generate_lint_workflow` takes `has_rust`
param — inserts `Swatinem/rust-cache` + `rustup component add clippy
rustfmt` when Rust is detected.
- **markdownlint migration**: rename config to `.markdownlint.yml` (from
`.json`), drop line-length rule (deferred to editorconfig-checker).
Removes legacy variants.
- **Idempotence fix**: `normalize_tools_section` sorts `[tools]` and
inserts `# Linters` header once; re-running `flint init` prints "No
changes to apply."

Registry refactor: `.toolchain()` / `.toolchain_components(..)` builders
replace hardcoded `REUSED_RUNTIME_KEYS`. Toolchain set is now derived
from the registry via `toolchain_keys()`.

## Test plan
- [ ] `mise exec -- cargo test` green
- [ ] new e2e fixture `tests/cases/general/init-rust/` asserts
rust-aware init
- [ ] `init-idempotent` fixture verifies re-run prints "No changes to
apply."
- [ ] unit test `generate_lint_workflow_with_rust` covers workflow
content (kept out of e2e snapshot to avoid renovate pin-bump flakes)

---------

Signed-off-by: Gregor Zeitlinger <[email protected]>
- remove duplicate `.mise_tool("cargo:xmloxide")` on `check_xmllint`
- fix `.style()` doc: Style category is not in `Profile::Lang`
- rename "deference" heading to "defers to formatters"
Signed-off-by: Gregor Zeitlinger <[email protected]>
Ports #176 (cargo-clippy --all-targets) onto the split registry module:
- `src/registry/checks.rs` — add `--all-targets` to `check_cargo_clippy`
- `src/registry/tests.rs` — `headers.iter().copied().collect()` → `headers.to_vec()`

Also keeps the newer mise `v2026.4.16` bump already on this branch and
adopts the let-chain style for `components()` in `src/init/mod.rs`.
Signed-off-by: Gregor Zeitlinger <[email protected]>
@zeitlinger
Copy link
Copy Markdown
Member Author

Check whether the Copilot comments need addressing, but otherwise LGTM.

addressed - not that this pr now contains 2 prs you reviewed before

@zeitlinger zeitlinger merged commit 113b8cd into main Apr 21, 2026
15 of 16 checks passed
@zeitlinger zeitlinger deleted the docs/split-and-v2-install branch April 21, 2026 05:06
This was referenced Apr 20, 2026
zeitlinger pushed a commit that referenced this pull request Apr 21, 2026
### Added

- *(registry)* switch shfmt to aqua backend
([#175](#175))

### Fixed

- treat cargo-clippy as a partial fixer
([#197](#197))
- *(registry)* add --tests to cargo-clippy, add test coverage
([#176](#176))

### Other

- *(deps)* update taiki-e/install-action digest to 055f5df
([#180](#180))
- *(deps)* update dependency npm:@biomejs/biome to v2.4.12
([#191](#191))
- *(deps)* update rust crate clap to v4.6.1
([#196](#196))
- *(deps)* update rust crate tokio to v1.52.1
([#192](#192))
- *(deps)* update dependency pipx:ruff to v0.15.11
([#198](#198))
- *(deps)* update node.js to v24.15.0
([#194](#194))
- *(deps)* update dependency npm:prettier to v3.8.3
([#193](#193))
- exclude mise install dir from Windows Defender
([#188](#188))
- *(deps)* update dependency npm:renovate to v43.129.0
([#200](#200))
- restructure README/docs and split registry module
([#187](#187))
- *(deps)* update dependency mise to v2026.4.15
([#199](#199))

> [!IMPORTANT]
> Close and reopen this PR to trigger CI checks.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
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.

3 participants