Skip to content

Roadmap (high level)

Phases are ordered by dependency and by risk: the riskiest ideas (declarative rules, preserve, comment handling) are proven on simple languages before the expensive ones are attempted.

Phase 0 — Decisions and scaffolding

  • Resolve the open decisions below.
  • Repository scaffolding: packaging, CI (lint, type-check, tests, coverage), contribution guide, fixture-test harness.

Phase 1 — Core pipeline on one trivial language

  • CST node interface over tree-sitter; trivia and comment attachment.
  • Doc IR and printer (including table and verbatim).
  • Option schema, config loading (TOML, YAML, pyproject.toml, package.json), cascading, provenance.
  • Verifier (equivalence + idempotency).
  • Minimal CLI: format, check, diff.
  • Language: JSON / JSONC — small grammar, comments, trailing commas, alignment; proves the whole pipeline end to end.

Exit criterion: JSON formatted under every option combination passes the verifier; a user-level rule override works.

Phase 2 — Stylesheets and Python

  • CSS, then SCSS (nesting, mixins, maps): exercises declarative rules on a real language with modest expression complexity.
  • Python: significant indentation, comments everywhere, docstrings, string prefixes — stress-tests preserve and comment attachment.
  • Inline directives, .editorconfig support (done).

Phase 3 — JavaScript and TypeScript

  • Expression-heavy layout: chains, arrow functions, JSX/TSX, template literals, ASI-sensitive semicolon handling (done: T20, T21).
  • Performance work: caching, parallelism, profiling of the rule engine (done: T22, T23). Released as 0.3.0.

Phase 4 — Markup and embedding (done)

  • Injection layer: a pack splices another pack's Doc into its own, with the embedded language's options and verification (T24).
  • HTML with whitespace-sensitivity rules (inline vs. block elements), <style> and <script> formatted by the CSS, JavaScript, TypeScript and JSON packs (T25).
  • Svelte: the HTML rules plus expressions and logic blocks (T26).
  • Language packs as plugins (entry points); a worked example and a style-guide howto in docs/howto; speed compared with Black and Prettier (T27). Markdown fences and tagged strings wait for the Markdown pack (Phase 6).

Phase 5 — Adoption tooling

  • Presets: rainbow:black and rainbow:prettier beside minimal and balanced; D6 decided (no preset applies implicitly; ADR 0006).
  • rainbow-fmt explain: the configuration sources that apply to a file, in order, with the options each one sets, and the file's directives.
  • rainbow-fmt infer: read a project and write the rainbow.toml whose options reproduce its dominant style, option by option, reporting the options the project is inconsistent about.
  • pre-commit hook and GitHub Action.
  • LSP server (rainbow-fmt lsp: document formatting over stdio, no dependencies) and a VS Code extension that runs it.

Phase 6 — Ecosystem and 1.0

  • Additional packs: YAML, TOML, Markdown (with fenced code formatted by the other packs through the injection layer), SQL: all on main (T34–T37). Jinja/Django templates have no tree-sitter grammar on PyPI yet.
  • Stable plugin API and rule format; test-pack command.
  • VS Code extension published on the Visual Studio Marketplace and Open VSX (T38), released with 1.0.
  • Documentation site at rainbow-fmt.dev (T39): on main.
  • Option reference generated from schemas (options.md, T41); 1.0 release.

Open decisions

# Question Options Decision / current leaning
D1 Implementation language of the core Python · Rust · TypeScript · Rust core + Python/JS bindings Decided (ADR 0002): Python 3.12+, printer isolated for a possible Rust port; PyPI, standalone executables, npm wrapper.
D2 Parser backend tree-sitter · per-language native parsers · mixed Decided (ADR 0003): tree-sitter by default, behind a Parser protocol.
D3 Rule format TOML templates · purpose-built DSL · Python builders Decided (ADR 0005): Python builder functions in packs; restricted expression templates for user [[rule]] overrides.
D4 Config file format TOML · YAML · both Decided (ADR 0001): TOML primary; YAML and package.json supported from the first release.
D5 License MIT · Apache-2.0 · MPL-2.0 Decided (ADR 0004): MIT.
D6 Default preset minimal · balanced · none Decided (ADR 0006): none applies implicitly; the schema defaults are the default style, presets (minimal, balanced, black, prettier) are opt-in, infer is the start for an existing project.

Key risks

  • Comment attachment is the leading source of bugs in every formatter. Mitigation: dedicated algorithm, dedicated tests, verifier catches losses.
  • Option combinatorics — n options × m values is untestable exhaustively. Mitigation: verifier-based safety on sampled combinations; golden tests only for documented examples.
  • Performance of an interpreted rule engine in Python. Mitigation: measure from Phase 1, cache per file hash, keep the printer isolated for a possible Rust port.
  • Scope creep across many languages. Mitigation: Level 0–4 support ladder; ship languages at partial levels.