refactor: restructure README/docs and split registry module#187
Merged
zeitlinger merged 9 commits intomainfrom Apr 21, 2026
Merged
refactor: restructure README/docs and split registry module#187zeitlinger merged 9 commits intomainfrom
zeitlinger merged 9 commits intomainfrom
Conversation
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]>
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]>
Contributor
There was a problem hiding this comment.
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.rsintosrc/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.mdintodocs/*.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.
4 tasks
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]>
4 tasks
Member
martincostello
left a comment
There was a problem hiding this comment.
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]>
Signed-off-by: Gregor Zeitlinger <[email protected]>
Member
Author
addressed - not that this pr now contains 2 prs you reviewed before |
martincostello
approved these changes
Apr 20, 2026
This was referenced Apr 20, 2026
Closed
Merged
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>
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.
Summary
"github:grafana/flint" = "0.20.2"now that v2 is released; new Renovate custom manager keeps the README version fresh.readme_linter_table_in_synctest generates summary into README and detail sections intodocs/linters.md;UPDATE_README=1 cargo test readme_linter_table_in_syncstill regenerates both.Test plan
cargo test --bin flint readme_linter_table_in_syncgreenmise run lintgreendocs/linters.md#<name>docs/linters.md: Scope[file](#scopes)anchors still resolve to the Scopes section on the same page