Skip to content
markdown-contract

Authoring Contracts in Code: Structure, Content, and Custom Rules

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. VALIDATION-PLANES-01: Parse markdown into a DocTree — parse(md) returns the raw DocTree of frontmatter, sections, and positions before any contract exists.
  2. VALIDATION-PLANES-02: The smallest contract: one required section — contract({body: sections([section(…)])}).validate(src) emits a single structure-plane Finding for a missing section.
  3. VALIDATION-PLANES-03: Constrain section order — sections({order:‘strict’}) makes out-of-order headings a positioned structure/section-order finding.
  4. VALIDATION-PLANES-04: Make a section optional — optional(section(…)) lets a slot be absent without a finding while the rest of the order still holds.
  5. VALIDATION-PLANES-05: Allow interchangeable headings with oneOf — oneOf([…]) accepts any one of several spellings at a single position as one logical slot.
  6. VALIDATION-PLANES-06: Admit unknown sections with a bounded gap — gap({max}) permits a counted window of unrecognized sections between required ones, flagging overflow as structure/gap-count.
  7. VALIDATION-PLANES-07: Require a block kind: a table — section(…, {content: table({columns})}) makes the structure plane require a table block of that shape inside the section.
  8. VALIDATION-PLANES-08: Require a list of checkboxes — list({everyItem:‘checkbox’, minItems}) requires a list block and constrains each item, reporting offenders at their own line.
  9. VALIDATION-PLANES-09: Require a fenced code block in a language — code({lang}) requires a fenced block and pins its language, separating the structural kind-gate from the content check.
  10. VALIDATION-PLANES-10: Cross into content: a one-field frontmatter schema — contract({frontmatter: z.object({…})}) runs Zod over the parsed frontmatter, line-mapping each issue to its key.
  11. VALIDATION-PLANES-11: Frontmatter enum, format, and bounds — Zod enum/date/min refinements over frontmatter surface as positioned frontmatter-plane findings.
  12. VALIDATION-PLANES-12: Typed table columns with a per-row constraint — table({columns, cells, minRows}) types each named column with Zod and flags a bad cell at that row’s source line.
  13. VALIDATION-PLANES-13: Bound a paragraph’s word count — maxWords(n) constrains a section’s prose, emitting content/max-words at the paragraph’s line when exceeded.
  14. VALIDATION-PLANES-14: A custom node rule with its own level — rule(id, fn) attached via SectionOpts.rules runs on its bound section node and mints a finding at a level it chooses.
  15. VALIDATION-PLANES-15: A cross-cutting docRule over the whole doc — docRule(id, fn) sees the typed Doc (frontmatter and body together) to enforce relationships no single plane can.
  16. VALIDATION-PLANES-16: All three planes in one deterministic order — One validate() merges frontmatter, structure, content, and rule findings and sorts them by line, then col, then plane.
  17. VALIDATION-PLANES-17: The same checks in code (TS-API parity) (planned) — Library predicate builders give a combinator-authored contract the same text checks the YAML compiles to.