@hawkeyexl/manni 3.0.0 → 4.0.0

package/dist/cli.js

@@ -7,40 +7,55 @@ import {
   readStdin,
   reportConfig,
   splitList
-} from "./chunk-G7INFKNJ.js";
+} from "./chunk-J3KIKNWZ.js";
 import {
   CiteError,
+  INFER_FORMATS,
   KeyError,
+  LINT_JOBS,
+  LintError,
   RULE_ID_PREFIX,
   SEVERITIES,
   SEVERITY_LIST,
+  TOOLS_BY_JOB,
   asCiteError,
   codeEndAt,
   codeRegions,
   errorSite,
   findingMessage,
   isCiteRule,
+  isInferFormat,
   isSeverity,
+  loadConfig,
   meetsSeverity,
+  rebaseConfig,
+  render,
   renderCheckGithub,
   renderCheckJson,
   renderCheckPretty,
   renderRemoveJson,
   renderRemovePretty,
+  renderTemplates,
+  renderTools,
   renderUpdateJson,
   renderUpdatePretty,
+  resolveStructureTool,
   runAdd,
   runCheck,
   runKeyRotate,
   runKeySet,
+  runLint,
   runRemove,
+  runTemplates,
+  runTemplatesInfer,
+  runTools,
   runUpdate,
   shortCommit,
   shortLine,
   shortPin,
   shortSrc,
   spellSource
-} from "./chunk-W75SLU7Z.js";
+} from "./chunk-YDUFTHBZ.js";
 import {
   COMMON_FORMAT_LIST,
   CONCEPT_FIELDS,
@@ -85,10 +100,10 @@ import {
   terminalConfirm,
   valeConfigPath,
   valueAt
-} from "./chunk-I6PYC7EP.js";
+} from "./chunk-O7RMPQZ4.js";
 
 // src/cli.ts
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 
 // src/a11y/cli.ts
 import { Command } from "commander";
@@ -843,7 +858,7 @@ var A11Y_FORMAT_LIST = A11Y_FORMATS.join(" | ");
 function isA11yFormat(value) {
   return A11Y_FORMATS.includes(value);
 }
-function render(format, run, opts) {
+function render2(format, run, opts) {
   switch (format) {
     case "pretty":
       return renderPretty(run, opts);
@@ -1094,7 +1109,7 @@ function buildProgram2() {
         { analyzer: createPlaywrightAnalyzer(), onProgress: progress.listener }
       );
       const color = resolveColor(parent, process.stdout);
-      const text2 = render(format, run, { color, quiet: Boolean(options.quiet) });
+      const text2 = render2(format, run, { color, quiet: Boolean(options.quiet) });
       if (text2.length > 0 || format !== "github") {
         process.stdout.write(`${text2}
 `);
@@ -1750,8 +1765,286 @@ function buildProgram4() {
   return program;
 }
 
-// src/term/cli.ts
+// src/lint/cli.ts
 import { Command as Command4 } from "commander";
+var LIST_FORMATS = /* @__PURE__ */ new Set(["pretty", "json"]);
+var TOOL_OPTIONS_GROUP = "Tool options:";
+function resolveColor2(program) {
+  const noColor = program.opts().color === false;
+  return shouldColor({ noColor, isTTY: process.stdout.isTTY });
+}
+function reportFormat(value) {
+  const format = String(value);
+  if (!isReportFormat(format)) {
+    throw new LintError(
+      `Unknown --format "${format}". Use ${REPORT_FORMAT_LIST}.`
+    );
+  }
+  return format;
+}
+function omittedWhenClean(format) {
+  return format !== "explain" && OMITTED_WHEN_CLEAN.has(format);
+}
+function listFormat(value) {
+  const format = String(value);
+  if (!LIST_FORMATS.has(format)) {
+    throw new LintError(
+      `Unknown --format "${format}". Use pretty or json.`
+    );
+  }
+  return format;
+}
+function inferFormat(value) {
+  const format = String(value);
+  if (!isInferFormat(format)) {
+    throw new LintError(`Unknown --format "${format}". Use yaml or json.`);
+  }
+  return format;
+}
+function assertStructureTool(value) {
+  if (value === void 0) return;
+  resolveStructureTool(value);
+}
+function withConfigOptions(command) {
+  return command.option("-c, --config <path>", "path to a manni config file").option("--no-config", "ignore any discovered config file");
+}
+function optionValue(command, key) {
+  for (let cmd = command; cmd !== null; cmd = cmd.parent ?? null) {
+    if (cmd.getOptionValueSource(key) === "cli") return cmd.getOptionValue(key);
+  }
+  return command.getOptionValue(key);
+}
+function withInputOptions(command) {
+  command.argument(
+    "[paths...]",
+    "files, directories, or globs to lint (use - for stdin)"
+  ).option(
+    "--collection <name>",
+    "configured collection to run over; repeatable",
+    collect,
+    []
+  ).option("--ext <list>", "comma-separated extensions for directory walks").option("--exclude <glob>", "glob to exclude; repeatable", collect, []).option("--as <format>", "force an input format (e.g. markdown, mdx)").option(
+    "-f, --format <format>",
+    `output: ${REPORT_FORMATS.join(" | ")}`,
+    "pretty"
+  );
+  return withConfigOptions(command).option("--allow-empty", "treat zero matched files as success").option("--no-gitignore", "lint files .gitignore covers");
+}
+function inputOptions(paths, options) {
+  return {
+    inputs: paths,
+    collection: options.collection,
+    ...options.ext ? { exts: splitList(options.ext) } : {},
+    exclude: options.exclude,
+    ...options.as === void 0 ? {} : { as: options.as },
+    ...configOption(options.config),
+    // `undefined` rather than `false` when absent, so config still wins.
+    ...options.allowEmpty ? { allowEmpty: true } : {},
+    respectGitignore: explicitFalse(options.gitignore),
+    onNotice: notice
+  };
+}
+function buildProgram5() {
+  const program = new Command4();
+  program.name("lint").description(
+    "Validate document structure against doctype templates. Deterministic, CI-friendly."
+  ).version(package_default.version, "-V, --version").option("--no-color", "disable colored output").showHelpAfterError().exitOverride();
+  const lint = async (paths, options, command, job = {}) => {
+    const tool = job.tool;
+    const format = reportFormat(options.format);
+    const explain = tool?.explain === true;
+    const stdinContent = paths.includes(STDIN_TOKEN) ? await readStdin() : void 0;
+    const cwd = process.cwd();
+    const run = await runLint({
+      ...inputOptions(paths, options),
+      ...tool?.tool === void 0 ? {} : { tool: tool.tool },
+      ...tool?.template === void 0 ? {} : { template: tool.template },
+      ...tool && tool.templates.length > 0 ? { templates: tool.templates } : {},
+      ...explain ? { explain: true } : {},
+      ...stdinContent === void 0 ? {} : { stdinContent },
+      // Which config governed the run, said where a report cannot be parsed
+      // around: discovery walks up to the project boundary, so an unexpected
+      // ancestor config is the difference between a five-minute diagnosis and
+      // an hour of confusion.
+      onConfigLoaded: reportConfig(format === "pretty", cwd)
+    });
+    const color = resolveColor2(command.parent ?? command);
+    const chosen = explain ? "explain" : format;
+    const text2 = render(run, chosen, { color });
+    if (text2.length > 0 || !omittedWhenClean(chosen)) {
+      process.stdout.write(`${text2}
+`);
+    }
+    process.exitCode = explain ? 0 : run.summary.failed > 0 ? 1 : 0;
+  };
+  withInputOptions(
+    program.command("check").description("Run every configured lint job over the given files/dirs/globs")
+  ).addHelpText(
+    "after",
+    [
+      "",
+      "Jobs: structure.",
+      "",
+      "Examples:",
+      "  manni lint check docs/                          # every configured job",
+      "  manni lint check                                # targets from collections:",
+      "  manni lint check --collection guides",
+      '  manni lint check "**/*.md" -f github            # CI annotations',
+      "  cat page.md | manni lint check - --as markdown"
+    ].join("\n")
+  ).action(async (paths, options, command) => {
+    try {
+      if (options.format === "pretty") {
+        process.stderr.write(`Checked: ${LINT_JOBS.join(", ")}.
+`);
+      }
+      await lint(paths, options, command);
+    } catch (err) {
+      fail(err);
+    }
+  });
+  const structure = withInputOptions(
+    program.command("structure").description(
+      "Lint document structure against doctype templates, routing each page by its `type`"
+    )
+  );
+  structure.optionsGroup(TOOL_OPTIONS_GROUP).option(
+    "--tool <name>",
+    `tool that performs the job: ${TOOLS_BY_JOB.structure.join(", ")}`
+  ).option(
+    "-t, --template <ref>",
+    "apply this template to every file, overriding type routing"
+  ).option(
+    "--templates <path>",
+    "template file to route by: its `types:` win over built-ins; repeatable",
+    collect,
+    []
+  ).option(
+    "--explain",
+    "print how each file's template was chosen, and lint nothing (always exits 0, unrouted pages included)"
+  ).addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni lint structure docs/                               # route each page by its `type`",
+      "  manni lint structure docs/ --templates ./templates.yaml  # add your own templates",
+      "  manni lint structure                                     # targets from collections:",
+      "  manni lint structure docs/ --explain                     # show why each page routed where",
+      "  manni lint structure page.md -t tgdp:how-to:1.6          # force one template",
+      '  manni lint structure "**/*.md" -f github                 # CI annotations',
+      "  manni lint structure docs/ --exclude '**/drafts/**'",
+      "  cat page.md | manni lint structure - -t tgdp:how-to:1.6 --as markdown"
+    ].join("\n")
+  ).action(
+    async (paths, options, command) => {
+      try {
+        assertStructureTool(options.tool);
+        await lint(paths, options, command, { tool: options });
+      } catch (err) {
+        fail(err);
+      }
+    }
+  );
+  const templates = program.command("templates").description("List the templates that can be applied, and the types they serve").option(
+    "--templates <path>",
+    "also list the templates in this file; repeatable",
+    collect,
+    []
+  );
+  withConfigOptions(templates).option("-f, --format <format>", "output: pretty | json", "pretty").action(async (options, command) => {
+    try {
+      const format = listFormat(options.format);
+      const { configPath, noConfig } = configOption(options.config);
+      const found = noConfig ? null : await loadConfig(configPath);
+      const info = await runTemplates({
+        templates: options.templates.length > 0 ? options.templates : rebaseConfig(found).templates
+      });
+      const color = resolveColor2(command.parent ?? command);
+      process.stdout.write(`${renderTemplates(info, format, { color })}
+`);
+    } catch (err) {
+      fail(err);
+    }
+  });
+  const inferCommand = templates.command("infer").description("Write a first template from a page that already has the shape you want").argument("<page>", "one file to infer from (use - for stdin)").option("--as <format>", "force an input format (e.g. markdown, mdx)").option(
+    "--name <name>",
+    "name for the template; defaults to the page's `type`, else its filename"
+  ).option("-f, --format <format>", `output: ${INFER_FORMATS.join(" | ")}`, "yaml").option("-o, --out <path>", "write the template here instead of to stdout").option("--force", "overwrite the --out path");
+  withConfigOptions(inferCommand).addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni lint templates infer docs/guides/install.md",
+      "  manni lint templates infer docs/guides/install.md --name how-to",
+      "  manni lint templates infer page.mdx -f json",
+      "  manni lint templates infer page.md -o ./templates.yaml",
+      "  manni lint templates infer page.md -o ./templates.yaml --force",
+      "  cat page.md | manni lint templates infer - --as markdown",
+      "",
+      "One page, and every rule it writes is exactly one occurrence: a single",
+      "page cannot show what varies. Loosening a heading into a list or a",
+      "pattern, setting `min: 0`, and adding a trailing rule with no heading",
+      "for the sections that may follow are your edits to make."
+    ].join("\n")
+  ).action(
+    async (page, options, command) => {
+      try {
+        const format = inferFormat(optionValue(command, "format"));
+        const { configPath, noConfig } = configOption(
+          optionValue(command, "config")
+        );
+        const stdinContent = page === STDIN_TOKEN ? await readStdin() : void 0;
+        const result = await runTemplatesInfer({
+          page,
+          format,
+          ...options.as === void 0 ? {} : { as: options.as },
+          ...options.name === void 0 ? {} : { name: options.name },
+          ...options.out === void 0 ? {} : { out: options.out },
+          ...options.force === void 0 ? {} : { force: options.force },
+          ...configPath === void 0 ? {} : { configPath },
+          ...noConfig === void 0 ? {} : { noConfig },
+          ...stdinContent === void 0 ? {} : { stdinContent },
+          // The template is the primary output, so with no --out it owns
+          // stdout and the config line goes to stderr beside it. With --out
+          // stdout is free, and the line still belongs on stderr: a reader
+          // piping nothing is not a reason to move a diagnostic.
+          onConfigLoaded: reportConfig(false, process.cwd())
+        });
+        if (result.written === void 0) {
+          process.stdout.write(result.text);
+          return;
+        }
+        process.stderr.write(
+          `Wrote template "${result.name}" to ${result.written}
+`
+        );
+      } catch (err) {
+        fail(err);
+      }
+    }
+  );
+  withConfigOptions(
+    program.command("tools").description(
+      "List the lint jobs, the tool that performs each, and what it reads"
+    )
+  ).option("-f, --format <format>", "output: pretty | json", "pretty").action(async (options, command) => {
+    try {
+      const format = listFormat(options.format);
+      const tools = await runTools(configOption(options.config));
+      const color = resolveColor2(command.parent ?? command);
+      process.stdout.write(`${renderTools(tools, format, { color })}
+`);
+    } catch (err) {
+      fail(err);
+    }
+  });
+  return program;
+}
+
+// src/term/cli.ts
+import { Command as Command5 } from "commander";
 
 // src/term/commands/check.ts
 import { existsSync as existsSync2 } from "node:fs";
@@ -4702,9 +4995,9 @@ var INTERCHANGE_LABELS = {
 };
 function rendered(writers, format, construct) {
   return writers.some((writer) => {
-    const render2 = DOCUMENT_RENDERS[writer.format];
-    if (render2?.input !== format) return false;
-    return writer.shapes.some((shape) => render2.shapes[shape] === construct);
+    const render3 = DOCUMENT_RENDERS[writer.format];
+    if (render3?.input !== format) return false;
+    return writer.shapes.some((shape) => render3.shapes[shape] === construct);
   });
 }
 function listFormats(opts = {}) {
@@ -4997,7 +5290,7 @@ async function lintTermSet(set, opts = {}) {
 }
 
 // src/term/commands/lint.ts
-async function runLint(opts) {
+async function runLint2(opts) {
   const { cwd, run, set } = await loadTerms(opts);
   const valeConfig = valeConfigFor(run);
   const findings = await lintTermSet(set, {
@@ -5019,7 +5312,7 @@ async function runLint(opts) {
 }
 
 // src/term/commands/list.ts
-var LIST_FORMATS = ["pretty", "json", "csv"];
+var LIST_FORMATS2 = ["pretty", "json", "csv"];
 async function runList(opts) {
   const { set } = await loadTerms(opts);
   return { terms: set.terms, set };
@@ -5143,14 +5436,14 @@ async function runWrite(opts) {
   const shape = format === "vale" || /[\\/]$/.test(opts.out ?? "") || isDirectory(targetPath) ? "directory" : "file";
   const target = { path: targetPath, shape };
   const existing = await existingFor(target);
-  let render2;
+  let render3;
   try {
-    render2 = writer.render(set.terms, target, { existing });
+    render3 = writer.render(set.terms, target, { existing });
   } catch (error) {
     if (error instanceof TermError) throw relativized(error, [...existing.keys(), targetPath], cwd);
     throw error;
   }
-  const changes = await applyChanges(render2.files, render2.removals, existing, cwd, !check && !dryRun);
+  const changes = await applyChanges(render3.files, render3.removals, existing, cwd, !check && !dryRun);
   const shown = format === "vale" ? displayPath(join4(targetPath, STYLE2), cwd) : opts.out ?? displayPath(targetPath, cwd);
   return {
     mode: "render",
@@ -5159,11 +5452,11 @@ async function runWrite(opts) {
     target: shown,
     terms: set.terms.length,
     changes,
-    files: render2.files.map((file) => ({ path: displayPath(file.path, cwd), content: file.content })),
+    files: render3.files.map((file) => ({ path: displayPath(file.path, cwd), content: file.content })),
     // A Vale style holds designations only, by design; its dropped definitions are not news.
-    dropped: format === "vale" ? [] : render2.dropped,
+    dropped: format === "vale" ? [] : render3.dropped,
     droppedFrom: droppedFrom(format, shape, readers),
-    skipped: render2.skipped,
+    skipped: render3.skipped,
     check,
     dryRun,
     ...wiring === void 0 ? {} : { wiring }
@@ -5630,12 +5923,12 @@ function renderFindings(report, format, options, references2) {
   if (text2.length > 0 || !OMITTED_WHEN_CLEAN.has(format)) print(text2);
   process.exitCode = report.summary.failed > 0 ? 1 : 0;
 }
-function buildProgram5() {
-  const program = new Command4();
+function buildProgram6() {
+  const program = new Command5();
   program.name("term").description("Check, lint and render a docset's terms and the references into them.").version(package_default.version, "-V, --version").showHelpAfterError("(add --help for usage)").exitOverride();
   withInputs(
     program.command("list").description("List the resolved entries").argument("[paths...]", "files, directories, or globs to read (use - for stdin)")
-  ).option("-f, --format <format>", `output: ${LIST_FORMATS.join(" | ")}`, "pretty").addHelpText(
+  ).option("-f, --format <format>", `output: ${LIST_FORMATS2.join(" | ")}`, "pretty").addHelpText(
     "after",
     [
       "",
@@ -5646,7 +5939,7 @@ function buildProgram5() {
     ].join("\n")
   ).action(async (paths, options) => {
     try {
-      const format = formatChoice(options.format, LIST_FORMATS);
+      const format = formatChoice(options.format, LIST_FORMATS2);
       const { terms } = await runList(await coreOptions(paths, options));
       print(format === "json" ? renderListJson(terms) : format === "csv" ? renderListCsv(terms) : renderListPretty(terms));
       process.exitCode = 0;
@@ -5700,7 +5993,7 @@ function buildProgram5() {
   ).action(async (paths, options) => {
     try {
       const format = formatChoice(options.format, FINDING_FORMATS);
-      const report = await runLint(await coreOptions(paths, options));
+      const report = await runLint2(await coreOptions(paths, options));
       renderFindings(report, format, options, false);
     } catch (err) {
       fail(err);
@@ -5749,12 +6042,12 @@ function buildProgram5() {
 }
 
 // src/cli.ts
-function buildProgram6() {
+function buildProgram7() {
   const meta = buildProgram().name("meta").description(
     "Validate, read, query and fill document metadata against JSON Schema"
   );
   const metaCommands = new Set(meta.commands.map((c) => c.name()));
-  const program = new Command5();
+  const program = new Command6();
   program.name("manni").description("Tools for documentation that is meant to be checked.").version(package_default.version, "-V, --version").showHelpAfterError("(add --help for usage)").exitOverride().configureOutput({
     outputError: (str, write) => {
       write(str);
@@ -5780,15 +6073,20 @@ function buildProgram6() {
     )
   );
   program.addCommand(
-    buildProgram5().name("term").description("Check, lint and render a docset's terms and the references into them")
+    buildProgram5().name("lint").description(
+      "Validate document structure against doctype templates, routed by a page's type"
+    )
+  );
+  program.addCommand(
+    buildProgram6().name("term").description("Check, lint and render a docset's terms and the references into them")
   );
   program.addCommand(
     buildProgram4().name("key").description("Set and rotate the family key that encrypted values are encrypted with.")
   );
   return program;
 }
-runIfMain(import.meta.url, buildProgram6);
+runIfMain(import.meta.url, buildProgram7);
 export {
-  buildProgram6 as buildProgram
+  buildProgram7 as buildProgram
 };
 //# sourceMappingURL=cli.js.map