@jasonbelmonti/markdown-engine 1.0.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonbelmonti/markdown-engine",
-  "version": "1.0.0",
+  "version": "3.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,10 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "dist-bundled",
+    "skills",
+    "docs/contracts",
+    "fixtures/declarative-validation/examples",
     "CHANGELOG.md",
     "SECURITY.md"
   ],
@@ -40,27 +44,42 @@
   "scripts": {
     "clean": "node scripts/clean-dist.mjs",
     "build": "npm run clean && tsc -p tsconfig.json",
+    "build:cli:bundled": "node scripts/build-bundled-cli.mjs",
+    "build:cli-bundle": "node scripts/build-cli-bundle.mjs",
     "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 && npm run build:cli:bundled && 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 tests/declarative-validation-table-column-coverage-fixtures.test.ts tests/declarative-validation-grouped-rules-fixtures.test.ts tests/declarative-validation-when-skipped-rules-fixtures.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"
@@ -68,6 +87,7 @@
   "devDependencies": {
     "@types/node": "^22.19.17",
     "cmark-gfm": "^0.9.0",
+    "esbuild": "^0.27.7",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
   },

package/skills/profile-backed-markdown/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: profile-backed-markdown
+description: Validate Markdown files that declare a local markdown-engine validation profile in frontmatter.
+---
+
+# Profile-Backed Markdown
+
+Use this skill when a Markdown file contains frontmatter with `validationProfile`
+and you need deterministic profile validation before editing or handing off the
+file.
+
+## Workflow
+
+1. Run the bundled wrapper:
+
+```bash
+node scripts/validate-profile-backed-markdown.mjs --file /path/to/file.md
+```
+
+2. Treat stdout as the validator JSON source of truth. Do not infer pass/fail
+   from prose or repair notes.
+3. If validation fails, rerun with `--repair-brief` to emit compact repair
+   guidance on stderr while preserving validator JSON on stdout.
+4. Edit the Markdown file only when the user asked for repair. Do not edit
+   validation profiles unless explicitly requested.
+5. Rerun the wrapper after edits and require exit code `0` before reporting the
+   document clean.
+
+## Frontmatter Contract
+
+The wrapper reads a top-level frontmatter scalar:
+
+```yaml
+validationProfile: operational-spec
+```
+
+Profile names resolve to `assets/profiles/<validationProfile>.yaml` by default.
+The wrapper rejects absolute paths and parent-directory traversal so validation
+profiles stay within the local skill assets.
+
+## Bundled CLI
+
+The wrapper does not require a globally installed `markdown-engine` binary. It
+uses `MARKDOWN_ENGINE_CLI` when set, then checks for a local
+`scripts/markdown-engine-cli.mjs`, then falls back to the package-level
+`dist-bundled/markdown-engine-cli.mjs`.
+
+For a standalone skill folder, build and copy the bundled CLI artifact before
+distribution:
+
+```bash
+npm run build:cli:bundled
+cp dist-bundled/markdown-engine-cli.mjs skills/profile-backed-markdown/scripts/
+```

package/skills/profile-backed-markdown/assets/profiles/operational-spec.yaml

@@ -0,0 +1,98 @@
+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.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: 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.link
+    select:
+      target: link
+      section: Handoff Links
+      text: "handoff packet"
+      url: "./handoff-packet.md"
+    assert:
+      exists: true

package/skills/profile-backed-markdown/references/repair-brief.md

@@ -0,0 +1,14 @@
+# Repair Brief Contract
+
+`--repair-brief` emits a compact diagnostic summary on stderr and preserves the
+validator JSON result on stdout.
+
+Each diagnostic entry is derived from validator JSON only:
+
+- `ruleId`: the failing profile rule when present, otherwise `(none)`.
+- `message`: the validator diagnostic message.
+- `sourceRange`: the validator diagnostic range when present, otherwise
+  `unavailable`.
+
+The wrapper must not invent validation outcomes, synthesize missing diagnostics,
+or edit local profile assets.