Summary
Replace the remaining Node-backed documentation/config formatting path with Rust-native tooling and clean up the surrounding recipe conventions before the next larger API/tooling push.
Motivation
The Rust crate should keep development tooling in Rust, Cargo, uv, or small standalone CLIs where practical. Documentation/config checks may still require Node when Markdown linting or YAML formatting depends on npx, markdownlint, or Prettier.
Moving this path to Rust-native tools reduces setup surface area and keeps future feature/API work focused on crate behavior rather than local tooling dependencies.
Proposed scope
- Standardize recipe naming around non-mutating
*-check commands and mutating *-fix commands, keeping backwards-compatible aliases where useful.
- Add or adjust aliases such as
yaml-check, toml-check, toml-fix, and possibly shell-fix so docs can describe the workflow consistently.
- Add a repository Semgrep rule that flags obvious user-facing command ordering mistakes, such as documenting
just fix before just check or just python-fix before just python-check.
- Add repository-owned Rust-native formatting/lint configuration as needed.
- Replace YAML formatting with a Rust-native YAML formatter (
pretty_yaml or an equivalent validated replacement) if behavior is acceptable.
- Trial
rumdl against the existing Markdown corpus and Markdown lint expectations.
- Replace Markdown check/fix recipes with
rumdl only if the rule/fix behavior is compatible enough.
- Add repository-owned Semgrep rules for GitHub Actions
uses: entries.
- Require external GitHub Actions to be pinned to full commit SHAs, while allowing local actions such as
./.github/actions/....
- Restrict external action references to an explicit allowlist of approved
owner/repo actions.
- Keep human-readable version comments next to SHA pins so Dependabot updates and human review remain manageable.
- Decide how the replacement tooling should handle Dependabot updates for SHA-pinned actions.
- Remove unused workflow permissions while touching workflow policy.
- Update CI setup to install the new tools and remove Node.js setup if no remaining recipe needs
node or npx.
- Update setup recipes, tool checks, contributing docs, command docs, and tooling-alignment docs where present.
Acceptance criteria
- User-facing docs consistently present non-mutating checks before mutating fixes.
- Recipe names make the check/fix split obvious and preserve useful compatibility aliases.
- A Semgrep guard catches obvious check/fix ordering regressions in Markdown docs and justfile/help text.
- YAML check/fix recipes use the selected Rust-native YAML path, or the PR documents why parity blocked replacement.
- Markdown check/fix recipes use
rumdl, or the PR documents any incompatibility that blocks replacement.
- GitHub Actions
uses: references are covered by repository-owned Semgrep rules that require SHA pinning for external actions.
- External GitHub Actions are limited to an explicit allowlist, with local action paths still permitted.
- Workflow action SHA pins retain readable version comments or an equivalent review/update aid.
- Unused workflow permissions are removed where found.
- The repository's normal check/CI command passes locally after the migration.
- CI no longer installs Node.js if it is no longer required.
- Tooling docs accurately describe the Rust-native formatting stack and workflow action policy.
- Formatting churn is reviewed and kept intentional.
Non-goals
- Do not change Markdown or YAML style rules beyond the minimum needed for equivalent checks.
- Do not remove compatibility aliases unless there is a strong reason.
- Do not mix this with unrelated test taxonomy, API, or performance cleanup.
Summary
Replace the remaining Node-backed documentation/config formatting path with Rust-native tooling and clean up the surrounding recipe conventions before the next larger API/tooling push.
Motivation
The Rust crate should keep development tooling in Rust, Cargo, uv, or small standalone CLIs where practical. Documentation/config checks may still require Node when Markdown linting or YAML formatting depends on
npx,markdownlint, or Prettier.Moving this path to Rust-native tools reduces setup surface area and keeps future feature/API work focused on crate behavior rather than local tooling dependencies.
Proposed scope
*-checkcommands and mutating*-fixcommands, keeping backwards-compatible aliases where useful.yaml-check,toml-check,toml-fix, and possiblyshell-fixso docs can describe the workflow consistently.just fixbeforejust checkorjust python-fixbeforejust python-check.pretty_yamlor an equivalent validated replacement) if behavior is acceptable.rumdlagainst the existing Markdown corpus and Markdown lint expectations.rumdlonly if the rule/fix behavior is compatible enough.uses:entries../.github/actions/....owner/repoactions.nodeornpx.Acceptance criteria
rumdl, or the PR documents any incompatibility that blocks replacement.uses:references are covered by repository-owned Semgrep rules that require SHA pinning for external actions.Non-goals