@jasonbelmonti/markdown-engine 3.4.0 → 3.6.0

package/docs/contracts/declarative-validation.md

@@ -323,7 +323,9 @@ interface DeclarativeAssertion {
     mustAppearIn: readonly string[];
   };
   tableColumnCoverage?: {
+    allowEmptySource?: boolean;
     source: {
+      rowWhere?: { column: string; equals?: string; includes?: string };
       section: string;
       column: string;
       prefix?: string;
@@ -343,9 +345,13 @@ interface DeclarativeAssertion {
       required?: true;
       valueType?: "string" | "number" | "boolean" | "array" | "object" | "null";
       nonEmpty?: true;
+      equals?: string;
+      nonBlank?: true;
+      forbidden?: true;
     }[];
   };
   text?: {
+    nonBlank?: true; // v2 only
     contains?: string;
     excludes?: readonly string[];
   };
@@ -458,18 +464,39 @@ target section do not satisfy coverage. Missing target sections, missing target
 columns, and missing target-column IDs emit deterministic validation diagnostics
 source-grounded to the source ID when source evidence is available.
 
+The opt-in `source.rowWhere` filter uses the same closed sibling-cell predicate
+as the `tableCell` selector: a non-empty `column` plus `equals`, `includes`, or
+both. Both predicates must match when both are present. Matching uses normalized,
+case-sensitive cell text before ID extraction; `source.caseSensitive` affects ID
+comparison only. Rows marked optional can therefore be excluded without encoding
+consumer vocabulary in the engine. A missing predicate column is unresolved,
+not a resolved empty source.
+
+`allowEmptySource` is an optional boolean. Absent or `false` preserves the existing
+`profile.validation.emptySelection` failure when no source IDs are extracted.
+`true` permits zero extracted IDs only when the source section and column resolve
+(including the predicate column when configured). With no source IDs there are no
+target obligations; target resolution is not evaluated. A missing source structure
+still fails. Pair this policy with consumer shape rules when tables or rows are
+mandatory. This option also permits prose sentinels in reverse declared-ID checks.
+
 For v2 profiles, `frontmatterShape` is admitted as a flat-rule schema and
 internal compiled-plan assertion. It is compatible only with a `document`
 selector because frontmatter is document metadata. `presence` is optional and
 must be exactly `"required"` or `"forbidden"` when provided. `fields` is an
 optional non-empty array of field constraints. Each field constraint has a
 required non-empty `field` name and must include at least one effective
-constraint: `required: true`, `valueType`, or `nonEmpty: true`. Field names
-within one `frontmatterShape.fields` array must be unique. `valueType` must be
+constraint: `required: true`, `valueType`, `nonEmpty: true`, `equals`,
+`nonBlank: true`, or `forbidden: true`. Field names within one
+`frontmatterShape.fields` array must be unique. `valueType` must be
 one of `"string"`, `"number"`, `"boolean"`, `"array"`, `"object"`, or `"null"`.
-`nonEmpty: true` is a string predicate; when it is combined with `valueType`,
-`valueType` must be `"string"`. `presence: "forbidden"` cannot be combined with
-`fields`.
+`nonEmpty: true`, `equals`, and `nonBlank: true` are string predicates; when
+any is combined with `valueType`, `valueType` must be `"string"`. `equals`
+accepts any string, including the empty string, and compares it exactly.
+`nonBlank: true` requires a string whose JavaScript `trim()` result is non-empty.
+`forbidden: true` requires the named field to be absent and cannot be combined
+with `required`, `valueType`, `nonEmpty`, `equals`, or `nonBlank`.
+`presence: "forbidden"` cannot be combined with `fields`.
 
 Runtime evaluation treats frontmatter as present when
 `document.frontmatter !== undefined`. `presence: "required"` fails absent
@@ -486,8 +513,29 @@ requires a present field value to be a non-empty string and emits
 `profile.validation.frontmatterFieldEmpty` when that predicate fails. When
 `valueType: "string"` and `nonEmpty: true` are combined, a non-string value
 emits the type-mismatch diagnostic without a duplicate empty-string diagnostic.
-
-`text` must include `contains` or a non-empty `excludes` array.
+`equals` compares present strings exactly without coercion and emits
+`profile.validation.frontmatterFieldValueMismatch` on mismatch. `nonBlank: true`
+uses JavaScript `trim()` without coercion and emits
+`profile.validation.frontmatterFieldBlank` when its field is not a non-blank
+string. `forbidden: true` emits `profile.validation.frontmatterFieldForbidden`
+when the named field is present, regardless of value. When `valueType: "string"`
+is combined with `equals` or `nonBlank`, a non-string value emits only
+`profile.validation.frontmatterFieldTypeMismatch` rather than an additional
+string-predicate diagnostic. Diagnostic messages do not include frontmatter
+values.
+
+`text` must include `contains`, a non-empty `excludes` array, or (v2 only)
+`nonBlank: true`. `nonBlank` cannot be `false`. It requires at least one character
+after JavaScript `trim()` on normalized node text excluding raw `html`, `definition`,
+and `yaml` nodes. Comments, empty HTML tags, and decoded whitespace entities cannot
+satisfy it. Markdown emphasis, link labels, literal code, and escaped angle brackets
+retain their text. Each selected target is checked independently; an empty selector
+still fails. Section selection includes its heading and direct body, as with ordinary
+section text. Original source ranges are optional; the normalized nodes provide the
+content. This is a structural textual-content check, not CSS visibility evaluation
+or browser rendering. It does not evaluate external evidence, freshness, truth,
+or implementation acceptance. Existing `contains`, `excludes`, and `textLength`
+semantics are unchanged, even when combined with `nonBlank`.
 `textOccurrenceCount.count` is a finite number and counts non-overlapping
 literal occurrences per selected target.
 `textLength` must include `min`, `max`, or both. Bounds are non-negative
@@ -558,9 +606,12 @@ an unproven pass.
 | `profile.validation.assertionFailed` | Rule severity | A supported assertion evaluates and fails without a more specific diagnostic code, including selector-count bound failures, missing table columns, exact table-header mismatches, exact occurrence-count mismatches, text-length bound failures, and text-format `isoDate` failures. |
 | `profile.validation.duplicateId` | Rule severity | An `ids.unique` assertion finds repeated IDs. |
 | `profile.validation.frontmatterForbidden` | Rule severity | A `frontmatterShape` assertion with `presence: "forbidden"` finds present frontmatter. |
+| `profile.validation.frontmatterFieldBlank` | Rule severity | A frontmatter field configured with `nonBlank: true` is not a non-blank string. |
 | `profile.validation.frontmatterFieldEmpty` | Rule severity | A frontmatter field configured with `nonEmpty: true` is not a non-empty string. |
+| `profile.validation.frontmatterFieldForbidden` | Rule severity | A frontmatter field configured with `forbidden: true` is present. |
 | `profile.validation.frontmatterFieldMissing` | Rule severity | A required frontmatter field is absent. |
 | `profile.validation.frontmatterFieldTypeMismatch` | Rule severity | A frontmatter field value does not match the configured `frontmatterShape.fields[].valueType` without coercion. |
+| `profile.validation.frontmatterFieldValueMismatch` | Rule severity | A frontmatter field configured with `equals` does not exactly match the configured string without coercion. |
 | `profile.validation.frontmatterMissing` | Rule severity | A `frontmatterShape` assertion with `presence: "required"` finds absent frontmatter. |
 | `profile.validation.idCountTooHigh` | Rule severity | Unique ID count after filtering is higher than `ids.maxCount`. |
 | `profile.validation.idCountTooLow` | Rule severity | Unique ID count after filtering is lower than `ids.minCount`. |
@@ -571,6 +622,7 @@ an unproven pass.
 | `profile.validation.tableColumnCoverageIdMissing` | Rule severity | A source ID is absent from the configured target table column. |
 | `profile.validation.tableColumnCoverageTargetColumnMissing` | Rule severity | The configured target table column cannot be resolved. |
 | `profile.validation.tableColumnCoverageTargetSectionMissing` | Rule severity | The configured target section cannot be resolved. |
+| `profile.validation.textBlank` | Rule severity | A target configured with `text.nonBlank` lacks non-whitespace text outside raw HTML. |
 | `profile.validation.textExcluded` | Rule severity | A selected target contains forbidden literal text. |
 | `profile.validation.textMissing` | Rule severity | A selected target lacks required literal text from a `text.contains` assertion. |
 | `profile.validation.assertionUnsupported` | `error` | A compiled assertion or compiled assertion feature has no evaluator implementation; this is an internal safety diagnostic. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonbelmonti/markdown-engine",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Deterministic Markdown parsing and validation engine package.",
   "license": "MIT",
   "type": "module",
@@ -71,7 +71,7 @@
     "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-frontmatter-shape-assertions.test.ts tests/declarative-validation-table-column-coverage-fixtures.test.ts tests/declarative-validation-table-columns-exact.test.ts tests/declarative-validation-source-assertion-coverage.test.ts tests/declarative-validation-source-length.test.ts tests/declarative-validation-selection-count.test.ts tests/declarative-validation-normalized-source-ranges.test.ts tests/declarative-validation-grouped-rules-fixtures.test.ts tests/declarative-validation-when-skipped-rules-fixtures.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts tests/declarative-validation-filtered-coverage.test.ts tests/declarative-validation-visible-text.test.ts tests/declarative-validation-frontmatter-shape-assertions.test.ts tests/declarative-validation-table-column-coverage-fixtures.test.ts tests/declarative-validation-table-columns-exact.test.ts tests/declarative-validation-source-assertion-coverage.test.ts tests/declarative-validation-source-length.test.ts tests/declarative-validation-selection-count.test.ts tests/declarative-validation-normalized-source-ranges.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/**\"",

package/scripts/install-markdown-engine-cli.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env sh
 set -eu
 
-VERSION="3.4.0"
+VERSION="3.6.0"
 PACKAGE="@jasonbelmonti/markdown-engine"
-EXPECTED_SHA256="41225925904c038c05392b19e7203bd723d1cbaaa47b48d96648fb0275d3d05b"
+EXPECTED_SHA256="69b855d4d3623d7cdb91a3ed09631715dde8b96fc57f49864ae2c7c7c071ad83"
 DEFAULT_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
 MARKDOWN_ENGINE_HOME="${MARKDOWN_ENGINE_HOME:-$DEFAULT_DATA_HOME/markdown-engine}"
 MARKDOWN_ENGINE_BIN_DIR="${MARKDOWN_ENGINE_BIN_DIR:-$HOME/.local/bin}"