feat(book): section-level scope for proof:* / figure / equation auto-prefix

[mmcky]

Summary

Closes #27. Adds a scope option to NumberingItem so authors can opt kinds into LaTeX \newtheorem{...}[section]-style numbering when numbering.book: true.

project:
  numbering:
    book: true
    proof:
      scope: section          # theorems, lemmas, … render as 5.1.1, 5.1.2, 5.2.1

• Counter resets on each new heading_2 (or heading_3 for subsection, etc.).
• Proofs before the first ## Section render literal 5.0.1 to match the LaTeX PDF (avoids collision with later 5.1.x).
• Resolution order: per-kind override (e.g. numbering.proof:theorem.scope) → numbering.proof.scope umbrella for the proof family → numbering.all.scope → chapter (today's default).
• Applies to every auto-prefix kind: figure, equation, table, exercise, proof:*. Default chapter preserves today's behaviour exactly.
• Validator normalises chapter/section/subsection to heading_N.
• continue: true still wins over scope (matches §3.4(6) opt-out — keeps the kind globally flat).

Dependency

Builds on the auto-prefix machinery shipped in #22 ("Book-style numbering: format, label, section-tagged TOC, auto-prefix"). Specifically extends packages/myst-transforms/src/enumerate.ts incrementCount, which #22 introduced as the auto-prefix hook. When upstreaming to jupyter-book/mystmd, #22 must land first.

Motivation

From testing of qe-v2 against QuantEcon/book-dp1: the LaTeX PDF is the canonical reference and prints Theorem 1.2.1 (chapter.section.theorem), but qe-v2 MyST printed Theorem 1.1 (chapter.theorem). Body prose like "see Theorem 5.1.2" then no longer agrees with the rendered enumerator. This adds the missing opt-in.

Test plan

• packages/myst-transforms — 8 new unit tests in enumerate.spec.ts covering: section-scoped multi-section reset, per-kind override of proof umbrella, pre-section literal 5.0.1, Alph chapter (appendix), heading_2 alias, subsection (heading_3) scope, continue: true opt-out wins, and figures picking up numbering.all.scope. All 81 enumerate tests pass.
• packages/myst-frontmatter — 3 new YAML golden cases (numbering.yml) for alias normalisation, heading_N direct form, invalid-scope warning. All 502 frontmatter tests pass.
• packages/myst-cli — 285 existing tests still pass (no behaviour change when scope is absent).
• tsc clean for both packages.

CI note

The single CI failure is the Concurrent execution end-to-end test, which runs myst build --site --execute --execute-parallel 2 with a 15s timeout for two Jupyter notebook kernels. It's a known timing-flaky test (file comment: "Used to be 5000, increased due to CI slowness") and has failed similarly on recent unrelated PRs (#20, #21). This PR touches the numbering schema and enumerate.ts only — nothing in the Jupyter execution path. A re-run should resolve.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an opt-in scope setting to book-mode numbering so auto-prefixed kinds (especially proof:*) can use LaTeX-style section-/subsection-scoped prefixes (e.g. 5.1.1) and reset counters at the chosen heading boundary, while preserving the current chapter-scoped default.

Changes:

• Implement scope resolution + scoped prefix formatting/reset logic for book-mode auto-prefix kinds in ReferenceState.incrementCount.
• Extend frontmatter numbering validation/types to accept and normalize scope (chapter/section/… → heading_N).
• Add unit + YAML golden tests covering scope behavior, overrides, aliases, and invalid values.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/myst-transforms/src/enumerate.ts	Adds scope resolution and scoped auto-prefix/reset behavior for book-mode numbering.
packages/myst-transforms/src/enumerate.spec.ts	Adds unit tests for section/subsection scoping, overrides, and edge cases.
packages/myst-frontmatter/src/numbering/validators.ts	Validates + normalizes scope values and emits warnings for invalid scope.
packages/myst-frontmatter/src/numbering/types.ts	Documents and exposes the new NumberingItem.scope option.
packages/myst-frontmatter/src/numbering/numbering.yml	Adds golden cases for scope normalization and warnings.
.changeset/book-proof-scope.md	Declares patch releases and summarizes the new scope feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.