Skip to content
markdown-contract

Declarative YAML: Contracts and Corpus Config, No Code

Each example builds on the one before it — read the ladder in order, or jump to the rung you need. Every shipped artifact is regression-checked against the real CLI and library output.

  1. DECLARATIVE-YAML-01: Validate one required frontmatter field by type — A minimal contract document (mcVersion 1, kind contract) that requires a single typed frontmatter field.
  2. DECLARATIVE-YAML-02: Constrain with enum and const — Pinning a field to a fixed literal (const) or a closed set of allowed values (enum).
  3. DECLARATIVE-YAML-03: Bound and shape strings with min/max, pattern, format — Adding numeric bounds, a regex pattern, and a named string format to a typed field.
  4. DECLARATIVE-YAML-04: Make fields optional, defaulted, or nullable — The three field wrappers — optional, default, nullable — applied over a base schema.
  5. DECLARATIVE-YAML-05: Toggle strict vs open frontmatter — Whether unlisted frontmatter keys are rejected (strict) or passed through (open).
  6. DECLARATIVE-YAML-06: Declare array and nested object fields — Composite frontmatter — an array with an element schema (of) and a nested object with its own fields.
  7. DECLARATIVE-YAML-07: Declare required body sections — Moving to the body plane: a sections grammar listing the H2 headings a document must contain, with ordering and unknown-section policy.
  8. DECLARATIVE-YAML-08: Optional, alias, oneOf and gap section nodes — The remaining body-node vocabulary — optional sections, heading aliases, a oneOf choice, and a gap allowance.
  9. DECLARATIVE-YAML-09: Declare required block kinds inside a section — Content leaves — requiring a typed table, a checkbox list, fenced code, or a word cap within a section.
  10. DECLARATIVE-YAML-10: Map one glob to one contract (corpus config) — The config plane: a kind config document whose single rule routes a glob to a contract file.
  11. DECLARATIVE-YAML-11: Route several globs first-match-wins, with named contracts and exclude — A multi-rule config with a named contracts map, per-rule exclude, and first-match-wins precedence.
  12. DECLARATIVE-YAML-12: Run a YAML config from the CLI — Feeding a declarative config into the validate command, which auto-discovers markdown-contract.yaml or takes an explicit –config.
  13. DECLARATIVE-YAML-13: YAML contract and its TypeScript equivalent, identical findings — That a YAML-authored contract compiles to the same Contract as the combinator API, producing identical findings.
  14. DECLARATIVE-YAML-14: Require a phrase in a section (planned) — A section node carries requires: so its prose must contain a literal phrase (compiles to a node-local rule).
  15. DECLARATIVE-YAML-15: Forbid a phrase document-wide (planned) — forbids: on the body root asserts a phrase appears nowhere in the document (compiles to a docRule).
  16. DECLARATIVE-YAML-16: Match by regex instead of a literal (planned) — A regex: entry matches a pattern (here either of two markers) rather than a fixed substring.
  17. DECLARATIVE-YAML-17: Tune the match: normalize and ignoreCase (planned) — normalize folds whitespace (tolerating prose line-wrapping) and ignoreCase makes the match case-insensitive.
  18. DECLARATIVE-YAML-18: Bound occurrences with min / max (planned) — min and max constrain how many times a phrase may occur; max: 0 is the in-section forbids dual.
  19. DECLARATIVE-YAML-19: Annotate and downgrade: note + level (planned) — Each entry can carry an author note (appended to the message) and a level to warn instead of error.
  20. DECLARATIVE-YAML-20: Retire an invariants list across both scopes (planned) — Independent entries on the body root (whole-doc) and on a section node together replace an invariants.yaml linter.