fix(docx-core): harden heading detection (#157 Phase 1)

[stevenobiajulu]

Summary

Phase 1 of #157: tighten the existing heading-detection signals in read_file(format=\"json\"), document the canonical precedence rule, and add a centered-title detector. Phase 2 (derived is_heading / heading_level schema fields) is deferred to a follow-up issue.

Three concrete bugs fixed against tests/test_documents/nvca-regression/source.docx:

1. False negative: the SPA's center-aligned, ALL-CAPS, bold title (SERIES […] PREFERRED STOCK PURCHASE AGREEMENT) now surfaces as header_style: 'title_caps_centered' instead of producing a null heading signal.
2. False positives in extractHeaderInfo(): the long-paragraph regex branch no longer returns title_bare when no explicit . or : terminator is matched — body prose like Termination of Section 2.2(d)(i) shall not affect … and Except as described in Section 2.2(d)(i), … no longer surface a leading-word header_text.
3. False positives in detectRunInHeader(): a formatting-transition invariant (headerCharCount < totalVisibleChars) ensures the bold/underline prefix is followed by non-header body. Whole-paragraph bold/underline blocks (signature labels, defined-term lead-in sentences) no longer get classified as run-in headers.

Smoke results across the 367-paragraph NVCA SPA

Header style	Main	This PR	Net
run_in_header	12 (all false positives, header_text = whole body prose)	0	-12 false positives
title_with_period	12	12	unchanged
title_with_colon	9	12	+3 (recovered from former run_in_header mis-classification)
title_bare	90	88	-2 (Termination/Except now correctly null)
title_caps_centered	0	3	+3 NEW true positives (SPA title + 2 others)

Why Phase 1 only (not Phase 2)

Peer-reviewed with both Gemini and Codex CLI before implementation. Codex flagged that:

• The existing signals are too noisy to bless with a top-level verdict field today (the 12 false-positive run_in_header entries on main are exactly that noise).
• The existing header string field is wired into toon header-stripping (document_view.ts:363) and grep locators (packages/docx-mcp/src/tools/grep.ts:56) — repurposing it would be more breaking than adding new fields later.
• The Google Docs renderer is structurally cast to DocumentViewNode at packages/docx-mcp/src/tools/gdocs/read_file.ts:21, so any new top-level field is immediately a cross-renderer contract.

Phase 1 lands the cleaner signals and the documented precedence rule first; the Phase 2 schema (heading: null | { text, source, level } per Codex's preference, vs. nested heading: { is_heading, tier, level, source, source_detail } per Gemini's) will be designed against stable signals in a follow-up issue.

Documentation

• skills/docx-editing/SKILL.md — new "Heading Detection (read_file JSON output)" subsection with the canonical precedence table.
• packages/docx-mcp/README.md — brief paragraph documenting list_metadata.header_text / header_style (previously undocumented), pointing to SKILL.md.

Out of scope (tracked in follow-up)

• Top-level is_heading / heading_level schema work.
• Refining Heading 1–Heading 6 style detection (e.g., the HeadingPara1 / HeadingPara2 footgun in the NVCA fixture where styles inherit from heading styles but behave like body).
• Mirroring on the Google Docs renderer (its structural cast already auto-mirrors any new top-level fields, so no Phase 1 changes break it).

Test plan

• npm -w @usejunior/docx-core test — 1137 pass, 1 skipped, 0 fail (5 new branch tests added).
• npm -w @usejunior/docx-mcp test — 675 pass, 0 fail (1 new end-to-end JSON-shape test against the SPA fixture).
• npm run lint:workspaces — 0 errors (1 pre-existing warning in edit.test.ts unchanged).
• Manual smoke against the actual NVCA SPA fixture: SPA title detected as title_caps_centered, Termination of Section … and Except as described in Section … no longer surface a non-null header_text, all 12 main-branch run_in_header false positives suppressed.
• Governing Law and Venue: … style inline headers still detected as title_with_colon (no regression in document_view.branch.test.ts:150).
• New regression test for a real bold-prefix + body-suffix paragraph confirms run_in_header still fires on legitimate cases.

Ref: #157

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
site	Ready	Preview, Comment	May 8, 2026 5:15pm

[codecov]

Codecov Report

❌ Patch coverage is 84.12698% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/docx-core/src/primitives/document_view.ts	84.12%	6 Missing and 4 partials ⚠️

📢 Thoughts on this report? Let us know!