@jasonbelmonti/markdown-engine 1.0.0 → 2.0.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonbelmonti/markdown-engine",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Deterministic Markdown parsing and validation engine package.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "bugs": {
     "url": "https://github.com/jasonbelmonti/markdown-engine/issues"
   },
-  "homepage": "https://github.com/jasonbelmonti/markdown-engine#readme",
+  "homepage": "https://jasonbelmonti.github.io/markdown-engine/",
   "keywords": [
     "markdown",
     "gfm",
@@ -31,6 +31,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "docs/contracts",
+    "fixtures/declarative-validation/examples",
     "CHANGELOG.md",
     "SECURITY.md"
   ],
@@ -42,25 +44,38 @@
     "build": "npm run clean && tsc -p tsconfig.json",
     "prepack": "npm run release:verify",
     "prepublishOnly": "npm run release:verify",
-    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run build && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
+    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run docs:rich-ir-contract && npm run docs:declarative-validation-contract && npm run audit:declarative-validation-boundary && npm run build && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
     "release:check-clean": "git diff --check HEAD -- && git diff --exit-code HEAD --",
     "snapshots:update:parser": "npm run build && vitest run tests/parser-fixtures.test.ts -u \"--exclude=.worktrees/**\"",
     "snapshots:update:rules": "npm run build && vitest run tests/rules.test.ts -u \"--exclude=.worktrees/**\"",
-    "snapshots:update:rich-ir": "npm run build && vitest run tests/rich-ir-targets.test.ts tests/rich-ir-queries.test.ts -u \"--exclude=.worktrees/**\"",
+    "snapshots:update:rich-ir": "npm run build && vitest run tests/rich-ir-targets.test.ts tests/rich-ir-queries.test.ts tests/rich-ir-link-references.test.ts -u \"--exclude=.worktrees/**\"",
     "snapshots:update:serialization": "npm run build && vitest run tests/serialization-repeatability.test.ts tests/boundary-inspection.test.ts -u \"--exclude=.worktrees/**\"",
     "test:rich-ir:proving": "npm run build && vitest run tests/rich-ir-proving.test.ts \"--exclude=.worktrees/**\"",
     "test:rich-ir:contract": "npm run build && tsc -p tsconfig.document-contract.json && vitest run tests/document-contract.test.ts \"--exclude=.worktrees/**\"",
     "test:rich-ir:targets": "npm run build && vitest run tests/rich-ir-targets.test.ts \"--exclude=.worktrees/**\"",
-    "test:rich-ir:queries": "npm run build && vitest run tests/rich-ir-queries.test.ts \"--exclude=.worktrees/**\"",
+    "test:rich-ir:queries": "npm run build && vitest run tests/rich-ir-queries.test.ts tests/rich-ir-link-references.test.ts \"--exclude=.worktrees/**\"",
     "test:rich-ir:annotations": "npm run build && vitest run tests/rich-ir-annotations.test.ts \"--exclude=.worktrees/**\"",
     "test:rich-ir:compat": "npm run build && vitest run tests/rich-ir-compat.test.ts \"--exclude=.worktrees/**\"",
     "test:rich-ir:repeatability": "npm run build && vitest run tests/rich-ir-repeatability.test.ts \"--exclude=.worktrees/**\"",
     "test:rich-ir:downstream": "npm run build && vitest run tests/rich-ir-downstream.test.ts \"--exclude=.worktrees/**\"",
     "audit:rich-ir-boundary": "node scripts/check-boundaries.mjs",
     "docs:rich-ir-contract": "node scripts/check-rich-ir-contract-docs.mjs",
+    "test:validation:proving": "npm run build && vitest run tests/declarative-validation-proving.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:contract": "npm run build && tsc -p tsconfig.declarative-validation-contract.json && vitest run tests/declarative-validation-contract.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:profile": "npm run build && vitest run tests/declarative-validation-profile.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:compiler": "npm run build && vitest run tests/declarative-validation-compiler.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:selectors": "npm run build && vitest run tests/declarative-validation-selectors.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:diagnostics": "npm run build && vitest run tests/declarative-validation-diagnostics.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:cli": "npm run build && vitest run tests/declarative-validation-cli.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:examples": "npm run build && vitest run tests/declarative-validation-examples.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:repeatability": "npm run build && vitest run tests/declarative-validation-repeatability.test.ts \"--exclude=.worktrees/**\" && node scripts/prove-declarative-validation-repeatability.mjs --runs 10",
+    "test:validation:downstream": "npm run build && vitest run tests/declarative-validation-downstream.test.ts \"--exclude=.worktrees/**\"",
+    "audit:declarative-validation-boundary": "node scripts/check-declarative-validation-boundary.mjs",
+    "docs:declarative-validation-contract": "node scripts/check-declarative-validation-contract-docs.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && vitest run \"--exclude=.worktrees/**\"",
-    "test:snapshots": "npm run build && vitest run tests/parser-fixtures.test.ts tests/rules.test.ts tests/rich-ir-targets.test.ts tests/rich-ir-queries.test.ts tests/serialization-repeatability.test.ts \"--exclude=.worktrees/**\""
+    "test:snapshots": "npm run build && vitest run tests/parser-fixtures.test.ts tests/rules.test.ts tests/rich-ir-targets.test.ts tests/rich-ir-queries.test.ts tests/rich-ir-link-references.test.ts tests/serialization-repeatability.test.ts \"--exclude=.worktrees/**\""
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/dist/ir/document-node-walk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"document-node-walk.d.ts","sourceRoot":"","sources":["../../src/ir/document-node-walk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,SAAS,CAAC,EAAE,GAC3C,CAAC,EAAE,CAKL;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE,CAEvE;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMjD"}

package/dist/ir/document-node-walk.js

@@ -1,16 +0,0 @@
-export function flatMapNodes(nodes, callback) {
-    return nodes.flatMap((node) => [
-        ...callback(node),
-        ...flatMapNodes(node.children ?? [], callback),
-    ]);
-}
-export function flattenNodes(nodes) {
-    return flatMapNodes(nodes, (node) => [node]);
-}
-export function nodeText(node) {
-    if (node.text !== undefined) {
-        return node.text;
-    }
-    return (node.children ?? []).map((child) => nodeText(child)).join("");
-}
-//# sourceMappingURL=document-node-walk.js.map

package/dist/ir/document-node-walk.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"document-node-walk.js","sourceRoot":"","sources":["../../src/ir/document-node-walk.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,YAAY,CAC1B,KAA4B,EAC5B,QAA4C;IAE5C,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7B,GAAG,QAAQ,CAAC,IAAI,CAAC;QACjB,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,QAAQ,CAAC;KAC/C,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAA4B;IACvD,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAgB;IACvC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC"}