simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/projection/markers.mjs

@@ -0,0 +1,349 @@
+// The generated-region primitive.
+//
+// This is the whole reason the estate can share rules without a git submodule and
+// without a runtime symlink (docs/plans/0001 section 2.2). A repo keeps its own
+// hand-written AGENTS.md; simt-dev owns only the bytes between two markers.
+//
+// The four properties that make it safe to hand to 16 repos:
+//
+//   idempotent   injecting the same body twice yields identical bytes, so `sync`
+//                never produces a spurious diff and CI never flakes
+//   contained    bytes outside the markers are never touched, so hand-written
+//                content cannot be clobbered by a projection
+//   diagnosable  the region records which simt-dev SHA produced it, so drift is
+//                detectable rather than invisible (ADR: 0001 section 7)
+//   honest       a malformed region is reported as malformed instead of being
+//                silently appended to, which is how a projection engine quietly
+//                duplicates a rule
+
+// The comment syntax a managed file speaks, and where in it the region goes.
+//
+// A marker has to be invisible to the tool that reads the file the region lives in,
+// so the syntax is a property of the FILE, not of this module. Markdown and every
+// `.mdc` are HTML comments; `.editorconfig` is INI, where `#` is the comment
+// character and an HTML comment would be parsed as a malformed key and make every
+// editor fall back to its own defaults - the file would be worse than absent.
+//
+// `where: 'top'` exists for the same reason. In a file whose semantics are
+// last-definition-wins, a shared block appended below the repo's own settings
+// silently overrules them. No byte is removed, so nothing looks clobbered, and the
+// repo's setting simply stops taking effect. Putting the shared block first means
+// the repo always wins, and `check` reports a region that has been moved down.
+import { CLI, MARKER_PREFIX, MARKER_PREFIX_LEGACY } from '../name.mjs';
+
+// The region namespace moved with the command (ADR-056), like the manifest. The read
+// regexes accept both spellings, so a repository still stamped with the legacy prefix
+// is seen rather than reported as unadopted, and the first sync migrates it in place:
+// the composed region carries only the new prefix, so the body comparison in `inject`
+// finds drift and rewrites it. Writing never emits the legacy spelling, so the window
+// closes on every write. A file holding BOTH regions is a state only a hand edit can
+// make; the marker validation below reports it as malformed instead of guessing which
+// region wins, and a human deletes the old one.
+//
+// Both prefixes are pinned to literals in test/naming.test.mjs, so they carry nothing
+// that needs escaping inside the regexes built here.
+const PREFIX = `(?:${MARKER_PREFIX}|${MARKER_PREFIX_LEGACY})`;
+
+export const STYLES = {
+  html: {
+    begin: `<!-- ${MARKER_PREFIX}:begin -->`,
+    end: `<!-- ${MARKER_PREFIX}:end -->`,
+    line: (s) => `<!-- ${s} -->`,
+    note: (first, second) => `<!-- ${first}\n     ${second} -->`,
+    sha: new RegExp(`<!--\\s*${PREFIX}:sha=([0-9a-f]{7,40})\\s*-->`),
+    beginRe: new RegExp(`^<!--\\s*${PREFIX}:begin\\s*-->$`, 'i'),
+    endRe: new RegExp(`^<!--\\s*${PREFIX}:end\\s*-->$`, 'i'),
+    where: 'bottom',
+  },
+  hash: {
+    begin: `# ${MARKER_PREFIX}:begin`,
+    end: `# ${MARKER_PREFIX}:end`,
+    line: (s) => `# ${s}`,
+    note: (first, second) => `# ${first}\n# ${second}`,
+    sha: new RegExp(`^#\\s*${PREFIX}:sha=([0-9a-f]{7,40})\\s*$`, 'm'),
+    beginRe: new RegExp(`^#\\s*${PREFIX}:begin\\s*$`, 'i'),
+    endRe: new RegExp(`^#\\s*${PREFIX}:end\\s*$`, 'i'),
+    where: 'top',
+  },
+};
+
+export const BEGIN = STYLES.html.begin;
+export const END = STYLES.html.end;
+
+/**
+ * The separator between hand-written text and the region, in the shape a Markdown
+ * formatter insists on.
+ *
+ * Markdown treats an HTML comment that follows a paragraph, a list, a fenced block
+ * or a heading as a new block, and every formatter inserts the blank line separating
+ * the two before writing it back. Measured with Prettier 3.8.1: a region appended
+ * after one newline comes back rewritten, and `--check` exits 1 — on a file the
+ * projection got right and the repository's own gate is simply enforcing. The
+ * projection emits the formatter's shape from the start, for the same reason it
+ * emits the trailing newline `compose` already owns.
+ *
+ * Note the list case is worse than a blank line: without one, Prettier reads the
+ * region as a continuation of the last list item and indents all of it.
+ */
+function seam(before) {
+  if (before === '') return '';
+  return before.endsWith('\n\n') ? before : `${before.replace(/\n+$/, '')}\n\n`;
+}
+
+function styleOf(style) {
+  return typeof style === 'string' ? (STYLES[style] ?? STYLES.html) : (style ?? STYLES.html);
+}
+
+const FENCE = /^\s*(`{3,}|~{3,})/;
+
+/**
+ * Split a document into the parts around the generated region.
+ *
+ * @param {string} text
+ * @param {string|object} [style] a key of `STYLES`, or a style row
+ * @returns {{status: 'absent'|'ok'|'malformed', before: string, body: string,
+ *            after: string, reason?: string, sha?: string}}
+ */
+export function parse(text, style) {
+  const s = styleOf(style);
+  const lines = text.split('\n');
+  const absent = { status: 'absent', before: text, body: '', after: '' };
+
+  const markers = [];
+  let fence = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    // Markers inside a fenced block are documentation, not control. An AGENTS.md
+    // that explains this mechanism with an example must not confuse the engine.
+    const fenceMatch = FENCE.exec(line);
+    if (fenceMatch) {
+      const char = fenceMatch[1][0];
+      if (fence === null) fence = char;
+      else if (fence === char) fence = null;
+      continue;
+    }
+    if (fence !== null) continue;
+    if (s.beginRe.test(line)) markers.push({ kind: 'begin', i });
+    else if (s.endRe.test(line)) markers.push({ kind: 'end', i });
+  }
+
+  if (markers.length === 0) return absent;
+
+  const first = markers[0];
+  if (first.kind !== 'begin') {
+    return malformed(lines, 0, first.i, 'end marker before any begin marker');
+  }
+  const last = markers[markers.length - 1];
+  if (last.kind !== 'end') {
+    return malformed(lines, first.i, first.i, 'begin marker with no matching end marker');
+  }
+
+  const between = markers.slice(1, -1);
+  const strayBegin = between.find((m) => m.kind === 'begin');
+  if (strayBegin) {
+    return malformed(lines, first.i, strayBegin.i, 'nested begin marker');
+  }
+  const strayEnd = between.find((m) => m.kind === 'end');
+  if (strayEnd) {
+    return malformed(lines, first.i, strayEnd.i, 'nested end marker');
+  }
+  if (markers.length > 2 && markers.slice(1).some((m) => m.kind === 'end' && m.i < last.i)) {
+    return malformed(lines, first.i, last.i, 'more than one region');
+  }
+
+  const body = lines.slice(first.i + 1, last.i).join('\n');
+  const sha = readSha(body, s);
+  return {
+    status: 'ok',
+    before: lines.slice(0, first.i).join('\n'),
+    body,
+    after: lines.slice(last.i + 1).join('\n'),
+    sha,
+    // The last byte of the end marker. A reader that stops at a fixed offset never
+    // sees a region whose end is past that offset, however correct the body is.
+    endByte: Buffer.byteLength(lines.slice(0, last.i + 1).join('\n')),
+  };
+}
+
+function malformed(lines, from, at, reason) {
+  return {
+    status: 'malformed',
+    before: lines.join('\n'),
+    body: '',
+    after: '',
+    reason,
+    line: at + 1,
+    fromLine: from + 1,
+  };
+}
+
+/** Pull the recorded source SHA out of the region's provenance header. */
+function readSha(body, style) {
+  const m = style.sha.exec(body);
+  return m ? m[1] : undefined;
+}
+
+/**
+ * Render the full region text, markers and provenance header included.
+ * The header lives *inside* the region so it regenerates with the body and can
+ * never drift independently of it.
+ */
+export function compose(body, { sha, sources = [] } = {}, style) {
+  const s = styleOf(style);
+  // A stamp this tool cannot read back is worse than no stamp: `parse` matches
+  // `[0-9a-f]{7,40}`, so the old `unknown` fallback produced a region that reported
+  // no provenance at all, while `upgrade` still compared it against real pins as a
+  // version (ADR-032). Identity is now a content digest and is always present, so the
+  // fallback is gone rather than fixed - but the asymmetry it created is worth naming.
+  if (typeof sha !== 'string' || !/^[0-9a-f]{7,40}$/.test(sha)) {
+    throw new Error(`compose: sha must match [0-9a-f]{7,40}, got ${JSON.stringify(sha)}`);
+  }
+  // Write-new, like the markers: the legacy spelling is read but never emitted, so a
+  // migrated region is stable and a legacy one drifts exactly once.
+  const header = [s.line(`${MARKER_PREFIX}:generated`), s.line(`${MARKER_PREFIX}:sha=${sha}`)];
+  if (sources.length > 0) {
+    header.push(s.line(`${MARKER_PREFIX}:sources=${sources.join(',')}`));
+  }
+  // Addressed to whoever reads this repo, not to whoever owns the rules upstream.
+  // "Edit the source in simt-dev" was the wrong instruction twice over: a consumer
+  // of the published package has no such tree, and an agent reading this repo has
+  // no business editing the region it was told not to edit. The only two actions
+  // available to a reader are: don't edit it, or regenerate it.
+  header.push(
+    s.note(
+      'Generated content. Do not edit by hand - your changes are overwritten.',
+      `Run \`${CLI} sync --yes\` to regenerate, or \`${CLI} check\` to see what is stale.`,
+    ),
+  );
+  const trimmed = body.replace(/\n+$/, '');
+  // Two lines here exist only because a real repo proved they are needed. A
+  // formatter that runs on commit - several repositories have one, and three of the
+  // other repos do too - rewrote the region on the very first commit: it inserted a
+  // blank line after the header comment and added the trailing newline. Both edits
+  // are things prettier considers correct, and either one alone makes `check`
+  // permanently red on a repo whose own tooling is working correctly. A generated
+  // file that a formatter rewrites is a fight the projection loses, so the
+  // projection emits the formatter's shape in the first place. The blank line before
+  // END is the same class: prettier treats an HTML comment after a paragraph as a
+  // new block and inserts the separating blank line itself, which made
+  // a `format:check` fail on a file whose generated region was correct.
+  const out =
+    trimmed === ''
+      ? [s.begin, ...header, s.end]
+      : [s.begin, ...header, '', ...trimmed.split('\n'), '', s.end];
+  return `${out.join('\n')}\n`;
+}
+
+/**
+ * Put the region back into the parts either side of it.
+ *
+ * `where` decides which side is authoritative. It is a style property rather than
+ * a caller argument because the correct answer is a fact about the file's syntax,
+ * and a caller who has to remember it is a caller who will get it wrong once.
+ */
+function splice(state, region, where) {
+  if (where === 'top') {
+    // Top placement is a repair, not a relocation: a region below the file's own
+    // settings is moved back above them, which is the one thing the bytes either
+    // side of the markers are allowed to move for. So the result here is not
+    // byte-comparable with the input even when nothing has changed.
+    const rest = `${state.before}${state.before === '' ? '' : '\n'}${state.after}`
+      .replace(/^\n+/, '')
+      .replace(/\n+$/, '');
+    if (rest === '') return region;
+    return `${region}\n${rest}\n`;
+  }
+  const before = seam(state.before);
+  const after = state.after.startsWith('\n') ? state.after : state.after === '' ? '' : `\n${state.after}`;
+  return `${before}${region}${after}`;
+}
+
+/**
+ * Insert or replace the region in `text`, preserving everything outside it.
+ *
+ * `region` and `previousBody` are the state the document was in, not the action taken on
+ * it. A caller asking "did this repository's *rules* change?" cannot read that off
+ * `action`: a wrong seam with a correct body is `updated` (ADR-037), and so is a changed
+ * body. Reporting "the rules changed" for the first is a false cause, and `upgrade` prints
+ * it to whoever ran the command. Two of them also answer "has this repo ever been
+ * adopted?" — `region: 'absent'` is that answer, and reading it off `previousBytes` gets a
+ * repository with hand-written prose and no region wrong.
+ *
+ * @param {object} [opts] `style` overrides the syntax; `where` overrides placement.
+ * @returns {{text: string, action: 'added'|'updated'|'unchanged'|'malformed', reason?: string,
+ *   region: 'absent'|'ok'|'malformed', previousBody: string}}
+ */
+export function inject(text, body, meta, opts = {}) {
+  const s = styleOf(opts.style);
+  const where = opts.where ?? s.where;
+  const state = parse(text, s);
+  const seen = { region: state.status, previousBody: state.body ?? '' };
+  if (state.status === 'malformed') {
+    return { ...seen, text, action: 'malformed', reason: state.reason, line: state.line };
+  }
+  const region = compose(body, meta, s);
+
+  if (state.status === 'absent') {
+    if (where === 'top') {
+      const rest = text.replace(/^\n+/, '').replace(/\n+$/, '');
+      return { ...seen, text: rest === '' ? region : `${region}\n${rest}\n`, action: 'added' };
+    }
+    const base = seam(text);
+    // No trailing newline here, and that is load-bearing. `compose` already
+    // terminates the region with one; adding a second left every adopted file
+    // ending in a blank line. Nothing in this tool noticed, because `check`
+    // compares region bodies and the byte after END is not part of the region —
+    // but a repository's own `git diff --check` gate did, and it is a gate
+    // that repo runs before every commit. The `updated` branch below has always
+    // been correct for exactly this reason.
+    //
+    // `seam` replaced a hand-rolled equivalent here. The two agreed, which is why the
+    // seam defect survived a read of this branch: it looks like the place the blank
+    // line is added, and it is — for a document with no region yet. It is not where
+    // the defect was, which is in `splice`.
+    return {
+      ...seen,
+      text: `${base}${region}`,
+      action: 'added',
+    };
+  }
+
+  // Compare ignoring only the trailing newline the region may pick up from the
+  // document; any other byte difference is real drift worth rewriting.
+  const current = state.body.replace(/^\n+/, '').replace(/\n+$/, '');
+  const next = region.slice(s.begin.length + 1, region.length - s.end.length - 1);
+  const unchanged = current === next.replace(/^\n+/, '').replace(/\n+$/, '');
+  const spliced = splice(state, region, where);
+
+  // Comparing the region BODY is not enough to decide, because the byte between the
+  // hand-written text and the region is part of the file a Markdown formatter reads
+  // too. A body that matches with a seam that does not is red on `format:check`, and
+  // reporting `unchanged` there means `check` finds no drift and `sync` never repairs
+  // it - the repository stays red with no remedy the tool offers. Top placement is
+  // excluded because there the splice is a repair that legitimately moves bytes
+  // outside the markers, so the two files differ for a reason unrelated to the seam.
+  const settled = unchanged && (where === 'top' || spliced === text);
+  if (settled) return { ...seen, text, action: 'unchanged' };
+
+  return { ...seen, text: spliced, action: 'updated' };
+}
+
+/**
+ * Compare a document against a desired region body without writing.
+ * `meta` must be the same provenance the writer would use, so a region produced
+ * by an older simt-dev SHA reads as drift rather than as unchanged.
+ *
+ * @returns {{action: 'added'|'updated'|'unchanged'|'malformed', reason?: string, line?: number,
+ *   region: 'absent'|'ok'|'malformed', previousBody: string}}
+ */
+export function diff(text, body, meta, opts = {}) {
+  const state = parse(text, styleOf(opts.style));
+  if (state.status === 'malformed') {
+    return { region: 'malformed', previousBody: '', action: 'malformed', reason: state.reason, line: state.line };
+  }
+  if (state.status === 'absent') {
+    return { region: 'absent', previousBody: '', action: 'added' };
+  }
+  const probe = inject(text, body, meta, opts);
+  return { region: probe.region, previousBody: probe.previousBody, action: probe.action };
+}

simt_dev/vendored/src/projection/mdc.mjs

@@ -0,0 +1,327 @@
+// Project `.mdc` rules as generated regions.
+//
+// The estate carried three always-on `.mdc` rule families across the Social repos
+// in eight files, and no two were byte-identical. The worst pair differed by one
+// byte while three semantically loaded lines changed, so no size-, hash- or
+// line-count-based duplicate detector could ever have flagged it. This module is
+// the answer to that finding: one canonical body, projected.
+//
+// Two decisions are load-bearing and neither is obvious:
+//
+//   1. VARIANT IS THE WRONG SHAPE FOR THIS CONTENT. The two divergent BLOCK
+//      bullets in `test-gate` are complementary (one catches a consumer that
+//      requires an unshipped field, the other a producer that ships an untested
+//      one), and the two divergent Requirements bullets in
+//      `preview-postflight` are complementary too (a build-config instruction and
+//      a credential-handling prohibition). Choosing one per repo would keep the
+//      estate's worst bug — a rule file that quietly stops catching half of what
+//      it exists to catch. So the canonical body carries BOTH, unconditionally.
+//
+//   2. WHAT ACTUALLY VARIES IS SUBSTRATE, NOT POLICY. A plan-tracker glob, a test
+//      path, a production domain. Those become declared substitutions with
+//      defaults, so an unconfigured repo still receives a correct, complete rule
+//      and the defaults are visible rather than guessed at render time.
+
+import { readFile, readdir } from 'node:fs/promises';
+
+import { frontmatterBlock } from './surfaces.mjs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse } from './markers.mjs';
+
+// ROOT is computed here rather than imported: project.mjs is the caller of every
+// function below, so importing it back would create a cycle for the sake of one
+// constant.
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const MDC_DIR = join(ROOT, 'rules', 'mdc');
+
+/**
+ * The keys a canonical `.mdc` may declare: ours prefixed, the editor's as documented
+ * (ADR-022).
+ *
+ * The allowlist earns its place twice. It is what tells a reader of the file which
+ * reader owns a key, and it is what turns an unprefixed simt key into a reported
+ * defect — which is the failure ADR-016 shipped once, a rule that reached no repo
+ * because `applies` was absent, silently and with a test green.
+ */
+const KNOWN_KEYS = new Set([
+  'simt-id',
+  'simt-target',
+  'simt-title',
+  'simt-applies',
+  'simt-opt-in',
+  'simt-substitutions',
+  'description',
+  'alwaysApply',
+]);
+
+/** A bare key beside a prefixed one is the typo this rule exists to catch. */
+function unknownKey(key) {
+  const prefixed = `simt-${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+  return KNOWN_KEYS.has(prefixed)
+    ? `key "${key}" is this tool's own, not the editor's; it is spelled "${prefixed}"`
+    : `unrecognised frontmatter key "${key}"; simt-dev's own keys are simt-id, simt-target, simt-title, simt-applies, simt-opt-in, simt-substitutions`;
+}
+
+/**
+ * Read every canonical `.mdc` rule with its frontmatter parsed.
+ *
+ * A rule without `simt-id` or `simt-target` is a defect rather than a default:
+ * `simt-id` is what a manifest keys its substitutions on, and `simt-target` is the
+ * only thing saying where the projected file goes. A rule that silently wrote nowhere
+ * would look like a successful sync.
+ */
+export async function loadMdcRules() {
+  let names;
+  try {
+    names = (await readdir(MDC_DIR)).filter((n) => n.endsWith('.mdc')).sort();
+  } catch {
+    return [];
+  }
+
+  const out = [];
+  for (const file of names) {
+    const text = await readFile(join(MDC_DIR, file), 'utf8');
+    const meta = parseFrontmatter(text);
+    // `simt-substitutions:` is a YAML list of maps, which the shared line-based
+    // frontmatter parser cannot express, so it is parsed separately and strictly.
+    const subs = parseSubstitutions(text);
+    const unknown = Object.keys(meta).filter((k) => !KNOWN_KEYS.has(k));
+    out.push({
+      file,
+      source: `rules/mdc/${file}`,
+      id: meta['simt-id'] ?? null,
+      target: meta['simt-target'] ?? null,
+      title: meta['simt-title'] ?? null,
+      description: meta.description ?? null,
+      alwaysApply: meta.alwaysApply === true,
+      // `simt-applies` is 'always' or a tag array; `simt-opt-in` means the repo must name
+      // this rule in its manifest rather than matching on a detected signal. A rule that
+      // names one product's Workers and secrets cannot be selected by stack, because
+      // detection cannot distinguish a Workers repo that has that problem from one
+      // that does not.
+      applies:
+        meta['simt-applies'] === 'always'
+          ? 'always'
+          : Array.isArray(meta['simt-applies'])
+            ? meta['simt-applies']
+            : [],
+      optIn: meta['simt-opt-in'] === true,
+      // A rule with no `simt-substitutions:` block has no placeholders, so an empty
+      // list is the correct answer. (This was `substitutions` — an undefined binding
+      // that would only have fired on a future rule without the block, which is
+      // exactly the kind of latent crash a new rule is most likely to trigger.)
+      substitutions: subs,
+      bytes: Buffer.byteLength(text),
+      body: stripFrontmatter(text),
+      error:
+        meta['simt-id'] === null
+          ? 'missing simt-id in frontmatter'
+          : meta['simt-target'] === null
+            ? 'missing simt-target in frontmatter'
+            : unknown.length > 0
+              ? unknownKey(unknown[0])
+              : null,
+    });
+  }
+  return out;
+}
+
+/** `simt-substitutions:` is a list of `- key: x` blocks. Any deviation is reported
+ *  rather than skipped, because a silently-dropped substitution projects a rule
+ *  containing a literal `{{placeholder}}`. */
+function parseSubstitutions(text) {
+  const m = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!m) return [];
+  const block = m[1];
+  if (!/^simt-substitutions:/m.test(block)) return [];
+
+  const out = [];
+  const re = /^\s*-\s*key:\s*(\S+)\s*$/gm;
+  const hits = [...block.matchAll(re)];
+  for (const hit of hits) {
+    const start = hit.index + hit[0].length;
+    const tail = block.slice(start);
+    const next = /^\s*-\s*key:/m.exec(tail.slice(1));
+    const scope = next ? tail.slice(0, next.index + 1) : tail;
+    const def = /^\s*default:\s*(.*)$/m.exec(scope);
+    const desc = /^\s*describe:\s*(.*)$/m.exec(scope);
+    out.push({
+      key: hit[1],
+      default: def ? unquote(def[1].trim()) : '',
+      describe: desc ? unquote(desc[1].trim()) : '',
+    });
+  }
+  return out;
+}
+
+function parseFrontmatter(text) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    // `simt-substitutions:` opens a nested block this parser cannot represent, so
+    // it and its list items are skipped here and read by parseSubstitutions.
+    if (/^\s*-\s/.test(line)) continue;
+    const kv = /^([a-zA-Z-]+):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const [, key, raw] = kv;
+    if (raw === '') continue;
+    if (raw === 'always') out[key] = 'always';
+    else if (raw === 'true') out[key] = true;
+    else if (raw === 'false') out[key] = false;
+    else if (raw.startsWith('[')) {
+      out[key] = raw
+        .slice(1, raw.lastIndexOf(']'))
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else out[key] = unquote(raw.trim());
+  }
+  return out;
+}
+
+function unquote(s) {
+  if (s.length >= 2 && ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function stripFrontmatter(text) {
+  return text
+    .replace(/^---\n[\s\S]*?\n---\n*/, '')
+    .replace(/^#\s+.*\n+/, '')
+    .trim();
+}
+
+/**
+ * Substitute declared placeholders.
+ *
+ * An empty-string default is a deliberate "this repo has nothing to add here"
+ * and the line it sits on is DROPPED. That is how `preview-postflight` reaches
+ * a repository without printing an empty bullet, and how a repo with no
+ * production-domain note gets a clean document instead of a blank one.
+ *
+ * A placeholder with neither a declared nor a default value is a defect: the
+ * rendered rule would ship a literal `{{key}}`, which reads as a finished rule
+ * and is not one.
+ */
+export function renderMdc(rule, declared = {}) {
+  const problems = [];
+  let body = rule.body;
+
+  for (const sub of rule.substitutions) {
+    const has = Object.prototype.hasOwnProperty.call(declared, sub.key);
+    const provided = has ? declared[sub.key] : undefined;
+
+    if (has && provided === '') {
+      // A repo declared this key and declared it empty: the line it sits on is
+      // removed. This is how preview-postflight reaches a repository without
+      // printing a blank bullet.
+      body = dropOrReplace(body, sub.key, '');
+      continue;
+    }
+
+    if (provided === undefined || provided === null || provided === '') {
+      // Fall back to the default. An empty DEFAULT is also a drop instruction,
+      // which is how the same file serves a repo that has nothing to add.
+      if (sub.default === '') {
+        body = dropOrReplace(body, sub.key, '');
+        continue;
+      }
+      if (sub.default === undefined) {
+        problems.push(`substitution ${sub.key} has no default and none declared`);
+        continue;
+      }
+      body = dropOrReplace(body, sub.key, sub.default);
+      continue;
+    }
+
+    body = dropOrReplace(body, sub.key, String(provided));
+  }
+
+  // A key that was already reported as unsubstitutable is not reported a second
+  // time as a leftover placeholder. Two messages for one fault trains a reader
+  // to skim past problems, and the first message is the actionable one.
+  const reported = new Set(
+    problems
+      .filter((p) => /^substitution /.test(p))
+      .map((p) => /^substitution ([^ ]+) /.exec(p)?.[1]),
+  );
+  const leftover = [...body.matchAll(/\{\{([a-zA-Z0-9_-]+)\}\}/g)].map((m) => m[1]);
+  for (const key of new Set(leftover)) {
+    if (reported.has(key)) continue;
+    problems.push(`placeholder {{${key}}} was never substituted`);
+  }
+
+  return { body, problems };
+}
+
+/**
+ * Replace every `{{key}}`, or remove the whole bullet when the value is empty.
+ *
+ * "Whole bullet" rather than "the line containing the token": an empty value on a
+ * wrapped bullet leaves its continuation lines behind, and the rule then reads as
+ * half a sentence starting with a lowercase word. A markdown bullet is the token's
+ * line plus every more-indented line that follows it.
+ *
+ * One placeholder per line is a rule on the content side, not a preference. Dropping
+ * a line removes EVERY token on it, so `{{a}}{{b}}` with `a` empty deletes `b` too —
+ * silently, and with no leftover placeholder left to report. Two independent optional
+ * clauses on one line lose one clause with no diagnostic at all.
+ */
+function dropOrReplace(text, key, value) {
+  const token = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+  if (value !== '') return text.replace(token, value);
+  // A second, non-global pattern for the line scan: reusing a `/g` regex with
+  // `.test()` carries `lastIndex` between lines, so every other line would be
+  // tested against the wrong offset.
+  const probe = new RegExp(`\\{\\{${key}\\}\\}`);
+
+  const kept = [];
+  let dropping = false;
+  for (const line of text.split('\n')) {
+    if (probe.test(line)) {
+      dropping = true;
+      continue;
+    }
+    if (dropping) {
+      // A continuation of the bullet just dropped: indented, and not itself the
+      // start of a new block element.
+      const indent = /^(\s*)/.exec(line)[1].length;
+      if (line.trim() === '') continue;
+      if (indent > 0 && !/^\s*([-*+]|\d+\.)\s/.test(line)) continue;
+      dropping = false;
+    }
+    kept.push(line);
+  }
+  return kept.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+
+/** The frontmatter a projected `.mdc` keeps. `alwaysApply` and `description` are
+ *  read by the editor before any rule text, so they belong outside the region. */
+export function mdcFrontmatter(rule) {
+  return frontmatterBlock([
+    `description: ${rule.description ?? `Canonical ${rule.id} rule managed by simt-dev`}`,
+    `alwaysApply: ${rule.alwaysApply ? 'true' : 'false'}`,
+  ]);
+}
+
+
+/**
+ * The rule's bare name, taken from the path it declares.
+ *
+ * `simt-target` is the canonical declaration and predates the surface table; deriving
+ * every other surface's path from its basename means a rule names itself once and
+ * a rename moves every editor's file with it, instead of four paths that can
+ * disagree about which rule a file holds.
+ */
+export function ruleName(rule) {
+  if (typeof rule.target !== 'string' || rule.target === '') return null;
+  const base = rule.target.slice(rule.target.lastIndexOf('/') + 1);
+  return base.replace(/\.mdc$/, '');
+}
+
+export { MDC_DIR, parse as parseRegion };