Skip to content

chore: replace Node markdown and YAML tooling with Rust-native tools #111

@acgetchell

Description

@acgetchell

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

  1. Standardize recipe naming around non-mutating *-check commands and mutating *-fix commands, keeping backwards-compatible aliases where useful.
  2. Add or adjust aliases such as yaml-check, toml-check, toml-fix, and possibly shell-fix so docs can describe the workflow consistently.
  3. 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.
  4. Add repository-owned Rust-native formatting/lint configuration as needed.
  5. Replace YAML formatting with a Rust-native YAML formatter (pretty_yaml or an equivalent validated replacement) if behavior is acceptable.
  6. Trial rumdl against the existing Markdown corpus and Markdown lint expectations.
  7. Replace Markdown check/fix recipes with rumdl only if the rule/fix behavior is compatible enough.
  8. Add repository-owned Semgrep rules for GitHub Actions uses: entries.
  9. Require external GitHub Actions to be pinned to full commit SHAs, while allowing local actions such as ./.github/actions/....
  10. Restrict external action references to an explicit allowlist of approved owner/repo actions.
  11. Keep human-readable version comments next to SHA pins so Dependabot updates and human review remain manageable.
  12. Decide how the replacement tooling should handle Dependabot updates for SHA-pinned actions.
  13. Remove unused workflow permissions while touching workflow policy.
  14. Update CI setup to install the new tools and remove Node.js setup if no remaining recipe needs node or npx.
  15. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions