panache-cli 2.49.0__tar.gz → 2.51.0__tar.gz

panache_cli-2.51.0/.claude/rules/yaml-formatter.md

@@ -0,0 +1,65 @@
+---
+paths:
+  - "crates/panache-formatter/src/formatter/yaml.rs"
+  - "crates/panache-formatter/src/formatter/yaml/**/*.rs"
+  - "crates/panache-formatter/src/formatter/yaml/**/*.md"
+  - "crates/panache-formatter/tests/yaml_cross_validation.rs"
+  - "crates/panache-formatter/tests/fixtures/yaml_corpus/**"
+  - "crates/panache-formatter/src/yaml_engine.rs"
+---
+
+This rule applies to the staged in-tree YAML formatter rollout. See
+[`yaml-formatter-cutover`](../skills/yaml-formatter-cutover/SKILL.md)
+for the phased plan and the canonical 13-rule style spec; this rule
+encodes the load-bearing invariants.
+
+- **The style spec is the source of truth.** The 13-rule spec in
+  `plan.md` (eventually `crates/panache-formatter/src/formatter/yaml/STYLE.md`)
+  defines what the formatter emits. pretty_yaml is used as a
+  cross-validation reference because it implements the same rules,
+  not as a divergence target. Don't introduce "we differ from
+  pretty_yaml here because…" comments — if we differ, one of us is
+  wrong relative to the spec; fix that.
+- **Shadow-first.** The in-tree YAML formatter is NOT wired into the
+  live formatting pipeline until Phase 2 (joint cutover) lands. While
+  in shadow, callers must continue to go through
+  `yaml_engine.rs::format_text` (pretty_yaml). Don't introduce a
+  partial cutover where some YAML output paths use the in-tree
+  formatter and others use pretty_yaml.
+- **Cross-validation disagreements are bugs, not divergences.** Every
+  difference between `format_in_tree(x)` and `pretty_yaml(x)` is
+  either (a) a bug in the in-tree formatter, (b) a parser CST shape
+  bug in `panache-parser`, or (c) a bug in pretty_yaml. Diagnose in
+  that order. Fix it; don't enumerate it.
+- **Adding a 14th rule is a deliberate act.** If Phase 1 surfaces an
+  edge case the 13 rules don't cover, the resolution is a new rule
+  in STYLE.md (with a one-line rationale and a fixture) — not a
+  special-case branch in the formatter. New rules need explicit
+  decision: does pretty_yaml's behavior become the spec, or do we
+  diverge? Document the decision.
+- **Idempotency is asserted in the harness.** Every corpus case must
+  satisfy `format(format(x)) == format(x)`. Second assertion per
+  case, not a separate test bucket. A new case that fails idempotency
+  blocks merge until fixed.
+- **Drive parser fixes through formatter symptoms.** A formatter
+  cross-validation failure often surfaces a parser CST shape gap
+  (mis-attached trivia, off-by-one comment placement, wrong indent
+  grouping). Before writing a formatter workaround, verify the
+  in-tree parser CST matches what a spec-compliant formatter would
+  expect. See the [`formatter`](formatter.md) rule on idempotency
+  root-causing.
+- **Formatter modules stay in `panache-formatter`.** No YAML
+  formatter logic in `panache-parser`. The parser stays policy-free
+  per [`yaml-parser`](yaml-parser.md) and [`parser`](parser.md).
+- **No ad-hoc YAML output paths.** All YAML rendering goes through
+  the in-tree formatter (or, until Phase 2, through
+  `yaml_engine.rs::format_text`). No one-off `format_yaml_inline`
+  helpers in feature modules.
+- **Plain metadata before hashpipe.** Phase 3 (hashpipe) starts after
+  Phase 2 cuts over. Hashpipe inherits the plain pipeline via
+  `normalize_hashpipe_input`; building hashpipe paths first locks in
+  behavior before the plain engine has fully stabilized.
+- **Don't update host golden cases under `tests/fixtures/cases/*/`
+  to match in-tree output until Phase 2.** Until the cutover, live
+  output is still pretty_yaml; changing host expectations would mask
+  cross-validation regressions.

panache_cli-2.51.0/.claude/skills/yaml-formatter-cutover/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: yaml-formatter-cutover
+description: Drive the staged in-tree YAML formatter rollout — implement
+  the rule-based style spec, cross-validate against pretty_yaml, joint
+  parser+formatter cutover, then hashpipe extension. Sibling to
+  yaml-shadow-expand (parser-coverage); invoke when the work is formatter-side
+  or the joint cutover gate.
+---
+
+Use this skill when:
+
+- Building, extending, or testing the in-tree YAML formatter under
+  `crates/panache-formatter/src/formatter/yaml/`.
+- Maintaining the cross-validation harness that compares formatter
+  output to `pretty_yaml` on the corpus.
+- Extending the style spec with a newly-discovered rule (rare —
+  see [`plan.md`](plan.md) for the 13-rule spec and the process for
+  adding a 14th).
+- Preparing or executing the joint cutover that retires `yaml_parser` and
+  `pretty_yaml` for plain metadata YAML in one commit.
+- Extending the same pipeline to hashpipe YAML after the plain cutover lands.
+
+For parser-side fixture nibbling, triage, allowlist work, or yaml-test-suite
+maintenance, use [`yaml-shadow-expand`](../yaml-shadow-expand/SKILL.md)
+instead. The two skills share parser code but own different concerns.
+
+## Current state
+
+Phase 1 in progress. 1.1 (module skeleton, byte-passthrough stub),
+1.2 (STYLE.md relocation), and 1.3 (cross-validation harness with
+starter corpus) have landed. Rule implementations (1.4+) outstanding.
+The live YAML path still goes through
+`crates/panache-formatter/src/yaml_engine.rs` → `pretty_yaml::format_text`,
+with the host CST carrying the legacy `yaml_parser` shape from
+`crates/panache-parser/src/syntax/yaml.rs`. The in-tree parser
+(`crates/panache-parser/src/parser/yaml/`) is fully event-parity green
+against yaml-test-suite (308 passes_now, 94 error_contract_ok, both
+`fails_needs_*` buckets empty); the in-tree formatter consumes its CST
+but is byte-passthrough until per-container renderers land.
+
+The plan lives in [`plan.md`](plan.md) alongside this file. Treat it as
+the authoritative phasing reference; update its "what landed" block as
+work progresses.
+
+## Scope boundaries
+
+- **Formatter crate** (`crates/panache-formatter/`) owns the new YAML
+  formatter modules. Don't put formatter logic in `panache-parser`; the
+  parser stays policy-free per [`yaml-parser`](../../rules/yaml-parser.md)
+  and [`formatter`](../../rules/formatter.md) rules.
+- **Shadow-first.** Until the joint cutover lands, the in-tree formatter
+  is NOT wired into the live formatting pipeline. It exists as a parallel
+  implementation cross-validated against pretty_yaml output. See
+  [`yaml-formatter`](../../rules/yaml-formatter.md) for the invariants.
+- **Rule-based deterministic style.** The 13-rule spec in [`plan.md`](plan.md)
+  (eventually `STYLE.md` in the formatter module) is the source of truth.
+  pretty_yaml is a cross-validation reference because it implements the
+  same rules — not a divergence target. If `format_in_tree(x) != pretty_yaml(x)`,
+  it's a bug in the in-tree formatter, the in-tree parser CST shape, or
+  pretty_yaml, in that diagnostic order.
+- **Plain metadata first, hashpipe last.** Hashpipe inherits the plain
+  engine via `normalize_hashpipe_input`. Doing hashpipe first means doing
+  the plain work anyway plus locking in hashpipe-specific behavior before
+  plain solidifies.
+
+## Architecture trajectory
+
+End state:
+
+```
+src/syntax/yaml.rs   →  panache-parser in-tree YAML CST
+                           ↓
+host CST            →  panache-formatter::formatter::yaml
+                           ↓
+                       formatted YAML text
+```
+
+`yaml_parser` and `pretty_yaml` both removed in the cutover commit.
+
+Phased path:
+
+1. **Shadow formatter (Phase 1).** Build
+   `crates/panache-formatter/src/formatter/yaml/` consuming the in-tree
+   parser's CST. No host wiring. Tests assert
+   `format_in_tree(text) == pretty_yaml(text)` over a corpus, plus
+   idempotency.
+2. **Joint cutover (Phase 2).** When cross-validation passes across
+   the corpus, swap `src/syntax/yaml.rs` to use the in-tree parser AND
+   replace `yaml_engine.rs::format_text` with the in-tree formatter in
+   one commit. Both `yaml_parser` and `pretty_yaml` come out together.
+3. **Hashpipe extension (Phase 3).** Wire the same parser+formatter
+   through `normalize_hashpipe_input` for `#|`-prefixed YAML inside
+   executable chunks. Hashpipe-specific edge cases (continuation lines,
+   blank-line semantics) get their own golden fixtures.
+
+## Key files
+
+- `crates/panache-formatter/src/formatter/yaml/` — in-tree YAML formatter
+  modules (created in Phase 1).
+- `crates/panache-formatter/src/formatter/yaml/STYLE.md` — canonical
+  style spec (13 rules), moved from `plan.md` once the module exists.
+- `crates/panache-formatter/tests/yaml_cross_validation.rs` — Phase 1
+  cross-validation harness. Walks a corpus, asserts
+  `format_in_tree == pretty_yaml` and idempotency
+  (`format(format(x)) == format(x)`). Disagreements are bugs to fix,
+  not divergences to enumerate.
+- `crates/panache-formatter/tests/fixtures/yaml_corpus/` — corpus of
+  representative frontmatter cases (real `.qmd`/`.Rmd` frontmatter
+  plus hand-picked stressors for flow overflow, comments, anchors).
+- `tests/fixtures/cases/*/` — host-level golden cases (existing
+  pattern). New cases that specifically exercise YAML formatting come
+  here; the host config schema lives at this level.
+- `crates/panache-formatter/src/yaml_engine.rs` — current pretty_yaml
+  wrapper. Untouched until Phase 2.
+- `crates/panache-parser/src/syntax/yaml.rs` — current `yaml_parser`
+  bridge. Untouched until Phase 2.
+
+## Workflow
+
+1. **Confirm phase.** Read [`plan.md`](plan.md) for the current
+   "what landed" annotations. Don't start Phase 2 work before Phase 1
+   parity holds; don't start Phase 3 before Phase 2 has cut over.
+
+2. **Diagnose cross-validation failures in order.** If
+   `format_in_tree(x) != pretty_yaml(x)`: first suspect the in-tree
+   formatter, then the in-tree parser CST shape, then pretty_yaml. Do
+   not enumerate the case as a divergence — fix the bug. The only
+   route to a legitimate output change is a deliberate spec extension
+   (a 14th rule with rationale and fixture), per
+   [`yaml-formatter`](../../rules/yaml-formatter.md).
+
+3. **Drive parser fixes through formatter symptoms.** A
+   cross-validation failure often surfaces a parser CST shape gap
+   (mis-attached trivia, wrong indent grouping). Verify against the
+   in-tree parser CST shape before reaching for a formatter
+   workaround — see [`formatter`](../../rules/formatter.md) rule on
+   idempotency root-causing.
+
+4. **Validate**:
+   - `cargo test -p panache-formatter --test yaml_cross_validation`
+   - `cargo test -p panache-parser --test yaml` (no regression in parser parity)
+   - `cargo test` (workspace)
+   - `cargo clippy --workspace --all-targets -- -D warnings`
+   - `cargo fmt -- --check`
+
+5. **Update `plan.md`** with a "what landed" annotation matching the
+   `scanner-rewrite.md` precedent in the sibling skill.
+
+## Dos and don'ts
+
+- **Do** treat the style spec as the source of truth and pretty_yaml
+  as a cross-validation reference, not a divergence target.
+- **Do** keep formatter modules in `crates/panache-formatter/`; the
+  parser stays policy-free.
+- **Do** treat idempotency as a first-class invariant, asserted in the
+  cross-validation harness, not just verified ad-hoc.
+- **Don't** wire the in-tree formatter into the live pipeline before
+  Phase 2. The shadow invariant is what keeps the cutover honest.
+- **Don't** add ad-hoc YAML output paths elsewhere (e.g. a
+  one-off `format_yaml_inline` somewhere). Funnel everything through
+  the in-tree formatter from Phase 1 forward.
+- **Don't** start hashpipe work before plain metadata has cut over.
+- **Don't** absorb parser-coverage triage work here — that lives in
+  [`yaml-shadow-expand`](../yaml-shadow-expand/SKILL.md).
+
+## Report-back format
+
+1. Phase status before and after the session (what landed, what's
+   blocking).
+2. Divergence cases added or modified, with the choice each pins.
+3. Parser changes driven by formatter-side symptoms (if any).
+4. Cases unblocked but not yet landed (candidates for follow-up).
+5. Suggested next target.
+6. **Session continuation recommendation** — same three options as
+   [`yaml-shadow-expand`](../yaml-shadow-expand/SKILL.md) (continue
+   here / compact, then continue / new session).