@refrakt-md/cli 0.35.0 → 0.37.0

package/dist/bin.js

@@ -24,6 +24,15 @@ else if (command === 'scaffold-css') {
 else if (command === 'validate') {
     runValidate(args.slice(1));
 }
+else if (command === 'stale') {
+    runStale(args.slice(1));
+}
+else if (command === 'migrate' && args[1] === 'snippets') {
+    runMigrateSnippets(args.slice(2));
+}
+else if (command === 'snippet') {
+    runSnippetCommand(args.slice(1));
+}
 else if (command === 'theme') {
     runTheme(args.slice(1));
 }
@@ -73,7 +82,9 @@ Commands:
   contracts [options]  Generate structure contracts from theme config
   i18n <subcommand>    i18n tooling (extract translation keys, check coverage)
   scaffold-css         Generate CSS stub files for all runes
-  validate             Validate theme config and manifest
+  validate             Validate this project's sites (config + content)
+  stale                Rank documentation references by how far their target has moved
+  snippet review       Stamp and check review markers on embedded source
   theme <subcommand>   Manage themes (install, info)
   edit                 Launch the browser-based content editor
   reference <subcommand>  Emit rune syntax reference for authors and AI agents
@@ -123,12 +134,16 @@ Scaffold-CSS Options:
   --force                  Overwrite existing files
 
 Validate Options:
-  --config <path>          Path to theme config module (default: auto-detect)
-  --manifest <path>        Path to manifest.json (default: auto-detect)
+  --site <name>            Restrict to one site from refrakt.config.json
+  --only <content|config>  Narrow to one layer (both run when absent)
+  --deep                   Add cross-page checks (costs a full pipeline run)
+  --format <text|json>     Output format (default: text)
+  --config-path <path>     Path to refrakt.config.json (default: ./refrakt.config.json)
 
 Theme Subcommands:
   theme install <source>   Install a theme (directory, .tgz, or npm package)
   theme info               Show current theme details
+  theme validate           Validate a ThemeConfig and/or theme manifest
 
 Examples:
   refrakt inspect hint --type=warning
@@ -852,47 +867,156 @@ function runScaffoldCss(scaffoldArgs) {
     });
 }
 function runValidate(validateArgs) {
+    let site;
+    let only;
+    let deep = false;
+    let format;
     let configPath;
-    let manifestPath;
     for (let i = 0; i < validateArgs.length; i++) {
         const arg = validateArgs[i];
-        if (arg === '--config') {
-            configPath = validateArgs[++i];
-            if (!configPath) {
-                console.error('Error: --config requires a file path');
+        // SPEC-135 D2 / D12 — retired rather than aliased through a deprecation
+        // window. These check theme-authoring artifacts, and they now live in the
+        // noun group that owns them. Pre-1.0, and the behaviour they hung off was
+        // close to a no-op, so nobody can be meaningfully depending on it; an
+        // alias would keep the audience confusion alive for no one's benefit.
+        if (arg === '--config' || arg === '--manifest') {
+            console.error(`Error: \`${arg}\` has moved to \`refrakt theme validate\`.\n`);
+            console.error(`  refrakt theme validate ${arg} ${validateArgs[i + 1] ?? '<path>'}\n`);
+            console.error('It validates a theme-authoring artifact; `refrakt validate` is the');
+            console.error("site author's command. See SPEC-135 D12.");
+            process.exit(1);
+        }
+        else if (arg === '--site') {
+            site = validateArgs[++i];
+            if (!site) {
+                console.error('Error: --site requires a site name');
                 process.exit(1);
             }
         }
-        else if (arg === '--manifest') {
-            manifestPath = validateArgs[++i];
-            if (!manifestPath) {
-                console.error('Error: --manifest requires a file path');
+        else if (arg === '--only') {
+            const value = validateArgs[++i];
+            if (value !== 'content' && value !== 'config') {
+                console.error('Error: --only must be "content" or "config"');
                 process.exit(1);
             }
+            only = value;
         }
-        else if (arg === '--site') {
-            // Accepted for forward compatibility; theme/manifest validation
-            // operates on explicit paths and is not yet site-scoped.
-            validateArgs[++i];
+        else if (arg === '--deep') {
+            deep = true;
+        }
+        else if (arg === '--format') {
+            const value = validateArgs[++i];
+            if (value !== 'text' && value !== 'json') {
+                console.error('Error: --format must be "text" or "json"');
+                process.exit(1);
+            }
+            format = value;
+        }
+        else if (arg === '--config-path') {
+            configPath = validateArgs[++i];
+            if (!configPath) {
+                console.error('Error: --config-path requires a file path');
+                process.exit(1);
+            }
+        }
+        else if (arg === '--strict') {
+            // SPEC-135 D3 — deliberately absent. `site/` carries 35 warnings, and
+            // a gate that goes red on day one is a gate someone turns off. The
+            // severity levels already say which findings are worth stopping for.
+            console.error('Error: `--strict` does not exist. Warnings never affect the exit code.\n');
+            console.error('Severity already says which findings stop a build: errors fail, warnings');
+            console.error('do not. See SPEC-135 D3.');
+            process.exit(1);
         }
         else if (arg === '--help' || arg === '-h') {
-            printUsage();
+            printValidateUsage();
             process.exit(0);
         }
         else if (arg.startsWith('-')) {
             console.error(`Error: Unknown flag "${arg}"\n`);
-            printUsage();
+            printValidateUsage();
             process.exit(1);
         }
         else {
             console.error(`Error: Unexpected argument "${arg}"\n`);
-            printUsage();
+            printValidateUsage();
             process.exit(1);
         }
     }
     import('./commands/validate.js')
-        .then(({ validateCommand }) => {
-        validateCommand({ configPath, manifestPath });
+        .then(({ validateCommand }) => validateCommand({ site, only, deep, format, configPath }))
+        .catch((err) => {
+        console.error(`\nError: ${err.message}`);
+        process.exit(1);
+    });
+}
+function printValidateUsage() {
+    console.log(`
+Usage: refrakt validate [options]
+
+Validate this project's sites: config resolution, then content, for every site
+in refrakt.config.json.
+
+Options:
+  --site <name>        Restrict to one site
+  --only <what>        "content" or "config" (both run when absent)
+  --deep               Add cross-page checks (broken refs, missing entities).
+                       Costs a full pipeline run; off by default.
+  --format <fmt>       "text" (default) or "json"
+  --config-path <p>    Path to refrakt.config.json (default: ./refrakt.config.json)
+
+Exit code is non-zero when any finding is at error severity, zero otherwise.
+Warnings never affect it.
+
+For theme-authoring artifacts, use \`refrakt theme validate\`.
+`);
+}
+/** `refrakt theme validate` — the theme-authoring checks, moved off the bare
+ *  `validate` command by WORK-579 (SPEC-135 D12). */
+function runThemeValidate(tvArgs) {
+    let configPath;
+    let manifestPath;
+    for (let i = 0; i < tvArgs.length; i++) {
+        const arg = tvArgs[i];
+        if (arg === '--config') {
+            configPath = tvArgs[++i];
+            if (!configPath) {
+                console.error('Error: --config requires a file path');
+                process.exit(1);
+            }
+        }
+        else if (arg === '--manifest') {
+            manifestPath = tvArgs[++i];
+            if (!manifestPath) {
+                console.error('Error: --manifest requires a file path');
+                process.exit(1);
+            }
+        }
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`
+Usage: refrakt theme validate [options]
+
+Validate theme-authoring artifacts. For a site's own content and config, use
+\`refrakt validate\`.
+
+Options:
+  --config <path>     Validate a ThemeConfig JSON file
+  --manifest <path>   Validate a theme manifest
+
+Examples:
+  refrakt theme validate --config ./theme.config.json
+  refrakt theme validate --manifest ./manifest.json
+`);
+            process.exit(0);
+        }
+        else {
+            console.error(`Error: Unexpected argument "${arg}"\n`);
+            process.exit(1);
+        }
+    }
+    import('./commands/theme-validate.js')
+        .then(({ themeValidateCommand }) => {
+        themeValidateCommand({ configPath, manifestPath });
     })
         .catch((err) => {
         console.error(`\nError: ${err.message}`);
@@ -961,6 +1085,7 @@ Subcommands:
   install <source>      Install a theme (directory, .tgz, or npm package name)
   info                  Show current theme details
   list                  List installed themes and the active one
+  validate              Validate a ThemeConfig and/or a theme manifest
   presets list          List presets from installed packs + the active theme
   presets validate      Validate installed preset-pack manifests
 
@@ -977,6 +1102,13 @@ Examples:
 `);
         process.exit(subcommand ? 0 : 1);
     }
+    // `theme validate` — the theme-authoring checks WORK-579 moved here from the
+    // bare `refrakt validate` (SPEC-135 D12). Dispatched before `presets` so
+    // `theme validate` and `theme presets validate` stay distinct.
+    if (subcommand === 'validate') {
+        runThemeValidate(themeArgs.slice(1));
+        return;
+    }
     // `theme presets <list|validate>` — preset-pack discovery/listing (SPEC-111 §4).
     if (subcommand === 'presets') {
         const action = themeArgs[1] ?? 'list';
@@ -1424,4 +1556,271 @@ async function buildReferenceContext(runesModule, assembleThemeConfig, configDir
     }
     return { runes: allRunes, fixtures, source };
 }
+// ─────────────────────────────────────────────────────────────────────
+// `refrakt stale` — SPEC-136 / WORK-594
+// ─────────────────────────────────────────────────────────────────────
+function runStale(staleArgs) {
+    let top;
+    let edgeClass;
+    let min;
+    let format = 'text';
+    for (let i = 0; i < staleArgs.length; i++) {
+        const arg = staleArgs[i];
+        if (arg === '--top') {
+            top = Number(staleArgs[++i]);
+            if (!Number.isInteger(top) || top < 1) {
+                console.error('Error: --top requires a positive integer');
+                process.exit(1);
+            }
+        }
+        else if (arg === '--class') {
+            edgeClass = staleArgs[++i];
+            const known = ['declared', 'embedded', 'described-link', 'prose'];
+            if (!edgeClass || !known.includes(edgeClass)) {
+                console.error(`Error: --class must be one of ${known.join(', ')}`);
+                process.exit(1);
+            }
+        }
+        else if (arg === '--min') {
+            min = Number(staleArgs[++i]);
+            if (!Number.isInteger(min) || min < 1) {
+                console.error('Error: --min requires a positive integer');
+                process.exit(1);
+            }
+        }
+        else if (arg === '--format') {
+            const value = staleArgs[++i];
+            if (value !== 'text' && value !== 'json') {
+                console.error('Error: --format must be "text" or "json"');
+                process.exit(1);
+            }
+            format = value;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            printStaleUsage();
+            process.exit(0);
+        }
+        else {
+            console.error(`Error: Unknown argument "${arg}"\n`);
+            printStaleUsage();
+            process.exit(1);
+        }
+    }
+    import('./commands/stale.js')
+        .then(({ staleCommand }) => staleCommand({ top, class: edgeClass, min, format }))
+        .catch((err) => {
+        console.error(`\nError: ${err.message}`);
+        process.exit(1);
+    });
+}
+function printStaleUsage() {
+    console.log(`
+Usage: refrakt stale [options]
+
+Rank documentation references by how far their target has moved since the page
+last changed:
+
+  staleness = commits touching the target since the referrer last changed
+
+This ranks; it never fails. Findings do not affect the exit code, deliberately:
+the cheapest way to turn an edge green is to edit the referring page, so a gate
+would train people to make trivial documentation edits to clear it, destroying
+the signal it measures.
+
+A refusal is different and does exit non-zero. A shallow clone or a non-git tree
+means the tool could not measure at all, which must not look like a clean
+corpus.
+
+Options:
+  --top <n>        Bound the output (default 10)
+  --class <name>   Narrow to one edge class: declared, embedded,
+                   described-link, prose
+  --min <n>        Floor on the commit count
+  --format <fmt>   text (default) or json
+  -h, --help       Show this help
+
+Content roots come from the sites declared in refrakt.config.json, so a
+multi-site project is scanned whole and nothing needs a flag.
+
+Two optional lists under "stale" in refrakt.config.json narrow what is measured:
+
+  "stale": {
+    "archival":  ["docs/migration/**", "blog/**"],
+    "generated": ["CHANGELOG.md", "**/*.generated.json"]
+  }
+
+  archival   globs matched against the referring PAGE — historical records
+             (changelogs, release notes, migration guides) that are correct as
+             written and must never be updated when the code moves on. Matching
+             pages contribute no edges at all, so they also stop answering the
+             "what documents this file" query.
+  generated  globs matched against the TARGET file — artifacts that change by
+             construction, where "commits since" measures the generator rather
+             than any divergence.
+
+Both default to empty. Neither is a place to put a page that is merely noisy: a
+noisy page means the extraction rule is wrong, or the page's real subject is
+narrower than what it mentions — say so with "documents:" in its frontmatter,
+which replaces every inferred edge for that page. Whatever the lists remove is
+counted in the report footer, so the exclusions cannot quietly grow until the
+report is empty.
+
+Note: a zero score is the absence of evidence of staleness, not evidence of
+freshness. The referrer side resets on any edit to the page.
+`);
+}
+// ─────────────────────────────────────────────────────────────────────
+// `refrakt migrate snippets` — SPEC-131 D7 / WORK-590
+// ─────────────────────────────────────────────────────────────────────
+function runMigrateSnippets(migrateArgs) {
+    let fix = false;
+    let format = 'text';
+    for (const arg of migrateArgs) {
+        if (arg === '--fix')
+            fix = true;
+        else if (arg === '--format=json')
+            format = 'json';
+        else if (arg === '--help' || arg === '-h') {
+            console.log(`
+Usage: refrakt migrate snippets [--fix]
+
+Convert \`lines=\` snippet and file-ref invocations to anchors, verifying that
+the anchored slice is byte-identical to the line-addressed one and refusing to
+rewrite when it is not.
+
+A refusal is information rather than an obstacle: it means the anchor engine
+could not reproduce the slice, which is exactly the case where a human should
+look at what that snippet was pointing at.
+
+Fenced invocations are skipped — they are examples of the syntax, not
+resolvable targets, so they cannot be verified and are rewritten by hand.
+
+This never stamps \`reviewed\` markers (SPEC-134 D8).
+
+Options:
+  --fix            Write the rewrites (default is a dry run)
+  --format=json    Machine-readable output
+`);
+            process.exit(0);
+        }
+        else {
+            console.error(`Error: Unknown argument "${arg}"`);
+            process.exit(1);
+        }
+    }
+    import('./commands/migrate-snippets.js')
+        .then(({ migrateSnippets }) => {
+        const result = migrateSnippets({ fix, format });
+        if (format === 'json') {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        for (const r of result.rewrites) {
+            console.log(`${r.page}:${r.line}`);
+            console.log(`  - ${r.before}`);
+            console.log(`  + ${r.after}`);
+            console.log('');
+        }
+        for (const r of result.refusals) {
+            console.log(`REFUSED ${r.page}:${r.line}`);
+            console.log(`  ${r.invocation}`);
+            console.log(`  ${r.reason}`);
+            console.log('');
+        }
+        const langs = Object.entries(result.languages)
+            .map(([k, v]) => `${k} ${v}`)
+            .join(', ');
+        console.log(`${result.rewrites.length} rewritable, ${result.refusals.length} refused, ` +
+            `${result.skippedFenced} fenced (skipped).`);
+        if (langs)
+            console.log(`Languages reached: ${langs}.`);
+        if (!fix && result.rewrites.length > 0)
+            console.log('Dry run — pass --fix to write.');
+    })
+        .catch((err) => {
+        console.error(`\nError: ${err.message}`);
+        process.exit(1);
+    });
+}
+// ─────────────────────────────────────────────────────────────────────
+// `refrakt snippet review` — SPEC-134 / WORK-591 + WORK-592
+// ─────────────────────────────────────────────────────────────────────
+function runSnippetCommand(snippetArgs) {
+    const sub = snippetArgs[0];
+    if (sub !== 'review') {
+        console.error(`Error: unknown snippet subcommand "${sub ?? ''}"\n`);
+        printSnippetReviewUsage();
+        process.exit(1);
+    }
+    const rest = snippetArgs.slice(1);
+    let all = false;
+    let check = false;
+    let update = false;
+    let interactive = false;
+    let format = 'text';
+    const pages = [];
+    for (const arg of rest) {
+        if (arg === '--all')
+            all = true;
+        else if (arg === '--check')
+            check = true;
+        else if (arg === '--update')
+            update = true;
+        else if (arg === '--interactive')
+            interactive = true;
+        else if (arg === '--format=json')
+            format = 'json';
+        else if (arg === '--help' || arg === '-h') {
+            printSnippetReviewUsage();
+            process.exit(0);
+        }
+        else if (arg.startsWith('-')) {
+            console.error(`Error: Unknown flag "${arg}"\n`);
+            printSnippetReviewUsage();
+            process.exit(1);
+        }
+        else {
+            pages.push(arg);
+        }
+    }
+    import('./commands/snippet-review.js')
+        .then(({ snippetReviewCommand }) => snippetReviewCommand({ pages, all, check, update, interactive, format }))
+        .catch((err) => {
+        console.error(`\nError: ${err.message}`);
+        process.exit(1);
+    });
+}
+function printSnippetReviewUsage() {
+    console.log(`
+Usage: refrakt snippet review [pages...] [options]
+
+Record that a human read a quoted region and confirmed the prose around it
+matched. The marker freezes nothing — the snippet still tracks HEAD and
+re-resolves every build. When the region changes, the marker asks for a
+re-read.
+
+Markers are never hand-written; this command writes them.
+
+  refrakt snippet review site/content/runes/file-ref.md   stamp unmarked
+  refrakt snippet review --all                            stamp every unmarked
+  refrakt snippet review --check                          report, own exit code
+  refrakt snippet review --update --interactive           re-stamp what changed
+
+A change that alters the content but not its meaning — a reformat — is
+re-stamped without prompting, because that is provable rather than a judgement
+made under time pressure. Everything else is held for a human.
+
+Options:
+  --all            Stamp every unmarked invocation (not every invocation)
+  --check          Report stale markers; exits non-zero when any are found
+  --update         Re-stamp what changed, showing the content diff
+  --interactive    Show each held diff one at a time
+  --format=json    Machine-readable output
+  -h, --help       Show this help
+
+Adoption is deliberately selective: mark the references whose prose makes
+specific claims about the code beside them. Marking everything makes --check
+permanently noisy and trains everyone to ignore it.
+`);
+}
 //# sourceMappingURL=bin.js.map