@metaobjectsdev/cli 1.0.9-rc.4 → 1.0.9-rc.6

package/src/commands/generator.ts

@@ -0,0 +1,390 @@
+// `meta generator new <name>` — scaffold a generator of YOUR OWN (ADR-0034 Amendment 4).
+//
+// MetaObjects' product is the core — the model, loader, `verify`, `migrate`, render and
+// extract. Every output an application needs beyond the reference generators (OpenAPI, JSON
+// Schema, a client, a DTO layer, docs) is a generator the adopter writes. This command makes
+// the first minute of that cheap: it writes a working, commented generator into
+// codegen/generators/ and wires it into metaobjects.config.ts, so `meta gen` runs it and
+// `meta verify --codegen` gates it before the author has changed a line.
+//
+// It is deliberately NOT eject: eject copies a reference generator; this writes a new one.
+// The two share only the dependency report.
+
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { catalogEntry } from "../lib/catalog.js";
+import { log } from "../lib/log.js";
+import { dependencyNotesForTemplate } from "./eject.js";
+import {
+  CONFIG_FILE,
+  GENERATOR_OPTIONS,
+  GENERATOR_SCOPES,
+  OWNED_GENERATORS_DIR,
+  type GeneratorScope,
+} from "./generator-help.js";
+
+export { GENERATOR_HELP, GENERATOR_OPTIONS, GENERATOR_SCOPES, OWNED_GENERATORS_DIR } from "./generator-help.js";
+export type { GeneratorScope } from "./generator-help.js";
+
+const NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/** kebab-case → the exported factory's name: `json-schema` → `jsonSchemaGenerator`. */
+export function factoryNameFor(name: string): string {
+  const camel = name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+  return `${camel}Generator`;
+}
+
+// ---------------------------------------------------------------------------
+// The skeleton
+// ---------------------------------------------------------------------------
+
+const HEADER = (name: string, scope: GeneratorScope) => `// ${name} — a generator of your own. It is yours: edit it freely; no MetaObjects release
+// changes it. Scaffolded by \`meta generator new ${name} --scope ${scope}\`.
+//
+// HOW IT RUNS. metaobjects.config.ts lists it in \`generators: [...]\`. \`meta gen\` calls
+// generate() with the loaded model and writes each returned { path, content } under outDir
+// (paths are relative to it). \`meta verify --codegen\` re-runs it and fails when committed
+// output is stale — nothing to register for that. Typecheck this file with
+//   npx tsc -p tsconfig.codegen.json
+// because \`meta gen\` loads it WITHOUT typechecking.
+//
+// READING THE MODEL (it is read-only — never mutate it):
+//   ctx.entities            EVERY object: entities, value objects, projections AND abstract
+//                           bases. The \`filter\` below decides which ones you get.
+//   obj.name / effectivePackage(obj)       the object's name and its package (or undefined)
+//   obj.fields()            all fields, INCLUDING those inherited through \`extends\`
+//   field.subType           "string" | "long" | "enum" | "object" | ... (\`meta types field\`)
+//   field.isRequired, field.maxLength, field.precision, field.scale
+//   field.resolvedIsArray() array-ness, inherited too
+//   field.attr("description")   any attribute's effective value (own, else inherited)
+//   enumValues(field)       a field.enum's members
+//   objectRefTarget(field)  the object a field.object points at (package-aware)
+//   obj.primaryIdentity()?.fields          the primary-key field names
+//
+// THE ONE RULE (ADR-0039): always read through the accessors above. The own*() forms
+// (ownFields, ownAttr, ownChildren) and the raw \`isArray\` flag skip everything an object or
+// field inherits through \`extends\` — the output compiles and is silently wrong.
+//
+// NAMING: toCamelCase / toPascalCase / toSnakeCase / pluralize, and servedPath(obj, prefix)
+// for the REST address the reference routes serve, all from "@metaobjectsdev/codegen-ts".
+// The config's apiPrefix reaches you as ctx.renderContext?.apiPrefix.
+`;
+
+/** Exactly the names the scope's skeleton uses — an unused import fails a strict tsconfig. */
+function importsFor(scope: GeneratorScope): string {
+  const names = ["effectivePackage", "enumValues", "isAbstract", "objectRefTarget", HELPER_BY_SCOPE[scope]];
+  if (scope !== "model") names.push("packageToPath");
+  const list = names.sort().map((n) => `  ${n},\n`).join("");
+  return `import {\n${list}  type Generator,\n} from "@metaobjectsdev/codegen-ts";\n` +
+    `import type { MetaField, MetaObject } from "@metaobjectsdev/metadata";\n`;
+}
+
+const DESCRIBE_FIELD = `
+/** One field, described. Replace this with whatever your output needs per field. */
+function describeField(field: MetaField): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    name: field.name,
+    type: field.subType,
+    required: field.isRequired,
+    array: field.resolvedIsArray(),
+  };
+  if (field.maxLength !== undefined) out.maxLength = field.maxLength;
+  const members = enumValues(field);
+  if (members !== undefined) out.values = members;
+  const target = objectRefTarget(field);
+  if (target !== undefined) out.ref = target.resolutionKey();
+  return out;
+}
+
+const describeObject = (obj: MetaObject) => ({
+  name: obj.name,
+  package: effectivePackage(obj) ?? null,
+  fields: obj.fields().map(describeField),
+});
+`;
+
+const FACTORY_HEAD = (name: string, factory: string) => `
+export interface ${factory.charAt(0).toUpperCase()}${factory.slice(1)}Opts {
+  /** Narrow which objects this generator sees (ANDed with the default filter below). */
+  filter?: (obj: MetaObject) => boolean;
+  /** Named output target from the config's \`targets\`; omit for the top-level outDir. */
+  target?: string;
+}
+
+export function ${factory}(opts: ${factory.charAt(0).toUpperCase()}${factory.slice(1)}Opts = {}): Generator {
+  const generator: Generator = {
+    name: "${name}",
+    // Which objects: here, every concrete one. Abstract bases only contribute fields to
+    // what \`extends\` them. Other predicates to compose: hasAnyRdbSource (persisted),
+    // servesReadApi / servesWriteApi (has reference routes), isProjection.
+    filter: (obj) => !isAbstract(obj) && (opts.filter?.(obj) ?? true),
+`;
+
+const FACTORY_TAIL = `  };
+  if (opts.target !== undefined) generator.target = opts.target;
+  return generator;
+}
+`;
+
+const GENERATE_BY_SCOPE: Record<GeneratorScope, (name: string) => string> = {
+  entity: (name) => `    // perEntity: generate() runs once per matched object; return one file (or an array).
+    generate: perEntity((obj) => {
+      const pkg = effectivePackage(obj);
+      const dir = pkg === undefined ? "${name}" : \`${name}/\${packageToPath(pkg)}\`;
+      return {
+        path: \`\${dir}/\${obj.name}.json\`,
+        content: \`\${JSON.stringify(describeObject(obj), null, 2)}\\n\`,
+      };
+    }),
+`,
+  package: (name) => `    // perPackage: generate() runs once per metadata package with that package's objects.
+    generate: perPackage((pkg, objects) => ({
+      path: \`${name}/\${pkg === "" ? "_root" : packageToPath(pkg)}.json\`,
+      content: \`\${JSON.stringify({ package: pkg, objects: objects.map(describeObject) }, null, 2)}\\n\`,
+    })),
+`,
+  model: (name) => `    // perModel: generate() runs once with every matched object; return one file (or more).
+    generate: perModel((objects) => ({
+      path: "${name}.json",
+      content: \`\${JSON.stringify({ objects: objects.map(describeObject) }, null, 2)}\\n\`,
+    })),
+`,
+};
+
+const HELPER_BY_SCOPE: Record<GeneratorScope, string> = {
+  entity: "perEntity",
+  package: "perPackage",
+  model: "perModel",
+};
+
+/** The generator source `meta generator new` writes. Exported for the gate that runs it. */
+export function renderGeneratorSkeleton(name: string, scope: GeneratorScope): string {
+  const factory = factoryNameFor(name);
+  return [
+    HEADER(name, scope),
+    importsFor(scope),
+    DESCRIBE_FIELD,
+    FACTORY_HEAD(name, factory),
+    GENERATE_BY_SCOPE[scope](name),
+    FACTORY_TAIL,
+  ].join("");
+}
+
+// ---------------------------------------------------------------------------
+// Wiring the config
+// ---------------------------------------------------------------------------
+
+export interface WireResult {
+  status: "wired" | "already-wired" | "manual";
+  source: string;
+}
+
+/**
+ * Index of the `]` closing the `[` at `open`, skipping string literals, template literals
+ * and comments so a bracket inside `"a]b"` does not end the array. -1 if unbalanced.
+ */
+function matchingBracket(src: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    const c = src[i]!;
+    if (c === '"' || c === "'" || c === "`") {
+      for (i++; i < src.length && src[i] !== c; i++) if (src[i] === "\\") i++;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "/") {
+      while (i < src.length && src[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "*") {
+      i = src.indexOf("*/", i + 2);
+      if (i === -1) return -1;
+      i++;
+      continue;
+    }
+    if (c === "[" || c === "(" || c === "{") depth++;
+    else if (c === "]" || c === ")" || c === "}") {
+      depth--;
+      if (depth === 0) return c === "]" ? i : -1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Add `importLine` after the config's last top-level import and `entry` to the end of its
+ * `generators: [...]` array. Edits only a config it can read unambiguously — exactly one
+ * literal `generators: [` array — and otherwise returns `manual` with the source untouched,
+ * so the caller prints the two lines instead of guessing.
+ */
+export function wireGeneratorIntoConfig(source: string, importLine: string, entry: string): WireResult {
+  if (source.includes(importLine)) return { status: "already-wired", source };
+
+  const arrays = [...source.matchAll(/\bgenerators\s*:\s*\[/g)];
+  if (arrays.length !== 1) return { status: "manual", source };
+  const open = arrays[0]!.index! + arrays[0]![0].length - 1;
+  const close = matchingBracket(source, open);
+  if (close === -1) return { status: "manual", source };
+
+  const inner = source.slice(open + 1, close);
+  let newInner: string;
+  if (inner.trim() === "") {
+    newInner = entry;
+  } else if (inner.includes("\n")) {
+    // Multi-line: a new line at the indent of the last element, keeping the closing line.
+    const trailing = inner.slice(inner.trimEnd().length);          // "\n  " before `]`
+    const body = inner.trimEnd();
+    const lastLine = body.slice(body.lastIndexOf("\n") + 1);
+    const indent = lastLine.slice(0, lastLine.length - lastLine.trimStart().length);
+    // A trailing line comment means the element's comma sits before the comment.
+    const hasComma = /,\s*(\/\/[^\n]*)?$/.test(body);
+    newInner = `${body}${hasComma ? "" : ","}\n${indent}${entry},${trailing}`;
+  } else {
+    const body = inner.trimEnd();
+    newInner = body.endsWith(",") ? `${body} ${entry}` : `${body}, ${entry}`;
+  }
+  let out = source.slice(0, open + 1) + newInner + source.slice(close);
+
+  // The import: after the last line that starts an import statement (and its `from` line).
+  const importRe = /^import[\s\S]*?from\s+["'][^"']+["'];?[^\n]*$/gm;
+  let lastEnd = -1;
+  for (const m of out.matchAll(importRe)) lastEnd = m.index! + m[0].length;
+  out = lastEnd === -1
+    ? `${importLine}\n${out}`
+    : `${out.slice(0, lastEnd)}\n${importLine}${out.slice(lastEnd)}`;
+  return { status: "wired", source: out };
+}
+
+// ---------------------------------------------------------------------------
+// The command
+// ---------------------------------------------------------------------------
+
+export interface NewGeneratorOptions {
+  cwd: string;
+  name: string;
+  scope?: GeneratorScope;
+  force?: boolean;
+  wire?: boolean;
+}
+
+export interface NewGeneratorResult {
+  file: string;
+  fileStatus: "created" | "overwritten";
+  wireStatus: WireResult["status"] | "skipped";
+  importLine: string;
+  entry: string;
+  dependencyNotes: string[];
+}
+
+export async function newGenerator(opts: NewGeneratorOptions): Promise<NewGeneratorResult> {
+  const { cwd, name } = opts;
+  const scope = opts.scope ?? "entity";
+  if (!NAME_PATTERN.test(name)) {
+    throw new Error(`generator name "${name}" must be kebab-case (e.g. json-schema, openapi).`);
+  }
+  if (catalogEntry(name) !== undefined) {
+    throw new Error(
+      `"${name}" is a reference generator's name. Pick another name for your own generator, ` +
+        `or take a copy of that one with \`meta eject ${name}\`.`,
+    );
+  }
+  const configPath = join(cwd, CONFIG_FILE);
+  const wire = opts.wire ?? true;
+  if (wire && !existsSync(configPath)) {
+    throw new Error(`no ${CONFIG_FILE} here — run \`meta init\` first, or pass --no-wire.`);
+  }
+
+  const rel = `${OWNED_GENERATORS_DIR}/${name}.ts`;
+  const abs = join(cwd, rel);
+  const existed = existsSync(abs);
+  if (existed && opts.force !== true) {
+    throw new Error(`${rel} already exists — it is yours; edit it, or pass --force to replace it.`);
+  }
+  const source = renderGeneratorSkeleton(name, scope);
+  await mkdir(join(cwd, OWNED_GENERATORS_DIR), { recursive: true });
+  await writeFile(abs, source, "utf8");
+
+  const factory = factoryNameFor(name);
+  const importLine = `import { ${factory} } from "./${OWNED_GENERATORS_DIR}/${name}.js";`;
+  const entry = `${factory}()`;
+
+  let wireStatus: NewGeneratorResult["wireStatus"] = "skipped";
+  if (wire) {
+    const result = wireGeneratorIntoConfig(await readFile(configPath, "utf8"), importLine, entry);
+    if (result.status === "wired") await writeFile(configPath, result.source, "utf8");
+    wireStatus = result.status;
+  }
+
+  return {
+    file: rel,
+    fileStatus: existed ? "overwritten" : "created",
+    wireStatus,
+    importLine,
+    entry,
+    // The same report eject gives, worded for a file nobody ejected.
+    dependencyNotes: (await dependencyNotesForTemplate(cwd, source)).map((n) =>
+      n.replace(/^The ejected file imports/, "The new generator imports")),
+  };
+}
+
+export async function generatorCommand(args: string[], cwd: string): Promise<number> {
+  let values: { scope?: string; force?: boolean; "no-wire"?: boolean };
+  let positionals: string[];
+  try {
+    ({ values, positionals } = parseArgs({ args, options: GENERATOR_OPTIONS, strict: true, allowPositionals: true }));
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+  const [sub, name, ...extra] = positionals;
+  if (sub !== "new" || name === undefined || extra.length > 0) {
+    log.error("usage: meta generator new <name> [--scope entity|package|model]. See `meta generator --help`.");
+    return 2;
+  }
+  const scope = values.scope ?? "entity";
+  if (!(GENERATOR_SCOPES as readonly string[]).includes(scope)) {
+    log.error(`--scope must be one of ${GENERATOR_SCOPES.join(", ")} (got "${scope}").`);
+    return 2;
+  }
+
+  let r: NewGeneratorResult;
+  try {
+    r = await newGenerator({
+      cwd,
+      name,
+      scope: scope as GeneratorScope,
+      force: values.force === true,
+      wire: values["no-wire"] !== true,
+    });
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  const lines = [`${r.fileStatus === "created" ? "Created" : "Overwrote"} ${r.file} — yours to edit.`];
+  if (r.wireStatus === "wired") {
+    lines.push(`Wired it into ${CONFIG_FILE}: ${r.entry}`);
+  } else if (r.wireStatus === "already-wired") {
+    lines.push(`${CONFIG_FILE} already imports it.`);
+  } else {
+    lines.push(
+      r.wireStatus === "manual"
+        ? `Could not find one literal \`generators: [...]\` in ${CONFIG_FILE} to edit safely. Add:`
+        : `Add to ${CONFIG_FILE}:`,
+      `  ${r.importLine}`,
+      `  generators: [..., ${r.entry}]`,
+    );
+  }
+  lines.push(
+    "",
+    "Next:",
+    "  meta gen                          # runs it; output lands under outDir",
+    "  meta verify --codegen             # drift-gates it (no registration needed)",
+    "  npx tsc -p tsconfig.codegen.json  # typecheck it — meta gen does not",
+    `Then edit ${r.file}: change what it emits, keep reading the model through fields() / attr().`,
+  );
+  if (r.dependencyNotes.length > 0) lines.push("", ...r.dependencyNotes);
+  log.info(lines.join("\n"));
+  return 0;
+}

package/src/commands/init.ts

@@ -114,6 +114,13 @@ export default defineConfig({
   // \`meta gen\` runs — and prints the import line to add here, the entry to add below,
   // what to install, and any config keys those generators read (\`dbImport\`,
   // \`apiPrefix\`, \`extStyle\`, …). Add them here as you go.
+  //
+  // Need an output nothing in that catalog emits — OpenAPI, JSON Schema, a client, a
+  // service layer, docs? Write your own generator; that is the normal path:
+  //
+  //   meta generator new openapi --scope model
+  //
+  // writes a working, commented generator into ./codegen/generators/ and adds it here.
   generators: [],
 
   docs: {
@@ -145,7 +152,9 @@ Next steps:
   3. meta eject <name>...       # take the ones you want — copies them into
                                 #   codegen/generators/ (yours to edit) and prints the
                                 #   import, the entry to wire, and what to install
-  4. meta gen                   # generate from exactly what you wired
+     meta generator new <name>  # an output no reference emits? write your own — this
+                                #   scaffolds a working one and wires it
+  4. meta gen                  # generate from exactly what you wired
   5. meta docs                  # neutral model + API docs (on by default)
   6. Create your tables: meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply
 `;

package/src/commands/verify.ts

@@ -17,6 +17,7 @@ import {
   libraryPrefixRows,
   unindexedFkRows,
   referentialActionConflictRows,
+  advisoryHelpLines,
 } from "../lib/advisory.js";
 import { scanForUnprovenancedLibraryPrefix } from "../lib/library-prefix-advisory.js";
 import { scanForUnindexedForeignKeys, type UnindexedFkFinding } from "../lib/fk-index-advisory.js";
@@ -1815,7 +1816,9 @@ function buildVerifyPayload(input: {
       : `${failed.length} of ${ran.length} gate(s) failed (${failed.map((g) => g.gate).join(", ")})`,
   ];
   if (input.antiPatterns.status === "ran" && input.antiPatterns.total > 0) {
-    parts.push(`${input.antiPatterns.total} advisory anti-pattern finding(s)`);
+    // "advisory", not "anti-pattern": the section also carries unindexed foreign keys, a
+    // missing baseUrl and the other non-scanner rows — `help` breaks the count down by kind.
+    parts.push(`${input.antiPatterns.total} advisory finding(s)`);
   }
   if (input.requirements.total > 0) {
     parts.push(`${input.requirements.total} requirement diagnostic(s)`);
@@ -1831,9 +1834,7 @@ function buildVerifyPayload(input: {
     );
   }
   if (input.antiPatterns.total > 0) {
-    help.push(
-      `${input.antiPatterns.total} authored site(s) hand-roll what MetaObjects can model — see antiPatterns.rows[] and run \`meta types <construct>\``,
-    );
+    help.push(...advisoryHelpLines(input.antiPatterns.rows));
   }
   if (input.overlays.total > 0) {
     help.push(

package/src/index.ts

@@ -3,6 +3,7 @@ import { log } from "./lib/log.js";
 import { cliVersion } from "./lib/version.js";
 import { resolveFormat, isValidFormat, VALID_FORMATS, type OutputFormat } from "./lib/format.js";
 import { resolveCollection } from "@metaobjectsdev/sdk";
+import { GENERATOR_HELP } from "./commands/generator-help.js";
 export { defineConfig } from "@metaobjectsdev/codegen-ts";
 export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
@@ -30,6 +31,8 @@ COMMANDS:
   init --config-only    Write only .metaobjects/config.json — for a Maven- or pip-rooted project
   agent-docs            Scaffold only the agent-context (.metaobjects/ + .claude/skills/) — canonical redirect target for all language ports
   gen [<entity>...]     Codegen TS targets from your declared metadata
+  generator new <name>  Write a generator of your own into codegen/generators/ and wire it — the
+                        way to get any output MetaObjects does not ship (OpenAPI, JSON Schema, …)
   eject <generator>     Copy a reference generator into codegen/generators/ to own it (any time after init)
   eject --list          List every ejectable generator name, grouped by package
   deps sync [<name>...] Resolve declared dependencies (path transport): sync the committed
@@ -158,6 +161,7 @@ See https://metaobjects.com for docs.
 
 /** Focused per-subcommand usage slices shown by `<cmd> --help`. */
 export const COMMAND_HELP: Record<string, string> = {
+  generator: GENERATOR_HELP,
   gen: `meta gen — codegen TS targets from your declared metadata
 
 USAGE:
@@ -613,6 +617,10 @@ export async function run(argv: string[]): Promise<number> {
       const { genCommand } = await import("./commands/gen.js");
       return genCommand(rest, cwd, fmt);
     }
+    case "generator": {
+      const { generatorCommand } = await import("./commands/generator.js");
+      return generatorCommand(rest, cwd);
+    }
     case "eject": {
       const { ejectCommand } = await import("./commands/eject.js");
       return ejectCommand(rest, cwd, fmt);

package/src/lib/advisory.ts

@@ -108,6 +108,72 @@ export function ranSection<Row>(rows: Row[]): AdvisorySection<Row> {
   return { status: "ran", total: rows.length, rows };
 }
 
+// The `rule` of each advisory row that is NOT an anti-pattern-scanner finding. A row whose
+// rule is none of these came from the scanner: an authored site hand-rolling a construct.
+export const RULE_MISSING_BASE_URL = "missing-base-url";
+export const RULE_REMOVED_PROP_PREFIX = "removed-prop:";
+export const RULE_LIBRARY_PREFIX = "library-prefix-unprovenanced";
+export const RULE_UNINDEXED_FK = "unindexed-foreign-key";
+export const RULE_REFERENTIAL_ACTION_CONFLICT = "overridden-referential-action";
+
+/** The next-step line for `n` rows of one advisory kind, each naming what the rows are. */
+const ADVISORY_HELP: ReadonlyArray<{ matches: (rule: string) => boolean; line: (n: number) => string }> = [
+  {
+    matches: (r) => r === RULE_UNINDEXED_FK,
+    line: (n) =>
+      `${n} foreign key(s) with no covering index — see antiPatterns.rows[] (rule "${RULE_UNINDEXED_FK}"); each names the index.lookup to declare`,
+  },
+  {
+    matches: (r) => r === RULE_REFERENTIAL_ACTION_CONFLICT,
+    line: (n) =>
+      `${n} foreign key(s) whose two sides disagree on the referential action — see antiPatterns.rows[] (rule "${RULE_REFERENTIAL_ACTION_CONFLICT}")`,
+  },
+  {
+    matches: (r) => r === RULE_MISSING_BASE_URL,
+    line: (n) =>
+      `${n} entity-fetcher provider(s) mounted with no baseUrl while apiPrefix is set — see antiPatterns.rows[] (rule "${RULE_MISSING_BASE_URL}")`,
+  },
+  {
+    matches: (r) => r.startsWith(RULE_REMOVED_PROP_PREFIX),
+    line: (n) =>
+      `${n} provider(s) still mounted with a prop 1.0 renamed away — see antiPatterns.rows[] (rule "${RULE_REMOVED_PROP_PREFIX}<prop>")`,
+  },
+  {
+    matches: (r) => r === RULE_LIBRARY_PREFIX,
+    line: (n) =>
+      `${n} node(s) declared under "metaobjects::" with no ejection provenance — see antiPatterns.rows[] (rule "${RULE_LIBRARY_PREFIX}")`,
+  },
+];
+
+/**
+ * One next-step line per KIND of advisory row, in a structured payload's `help`.
+ *
+ * The advisory section carries several kinds of row keyed by `rule`, and the help line used
+ * to count them all as "authored site(s) hand-roll what MetaObjects can model" — so a project
+ * whose only advisories were unindexed foreign keys was told it hand-rolled three constructs.
+ * Scanner findings keep that line; every other kind is counted under its own label.
+ */
+export function advisoryHelpLines(rows: readonly AdvisoryFindingRow[]): string[] {
+  const counts = ADVISORY_HELP.map(() => 0);
+  let handRolled = 0;
+  for (const row of rows) {
+    const kind = ADVISORY_HELP.findIndex((k) => k.matches(row.rule));
+    if (kind === -1) handRolled++;
+    else counts[kind] = (counts[kind] ?? 0) + 1;
+  }
+  const lines: string[] = [];
+  if (handRolled > 0) {
+    lines.push(
+      `${handRolled} authored site(s) hand-roll what MetaObjects can model — see antiPatterns.rows[] and run \`meta types <construct>\``,
+    );
+  }
+  ADVISORY_HELP.forEach((k, i) => {
+    const n = counts[i] ?? 0;
+    if (n > 0) lines.push(k.line(n));
+  });
+  return lines;
+}
+
 /** Project the scanner's findings into payload rows. `snippet` is deliberately
  *  dropped: it is a copy of the reader's own source line, and `file`+`line`
  *  already address it. */
@@ -129,7 +195,7 @@ export function missingBaseUrlRows(findings: readonly BaseUrlFinding[]): Advisor
   return findings.map((f) => ({
     file: f.file,
     line: f.line,
-    rule: "missing-base-url",
+    rule: RULE_MISSING_BASE_URL,
     construct: f.construct,
     message: f.message,
   }));
@@ -144,7 +210,7 @@ export function removedPropRows(findings: readonly RemovedPropFinding[]): Adviso
   return findings.map((f) => ({
     file: f.file,
     line: f.line,
-    rule: `removed-prop:${f.prop}`,
+    rule: `${RULE_REMOVED_PROP_PREFIX}${f.prop}`,
     construct: f.construct,
     message: f.message,
   }));
@@ -157,7 +223,7 @@ export function libraryPrefixRows(
   return findings.map((f) => ({
     file: f.file,
     line: 0,
-    rule: "library-prefix-unprovenanced",
+    rule: RULE_LIBRARY_PREFIX,
     construct: f.fqn,
     message: f.message,
   }));
@@ -174,7 +240,7 @@ export function unindexedFkRows(
   return findings.map((f) => ({
     file: f.file,
     line: 0,
-    rule: "unindexed-foreign-key",
+    rule: RULE_UNINDEXED_FK,
     construct: f.construct,
     message: f.message,
   }));
@@ -190,7 +256,7 @@ export function referentialActionConflictRows(
   return findings.map((f) => ({
     file: f.file,
     line: 0,
-    rule: "overridden-referential-action",
+    rule: RULE_REFERENTIAL_ACTION_CONFLICT,
     construct: f.construct,
     message: f.message,
   }));