feat(overlay): add Overlay 1.2.0 support

[char0n]

Summary

• Update ApiDOM (apidom-core, apidom-overlay, apidom-reference) to ^6.0.6 and @speclynx/api-languageservice to ^2.14.0 (release), adding Overlay 1.2.0 support to overlay apply, overlay diff and validate.
• applyOverlayApiDOM returns a Promise since ApiDOM 6.0.0, so additional overlays passed via --overlay are now awaited. They also pass their own URI as the dereferencing base URI, like the first overlay.
• overlay diff emits Overlay 1.2.0 by default. The new --overlay-version <1.1.0|1.2.0> option targets an older version. 1.0.0 is not offered: the generated actions update primitive nodes and concatenate arrays, which 1.0.0 forbids (upstream: apidom-overlay: diff emits invalid actions for overlay: 1.0.0 apidom#606).
• overlay apply --verbose now prints the trace up to the failing action when applying fails (e.g. --strict zero-match), instead of printing nothing.
• The CLI exits quietly when stdout is closed early (e.g. | head) instead of crashing with an unhandled EPIPE.
• Removed the unused CommonJS build. The package is ESM-only ("type": "module", no main/exports, publishes only .mjs), so the .cjs output was never shipped, and src/cli.cjs could not even load because of import.meta.
• README updated: Overlay 1.2.0 supported, reusable action references noted, --overlay-version documented. CLAUDE.md updated for the removed CJS build.

Notes

package-lock.json was regenerated from scratch. With api-languageservice 2.13.x still pinned to ApiDOM 5, npm installed nested duplicate copies of apidom-ns-overlay-1@6, which broke the overlay element type checks. With 2.14.0, everything uses one deduped ApiDOM 6 tree. As a side effect, the critical handlebars audit advisory is gone, and npm audit --omit=dev reports 0 vulnerabilities.

Upstream issue found during review: speclynx/api-languageservice#71 (the "local reference not found" diagnostic code is built from Date.now()).

Test plan

• npm run typescript:check-types
• npm run lint
• npm test: 101 passing. New tests cover:
  • Overlay 1.2.0 reusable actions (first and additional overlays, unresolvable refs, --strict, --verbose)
  • the 1.1.0 copy action and its trace
  • the failure trace
  • valid and invalid 1.2.0 documents in validate
  • diff → validate → apply round trip for 1.1.0 and 1.2.0
  • rejection of --overlay-version 1.0.0
• Manual: Node 20.0.0 / 20.19.1 / 26.3.1 smoke run, npm pack --dry-run, overlay apply ... | head

[mergewatch]

18 files scanned · 395 lines reviewed · 6 specialized agents ran · dependency files detected

🟡 3/5 — Review recommended — One substantive warning about incorrect reference resolution for additional overlays that could cause silent failures or wrong behavior — warrants review before merging.

Diagram — Overlay 1.2.0 support: dependency upgrades, async overlay application, and new CLI options

flowchart TD
    A["package.json<br/>apidom deps 5→6<br/>api-languageservice 2.13→2.14"] -->|enables| B["applyOverlayApiDOM<br/>now returns Promise"]
    
    A -->|enables| C["Overlay 1.2.0<br/>reusable actions"]
    
    B -->|requires| D["src/commands/overlay/apply/action.ts<br/>await applyOverlayApiDOM"]
    
    C -->|requires| E["src/commands/overlay/apply/action.ts<br/>resolve $ref in components.actions"]
    
    E -->|uses| F["parse + url.sanitize<br/>from apidom-reference"]
    
    G["src/commands/overlay/diff/index.ts<br/>--overlay-version option"] -->|passes to| H["src/commands/overlay/diff/action.ts<br/>diffOverlay opts.overlay"]
    
    H -->|generates| I["Overlay 1.1.0 or 1.2.0<br/>default 1.2.0"]
    
    D -->|improves| J["src/commands/overlay/apply/trace.ts<br/>print trace on failure"]
    
    K["bin/speclynx.mjs<br/>EPIPE handler"] -->|prevents| L["broken pipe errors<br/>when piped to head"]
    
    M["babel.config.cjs<br/>remove cjs env"] -->|aligns with| N["package.json<br/>ESM-only build"]
    
    O["test fixtures<br/>overlay-reusable.yaml<br/>overlay-copy.yaml<br/>overlay-1-2.yaml"] -->|test| D
    O -->|test| G
    O -->|test| C

Loading

_{Covers files changed in this PR — not the whole system.}

This PR upgrades ApiDOM and api-languageservice dependencies to support Overlay 1. 2.

Requires your attention

	Location	Finding
⚠️	apply/action.ts:71	parse() called with wrong options for additional overlays

🟡 Warnings (1)

• src/commands/overlay/apply/action.ts:71 — parse() called with wrong options for additional overlays
  When parsing additional overlays, parse() is called with defaultApplyOverlayOptions.reference as its options argument. However, the intent (as shown by the new reference key in additionalApplyOpts) is to resolve reusable action references relative to the additional overlay's own URI. Using defaultApplyOverlayOptions.reference means the base URI for reference resolution during parsing is the default one (likely the first overlay's path or a global default), not additionalOverlayURI. This could cause $ref resolution to fail or silently resolve against the wrong base when the additional overlay contains reusable action references.

  Suggestion: Pass additionalApplyOpts (or at least { reference: additionalApplyOpts.reference }) to parse() instead of defaultApplyOverlayOptions.reference, so that the parse step also uses the correct base URI.
  ↳ Line 71 calls parse(additionalOverlayURI, defaultApplyOverlayOptions.reference) but the additionalApplyOpts object defined on lines 60-66 explicitly sets `reference: { resolve: { baseURI: url.san…

ℹ️ Review details — 23,930 tokens · ~$0.3531 · 17.3s

Model	claude-sonnet-4.6
Review time	17.3s
Tokens	21,948 in · 1,982 out · 23,930 total
Est. cost	~$0.2299 this run · ~$0.3531 total for PR (LLM only)
Suppressed	1 finding removed by dedup & quality filters

_{Was this review helpful? React with 👍 or 👎 on this comment.
View full details}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

Superseded by new review on latest commit.

[mergewatch]

📝 Review feedback — see the full review in the summary comment above.

[char0n]

🎉 This PR is included in version 1.5.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀