@hawkeyexl/manni 2.0.1 → 2.2.0

package/README.md

@@ -98,7 +98,7 @@ actually reads rather than hand-written:
 ```yaml
 repos:
   - repo: https://github.com/hawkeyexl/manni
-    rev: v2.0.1
+    rev: v2.2.0
     hooks:
       - id: manni-meta
 ```

package/dist/{chunk-MV2T7XAW.js → chunk-2Q5JUEIO.js}

@@ -8,13 +8,20 @@ import {
   DocmetaError,
   FILL_FORMATS,
   FILL_FORMAT_LIST,
+  LOCATION_EXTERNAL_SCHEMA,
+  LOCATION_PAGE_SCHEMA,
   OMITTED_WHEN_CLEAN,
   QUERY_FORMATS,
   QUERY_FORMAT_LIST,
   REPORT_FORMATS,
   REPORT_FORMAT_LIST,
-  ToolError,
-  errorMessage,
+  STDIN_LABEL,
+  Validator,
+  applyRelocation,
+  collectSchemaPins,
+  deriveFailed,
+  fail,
+  formatList,
   getSchemasInfo,
   isCommonFormat,
   isDeriveFormat,
@@ -24,74 +31,37 @@ import {
   isQueryFindingsFormat,
   isQueryFormat,
   isReportFormat,
+  keyHome,
   notice,
+  offerPrompt,
   package_default,
   palette,
+  planRelocation,
   programName,
+  relocateFailed,
+  relocationContext,
   render,
   renderDerive,
   renderFill,
   renderGet,
   renderQuery,
   renderQueryCsv,
+  resolveRunConfig,
   rowsToFindings,
   runDerive,
   runFill,
   runGet,
   runInferSchema,
   runQuery,
+  runRelocate,
   runValidate,
   runVendorSchema,
-  setProgramName,
+  schemaLoadOptions,
   shouldColor,
   supportedExtensions,
   terminalConfirm,
   toJsonText
-} from "./chunk-PDNSN5UJ.js";
-
-// src/shared/run.ts
-import { realpathSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { CommanderError } from "commander";
-function fail(err) {
-  const msg = err instanceof ToolError ? err.message : `Unexpected error: ${errorMessage(err)}`;
-  process.stderr.write(`${programName()}: ${msg}
-`);
-  process.exit(2);
-}
-var STDIN_LINES_MARKER = "\0";
-var STDIN_WITH_LINES = /^-(:[1-9][0-9]*(?:-[1-9][0-9]*)?)$/;
-function normalizeStdinArgv(argv) {
-  return argv.map((arg) => {
-    const lines = STDIN_WITH_LINES.exec(arg)?.[1];
-    return lines === void 0 ? arg : `${STDIN_LINES_MARKER}${lines}`;
-  });
-}
-async function runProgram(program, argv = process.argv) {
-  setProgramName(program.name());
-  try {
-    await program.parseAsync(normalizeStdinArgv(argv));
-  } catch (err) {
-    if (err instanceof CommanderError) {
-      process.exitCode = err.exitCode === 0 ? 0 : 2;
-      return;
-    }
-    throw err;
-  }
-}
-function isMainModule(moduleUrl) {
-  const entry = process.argv[1];
-  if (!entry) return false;
-  try {
-    return realpathSync(entry) === fileURLToPath(moduleUrl);
-  } catch {
-    return false;
-  }
-}
-function runIfMain(moduleUrl, build) {
-  if (!isMainModule(moduleUrl)) return;
-  runProgram(build()).catch(fail);
-}
+} from "./chunk-5O4FIGDJ.js";
 
 // src/meta/cli.ts
 import { existsSync } from "node:fs";
@@ -128,6 +98,238 @@ function reportConfig(toStdout, cwd) {
   };
 }
 
+// src/meta/reporters/relocate.ts
+var RELOCATE_FORMATS = ["pretty", "json"];
+var RELOCATE_FORMAT_LIST = formatList(RELOCATE_FORMATS);
+function isRelocateFormat(value) {
+  return RELOCATE_FORMATS.includes(value);
+}
+function renderRelocate(result, format, opts = {}) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(relocateJson(result), null, 2);
+    case "pretty":
+      return renderRelocatePretty(result, opts);
+    default: {
+      const unreachable = format;
+      throw new DocmetaError(
+        `relocate --format must be pretty or json; got ${JSON.stringify(unreachable)}.`
+      );
+    }
+  }
+}
+function relocateJson(result) {
+  return {
+    dryRun: result.dryRun,
+    config: {
+      file: result.config.file,
+      created: result.config.created,
+      collectionsCreated: result.config.collectionsCreated,
+      pathsAdded: result.config.pathsAdded
+    },
+    manifests: result.manifests.map((m) => ({
+      file: m.file,
+      collection: m.collection,
+      created: m.created,
+      keysAdded: m.keysAdded,
+      keysRemoved: m.keysRemoved,
+      undeclared: m.undeclared
+    })),
+    files: result.files.map((f) => ({
+      file: f.file,
+      moved: f.moved,
+      stayed: f.stayed.map((s) => ({ key: s.key, reason: s.reason }))
+    })),
+    summary: result.summary
+  };
+}
+var plural = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+var list = (xs) => xs.join(", ");
+function renderRelocatePretty(result, opts = {}) {
+  const c = palette(opts.color ?? false);
+  const dry = result.dryRun;
+  const lines = [];
+  if (result.config.created && result.config.file !== null) {
+    lines.push(dry ? `Would create ${result.config.file}.` : `Created ${result.config.file}.`);
+  }
+  const pathsOf = (collection) => result.config.pathsAdded.filter((p) => p.collection === collection).map((p) => p.path);
+  const said = /* @__PURE__ */ new Set();
+  for (const created of result.config.collectionsCreated) {
+    said.add(created.name);
+    const made = result.manifests.filter((m) => m.collection === created.name && m.created);
+    const head = `${dry ? "Would create" : "Created"} collection ${created.name} (paths: ${list(created.paths)})`;
+    if (made.length === 0) {
+      lines.push(`${head}.`);
+      continue;
+    }
+    const owns = list(made.flatMap((m) => m.keys));
+    lines.push(`${head} and ${list(made.map((m) => m.file))}; it ${dry ? "would own" : "owns"} ${owns}.`);
+  }
+  for (const m of result.manifests) {
+    if (said.has(m.collection) && m.created) continue;
+    const added = said.has(m.collection) ? [] : pathsOf(m.collection);
+    if (added.length > 0) said.add(m.collection);
+    const keys = list(m.keys);
+    if (m.created) {
+      if (added.length > 0) {
+        lines.push(
+          dry ? `Would add ${list(added)} to collection ${m.collection}'s paths and create ${m.file}; it would own ${keys}.` : `Added ${list(added)} to collection ${m.collection}'s paths and created ${m.file}; it owns ${keys}.`
+        );
+      } else {
+        lines.push(
+          dry ? `Would create ${m.file}; collections[${m.collection}].externalMetadata[${m.index}] would own ${keys}.` : `Created ${m.file}; collections[${m.collection}].externalMetadata[${m.index}] owns ${keys}.`
+        );
+      }
+      continue;
+    }
+    const beyond = m.beyond > 0 ? `, ${m.beyond} beyond the paths you named` : "";
+    const pronoun = (n) => n === 1 ? "it" : "them";
+    if (m.keysRemoved.length > 0) {
+      const what = `${list(m.keysRemoved)} from ${m.file}'s keys`;
+      const it = pronoun(m.keysRemoved.length);
+      const where = `into every page in collection ${m.collection}${beyond}`;
+      lines.push(dry ? `Would remove ${what}, moving ${it} ${where}.` : `Removing ${what} moves ${it} ${where}.`);
+    }
+    if (added.length > 0) {
+      lines.push(
+        dry ? `Would add ${list(added)} to collection ${m.collection}'s paths; ${m.file} would own ${keys}.` : `Added ${list(added)} to collection ${m.collection}'s paths; ${m.file} now owns ${keys}.`
+      );
+    } else if (m.keysAdded.length > 0) {
+      const what = `${list(m.keysAdded)} to ${m.file}'s keys`;
+      const it = pronoun(m.keysAdded.length);
+      const where = `out of every page in collection ${m.collection}${beyond}`;
+      lines.push(dry ? `Would add ${what}, moving ${it} ${where}.` : `Adding ${what} moves ${it} ${where}.`);
+    }
+    if (m.undeclared) {
+      lines.push(
+        dry ? `${m.file} would no longer own any keys and would no longer be declared; delete it when you are ready.` : `${m.file} no longer owns any keys and is no longer declared; delete it when you are ready.`
+      );
+    }
+  }
+  for (const p of result.config.pathsAdded) {
+    if (said.has(p.collection)) continue;
+    said.add(p.collection);
+    lines.push(`${dry ? "Would add" : "Added"} ${list(pathsOf(p.collection))} to collection ${p.collection}'s paths.`);
+  }
+  const width = Math.max(
+    7,
+    ...result.files.flatMap((f) => [...f.moved, ...f.stayed].map((v) => v.key.length))
+  );
+  const shown = result.files.filter((f) => !f.beyond || f.stayed.length > 0);
+  for (const f of shown) {
+    lines.push(f.file);
+    for (const mv of f.moved) {
+      const name = c.cyan(mv.key.padEnd(width));
+      if (mv.to === "page") {
+        lines.push(`    ${name}  \u2190 ${mv.from}`);
+      } else {
+        lines.push(`    ${name}  \u2192 ${mv.manifest}${mv.line !== void 0 ? `:${mv.line}` : ""}`);
+      }
+    }
+    for (const st of f.stayed) {
+      lines.push(`    ${c.cyan(st.key.padEnd(width))}  ${c.yellow(`stays: ${st.detail ?? st.reason}`)}`);
+    }
+  }
+  const hidden = result.files.length - shown.length;
+  if (hidden > 0) lines.push(`\u2026 (${plural(hidden, "more file")})`);
+  const s = result.summary;
+  if (s.files === 0) {
+    lines.push("0 files, nothing to move");
+    return lines.join("\n");
+  }
+  const moves = result.files.flatMap((f) => f.moved);
+  const toPage = moves.filter((m) => m.to === "page").length;
+  const toManifest = moves.flatMap((m) => m.to === "manifest" ? [m.manifest] : []);
+  const manifests = plural(new Set(toManifest).size, "manifest");
+  let footer = `${plural(s.files, "file")}, ${plural(s.moved, "value")} ${dry ? "would move" : "moved"}`;
+  if (toPage > 0 && toManifest.length > 0) {
+    footer += `: ${toPage} into pages, ${toManifest.length} into ${manifests}`;
+  } else if (toManifest.length > 0) {
+    footer += ` to ${manifests}`;
+  } else if (toPage > 0) {
+    footer += " into pages";
+  }
+  if (s.stayed > 0) footer += `, ${s.stayed} stayed`;
+  lines.push(s.stayed > 0 ? c.yellow(footer) : footer);
+  return lines.join("\n");
+}
+
+// src/meta/commands/validate-offer.ts
+async function offerRelocation(opts) {
+  const { confirm, output } = opts;
+  if (confirm === void 0 || opts.noConfig === true) return [];
+  const findings = opts.results.flatMap(
+    (r) => r.file === STDIN_LABEL ? [] : r.errors.filter((e) => e.schema === LOCATION_EXTERNAL_SCHEMA || e.schema === LOCATION_PAGE_SCHEMA).flatMap((e) => e.subject === void 0 ? [] : [{ file: r.file, key: e.subject, schema: e.schema }])
+  );
+  if (findings.length === 0) return [];
+  const cwd = opts.cwd ?? process.cwd();
+  const run = await resolveRunConfig({
+    cwd,
+    ...opts.configPath !== void 0 ? { configPath: opts.configPath } : {},
+    inputs: opts.inputs,
+    ...opts.collections !== void 0 ? { collections: opts.collections } : {}
+  });
+  const validator = new Validator(
+    schemaLoadOptions({
+      root: run.configDir ?? cwd,
+      fileBase: cwd,
+      ttlHours: run.config?.schemaCache?.ttlHours,
+      offline: opts.offline ?? run.config?.offline,
+      pins: collectSchemaPins(run.config)
+    })
+  );
+  const ctx = relocationContext(run, {
+    cwd,
+    targets: run.fromCollections ? [] : opts.inputs,
+    validator,
+    ...opts.cliSchemas !== void 0 && opts.cliSchemas.length > 0 ? { cliSchemas: opts.cliSchemas } : {},
+    ...opts.as !== void 0 ? { as: opts.as } : {},
+    ...opts.respectGitignore !== void 0 ? { respectGitignore: opts.respectGitignore } : {},
+    ...opts.env !== void 0 ? { env: opts.env } : {}
+  });
+  const groups = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    const home = await keyHome(ctx, f.file, {}, f.key);
+    let collection;
+    if (f.schema === LOCATION_PAGE_SCHEMA) {
+      if (home.kind === "manifest") collection = home.collection;
+    } else if (home.kind === "unowned" && home.home.kind === "collection") {
+      collection = home.home.collection;
+    }
+    if (collection === void 0) continue;
+    const group = groups.get(collection) ?? { files: /* @__PURE__ */ new Set(), keys: /* @__PURE__ */ new Set() };
+    group.files.add(f.file);
+    group.keys.add(f.key);
+    groups.set(collection, group);
+  }
+  const applied = [];
+  const say = (message) => {
+    output.write(`${programName()}: ${message}
+`);
+  };
+  for (const [collection, group] of groups) {
+    let plan;
+    try {
+      plan = await planRelocation(ctx, { files: [...group.files], fields: [...group.keys] });
+    } catch (err) {
+      if (!(err instanceof DocmetaError)) throw err;
+      say(err.message);
+      continue;
+    }
+    if (plan.writes.length === 0) continue;
+    const offer = plan.offers.find((o) => o.collection === collection);
+    if (offer === void 0) continue;
+    const { notice: notice2, question } = offerPrompt(offer, "validate");
+    say(notice2);
+    if (!await confirm(question)) continue;
+    const result = await applyRelocation(ctx, plan);
+    output.write(`${renderRelocatePretty(result, { color: opts.color ?? false })}
+`);
+    applied.push(result);
+  }
+  return applied;
+}
+
 // src/meta/reporters/infer.ts
 var OUTLIERS_SHOWN = 5;
 var ENUM_SHOWN = 3;
@@ -542,6 +744,22 @@ function buildProgram() {
 `);
         }
         process.exitCode = summary.failed > 0 ? 1 : 0;
+        await offerRelocation({
+          results,
+          inputs: paths,
+          cliSchemas: options.schema,
+          as: options.as,
+          collections: options.collection,
+          ...configOption(options.config),
+          respectGitignore: explicitFalse(options.gitignore),
+          offline: options.offline ? true : void 0,
+          confirm: paths.includes(STDIN) ? void 0 : terminalConfirm(),
+          output: process.stderr,
+          color: shouldColor({
+            noColor: (command.parent ?? command).opts().color === false,
+            isTTY: process.stderr.isTTY
+          })
+        });
       } catch (err) {
         fail(err);
       }
@@ -762,7 +980,17 @@ function buildProgram() {
           onNotice: notice,
           // A write to a column marked x-manni-encrypt with no key asks
           // for one on a terminal, and refuses off one (proposal 0045).
-          confirm: terminalConfirm()
+          // The same Confirm asks P1 (proposal 0047).
+          confirm: terminalConfirm(),
+          // An accepted P1 offer prints relocate's report: on stdout
+          // beside a pretty report, on stderr when stdout must parse.
+          onRelocated: (result) => {
+            const text = renderRelocate(result, "pretty", {
+              color: format === "pretty" && resolveColor(command.parent ?? command)
+            });
+            (format === "pretty" ? process.stdout : process.stderr).write(`${text}
+`);
+          }
         });
         if (run.db && sql === "") {
           process.stdout.write(
@@ -926,8 +1154,18 @@ function buildProgram() {
         includeContent: usingStdin,
         // A field marked x-manni-encrypt with no key asks for one on a
         // terminal, and refuses off one (proposal 0045). Reading the page
-        // from stdin leaves no terminal to ask on.
-        confirm: usingStdin ? void 0 : terminalConfirm()
+        // from stdin leaves no terminal to ask on. The same Confirm asks
+        // P1 (proposal 0047).
+        confirm: usingStdin ? void 0 : terminalConfirm(),
+        // An accepted P1 offer prints relocate's report: on stdout beside a
+        // pretty report, on stderr when stdout must parse.
+        onRelocated: (result) => {
+          const text = renderRelocate(result, "pretty", {
+            color: format === "pretty" && resolveColor(command.parent ?? command)
+          });
+          (format === "pretty" ? process.stdout : process.stderr).write(`${text}
+`);
+        }
       });
       const color = resolveColor(command.parent ?? command);
       const report = renderFill(format, run, {
@@ -950,9 +1188,15 @@ function buildProgram() {
   });
   program.command("derive").description(
     "Stamp the managed stewardship fields from git history, CODEOWNERS and GitHub or GitLab reviews"
-  ).argument("[paths...]", "files, directories, or globs to stamp").option(
+  ).argument(
+    "[paths...]",
+    "files, directories, or globs to stamp; <path>:L1-L2 names lines for --generated-by"
+  ).option(
     "--fields <list>",
     "comma-separated managed fields to stamp; config derive.fields otherwise"
+  ).option(
+    "--generated-by <name>",
+    "attribute uncommitted body lines, or a <path>:L1-L2 range, to this machine in provenance; MANNI_GENERATED_BY otherwise"
   ).option(
     "--sources <list>",
     "comma-separated sources to consult: git, codeowners, github, gitlab, command (default all)"
@@ -978,7 +1222,9 @@ function buildProgram() {
       "  manni meta derive --dry-run docs/install.md      # what would change, nothing written",
       "  manni meta derive --check -f github              # CI: a stale stamp is an annotation, exit 1",
       "  manni meta derive --fields reviewed-by,last-reviewed",
-      "  manni meta derive --sources git,codeowners       # no gh on this machine"
+      "  manni meta derive --sources git,codeowners       # no gh on this machine",
+      "  MANNI_GENERATED_BY=claude-fable-5 manni meta derive --fields provenance",
+      "  manni meta derive docs/limits.md:12-31 --generated-by claude-fable-5"
     ].join("\n")
   ).action(async (paths, options, command) => {
     try {
@@ -998,6 +1244,7 @@ function buildProgram() {
         inputs: paths,
         fields: options.fields ? splitList(options.fields) : void 0,
         sources: options.sources ? splitList(options.sources) : void 0,
+        ...options.generatedBy !== void 0 ? { generatedBy: options.generatedBy } : {},
         dryRun: Boolean(options.dryRun),
         check: Boolean(options.check),
         cache: options.cache,
@@ -1011,8 +1258,18 @@ function buildProgram() {
         respectGitignore: explicitFalse(options.gitignore),
         onNotice: notice,
         // A field its schema marks x-manni-encrypt (proposal 0045) with no
-        // key yet: asked on a terminal, refused off one.
-        confirm: terminalConfirm()
+        // key yet: asked on a terminal, refused off one. The same Confirm
+        // asks P1 (proposal 0047).
+        confirm: terminalConfirm(),
+        // An accepted P1 offer prints relocate's report: on stdout beside a
+        // pretty report, on stderr when stdout must parse.
+        onRelocated: (result) => {
+          const text2 = renderRelocate(result, "pretty", {
+            color: format === "pretty" && resolveColor(command.parent ?? command)
+          });
+          (format === "pretty" ? process.stdout : process.stderr).write(`${text2}
+`);
+        }
       });
       const text = renderDerive(run, format, {
         color: resolveColor(command.parent ?? command),
@@ -1023,9 +1280,73 @@ function buildProgram() {
         process.stdout.write(`${text}
 `);
       }
-      const { stale, unset, errors } = run.summary;
-      const failed = errors > 0 || options.check && stale + unset > 0;
-      process.exitCode = failed ? 1 : 0;
+      process.exitCode = deriveFailed(run) ? 1 : 0;
+    } catch (err) {
+      fail(err);
+    }
+  });
+  program.command("relocate").description(
+    "Move each value to where its schema's x-manni-location and the config's manifests say it belongs"
+  ).argument(
+    "[paths...]",
+    "files, directories, or globs to relocate (stdin is refused)"
+  ).option(
+    "--fields <list>",
+    "comma-separated fields to move; each must be marked x-manni-location or manifest-owned"
+  ).option(
+    "--collection <name>",
+    "configured collection to run over; repeatable",
+    collect,
+    []
+  ).option(
+    "-s, --schema <ref>",
+    "schema to judge preferences against; repeatable; overrides $schema/config",
+    collect,
+    []
+  ).option("--dry-run", "report what would move and be created, and write nothing").option(
+    "-f, --format <format>",
+    `output: ${RELOCATE_FORMATS.join(" | ")}`,
+    "pretty"
+  ).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("-c, --config <path>", "path to a manni config file").option("--no-config", "ignore any discovered config file (refused: relocate writes the config)").option("--allow-empty", "treat zero matched files as success").option("--no-gitignore", "relocate files .gitignore covers").addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  manni meta relocate                              # every collection, as config declares it",
+      "  manni meta relocate --dry-run                    # what would move and be created",
+      "  manni meta relocate docs/install.md --fields owner",
+      "  manni meta relocate docs/ guides/intro.md        # no collections yet: creates collection default",
+      "  manni meta relocate -f json --dry-run            # the scripting form"
+    ].join("\n")
+  ).action(async (paths, options, command) => {
+    try {
+      const format = options.format;
+      if (!isRelocateFormat(format)) {
+        throw new DocmetaError(
+          `relocate --format must be pretty or json; got "${format}".`
+        );
+      }
+      const result = await runRelocate({
+        inputs: paths,
+        fields: options.fields ? splitList(options.fields) : void 0,
+        collections: options.collection,
+        cliSchemas: options.schema,
+        dryRun: Boolean(options.dryRun),
+        exts: options.ext ? splitList(options.ext) : void 0,
+        exclude: options.exclude,
+        as: options.as,
+        ...configOption(options.config),
+        onConfigLoaded: reportConfig(format === "pretty", process.cwd()),
+        allowEmpty: options.allowEmpty ? true : void 0,
+        respectGitignore: explicitFalse(options.gitignore),
+        onNotice: notice
+      });
+      const text = renderRelocate(result, format, {
+        color: resolveColor(command.parent ?? command)
+      });
+      process.stdout.write(`${text}
+`);
+      process.exitCode = relocateFailed(result) ? 1 : 0;
     } catch (err) {
       fail(err);
     }
@@ -1195,9 +1516,6 @@ function buildProgram() {
 }
 
 export {
-  fail,
-  STDIN_LINES_MARKER,
-  runIfMain,
   collect,
   splitList,
   readStdin,
@@ -1206,4 +1524,4 @@ export {
   reportConfig,
   buildProgram
 };
-//# sourceMappingURL=chunk-MV2T7XAW.js.map
+//# sourceMappingURL=chunk-2Q5JUEIO.js.map