@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/watch.js

@@ -0,0 +1,79 @@
+import { watch } from "fs";
+import { relative } from "path";
+const DEFAULT_OPTIONS = {
+    debounceMs: 300,
+    extensions: [".ts"],
+    ignoreDirs: ["node_modules", ".chant"],
+};
+/**
+ * Check if a file path should be watched
+ */
+export function shouldWatch(filePath, options) {
+    // Ignore dotdirs
+    const parts = filePath.split("/");
+    for (const part of parts) {
+        if (part.startsWith(".") && part.length > 1)
+            return false;
+        if (options.ignoreDirs.includes(part))
+            return false;
+    }
+    // Ignore test/spec files
+    if (filePath.endsWith(".test.ts") || filePath.endsWith(".spec.ts"))
+        return false;
+    // Check extension
+    return options.extensions.some((ext) => filePath.endsWith(ext));
+}
+/**
+ * Format a timestamp as HH:MM:SS
+ */
+export function formatTimestamp(date = new Date()) {
+    const h = String(date.getHours()).padStart(2, "0");
+    const m = String(date.getMinutes()).padStart(2, "0");
+    const s = String(date.getSeconds()).padStart(2, "0");
+    return `${h}:${m}:${s}`;
+}
+/**
+ * Format changed files for display (relative paths, truncated if many)
+ */
+export function formatChangedFiles(files, basePath, maxShow = 3) {
+    const relative_paths = files.map((f) => relative(basePath, f));
+    if (relative_paths.length <= maxShow) {
+        return relative_paths.join(", ");
+    }
+    const shown = relative_paths.slice(0, maxShow);
+    return `${shown.join(", ")} (+${relative_paths.length - maxShow} more)`;
+}
+/**
+ * Watch a directory for file changes with debouncing.
+ * Returns a cleanup function to stop watching.
+ */
+export function watchDirectory(path, callback, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    let pendingFiles = new Set();
+    let timer = null;
+    const watcher = watch(path, { recursive: true }, (_event, filename) => {
+        if (!filename)
+            return;
+        if (!shouldWatch(filename, opts))
+            return;
+        // Collect the full path
+        const fullPath = `${path}/${filename}`;
+        pendingFiles.add(fullPath);
+        // Reset the debounce timer
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            const files = [...pendingFiles];
+            pendingFiles = new Set();
+            timer = null;
+            if (files.length > 0) {
+                callback(files);
+            }
+        }, opts.debounceMs);
+    });
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        watcher.close();
+    };
+}

package/dist/codegen/bound-property-types.js

@@ -0,0 +1,82 @@
+/**
+ * Bound the set of generated property-type interfaces a lexicon emits.
+ *
+ * Cloud provider schemas (ARM, CloudFormation, …) embed a named definition for
+ * every nested object. Fully expanding all of them per-resource produces huge
+ * `.d.ts` declarations (azure was ~273MB — see #438). This helper keeps only
+ * the property types reachable from a resource's top-level properties within a
+ * depth bound, plus a curated force-keep set; references that fall outside the
+ * kept set are rewritten to `Record<string, unknown>`. Enum references are
+ * preserved. The input property refs are mutated in place. (#438, #440)
+ */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Extract `${shortName}_Ident` type-reference tokens from a tsType string. */
+function referencedTypeNames(tsType, shortName) {
+    const re = new RegExp("\\b" + escapeRegExp(shortName) + "_[A-Za-z0-9_]+", "g");
+    return tsType.match(re) ?? [];
+}
+/**
+ * Filter `propertyTypes` to the bounded set and loosen out-of-set references.
+ * Mutates the `tsType` of `resourceProps` and retained property types; returns
+ * the retained property types.
+ */
+export function boundPropertyTypes(shortName, resourceProps, propertyTypes, enumNames, options) {
+    const { maxDepth } = options;
+    const curated = options.curatedDefs ? [...options.curatedDefs] : [];
+    const byName = new Map(propertyTypes.map((pt) => [pt.name, pt]));
+    const reached = new Set();
+    const queue = [];
+    const seed = (tsType, depth) => {
+        for (const n of referencedTypeNames(tsType, shortName)) {
+            if (byName.has(n) && !reached.has(n)) {
+                reached.add(n);
+                queue.push({ name: n, depth });
+            }
+        }
+    };
+    for (const p of resourceProps)
+        seed(p.tsType, 1);
+    // Force-keep curated property types (depth-1 seeds), matched by substring so
+    // schema variant names (e.g. "SecurityRulePropertiesFormat") are retained.
+    if (curated.length > 0) {
+        for (const pt of propertyTypes) {
+            if (!reached.has(pt.name) && curated.some((c) => pt.specType.includes(c))) {
+                reached.add(pt.name);
+                queue.push({ name: pt.name, depth: 1 });
+            }
+        }
+    }
+    while (queue.length) {
+        const { name, depth } = queue.shift();
+        if (depth >= maxDepth)
+            continue; // do not expand children beyond the cap
+        const pt = byName.get(name);
+        if (!pt)
+            continue;
+        for (const p of pt.properties)
+            seed(p.tsType, depth + 1);
+    }
+    // Rewrite references to property types we are not emitting (keep enums).
+    const loosen = (tsType) => {
+        let out = tsType;
+        for (const n of referencedTypeNames(tsType, shortName)) {
+            if (reached.has(n) || enumNames.has(n) || !byName.has(n))
+                continue;
+            out = out.replace(new RegExp("\\b" + escapeRegExp(n) + "\\b", "g"), "Record<string, unknown>");
+        }
+        return out;
+    };
+    for (const p of resourceProps)
+        p.tsType = loosen(p.tsType);
+    const retained = [];
+    for (const pt of propertyTypes) {
+        if (!reached.has(pt.name))
+            continue;
+        for (const p of pt.properties)
+            p.tsType = loosen(p.tsType);
+        retained.push(pt);
+    }
+    return retained;
+}

package/dist/codegen/coverage.js

@@ -0,0 +1,119 @@
+/**
+ * Coverage analysis for lexicon artifacts.
+ *
+ * Analyzes a generated lexicon JSON to measure coverage across dimensions:
+ * property constraints, lifecycle attributes, return attributes, and extension constraints.
+ */
+/**
+ * Compute coverage from lexicon JSON content.
+ */
+export function computeCoverage(lexiconJSON) {
+    const entries = JSON.parse(lexiconJSON);
+    // Deduplicate: multiple TS names may map to the same resource type
+    const seen = new Set();
+    const resources = [];
+    for (const [name, entry] of Object.entries(entries)) {
+        if (entry.kind !== "resource")
+            continue;
+        if (seen.has(entry.resourceType))
+            continue;
+        seen.add(entry.resourceType);
+        resources.push({
+            name,
+            resourceType: entry.resourceType,
+            hasPropertyConstraints: !!(entry.propertyConstraints && Object.keys(entry.propertyConstraints).length > 0),
+            hasLifecycle: !!(entry.createOnly?.length || entry.writeOnly?.length),
+            hasAttrs: !!(entry.attrs && Object.keys(entry.attrs).length > 0),
+            hasConstraints: !!(entry.constraints && entry.constraints.length > 0),
+        });
+    }
+    const count = resources.length;
+    if (count === 0) {
+        return {
+            resourceCount: 0,
+            propertyPct: 0,
+            lifecyclePct: 0,
+            attrPct: 0,
+            constraintPct: 0,
+            resources: [],
+        };
+    }
+    const propertyCount = resources.filter((r) => r.hasPropertyConstraints).length;
+    const lifecycleCount = resources.filter((r) => r.hasLifecycle).length;
+    const attrCount = resources.filter((r) => r.hasAttrs).length;
+    const constraintCount = resources.filter((r) => r.hasConstraints).length;
+    return {
+        resourceCount: count,
+        propertyPct: Math.round((propertyCount / count) * 100),
+        lifecyclePct: Math.round((lifecycleCount / count) * 100),
+        attrPct: Math.round((attrCount / count) * 100),
+        constraintPct: Math.round((constraintCount / count) * 100),
+        resources,
+    };
+}
+/**
+ * Overall coverage percentage (average of all dimensions).
+ */
+export function overallPct(report) {
+    return Math.round((report.propertyPct + report.lifecyclePct + report.attrPct + report.constraintPct) / 4);
+}
+/**
+ * Format a human-readable coverage summary.
+ */
+export function formatSummary(report) {
+    const lines = [];
+    lines.push(`Coverage Report: ${report.resourceCount} resources`);
+    lines.push(`  Property constraints: ${report.propertyPct}%`);
+    lines.push(`  Lifecycle (createOnly/writeOnly): ${report.lifecyclePct}%`);
+    lines.push(`  Return attributes: ${report.attrPct}%`);
+    lines.push(`  Extension constraints: ${report.constraintPct}%`);
+    lines.push(`  Overall: ${overallPct(report)}%`);
+    return lines.join("\n");
+}
+/**
+ * Check coverage report against thresholds.
+ */
+export function checkThresholds(report, thresholds) {
+    const violations = [];
+    if (thresholds.minPropertyPct !== undefined && report.propertyPct < thresholds.minPropertyPct) {
+        violations.push(`Property constraints: ${report.propertyPct}% < ${thresholds.minPropertyPct}% minimum`);
+    }
+    if (thresholds.minLifecyclePct !== undefined && report.lifecyclePct < thresholds.minLifecyclePct) {
+        violations.push(`Lifecycle: ${report.lifecyclePct}% < ${thresholds.minLifecyclePct}% minimum`);
+    }
+    if (thresholds.minAttrPct !== undefined && report.attrPct < thresholds.minAttrPct) {
+        violations.push(`Return attributes: ${report.attrPct}% < ${thresholds.minAttrPct}% minimum`);
+    }
+    if (thresholds.minConstraintPct !== undefined && report.constraintPct < thresholds.minConstraintPct) {
+        violations.push(`Extension constraints: ${report.constraintPct}% < ${thresholds.minConstraintPct}% minimum`);
+    }
+    if (thresholds.minOverallPct !== undefined && overallPct(report) < thresholds.minOverallPct) {
+        violations.push(`Overall: ${overallPct(report)}% < ${thresholds.minOverallPct}% minimum`);
+    }
+    return { ok: violations.length === 0, violations };
+}
+/**
+ * Format verbose per-resource coverage details.
+ */
+export function formatVerbose(report) {
+    const lines = [formatSummary(report), ""];
+    const sorted = [...report.resources].sort((a, b) => a.name.localeCompare(b.name));
+    for (const r of sorted) {
+        const missing = [];
+        if (!r.hasPropertyConstraints)
+            missing.push("property-constraints");
+        if (!r.hasLifecycle)
+            missing.push("lifecycle");
+        if (!r.hasAttrs)
+            missing.push("attrs");
+        if (!r.hasConstraints)
+            missing.push("constraints");
+        if (missing.length === 0) {
+            lines.push(`  ${r.name} (${r.resourceType}): full coverage`);
+        }
+        else {
+            lines.push(`  ${r.name} (${r.resourceType}): missing ${missing.join(", ")}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/codegen/docs-file-markers.js

@@ -0,0 +1,60 @@
+/**
+ * File marker interpolation and MDX escaping utilities.
+ */
+import { readFileSync } from "fs";
+import { join } from "path";
+/** Escape curly braces so MDX doesn't treat them as JSX expressions. */
+export function escapeMdx(text) {
+    return text.replace(/\{/g, "\\{").replace(/\}/g, "\\}");
+}
+/**
+ * Expand `{{file:path.ts}}` markers in content with fenced code blocks.
+ *
+ * Supported forms:
+ * - `{{file:path.ts}}` — full file
+ * - `{{file:path.ts:5-12}}` — lines 5–12 (1-based, inclusive)
+ * - `{{file:path.ts|title=custom.ts}}` — override the code block title
+ * - `{{file:path.ts:5-12|title=custom.ts}}` — both
+ */
+export function expandFileMarkers(content, examplesDir) {
+    return content.replace(/\{\{file:([^}]+)\}\}/g, (_match, spec) => {
+        // Parse options after |
+        let filePart = spec;
+        let title;
+        const pipeIdx = spec.indexOf("|");
+        if (pipeIdx !== -1) {
+            filePart = spec.substring(0, pipeIdx);
+            const opts = spec.substring(pipeIdx + 1);
+            const titleMatch = opts.match(/title=([^\s|]+)/);
+            if (titleMatch)
+                title = titleMatch[1];
+        }
+        // Parse line range after :digits-digits at end of filePart
+        let lineStart;
+        let lineEnd;
+        const rangeMatch = filePart.match(/^(.+):(\d+)-(\d+)$/);
+        if (rangeMatch) {
+            filePart = rangeMatch[1];
+            lineStart = parseInt(rangeMatch[2], 10);
+            lineEnd = parseInt(rangeMatch[3], 10);
+        }
+        const filePath = join(examplesDir, filePart);
+        let fileContent;
+        try {
+            fileContent = readFileSync(filePath, "utf-8");
+        }
+        catch {
+            throw new Error(`File marker {{file:${spec}}} — file not found: ${filePath}`);
+        }
+        // Extract line range if specified
+        if (lineStart !== undefined && lineEnd !== undefined) {
+            const lines = fileContent.split("\n");
+            fileContent = lines.slice(lineStart - 1, lineEnd).join("\n");
+        }
+        // Determine language from extension
+        const ext = filePart.substring(filePart.lastIndexOf(".") + 1);
+        const lang = ext === "ts" || ext === "tsx" ? "typescript" : ext;
+        const displayTitle = title ?? filePart.substring(filePart.lastIndexOf("/") + 1);
+        return `\`\`\`${lang} title="${displayTitle}"\n${fileContent.trimEnd()}\n\`\`\``;
+    });
+}

package/dist/codegen/docs-pages.js

@@ -0,0 +1,115 @@
+/**
+ * Authored lexicon doc pages (chant #1731 / #1733).
+ *
+ * A lexicon's prose lives as `.mdx` files under `lexicons/<name>/docs/pages/`.
+ * Each carries a `diataxis` frontmatter field naming its Diátaxis quadrant
+ * (https://diataxis.fr). The pipeline expands `{{file:...}}` markers, stamps a
+ * provenance marker and writes the result into `src/content/docs/`, and the
+ * sidebar is grouped from the field. This replaced two older modes — prose
+ * inside `docs.ts` template literals (`extraPages`) and hand-written content
+ * pages wired through `sidebarExtra` — removed in chant #1757.
+ *
+ * Frontmatter recognised here, on top of Starlight's `title` / `description`:
+ *
+ * - `diataxis`: `tutorial | how-to | reference | explanation`. Required.
+ * - `label`: sidebar label; defaults to `title`.
+ * - `group`: a nested subgroup label inside the quadrant (e.g. "Vendor Composites").
+ * - `order`: number; lower sorts first within its group. Unordered pages follow, by label.
+ * - `hidden`: `true` keeps the page out of the sidebar (reachable by URL only).
+ *
+ * `group` / `order` / `hidden` / `label` are stripped from the written copy so
+ * Starlight's schema never sees them; `diataxis` stays, and the generated
+ * `content.config.ts` declares it.
+ */
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { expandFileMarkers } from "./docs-file-markers.js";
+export const QUADRANTS = ["tutorial", "how-to", "reference", "explanation"];
+/** Sidebar group label for each quadrant, in display order. */
+export const QUADRANT_LABELS = {
+    tutorial: "Tutorials",
+    "how-to": "How-to guides",
+    reference: "Reference",
+    explanation: "Explanation",
+};
+function parseFrontmatter(text, file) {
+    if (!text.startsWith("---\n")) {
+        throw new Error(`${file}: authored doc page must start with a frontmatter block`);
+    }
+    const end = text.indexOf("\n---", 4);
+    if (end === -1)
+        throw new Error(`${file}: unterminated frontmatter`);
+    const lines = text.slice(4, end).split("\n");
+    const fields = new Map();
+    for (const line of lines) {
+        const m = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+        if (m)
+            fields.set(m[1], m[2].trim());
+    }
+    // Skip the closing `---` and the newline after it.
+    const afterClose = text.indexOf("\n", end + 1);
+    const body = afterClose === -1 ? "" : text.slice(afterClose + 1);
+    return { fields, lines, body };
+}
+function unquote(v) {
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        try {
+            return v.startsWith('"') ? JSON.parse(v) : v.slice(1, -1);
+        }
+        catch {
+            return v.slice(1, -1);
+        }
+    }
+    return v;
+}
+/** Keys this module consumes and removes from the written page. */
+const SIDEBAR_KEYS = new Set(["label", "group", "order", "hidden"]);
+/**
+ * Read every authored page under `pagesDir`. Returns an empty list when the
+ * directory does not exist, which is every lexicon before it migrates.
+ */
+export function readAuthoredPages(config) {
+    const pagesDir = config.pagesDir ?? join(config.outDir, "pages");
+    if (!existsSync(pagesDir))
+        return [];
+    const pages = [];
+    for (const file of readdirSync(pagesDir).sort()) {
+        if (!file.endsWith(".mdx") && !file.endsWith(".md"))
+            continue;
+        const path = join(pagesDir, file);
+        const { fields, lines, body } = parseFrontmatter(readFileSync(path, "utf-8"), path);
+        const title = fields.get("title");
+        if (!title)
+            throw new Error(`${path}: frontmatter needs a title`);
+        const quadrant = fields.get("diataxis");
+        if (!quadrant) {
+            throw new Error(`${path}: frontmatter needs \`diataxis: ${QUADRANTS.join(" | ")}\` (https://diataxis.fr)`);
+        }
+        if (!QUADRANTS.includes(quadrant)) {
+            throw new Error(`${path}: diataxis "${quadrant}" is not one of ${QUADRANTS.join(", ")}`);
+        }
+        const orderRaw = fields.get("order");
+        const order = orderRaw === undefined ? undefined : Number(orderRaw);
+        if (order !== undefined && Number.isNaN(order)) {
+            throw new Error(`${path}: order must be a number, got "${orderRaw}"`);
+        }
+        const kept = lines.filter((line) => {
+            const key = line.match(/^([A-Za-z_][\w-]*):/)?.[1];
+            return !(key && SIDEBAR_KEYS.has(key));
+        });
+        let content = body;
+        if (config.examplesDir)
+            content = expandFileMarkers(content, config.examplesDir);
+        pages.push({
+            file,
+            slug: file.replace(/\.mdx?$/, ""),
+            label: unquote(fields.get("label") ?? title),
+            quadrant: quadrant,
+            group: fields.has("group") ? unquote(fields.get("group")) : undefined,
+            order,
+            hidden: fields.get("hidden") === "true",
+            content: ["---", ...kept, "---", "", content].join("\n"),
+        });
+    }
+    return pages;
+}

package/dist/codegen/docs-rule-scanning.js

@@ -0,0 +1,164 @@
+/**
+ * Rule scanning and rule page generation for lexicon documentation.
+ *
+ * Scans lint rule and post-synth check source files to extract metadata,
+ * and generates an MDX page listing them.
+ */
+import { readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { escapeMdx } from "./docs-file-markers.js";
+/**
+ * Scan lint rule and post-synth check source files to extract metadata.
+ * Uses regex to find id, severity, category, and description from source.
+ */
+export function scanRules(srcDir) {
+    return scanRulesWithSources(srcDir).map((r) => r.meta);
+}
+/**
+ * Like {@link scanRules}, but keeps each rule's source text alongside its
+ * metadata — the OKF bundle builder (#1060) reads the source to associate a
+ * rule with the resource types it mentions.
+ */
+export function scanRulesWithSources(srcDir) {
+    const rules = [];
+    // Scan lint rules
+    scanDir(join(srcDir, "lint", "rules"), "lint", rules);
+    // Scan post-synth checks
+    scanDir(join(srcDir, "lint", "post-synth"), "post-synth", rules);
+    return rules;
+}
+function scanDir(dir, type, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".ts"))
+            continue;
+        if (entry.endsWith(".test.ts"))
+            continue;
+        if (entry === "index.ts")
+            continue;
+        // Skip utility files (no rule definitions)
+        if (entry === "cf-refs.ts")
+            continue;
+        let content;
+        try {
+            content = readFileSync(join(dir, entry), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (type === "lint") {
+            // Extract from LintRule objects: id, severity, category
+            const idMatch = content.match(/id:\s*"([^"]+)"/);
+            const severityMatch = content.match(/severity:\s*"([^"]+)"/);
+            const categoryMatch = content.match(/category:\s*"([^"]+)"/);
+            if (idMatch) {
+                // Try to get description from JSDoc comment
+                const descMatch = content.match(new RegExp(`\\*\\s*${idMatch[1]}:\\s*(.+?)\\n`));
+                out.push({
+                    meta: {
+                        id: idMatch[1],
+                        severity: severityMatch?.[1] ?? "warning",
+                        category: categoryMatch?.[1] ?? "general",
+                        description: descMatch?.[1]?.trim() ??
+                            extractDescriptionFromComment(content, idMatch[1]),
+                        type: "lint",
+                    },
+                    source: content,
+                });
+            }
+        }
+        else {
+            // Extract from PostSynthCheck objects: id, description
+            const idMatch = content.match(/id:\s*"([^"]+)"/);
+            const descMatch = content.match(/description:\s*"((?:[^"\\]|\\.)*)"/);
+            if (idMatch) {
+                out.push({
+                    meta: {
+                        id: idMatch[1],
+                        severity: "error",
+                        category: "post-synth",
+                        description: descMatch ? unescapeStringLiteral(descMatch[1]) : idMatch[1],
+                        type: "post-synth",
+                    },
+                    source: content,
+                });
+            }
+        }
+    }
+}
+/**
+ * Undo the backslash escaping of a double-quoted JS/TS string literal body
+ * captured by a regex like `/description:\s*"((?:[^"\\]|\\.)*)"/` — the
+ * capture group still has the source's escape sequences (`\"`, `\\`, `\n`,
+ * ...) in it verbatim, so a description written as `"say \"hi\""` would
+ * otherwise render in generated docs as `say \"hi\"` instead of `say "hi"`.
+ */
+function unescapeStringLiteral(raw) {
+    return raw.replace(/\\(.)/g, (_, ch) => {
+        switch (ch) {
+            case "n":
+                return "\n";
+            case "t":
+                return "\t";
+            case "r":
+                return "\r";
+            default:
+                // \" -> ", \\ -> \, \' -> ', and anything else -> itself unescaped
+                return ch;
+        }
+    });
+}
+function extractDescriptionFromComment(content, ruleId) {
+    // Try to extract from the first line after the rule ID in JSDoc
+    const pattern = new RegExp(`${ruleId}[:\\s]+([^\\n]+?)\\n\\s*\\*\\s*\\n\\s*\\*\\s*(.+?)\\n`);
+    const match = content.match(pattern);
+    if (match)
+        return match[1].trim();
+    // Fallback: use text after "ruleId:" in JSDoc
+    const simpleMatch = content.match(new RegExp(`\\*\\s*${ruleId}:\\s*(.+?)(?:\\n|\\*)`));
+    if (simpleMatch)
+        return simpleMatch[1].trim();
+    return ruleId;
+}
+function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+export function generateRules(config, rules) {
+    const lintRules = rules.filter((r) => r.type === "lint");
+    const postSynthRules = rules.filter((r) => r.type === "post-synth");
+    const lines = [
+        "---",
+        // "All Rules", not "Lint Rules": most lexicons also ship a hand-written
+        // page under the latter title that covers a selected subset, and two pages
+        // with the same title reads as a duplicate rather than a complete table.
+        `title: "All Rules"`,
+        `description: "Every lint rule and post-synth check provided by the ${config.displayName} lexicon"`,
+        "---",
+        "",
+        `The ${config.displayName} lexicon provides **${rules.length}** rules: ` +
+            `${plural(lintRules.length, "lint rule")} and ` +
+            `${plural(postSynthRules.length, "post-synth check")}.`,
+        "",
+    ];
+    if (lintRules.length > 0) {
+        lines.push("## Lint Rules", "", "| ID | Severity | Category | Description |", "|----|----------|----------|-------------|");
+        for (const rule of lintRules.sort((a, b) => a.id.localeCompare(b.id))) {
+            lines.push(`| \`${rule.id}\` | ${rule.severity} | ${rule.category} | ${escapeMdx(rule.description)} |`);
+        }
+        lines.push("");
+    }
+    if (postSynthRules.length > 0) {
+        lines.push("## Post-Synth Checks", "", "Post-synth checks validate the serialized output after the build pipeline completes.", "", "| ID | Description |", "|----|-------------|");
+        for (const rule of postSynthRules.sort((a, b) => a.id.localeCompare(b.id))) {
+            lines.push(`| \`${rule.id}\` | ${escapeMdx(rule.description)} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}