notescraft/specs/code-blocks-and-formatting/tasks.md

Tasks: Code blocks, language grammars and batch formatting

Rules: each task is independently testable. No task depends on work in an unfinished task. Order = execution order. Every task ends with cargo test -p <crate>, cargo clippy -p <crate> --all-targets -- -D warnings and cargo fmt -p <crate> for the crates it touched; the last task runs cargo xtask ci and cargo xtask i18n.

• 1. Prototype syntect and fix the dependency set
  Files: root Cargo.toml, xtask/src/layers.rs (("syntax", Class::Layer(0))), crates/syntax/ (Cargo.toml, src/lib.rs, src/load.rs)
  Done when: cargo xtask layers green; a test loads the bundled syntaxes with the fancy-regex backend (no onig in Cargo.lock) and lists which of the 12 built-in languages, TOML and TypeScript are present; the result is written into plan Risks (embed .sublime-syntax for any missing one).

• 2. Map scopes to 8 token kinds and highlight a block with caps
  Files: crates/syntax/src/scopes.rs, src/highlight.rs
  Done when: tests pass: each of the 8 TokenKinds reachable, unknown scopes ignored; lines over 10 KiB and blocks over the cap fall back to plain; a checkpointed window result equals the full-run result; 1 MiB line and random bytes do not panic.

• 3. Add the highlight cache and worker thread
  Files: crates/syntax/src/cache.rs
  Done when: tests pass: get never blocks and returns None on a miss, then Some after the worker finishes; key = hash(language, body) so an edit misses; entries and bytes are bounded with age eviction; latest request wins in the bounded queue.

• 4. Suggest languages for typos and unknown names
  Files: crates/syntax/src/suggest.rs
  Done when: tests pass: jsno suggests json, pyhton suggests python; ties are stable; an exact or alias match returns no suggestion; unknown garbage returns none.

• 5. Fetch and validate grammars with bounded curl
  Files: crates/syntax/src/fetch.rs, src/validate.rs, root Cargo.toml (sha2, default features off)
  Done when: tests pass with an injectable transport (no network): http, credentials, IP literal, localhost, redirects, oversize, non-grammar, bad sample and sha256 mismatch are each refused with a distinct error; a good grammar passes; offline gives a data error; registry host allow-list checked before spawn.

• 6. Add syntax colors to themes
  Files: crates/themes/src/{syntax.rs,model.rs,builtin.rs,load.rs,lib.rs}
  Done when: tests pass: every built-in theme has 8 token colors; a user theme with an optional [syntax] table overrides and falls back per variant; each token color has >= 4.5:1 contrast on code_background in every built-in theme; inline-code chip text vs chip background also >= 4.5:1.

• 7. Add JSON detect, validate, format and minify
  Files: crates/blocks/Cargo.toml, crates/blocks/src/json.rs
  Done when: tests pass: valid/invalid; format keeps key order and 1e5 byte-for-byte; minify round-trips; depth and 1 MiB caps return Err; hostile bytes do not panic; looks_like_json catches unlabeled and single template-string cases.

• 8. Register JSON block commands in the engine
  Files: crates/engine/src/block_edit/mod.rs, crates/engine/src/commands.rs, engine gate lists (ai/assistant_gate.rs, crates/mcp/src/calls/gate.rs)
  Done when: tests pass: json.format_block and json.minify_block are one undo step through lint_commit; invalid JSON leaves the text identical and returns Err; core_commands ids updated.

• 9. Add grammar install commands and settings
  Files: crates/engine/src/grammars.rs, crates/engine/src/prefs/app_settings.rs, crates/engine/src/commands.rs, crates/engine/Cargo.toml
  Done when: tests pass with the injectable transport: grammar.info, grammar.install, grammar.remove; a failed gate saves nothing and changes no state; the file is written via craft-atomic in the config dir; removal deletes file and entry; settings round-trip.

• 10. Style fenced code in source mode
  Files: crates/editor/Cargo.toml, crates/editor/src/{fence_syntax.rs,highlight.rs,colors.rs,lib.rs}
  Done when: tests pass: a fence gets Sty::Syntax sub-assignments with code_background; a cache miss paints plain Sty::Code; fences over 2,000 lines or 256 KiB stay plain; non-overlapping assignments hold with other styles; layout job for a hostile fence does not panic.

• 11. Render the code card in rendered mode
  Files: crates/ui-egui/src/views/note_view/blocks/code_card.rs, note_view/blocks.rs, note_view/inlines.rs (Span::CodeTok), views/note_view.rs (call site), src/text/views/code_card.rs, crates/i18n/locales/en.toml
  Done when: tests pass: uppercase language label, Copy puts the body without fences on the clipboard, Wrap reflows; unknown language renders plain; tokens colored for the 12 built-in languages; a 1,000+ line block draws only the visible window plus margin. Snapshot matches the "Code block" artboard in specs/large-vaults-and-code/design.

• 12. Draw inline code chips with rounded corners
  Files: crates/ui-egui/src/views/note_view/painting.rs
  Done when: tests pass: Span::Mono runs paint a radius-6 rect behind the galley; rows with inline math keep the flat background; click hit rects unchanged. Snapshot in Mocha and Latte.

• 13. Add language picker, JSON chip and grammar UI
  Files: crates/ui-egui/src/widgets/lang_picker.rs, views/note_view/blocks/code_card.rs, grammar install dialog strings, dismissed-offer list in the ui blob
  Done when: tests pass: typo in a label shows a suggestion that rewrites the label with a char-boundary-safe edit; valid unlabeled JSON shows a Format chip; a dismissed offer stays dismissed after restart; install flow shows errors from each gate.

• 14. Build the batch format/lint engine
  Files: crates/engine/src/batch/{mod.rs,commands.rs,propose.rs}, crates/engine/src/vault/session.rs
  Done when: tests pass: dry run on a temp vault writes nothing (fs compared) with correct counts; unreadable/invalid/read-only files listed as Not edited; Apply skips a file changed after the dry run; overlapping changes skipped and listed; cancel writes nothing; .obsidian/ and .notescraft/ never touched; one lint_commit per file.

• 15. Review batch changes file by file, then update docs and run the gate
  Files: crates/ui-egui/src/views/batch_view/{mod.rs,review.rs}, ROADMAP.md, docs/ARCHITECTURE.md, i18n tables
  Done when: review view shows per-file diffs with Accept/Skip, progress and cancel; cargo xtask ci and cargo xtask i18n green; ROADMAP and ARCHITECTURE list the new crate, commands and measured numbers (note with 50 blocks opens within 50 ms).