@jasonbelmonti/markdown-engine 1.0.0 → 3.0.0

package/docs/contracts/frontmatter.md

@@ -0,0 +1,122 @@
+# Frontmatter Contract
+
+Status: Initial contract for `BEL-907 / WP-2A`
+Last updated: 2026-04-30
+
+This document defines the public behavior of YAML frontmatter parsing in
+`markdown-engine`. The raw `yaml` parser document and AST are internal adapter
+details and are not exposed through the public parse result.
+
+## Extraction
+
+Frontmatter is recognized only when the Markdown document begins with an
+optional UTF-8 BOM followed by an opening `---` line and a later closing `---`
+line. If the opening delimiter is not closed, the input is treated as Markdown
+body content.
+
+Absent frontmatter produces no diagnostics and leaves `parsed.frontmatter` and
+`parsed.document.frontmatter` unset. Empty frontmatter, such as:
+
+```yaml
+---
+---
+```
+
+produces `{}` with no diagnostics.
+
+## YAML Parser Options
+
+The adapter uses `yaml` package APIs verified against `yaml@2.8.3`. Parser
+behavior is pinned with these engine-owned options:
+
+```ts
+{
+  compat: null,
+  customTags: null,
+  intAsBigInt: false,
+  keepSourceTokens: false,
+  logLevel: "error",
+  merge: false,
+  prettyErrors: false,
+  resolveKnownTags: false,
+  schema: "core",
+  strict: true,
+  stringKeys: false,
+  uniqueKeys: true,
+  version: "1.2",
+}
+```
+
+Materialization uses:
+
+```ts
+{
+  mapAsMap: true,
+  maxAliasCount: 50,
+}
+```
+
+`mapAsMap: true` prevents JavaScript object key coercion during materialization.
+The engine then validates keys and converts supported maps into JSON-safe plain
+objects.
+
+## Values
+
+The schema is YAML 1.2 core. Representative scalar behavior:
+
+| YAML source | Parsed value |
+| --- | --- |
+| `yes`, `no`, `on`, `off` | strings |
+| `true`, `false` | booleans |
+| `null`, `~` | `null` |
+| integer and finite float values | numbers |
+
+The public frontmatter value must be JSON-safe: `null`, booleans, finite
+numbers, strings, arrays, and objects with string keys. Non-finite numbers such
+as `.nan` or `.inf` are rejected because JSON serialization would otherwise
+coerce them silently.
+
+## Keys
+
+Duplicate mapping keys are invalid. They produce a
+`frontmatter.yaml.invalid` diagnostic and no parsed frontmatter value.
+
+All mapping keys must be YAML string scalars. Numeric, boolean, null, sequence,
+or mapping keys are rejected with a `frontmatter.yaml.invalid` diagnostic before
+JavaScript key coercion can change the input shape.
+
+## Warnings
+
+YAML warnings are preserved as `frontmatter.yaml.warning` diagnostics with
+severity `warning`. Warnings do not block `parsed.frontmatter` when the YAML can
+still materialize into JSON-safe data.
+
+Explicit tags outside the YAML 1.2 core contract are not resolved through
+YAML 1.1 known-tag behavior. For example, `!!timestamp 2026-04-30` is preserved
+as the string `2026-04-30` and accompanied by an unresolved-tag warning.
+
+## Aliases And Merge Keys
+
+Aliases are supported with `maxAliasCount: 50` as the materialization limit. In
+`yaml@2.8.3`, inputs that reach that threshold are rejected as excessive alias
+expansion. Missing aliases are invalid and produce `frontmatter.yaml.invalid`.
+
+Cyclic aliases are invalid. They produce `frontmatter.yaml.invalid` and no
+parsed frontmatter value.
+
+YAML merge keys are disabled. A `<<` key is treated as an ordinary string key,
+not as an instruction to merge mappings.
+
+## Diagnostics
+
+Invalid YAML, multiple YAML documents, duplicate keys, unsupported keys, alias
+failures, cyclic aliases, non-finite numbers, and non-JSON-safe materialized
+values produce
+`frontmatter.yaml.invalid` diagnostics with severity `error`. Diagnostic source
+ranges are mapped back to Markdown source positions when the YAML package
+provides offsets; otherwise the full frontmatter block range is used.
+
+Warnings produce `frontmatter.yaml.warning` diagnostics with severity
+`warning`.
+
+Markdown body parsing continues even when frontmatter parsing fails.

package/fixtures/declarative-validation/examples/operational-spec/fail.md

@@ -0,0 +1,32 @@
+---
+title: Operational Spec Example
+status: ready
+---
+
+# Objective
+
+Mission control.
+
+# Context / Constraints
+
+The example stays generic. It validates Markdown headings, tables, IDs, list
+content, literal text, and links without attaching domain meaning to the core
+engine.
+
+# Execution Plan
+
+- MUST Validate profile fixtures locally.
+- Record evidence before requesting review.
+- Keep the checks deterministic and local-only.
+
+# Risk Register
+
+| ID | Mitigation | Status |
+| --- | --- | --- |
+| OPS-RISK-1 | Keep examples structural. | tracked |
+| OPS-RISK-2 | Keep commands local. | closed |
+
+# Handoff Links
+
+The [handoff packet](./handoff-packet.md) records follow-up review notes for the
+next operator.

package/fixtures/declarative-validation/examples/operational-spec/pass.md

@@ -0,0 +1,34 @@
+---
+title: Operational Spec Example
+owner: platform-team
+status: ready
+---
+
+# Objective
+
+Mission control uses this structural profile to confirm a small operating spec
+has the required sections, handoff links, and risk tracking details.
+
+# Context / Constraints
+
+The example stays generic. It validates Markdown headings, tables, IDs, list
+content, literal text, and links without attaching domain meaning to the core
+engine.
+
+# Execution Plan
+
+- MUST Validate profile fixtures locally.
+- MUST Record evidence before requesting review.
+- Keep the checks deterministic and local-only.
+
+# Risk Register
+
+| ID | Mitigation | Status |
+| --- | --- | --- |
+| OPS-RISK-1 | Keep examples structural. | tracked |
+| OPS-RISK-2 | Keep commands local. | closed |
+
+# Handoff Links
+
+The [handoff packet](./handoff-packet.md) records follow-up review notes for the
+next operator.

package/fixtures/declarative-validation/examples/operational-spec/profile.yaml

@@ -0,0 +1,131 @@
+syntaxVersion: markdown-engine.validation@v1
+documentVersion: 1.0.0
+rules:
+  - id: frontmatter.required
+    select:
+      target: document
+    assert:
+      frontmatterRequired:
+        fields:
+          - title
+          - owner
+          - status
+
+  - id: sections.required
+    select:
+      target: document
+    assert:
+      sectionsRequired:
+        order: strict
+        headings:
+          - Objective
+          - Context / Constraints
+          - Execution Plan
+          - Risk Register
+          - Handoff Links
+
+  - id: objective.text
+    select:
+      target: section
+      title: Objective
+    assert:
+      text:
+        contains: "Mission control"
+
+  - id: objective.length
+    select:
+      target: section
+      title: Objective
+    assert:
+      textLength:
+        min: 80
+        max: 180
+
+  - id: risk.heading.text
+    select:
+      target: heading
+      text: Risk Register
+    assert:
+      text:
+        contains: "Risk Register"
+
+  - id: risk.table.columns
+    select:
+      target: table
+      section: Risk Register
+      header:
+        - ID
+        - Mitigation
+        - Status
+    assert:
+      tableColumnsRequired:
+        columns:
+          - ID
+          - Mitigation
+          - Status
+
+  - id: risk.ids.unique
+    select:
+      target: tableCell
+      section: Risk Register
+      tableHeader:
+        - ID
+        - Mitigation
+        - Status
+      column: ID
+    assert:
+      ids:
+        prefix: OPS-RISK
+        unique: true
+
+  - id: tracked.risk.row
+    select:
+      target: tableRow
+      section: Risk Register
+      tableHeader:
+        - ID
+        - Mitigation
+        - Status
+      where:
+        column: Status
+        equals: tracked
+    assert:
+      text:
+        contains: OPS-RISK-1
+
+  - id: execution.must.count
+    select:
+      target: section
+      title: Execution Plan
+    assert:
+      textOccurrenceCount:
+        text: MUST
+        count: 2
+
+  - id: execution.list
+    select:
+      target: list
+      section: Execution Plan
+      ordered: false
+    assert:
+      text:
+        contains: "Validate profile"
+
+  - id: handoff.paragraph
+    select:
+      target: textSpan
+      section: Handoff Links
+      nodeType: paragraph
+      textIncludes: "handoff packet"
+    assert:
+      text:
+        contains: "follow-up"
+
+  - id: handoff.link
+    select:
+      target: link
+      section: Handoff Links
+      text: "handoff packet"
+      url: "./handoff-packet.md"
+    assert:
+      exists: true

package/fixtures/declarative-validation/examples/release-checklist/fail.md

@@ -0,0 +1,22 @@
+---
+title: Release Checklist Example
+release: 1.0.0
+owner: release-team
+---
+
+# Release Checklist
+
+- Verify package metadata.
+- Use manual bypass for the dry run.
+- Record release evidence.
+
+# Gate Table
+
+| ID | Gate | Status |
+| --- | --- | --- |
+| REL-GATE-1 | Contract docs | blocked |
+| REL-GATE-1 | Boundary audit | ready |
+
+# Links
+
+Publish review uses the [release notes](./release-notes.md) after all gates pass.

package/fixtures/declarative-validation/examples/release-checklist/pass.md

@@ -0,0 +1,22 @@
+---
+title: Release Checklist Example
+release: 1.0.0
+owner: release-team
+---
+
+# Release Checklist
+
+- Verify package metadata.
+- Verify package dry run.
+- Record release evidence.
+
+# Gate Table
+
+| ID | Gate | Status |
+| --- | --- | --- |
+| REL-GATE-1 | Contract docs | ready |
+| REL-GATE-2 | Boundary audit | ready |
+
+# Links
+
+Publish review uses the [release notes](./release-notes.md) after all gates pass.

package/fixtures/declarative-validation/examples/release-checklist/profile.yaml

@@ -0,0 +1,96 @@
+syntaxVersion: markdown-engine.validation@v1
+documentVersion: 1.0.0
+rules:
+  - id: frontmatter.required
+    select:
+      target: document
+    assert:
+      frontmatterRequired:
+        fields:
+          - title
+          - release
+          - owner
+
+  - id: sections.required
+    select:
+      target: document
+    assert:
+      sectionsRequired:
+        order: strict
+        headings:
+          - Release Checklist
+          - Gate Table
+          - Links
+
+  - id: checklist.list
+    select:
+      target: list
+      section: Release Checklist
+      ordered: false
+    assert:
+      text:
+        contains: "Verify package"
+        excludes:
+          - "manual bypass"
+
+  - id: gate.table.columns
+    select:
+      target: table
+      section: Gate Table
+      header:
+        - ID
+        - Gate
+        - Status
+    assert:
+      tableColumnsRequired:
+        columns:
+          - ID
+          - Gate
+          - Status
+
+  - id: gate.ids.unique
+    select:
+      target: tableCell
+      section: Gate Table
+      column: ID
+    assert:
+      ids:
+        prefix: REL-GATE
+        unique: true
+
+  - id: ready.gate.row
+    select:
+      target: tableRow
+      section: Gate Table
+      tableHeader:
+        - ID
+        - Gate
+        - Status
+      where:
+        column: Gate
+        equals: "Contract docs"
+    assert:
+      text:
+        contains: ready
+
+  - id: status.ready.count
+    select:
+      target: tableCell
+      section: Gate Table
+      column: Status
+      rowWhere:
+        column: ID
+        equals: REL-GATE-1
+    assert:
+      textOccurrenceCount:
+        text: ready
+        count: 1
+
+  - id: release.link
+    select:
+      target: link
+      section: Links
+      text: "release notes"
+      url: "./release-notes.md"
+    assert:
+      exists: true

package/fixtures/declarative-validation/examples/requirements-traceability/fail.md

@@ -0,0 +1,27 @@
+---
+title: Requirements Traceability Example
+owner: quality-team
+status: ready
+---
+
+# Requirements
+
+| ID | Requirement statement | Source |
+| --- | --- | --- |
+| REQ-1 | The package shall parse one Markdown file. | CLI |
+| REQ-2 | The package shall validate a configured profile. | API |
+| REQ-3 | The package shall emit deterministic diagnostics. | Evidence |
+
+# Evidence Matrix
+
+| ID | Requirement | Note |
+| --- | --- | --- |
+| EVD-1 | REQ-1 | CLI parse fixture |
+| EVD-2 | REQ-2 | Profile validation fixture |
+| EVD-3 | REQ-3 | Diagnostic assertion fixture |
+
+# Traceability
+
+REQ-1 is covered by EVD-1.
+REQ-2 is covered by EVD-2.
+EVD-3 has evidence, but the final requirement reference is missing.

package/fixtures/declarative-validation/examples/requirements-traceability/pass.md

@@ -0,0 +1,27 @@
+---
+title: Requirements Traceability Example
+owner: quality-team
+status: ready
+---
+
+# Requirements
+
+| ID | Requirement statement | Source |
+| --- | --- | --- |
+| REQ-1 | The package shall parse one Markdown file. | CLI |
+| REQ-2 | The package shall validate a configured profile. | API |
+| REQ-3 | The package shall emit deterministic diagnostics. | Evidence |
+
+# Evidence Matrix
+
+| ID | Requirement | Evidence |
+| --- | --- | --- |
+| EVD-1 | REQ-1 | CLI parse fixture |
+| EVD-2 | REQ-2 | Profile validation fixture |
+| EVD-3 | REQ-3 | Diagnostic assertion fixture |
+
+# Traceability
+
+REQ-1 is covered by EVD-1.
+REQ-2 is covered by EVD-2.
+REQ-3 is covered by EVD-3.

package/fixtures/declarative-validation/examples/requirements-traceability/profile.yaml

@@ -0,0 +1,119 @@
+syntaxVersion: markdown-engine.validation@v1
+documentVersion: 1.0.0
+rules:
+  - id: frontmatter.required
+    select:
+      target: document
+    assert:
+      frontmatterRequired:
+        fields:
+          - title
+          - owner
+          - status
+
+  - id: sections.required
+    select:
+      target: document
+    assert:
+      sectionsRequired:
+        order: strict
+        headings:
+          - Requirements
+          - Evidence Matrix
+          - Traceability
+
+  - id: requirements.table.columns
+    select:
+      target: table
+      section: Requirements
+      header:
+        - ID
+        - Requirement statement
+        - Source
+    assert:
+      tableColumnsRequired:
+        columns:
+          - ID
+          - Requirement statement
+          - Source
+
+  - id: evidence.table.columns
+    select:
+      target: table
+      section: Evidence Matrix
+      header:
+        - ID
+        - Requirement
+    assert:
+      tableColumnsRequired:
+        columns:
+          - ID
+          - Requirement
+          - Evidence
+
+  - id: requirement.ids.unique
+    select:
+      target: tableCell
+      section: Requirements
+      column: ID
+    assert:
+      ids:
+        prefix: REQ
+        unique: true
+
+  - id: evidence.ids.unique
+    select:
+      target: tableCell
+      section: Evidence Matrix
+      column: ID
+    assert:
+      ids:
+        prefix: EVD
+        unique: true
+
+  - id: requirement.text
+    select:
+      target: tableCell
+      section: Requirements
+      column: Requirement statement
+      rowWhere:
+        column: ID
+        equals: REQ-2
+    assert:
+      text:
+        contains: shall
+        excludes:
+          - TBD
+
+  - id: requirements.shall.count
+    select:
+      target: section
+      title: Requirements
+    assert:
+      textOccurrenceCount:
+        text: shall
+        count: 3
+
+  - id: traceability.requirements
+    select:
+      target: document
+    assert:
+      references:
+        idsFrom:
+          section: Requirements
+          column: ID
+          prefix: REQ
+        mustAppearIn:
+          - Traceability
+
+  - id: traceability.evidence
+    select:
+      target: document
+    assert:
+      references:
+        idsFrom:
+          section: Evidence Matrix
+          column: ID
+          prefix: EVD
+        mustAppearIn:
+          - Traceability