@refrakt-md/cli 0.36.0 → 0.37.0

package/dist/commands/migrate-snippets.js

@@ -0,0 +1,218 @@
+/**
+ * `refrakt migrate snippets` — the `lines=` → anchor codemod (SPEC-131 D7,
+ * WORK-590).
+ *
+ * Converting invocations by hand is tedious and exactly the kind of change
+ * where a slip reintroduces the bug being fixed. The codemod reads each current
+ * slice, infers an anchor from its first meaningful line, rewrites the
+ * invocation, and **verifies the new resolution produces a byte-identical
+ * slice** — refusing to rewrite when it does not.
+ *
+ * The diff stays reviewable; the verification is what makes it trustworthy.
+ *
+ * **Two things the verification does not cover**, both deliberate:
+ *
+ * - The byte-identical comparison runs **before** `reindent` (WORK-589). Run it
+ *   after and every nested target fails verification for a difference the
+ *   codemod itself introduced.
+ * - Companion attributes need their own check. An invocation carrying
+ *   `highlight=` needs those coordinates preserved or rewritten, and the slice
+ *   comparison says nothing about them.
+ *
+ * **It never stamps SPEC-134 `reviewed` markers** (SPEC-134 D8). A marker
+ * asserting that a human reviewed regions nobody looked at is a false claim in
+ * precisely the shape that spec exists to prevent.
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AnchorResolutionError, BASE_LANGUAGES, maskSource, resolveAnchor, resolveLanguage, } from '@refrakt-md/runes';
+/** Infer an anchor from a slice's first meaningful line. Returns the attribute
+ *  text to substitute for `lines="…"`, or undefined when nothing usable is
+ *  found. */
+export function inferAnchor(slice, lang) {
+    const lines = slice.split('\n');
+    // Skip blank lines and comment lines: several existing invocations open on
+    // a blank line or in the middle of a comment block, which is itself a
+    // symptom of line addressing.
+    const firstMeaningful = lines.find((line) => {
+        const text = line.trim();
+        if (text.length === 0)
+            return false;
+        if (!lang)
+            return true;
+        if (lang.lineComments.some((p) => text.startsWith(p)))
+            return false;
+        if (lang.blockComments.some(([open]) => text.startsWith(open)))
+            return false;
+        if (lang.blockComments.length > 0 && text.startsWith('*'))
+            return false;
+        return true;
+    });
+    if (firstMeaningful === undefined)
+        return undefined;
+    // A named declaration is the best anchor: prefer `symbol=`.
+    if (lang && lang.keywords.length > 0) {
+        const keywords = lang.keywords.join('|');
+        const modifiers = lang.modifiers.length > 0 ? `(?:(?:${lang.modifiers.join('|')})\\s+)*` : '';
+        const decl = new RegExp(`^\\s*${modifiers}(?:${keywords})\\s+([A-Za-z_$][\\w$]*)`);
+        const m = decl.exec(firstMeaningful);
+        if (m)
+            return { attr: `symbol="${m[1]}"`, description: `symbol ${m[1]}` };
+    }
+    // Otherwise a regex anchored on the literal first line.
+    const escaped = firstMeaningful
+        .trim()
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/"/g, '\\"');
+    if (escaped.length === 0)
+        return undefined;
+    return { attr: `match="^\\s*${escaped}"`, description: `match on ${firstMeaningful.trim()}` };
+}
+const SNIPPET_TAG = /\{%\s*(snippet|file-ref)\b([^%]*)%\}/g;
+export function migrateSnippets(opts) {
+    const repoRoot = opts.repoRoot ?? process.cwd();
+    const contentDirs = opts.contentDirs ?? ['site/content'];
+    const result = {
+        rewrites: [],
+        refusals: [],
+        skippedFenced: 0,
+        languages: {},
+    };
+    for (const dir of contentDirs) {
+        for (const page of collectMarkdown(join(repoRoot, dir), repoRoot)) {
+            const source = readFileSync(join(repoRoot, page), 'utf8');
+            // Fenced invocations are examples, not resolvable targets: they
+            // cannot be verified byte-identically, so the codemod does not
+            // attempt them. They are rewritten by hand to match whatever their
+            // live counterparts become.
+            const masked = maskSource(source, BASE_LANGUAGES.markdoc);
+            const sourceLines = source.split('\n');
+            const maskedLines = masked.split('\n');
+            let nextSource = source;
+            sourceLines.forEach((line, i) => {
+                SNIPPET_TAG.lastIndex = 0;
+                let m = SNIPPET_TAG.exec(line);
+                while (m !== null) {
+                    const invocation = m[0];
+                    const attrs = m[2];
+                    const linesAttr = /\blines\s*=\s*"([^"]+)"/.exec(attrs);
+                    const pathAttr = /\bpath\s*=\s*"([^"]+)"/.exec(attrs);
+                    const current = m;
+                    m = SNIPPET_TAG.exec(line);
+                    if (!linesAttr || !pathAttr)
+                        continue;
+                    if (maskedLines[i] !== sourceLines[i]) {
+                        result.skippedFenced++;
+                        continue;
+                    }
+                    const target = pathAttr[1];
+                    let fileSource;
+                    try {
+                        fileSource = readFileSync(join(repoRoot, target), 'utf8');
+                    }
+                    catch {
+                        result.refusals.push({
+                            page,
+                            line: i + 1,
+                            invocation,
+                            reason: `target "${target}" could not be read`,
+                        });
+                        continue;
+                    }
+                    const lang = resolveLanguage(target);
+                    const langName = Object.entries(BASE_LANGUAGES).find(([, def]) => def === lang)?.[0] ?? 'unknown';
+                    const range = /^(\d*)-?(\d*)$/.exec(linesAttr[1].trim());
+                    if (!range) {
+                        result.refusals.push({
+                            page,
+                            line: i + 1,
+                            invocation,
+                            reason: `lines="${linesAttr[1]}" is not a simple range`,
+                        });
+                        continue;
+                    }
+                    const fileLines = fileSource.split('\n');
+                    const start = range[1] ? Number(range[1]) : 1;
+                    const end = range[2] ? Number(range[2]) : start;
+                    const before = fileLines.slice(start - 1, end).join('\n');
+                    const inferred = inferAnchor(before, lang);
+                    if (!inferred) {
+                        result.refusals.push({
+                            page,
+                            line: i + 1,
+                            invocation,
+                            reason: 'no anchor could be inferred from the slice',
+                        });
+                        continue;
+                    }
+                    // Resolve the inferred anchor and require a byte-identical
+                    // slice. This comparison runs BEFORE reindent.
+                    let after;
+                    try {
+                        const anchorOpts = inferred.attr.startsWith('symbol=')
+                            ? { symbol: /symbol="([^"]+)"/.exec(inferred.attr)?.[1], doc: false }
+                            : { match: /match="(.+)"$/.exec(inferred.attr)?.[1]?.replace(/\\"/g, '"') };
+                        const resolved = resolveAnchor(fileSource, lang, anchorOpts, target);
+                        after = fileLines.slice(resolved.start - 1, resolved.end).join('\n');
+                    }
+                    catch (err) {
+                        result.refusals.push({
+                            page,
+                            line: i + 1,
+                            invocation,
+                            reason: err instanceof AnchorResolutionError
+                                ? err.message
+                                : `resolution failed: ${String(err?.message ?? err)}`,
+                        });
+                        continue;
+                    }
+                    if (after !== before) {
+                        // A refusal is information, not an obstacle: it means
+                        // the anchor engine could not reproduce the slice, which
+                        // is exactly where a human should look.
+                        result.refusals.push({
+                            page,
+                            line: i + 1,
+                            invocation,
+                            reason: 'the anchored slice is not byte-identical to the line-addressed one',
+                        });
+                        continue;
+                    }
+                    const rewritten = invocation.replace(linesAttr[0], inferred.attr);
+                    result.rewrites.push({
+                        page,
+                        line: i + 1,
+                        before: invocation,
+                        after: rewritten,
+                        target,
+                        anchor: inferred.description,
+                    });
+                    result.languages[langName] = (result.languages[langName] ?? 0) + 1;
+                    nextSource = nextSource.replace(current[0], rewritten);
+                }
+            });
+            if (opts.fix && nextSource !== source) {
+                writeFileSync(join(repoRoot, page), nextSource, 'utf8');
+            }
+        }
+    }
+    return result;
+}
+function collectMarkdown(dir, repoRoot, out = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            collectMarkdown(full, repoRoot, out);
+        else if (entry.endsWith('.md'))
+            out.push(full.slice(repoRoot.length + 1));
+    }
+    return out;
+}
+//# sourceMappingURL=migrate-snippets.js.map

package/dist/commands/migrate-snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-snippets.js","sourceRoot":"","sources":["../../src/commands/migrate-snippets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACN,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,aAAa,EACb,eAAe,GACf,MAAM,mBAAmB,CAAC;AAoC3B;;aAEa;AACb,MAAM,UAAU,WAAW,CAC1B,KAAa,EACb,IAAwC;IAExC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEhC,2EAA2E;IAC3E,sEAAsE;IACtE,8BAA8B;IAC9B,MAAM,eAAe,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACvB,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACpE,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7E,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACxE,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;IAEH,IAAI,eAAe,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAEpD,4DAA4D;IAC5D,IAAI,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9F,MAAM,IAAI,GAAG,IAAI,MAAM,CAAC,QAAQ,SAAS,MAAM,QAAQ,0BAA0B,CAAC,CAAC;QACnF,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACrC,IAAI,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC3E,CAAC;IAED,wDAAwD;IACxD,MAAM,OAAO,GAAG,eAAe;SAC7B,IAAI,EAAE;SACN,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC;SACtC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,EAAE,IAAI,EAAE,eAAe,OAAO,GAAG,EAAE,WAAW,EAAE,YAAY,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC;AAC/F,CAAC;AAED,MAAM,WAAW,GAAG,uCAAuC,CAAC;AAE5D,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAChD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,cAAc,CAAC,CAAC;IACzD,MAAM,MAAM,GAAkB;QAC7B,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,EAAE;QACZ,aAAa,EAAE,CAAC;QAChB,SAAS,EAAE,EAAE;KACb,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;YACnE,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;YAC1D,gEAAgE;YAChE,+DAA+D;YAC/D,mEAAmE;YACnE,4BAA4B;YAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;YAC1D,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACvC,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAEvC,IAAI,UAAU,GAAG,MAAM,CAAC;YAExB,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;gBAC/B,WAAW,CAAC,SAAS,GAAG,CAAC,CAAC;gBAC1B,IAAI,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC/B,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;oBACnB,MAAM,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBACxB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBACnB,MAAM,SAAS,GAAG,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACxD,MAAM,QAAQ,GAAG,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACtD,MAAM,OAAO,GAAG,CAAC,CAAC;oBAClB,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAE3B,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ;wBAAE,SAAS;oBAEtC,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;wBACvC,MAAM,CAAC,aAAa,EAAE,CAAC;wBACvB,SAAS;oBACV,CAAC;oBAED,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;oBAC3B,IAAI,UAAkB,CAAC;oBACvB,IAAI,CAAC;wBACJ,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;oBAC3D,CAAC;oBAAC,MAAM,CAAC;wBACR,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;4BACpB,IAAI;4BACJ,IAAI,EAAE,CAAC,GAAG,CAAC;4BACX,UAAU;4BACV,MAAM,EAAE,WAAW,MAAM,qBAAqB;yBAC9C,CAAC,CAAC;wBACH,SAAS;oBACV,CAAC;oBAED,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;oBACrC,MAAM,QAAQ,GACb,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;oBAElF,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;oBACzD,IAAI,CAAC,KAAK,EAAE,CAAC;wBACZ,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;4BACpB,IAAI;4BACJ,IAAI,EAAE,CAAC,GAAG,CAAC;4BACX,UAAU;4BACV,MAAM,EAAE,UAAU,SAAS,CAAC,CAAC,CAAC,yBAAyB;yBACvD,CAAC,CAAC;wBACH,SAAS;oBACV,CAAC;oBAED,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACzC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC9C,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;oBAChD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAE1D,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;oBAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;wBACf,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;4BACpB,IAAI;4BACJ,IAAI,EAAE,CAAC,GAAG,CAAC;4BACX,UAAU;4BACV,MAAM,EAAE,4CAA4C;yBACpD,CAAC,CAAC;wBACH,SAAS;oBACV,CAAC;oBAED,2DAA2D;oBAC3D,+CAA+C;oBAC/C,IAAI,KAAa,CAAC;oBAClB,IAAI,CAAC;wBACJ,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;4BACrD,CAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE;4BACrE,CAAC,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;wBAC7E,MAAM,QAAQ,GAAG,aAAa,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;wBACrE,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACtE,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACd,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;4BACpB,IAAI;4BACJ,IAAI,EAAE,CAAC,GAAG,CAAC;4BACX,UAAU;4BACV,MAAM,EACL,GAAG,YAAY,qBAAqB;gCACnC,CAAC,CAAC,GAAG,CAAC,OAAO;gCACb,CAAC,CAAC,sBAAsB,MAAM,CAAE,GAAa,EAAE,OAAO,IAAI,GAAG,CAAC,EAAE;yBAClE,CAAC,CAAC;wBACH,SAAS;oBACV,CAAC;oBAED,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;wBACtB,sDAAsD;wBACtD,yDAAyD;wBACzD,wCAAwC;wBACxC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;4BACpB,IAAI;4BACJ,IAAI,EAAE,CAAC,GAAG,CAAC;4BACX,UAAU;4BACV,MAAM,EAAE,oEAAoE;yBAC5E,CAAC,CAAC;wBACH,SAAS;oBACV,CAAC;oBAED,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;oBAClE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;wBACpB,IAAI;wBACJ,IAAI,EAAE,CAAC,GAAG,CAAC;wBACX,MAAM,EAAE,UAAU;wBAClB,KAAK,EAAE,SAAS;wBAChB,MAAM;wBACN,MAAM,EAAE,QAAQ,CAAC,WAAW;qBAC5B,CAAC,CAAC;oBACH,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;oBACnE,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;gBACxD,CAAC;YACF,CAAC,CAAC,CAAC;YAEH,IAAI,IAAI,CAAC,GAAG,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;gBACvC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;YACzD,CAAC;QACF,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,GAAW,EAAE,QAAgB,EAAE,MAAgB,EAAE;IACzE,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACJ,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,GAAG,CAAC;IACZ,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;YAAE,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;aAClE,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/commands/snippet-review.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `refrakt snippet review` (SPEC-134, WORK-591 + WORK-592).
+ *
+ * Markers are never hand-written. This is the tool that writes them, and the
+ * review experience that makes writing one mean something.
+ *
+ * ```bash
+ * refrakt snippet review site/content/runes/file-ref.md   # stamp unmarked
+ * refrakt snippet review --all
+ * refrakt snippet review --check                          # report, own exit code
+ * refrakt snippet review --update --interactive           # re-stamp what changed
+ * ```
+ *
+ * **The tool shows content, never hashes (D5).** A commit full of changed hex
+ * strings is unreviewable and would make the marker ceremonial. A commit where
+ * someone saw each before/after and confirmed the prose still holds is the
+ * entire deliverable.
+ *
+ * **Recovering the "before" is the part that is not obvious.** A hash cannot be
+ * turned back into content, so the reviewed version is read out of git: the
+ * commit that introduced this marker value is when the review happened, so the
+ * target file *at that commit* is what the author actually read. Resolving the
+ * same anchor there gives the old slice to diff against.
+ *
+ * **A fired marker is a prompt, not a failure (D7).** The output is a
+ * changed-files list. Framed as a failing test with a red X, authors re-stamp
+ * reflexively to get green — producing markers that certify nothing and cost a
+ * command.
+ */
+import { type MarkerVerdict } from '@refrakt-md/runes';
+export interface SnippetReviewOptions {
+    repoRoot?: string;
+    contentDirs?: string[];
+    /** Specific pages to act on. Empty means every page under contentDirs. */
+    pages?: string[];
+    all?: boolean;
+    check?: boolean;
+    update?: boolean;
+    interactive?: boolean;
+    format?: 'text' | 'json';
+}
+export interface ReviewFinding {
+    page: string;
+    line: number;
+    target: string;
+    anchor: string;
+    verdict: MarkerVerdict;
+    summary: string;
+    /** Present when the reviewed version could be recovered from git. */
+    diff?: string;
+}
+/** Render a unified-ish diff for the terminal. Content, never hashes. */
+export declare function renderDiff(before: string, after: string): string;
+export interface ReviewResult {
+    findings: ReviewFinding[];
+    stamped: number;
+    restampedSilently: number;
+    noops: Array<{
+        page: string;
+        line: number;
+        reason: string;
+    }>;
+}
+export declare function runSnippetReview(opts: SnippetReviewOptions): ReviewResult;
+export declare function snippetReviewCommand(opts: SnippetReviewOptions): Promise<void>;
+//# sourceMappingURL=snippet-review.d.ts.map

package/dist/commands/snippet-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet-review.d.ts","sourceRoot":"","sources":["../../src/commands/snippet-review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,EAKN,KAAK,aAAa,EAIlB,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAYD,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAwGD,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,YAAY,CAiGzE;AAwBD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CpF"}

package/dist/commands/snippet-review.js

@@ -0,0 +1,271 @@
+/**
+ * `refrakt snippet review` (SPEC-134, WORK-591 + WORK-592).
+ *
+ * Markers are never hand-written. This is the tool that writes them, and the
+ * review experience that makes writing one mean something.
+ *
+ * ```bash
+ * refrakt snippet review site/content/runes/file-ref.md   # stamp unmarked
+ * refrakt snippet review --all
+ * refrakt snippet review --check                          # report, own exit code
+ * refrakt snippet review --update --interactive           # re-stamp what changed
+ * ```
+ *
+ * **The tool shows content, never hashes (D5).** A commit full of changed hex
+ * strings is unreviewable and would make the marker ceremonial. A commit where
+ * someone saw each before/after and confirmed the prose still holds is the
+ * entire deliverable.
+ *
+ * **Recovering the "before" is the part that is not obvious.** A hash cannot be
+ * turned back into content, so the reviewed version is read out of git: the
+ * commit that introduced this marker value is when the review happened, so the
+ * target file *at that commit* is what the author actually read. Resolving the
+ * same anchor there gives the old slice to diff against.
+ *
+ * **A fired marker is a prompt, not a failure (D7).** The output is a
+ * changed-files list. Framed as a failing test with a red X, authors re-stamp
+ * reflexively to get green — producing markers that certify nothing and cost a
+ * command.
+ */
+import { execSync } from 'node:child_process';
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { BASE_LANGUAGES, compareMarker, formatMarker, hashSlice, maskSource, parseMarker, sliceForInvocation, } from '@refrakt-md/runes';
+import { computeLineDiff, summarizeDiff } from '@refrakt-md/runes';
+const TAG = /\{%\s*(snippet|file-ref)\b([^%]*)%\}/g;
+function attr(attrs, name) {
+    return new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`).exec(attrs)?.[1];
+}
+function collect(dir, repoRoot, out = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            collect(full, repoRoot, out);
+        else if (entry.endsWith('.md'))
+            out.push(relative(repoRoot, full).split(sep).join('/'));
+    }
+    return out;
+}
+/** Every live invocation carrying a `path=`. Fenced ones are examples of the
+ *  syntax rather than references, so they are not marked. */
+function findInvocations(repoRoot, pages) {
+    const found = [];
+    for (const page of pages) {
+        let source;
+        try {
+            source = readFileSync(join(repoRoot, page), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const masked = maskSource(source, BASE_LANGUAGES.markdoc).split('\n');
+        source.split('\n').forEach((line, i) => {
+            if (masked[i] !== line)
+                return;
+            TAG.lastIndex = 0;
+            let m = TAG.exec(line);
+            while (m !== null) {
+                const attrs = m[2];
+                const path = attr(attrs, 'path');
+                if (path) {
+                    found.push({
+                        page,
+                        line: i + 1,
+                        raw: m[0],
+                        rune: m[1],
+                        attrs,
+                        path,
+                        reviewed: attr(attrs, 'reviewed'),
+                    });
+                }
+                m = TAG.exec(line);
+            }
+        });
+    }
+    return found;
+}
+/** Resolve an invocation against a given version of its target file. */
+function sliceFor(inv, fileSource) {
+    // Shared with the staleness ranking (`@refrakt-md/runes`): if the two
+    // resolved an anchor differently, a marker would read as stale on one side
+    // and current on the other.
+    return sliceForInvocation(inv.attrs, inv.path, fileSource);
+}
+function git(command, cwd) {
+    try {
+        return execSync(command, {
+            cwd,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The slice as it stood when the marker was written.
+ *
+ * The commit that introduced this marker value is when the review happened, so
+ * the target file at that commit is what the author actually read. Without this
+ * the tool could only show a hash changing, which D5 forbids.
+ */
+function reviewedSlice(repoRoot, inv) {
+    if (!inv.reviewed)
+        return undefined;
+    const sha = git(`git log -1 --format=%H -S'reviewed="${inv.reviewed}"' -- "${inv.page}"`, repoRoot)?.trim();
+    if (!sha)
+        return undefined;
+    const old = git(`git show ${sha}:"${inv.path}"`, repoRoot);
+    if (old === undefined)
+        return undefined;
+    return sliceFor(inv, old);
+}
+/** Render a unified-ish diff for the terminal. Content, never hashes. */
+export function renderDiff(before, after) {
+    return computeLineDiff(before, after)
+        .map((h) => {
+        if (h.type === 'add')
+            return `+ ${h.text}`;
+        if (h.type === 'remove')
+            return `- ${h.text}`;
+        return `  ${h.text}`;
+    })
+        .join('\n');
+}
+export function runSnippetReview(opts) {
+    const repoRoot = opts.repoRoot ?? process.cwd();
+    const contentDirs = opts.contentDirs ?? ['site/content'];
+    const pages = opts.pages && opts.pages.length > 0
+        ? opts.pages
+        : contentDirs.flatMap((d) => collect(join(repoRoot, d), repoRoot));
+    const result = { findings: [], stamped: 0, restampedSilently: 0, noops: [] };
+    const edits = new Map();
+    for (const inv of findInvocations(repoRoot, pages)) {
+        let fileSource;
+        try {
+            fileSource = readFileSync(join(repoRoot, inv.path), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // D10 — an invocation that cannot change can never fire, so stamping it
+        // means nothing. Report rather than stamp.
+        if (inv.rune === 'expand') {
+            result.noops.push({
+                page: inv.page,
+                line: inv.line,
+                reason: '`expand` embeds a whole document, so there is no slice to hash',
+            });
+            continue;
+        }
+        const current = sliceFor(inv, fileSource);
+        if (current === undefined) {
+            // The anchor refused. SPEC-131 already reports that; this layer
+            // stays silent rather than double-reporting (D9).
+            continue;
+        }
+        const pair = hashSlice(current);
+        if (!inv.reviewed) {
+            // Unmarked. Stamping is only done on request — never in bulk by
+            // default (D8).
+            if (opts.update || opts.check)
+                continue;
+            const stamped = inv.raw.replace(/\s*\/?%\}$/, (tail) => ` reviewed="${formatMarker(pair)}"${tail}`);
+            pushEdit(edits, inv.page, inv.raw, stamped);
+            result.stamped++;
+            continue;
+        }
+        const stored = parseMarker(inv.reviewed);
+        const comparison = compareMarker(stored.strict, current, stored.loose);
+        if (comparison.verdict === 'current')
+            continue;
+        if (comparison.verdict === 'formatting-only') {
+            // Proven formatting-only — re-stamp without prompting (D3). This is
+            // what stops a repo-wide formatter run from costing fifty reviews.
+            if (opts.update) {
+                pushEdit(edits, inv.page, inv.raw, inv.raw.replace(/reviewed="[^"]*"/, `reviewed="${formatMarker(pair)}"`));
+                result.restampedSilently++;
+            }
+            continue;
+        }
+        const before = reviewedSlice(repoRoot, inv);
+        result.findings.push({
+            page: inv.page,
+            line: inv.line,
+            target: inv.path,
+            anchor: attr(inv.attrs, 'symbol') ?? attr(inv.attrs, 'match') ?? inv.path,
+            verdict: 'stale',
+            summary: before ? summarizeDiff(before, current) : 'content changed',
+            diff: before ? renderDiff(before, current) : undefined,
+        });
+        if (opts.update && !opts.interactive) {
+            pushEdit(edits, inv.page, inv.raw, inv.raw.replace(/reviewed="[^"]*"/, `reviewed="${formatMarker(pair)}"`));
+        }
+    }
+    if (!opts.check)
+        applyEdits(repoRoot, edits);
+    return result;
+}
+function pushEdit(edits, page, from, to) {
+    const list = edits.get(page);
+    if (list)
+        list.push({ from, to });
+    else
+        edits.set(page, [{ from, to }]);
+}
+function applyEdits(repoRoot, edits) {
+    for (const [page, list] of edits) {
+        let source = readFileSync(join(repoRoot, page), 'utf8');
+        for (const { from, to } of list)
+            source = source.replace(from, to);
+        writeFileSync(join(repoRoot, page), source, 'utf8');
+    }
+}
+export async function snippetReviewCommand(opts) {
+    const result = runSnippetReview(opts);
+    if (opts.format === 'json') {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        process.exit(opts.check && result.findings.length > 0 ? 1 : 0);
+    }
+    const out = [];
+    if (result.findings.length > 0) {
+        // D7's wording. A changed-files list, not a failing check.
+        out.push(`${result.findings.length} documented region${result.findings.length === 1 ? '' : 's'} changed since last review:`);
+        out.push('');
+        for (const f of result.findings) {
+            out.push(`  ${f.page}:${f.line} — ${f.anchor} (${f.summary})`);
+            if (f.diff && (opts.update || opts.interactive)) {
+                out.push('');
+                for (const line of f.diff.split('\n'))
+                    out.push(`    ${line}`);
+                out.push('');
+            }
+        }
+        out.push('');
+        out.push('Re-read the prose around each, then `refrakt snippet review --update` to re-stamp.');
+    }
+    if (result.stamped > 0)
+        out.push(`Stamped ${result.stamped} unmarked invocation(s).`);
+    if (result.restampedSilently > 0) {
+        out.push(`Re-stamped ${result.restampedSilently} formatting-only change(s) without prompting.`);
+    }
+    for (const n of result.noops) {
+        out.push(`No-op: ${n.page}:${n.line} — ${n.reason}.`);
+    }
+    if (out.length === 0)
+        out.push('All review markers are current.');
+    process.stdout.write(`${out.join('\n')}\n`);
+    // `--check` has its own exit code, independent of the pipeline diagnostic
+    // channel — it is the surface that works in a job.
+    process.exit(opts.check && result.findings.length > 0 ? 1 : 0);
+}
+//# sourceMappingURL=snippet-review.js.map

package/dist/commands/snippet-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet-review.js","sourceRoot":"","sources":["../../src/commands/snippet-review.ts"],"names":[],"mappings":"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"}

package/dist/commands/stale.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `refrakt stale` — staleness ranking for documentation references (SPEC-136,
+ * WORK-594).
+ *
+ * ```
+ * staleness = commits touching the target since the referrer last changed
+ * ```
+ *
+ * **This ranks. It never fails (D1).** No exit code on findings, no build
+ * failure, no required check, not even an opt-in flag to make it failing. The
+ * failure mode of getting that wrong is specific and fatal: the cheapest way to
+ * turn any edge green is to edit the referring page, so a gate would train
+ * people to make trivial documentation edits to clear it — actively destroying
+ * the signal it measures. The measure only survives if nothing depends on it
+ * being zero.
+ *
+ * **A refusal is a different event, and does exit non-zero.** D1 is about
+ * findings. Being unable to run at all — a shallow clone, a non-git tree —
+ * produced no answer, and a CI step that silently succeeds while measuring
+ * nothing is exactly the silent-wrong this feature exists to avoid.
+ */
+export interface StaleOptions {
+    top?: number;
+    class?: string;
+    min?: number;
+    format?: 'text' | 'json';
+    repoRoot?: string;
+    /** Override the content roots taken from `refrakt.config.json`. */
+    contentDirs?: string[];
+}
+export declare function staleCommand(opts: StaleOptions): Promise<void>;
+//# sourceMappingURL=stale.d.ts.map

package/dist/commands/stale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale.d.ts","sourceRoot":"","sources":["../../src/commands/stale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,WAAW,YAAY;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AA0BD,wBAAsB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgGpE"}