fix(docs): prevent silent doc-page overwrite on cross-package short-name collisions (hard-error + package layout)

Doc pages were placed by short name (<Name>.md). Two metadata nodes
sharing a short name across packages (e.g. an object acme::sales::Order
and a template.output acme::comms::Order) both wrote Order.md and
silently overwrote each other.

- New docs-paths.ts: single source of truth for page placement AND
  cross-link hrefs. docPageOutputPath()/docPageHref() derive a file's
  location and every inbound link from the SAME effective package, so
  they can never diverge. effectivePackage() reads the package off the
  node's resolutionKey() (object fqn() stays bare per FR5d).
- assertNoDuplicateDocPaths(): hard backstop (ALL layouts) — two nodes
  resolving to the same path throw, naming both FQNs + the path.
- docsFile() respects ctx.config.outputLayout; package layout folds
  pages under package-path subdirs (acme/sales/Order.md) with correct
  relative cross-links (../comms/OrderEmail.md).
- meta docs gains --layout flat|package (default flat = unchanged).
  Duplicate-path error surfaces as a clean non-zero exit, not a trace.

Flat default + existing goldens/byte-identity/neutrality unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/cli/src/commands/docs.ts

@@ -26,20 +26,35 @@ import {
 import type { GenContext } from "@metaobjectsdev/codegen-ts";
 import { docsFile } from "@metaobjectsdev/codegen-ts/generators";
 
+type DocsLayout = "flat" | "package";
+
 interface DocsFlags {
   /** Project root holding `metaobjects/` (the metadata to document). */
   metadata: string;
   /** Output directory for the rendered pages. */
   out: string;
+  /** Page-placement layout. `flat` (default) writes `<Name>.md` at the out
+   *  root; `package` folds pages under package-path subdirs (collision-proof
+   *  for multi-package models with repeated short names). */
+  layout: DocsLayout;
   /** Optional override for the project root used to resolve adopter
    *  `templates/` overrides. Defaults to the metadata root. */
   templates?: string;
 }
 
+function parseLayout(v: string | undefined, flag: string): DocsLayout {
+  if (v === undefined) throw new Error(`${flag} requires flat|package`);
+  if (v !== "flat" && v !== "package") {
+    throw new Error(`${flag} must be "flat" or "package" (got "${v}")`);
+  }
+  return v;
+}
+
 function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   let metadata: string | undefined;
   let out: string | undefined;
   let templates: string | undefined;
+  let layout: DocsLayout | undefined;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
     if (a === "--out" || a === "-o") {
@@ -48,6 +63,10 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
       out = v;
     } else if (a.startsWith("--out=")) {
       out = a.slice("--out=".length);
+    } else if (a === "--layout") {
+      layout = parseLayout(argv[++i], a);
+    } else if (a.startsWith("--layout=")) {
+      layout = parseLayout(a.slice("--layout=".length), "--layout");
     } else if (a === "--templates") {
       const v = argv[++i];
       if (v === undefined) throw new Error(`${a} requires a directory argument`);
@@ -68,6 +87,8 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
     metadata: metadata ?? cwd,
     // Default out dir, resolved against the metadata root below.
     out: out ?? "./docs",
+    // Default flat preserves today's single-package output (+ existing goldens).
+    layout: layout ?? "flat",
     ...(templates !== undefined ? { templates } : {}),
   };
 }
@@ -148,7 +169,13 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     entities: root.objects(),
     loadedRoot: root,
     matches: () => true,
-    config: { outDir, extStyle: "none", dbImport: "", dialect: "sqlite" } as never,
+    config: {
+      outDir,
+      extStyle: "none",
+      dbImport: "",
+      dialect: "sqlite",
+      outputLayout: flags.layout,
+    } as never,
     renderContext,
     projectRoot,
     warn: (msg) => log.warn(`docs: ${msg}`),
@@ -159,6 +186,13 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     files = await docsFile().generate(ctx);
   } catch (err) {
     const msg = (err as Error).message;
+    // Duplicate output path (silent-overwrite backstop): the generator already
+    // names both colliding FQNs + the path and starts with "docs:". Surface it
+    // verbatim as a clean non-zero exit (no double prefix, no stack trace).
+    if (msg.startsWith("docs: duplicate output path")) {
+      log.error(msg);
+      return 1;
+    }
     // The framework templates resolve from disk; inside the compiled `meta`
     // binary they live on a virtual fs the provider cannot read. Surface that
     // as an actionable message rather than a cryptic render failure.

server/typescript/packages/cli/test/docs-command.test.ts

@@ -113,6 +113,47 @@ async function customTypeProject(): Promise<string> {
   return root;
 }
 
+// TWO-package metadata with a SHORT-NAME collision across packages: an
+// `object.value acme::sales::Order` and a `template.output acme::comms::Order`.
+// In flat layout both want `Order.md` (collision → hard error); in package
+// layout they fold under distinct subdirs.
+const COLLIDING_META = {
+  "metadata.root": {
+    children: [
+      {
+        "object.value": {
+          name: "Order",
+          package: "acme::sales",
+          children: [{ "field.string": { name: "sku" } }],
+        },
+      },
+      {
+        "template.output": {
+          name: "Order",
+          package: "acme::comms",
+          "@kind": "document",
+          "@payloadRef": "Order",
+          "@textRef": "comms/order",
+          "@format": "html",
+        },
+      },
+    ],
+  },
+};
+
+/** Project root holding the cross-package short-name collision metadata. */
+async function collidingProject(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "meta-docs-collide-"));
+  dirs.push(root);
+  await mkdir(join(root, "metaobjects"), { recursive: true });
+  await writeFile(
+    join(root, "metaobjects", "meta.json"),
+    JSON.stringify(COLLIDING_META),
+    "utf8",
+  );
+  return root;
+}
+
 afterAll(async () => {
   for (const d of dirs) await rm(d, { recursive: true, force: true });
 });
@@ -253,4 +294,54 @@ describe("meta docs — standalone neutral metadata docs", () => {
     const help = logged.join("\n");
     expect(help).toContain("docs");
   });
+
+  test("default (flat) on a cross-package short-name collision → non-zero, no overwrite", async () => {
+    const root = await collidingProject();
+    const out = join(root, "out-collide-flat");
+
+    const errLogged: string[] = [];
+    const origErr = console.error;
+    console.error = (...args: unknown[]) => errLogged.push(args.map(String).join(" "));
+    let code: number;
+    try {
+      code = await docsCommand([root, "--out", out], root);
+    } finally {
+      console.error = origErr;
+    }
+
+    expect(code).not.toBe(0); // hard error, not a silent overwrite
+    const stderr = errLogged.join("\n");
+    expect(stderr).toContain("duplicate output path");
+    expect(stderr).toContain("Order.md");
+    expect(stderr).toContain("acme::sales::Order");
+    expect(stderr).toContain("acme::comms::Order");
+  });
+
+  test("--layout package: distinct nested files, exit 0", async () => {
+    const root = await collidingProject();
+    const out = join(root, "out-collide-pkg");
+
+    const code = await docsCommand([root, "--out", out, "--layout", "package"], root);
+    expect(code).toBe(0);
+
+    // Both pages survive under package-folded subdirs.
+    expect(existsSync(join(out, "acme", "sales", "Order.md"))).toBe(true);
+    expect(existsSync(join(out, "acme", "comms", "Order.md"))).toBe(true);
+  });
+
+  test("--layout package preserves single-package output as nested (no flat regression)", async () => {
+    // The default-flat single-package fixture still emits flat <name>.md.
+    const root = await project();
+    const out = join(root, "out-flat-default");
+    expect(await docsCommand([root, "--out", out], root)).toBe(0);
+    expect(existsSync(join(out, "Welcome.md"))).toBe(true);
+    expect(existsSync(join(out, "WelcomePage.md"))).toBe(true);
+  });
+
+  test("--layout rejects an invalid value", async () => {
+    const root = await project();
+    const out = join(root, "out-badlayout");
+    const code = await docsCommand([root, "--out", out, "--layout", "nested"], root);
+    expect(code).toBe(2); // arg parse error
+  });
 });

server/typescript/packages/codegen-ts/src/docs-paths.ts

@@ -0,0 +1,106 @@
+// docs-paths.ts — the SINGLE source of truth for where a docs page is written
+// AND how one page links to another. The file location and every inbound link
+// href are derived from the SAME functions here, so they can never diverge.
+//
+// Why this matters: pages are placed by short name. In "flat" layout two nodes
+// that share a short name across different packages (e.g. `acme::sales::Order`
+// and `acme::billing::Order`) would both want `Order.md` and one would silently
+// overwrite the other. `assertNoDuplicateDocPaths()` is the hard backstop that
+// turns that data-loss into a clear error; "package" layout folds pages under
+// package-path subdirs (`acme/sales/Order.md`) so multi-package models work.
+
+import { PACKAGE_SEPARATOR } from "@metaobjectsdev/metadata";
+import { relative as posixRelative } from "node:path/posix";
+import { packageToPath, type OutputLayout } from "./import-path.js";
+
+/** The minimal shape needed to place a docs page / compute a link to it: a
+ *  short name and its EFFECTIVE package. Build one from a metadata node via
+ *  `docPageNode()`. */
+export interface DocPageNode {
+  readonly name: string;
+  readonly package?: string | undefined;
+}
+
+/** A metadata node enough to derive page placement. `resolutionKey()` carries
+ *  the EFFECTIVE package (own package OR the file-default captured at parse
+ *  time) folded as `<pkg>::<name>` — `.package` alone is often undefined for
+ *  objects (FR5d keeps object fqn() bare), so we read placement off the
+ *  resolution key instead. */
+interface PlaceableNode {
+  readonly name: string;
+  resolutionKey(): string;
+}
+
+/** Effective package of a placeable node: the prefix of `resolutionKey()`
+ *  before the trailing `::<name>`, or undefined when the node is package-less. */
+export function effectivePackage(node: PlaceableNode): string | undefined {
+  const key = node.resolutionKey();
+  const suffix = `${PACKAGE_SEPARATOR}${node.name}`;
+  if (key === node.name) return undefined;
+  if (key.endsWith(suffix)) {
+    const pkg = key.slice(0, key.length - suffix.length);
+    return pkg === "" ? undefined : pkg;
+  }
+  return undefined;
+}
+
+/** Build a placement node ({name, effective package}) from a metadata node. The
+ *  single bridge from a loaded node to the path/href helpers — so file location
+ *  and link href derive from the SAME effective package. */
+export function docPageNode(node: PlaceableNode): DocPageNode {
+  return { name: node.name, package: effectivePackage(node) };
+}
+
+/** Output path (relative to the docs out dir) for a node's `.md` page.
+ *  Flat → `<name>.md` (today's value, byte-identical). Package → folded under
+ *  the package path (`acme/sales/Order.md`); a package-less node stays at root. */
+export function docPageOutputPath(layout: OutputLayout, node: DocPageNode): string {
+  const filename = `${node.name}.md`;
+  if (layout === "flat") return filename;
+  const dir = packageToPath(node.package);
+  return dir === "" ? filename : `${dir}/${filename}`;
+}
+
+/** Relative href FROM `fromNode`'s page TO `toNode`'s page. Derived from the
+ *  same `docPageOutputPath()` placement, so a link always points at the file's
+ *  real location in BOTH layouts. Flat → `./<to>.md`; package → a correct
+ *  relative path (e.g. `../comms/OrderEmail.md`). */
+export function docPageHref(
+  layout: OutputLayout,
+  fromNode: DocPageNode,
+  toNode: DocPageNode,
+): string {
+  const toPath = docPageOutputPath(layout, toNode);
+  if (layout === "flat") return `./${toPath}`;
+  const fromPath = docPageOutputPath(layout, fromNode);
+  // Relative path from the FROM page's directory to the TO page.
+  const fromDir = fromPath.includes("/") ? fromPath.slice(0, fromPath.lastIndexOf("/")) : "";
+  let rel = posixRelative(fromDir, toPath);
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel;
+}
+
+/** A page about to be emitted, paired with the FQN of the node that produced it
+ *  (for a precise collision diagnostic). */
+export interface DocPagePlacement {
+  path: string;
+  fqn: string;
+}
+
+/** Hard backstop against silent overwrite (ALL layouts): if two placements
+ *  resolve to the SAME output path, THROW naming both colliding node FQNs and
+ *  the path. Guarantees a docs run never silently drops a page. */
+export function assertNoDuplicateDocPaths(placements: DocPagePlacement[]): void {
+  const seen = new Map<string, string>();
+  for (const { path, fqn } of placements) {
+    const prior = seen.get(path);
+    if (prior !== undefined) {
+      throw new Error(
+        `docs: duplicate output path "${path}" from nodes ${prior} and ${fqn} — ` +
+          `use package layout (outputLayout: "package" / meta docs --layout package) ` +
+          `to disambiguate.`,
+      );
+    }
+    seen.set(path, fqn);
+  }
+}

server/typescript/packages/codegen-ts/src/generators/docs-data-builder.ts

@@ -41,6 +41,8 @@ import {
 } from "@metaobjectsdev/metadata";
 import type { Dialect } from "../column-mapper.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
+import type { OutputLayout } from "../import-path.js";
+import { docPageHref, docPageNode } from "../docs-paths.js";
 import { enumValues } from "../enum-meta.js";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { GENERATED_HEADER } from "../constants.js";
@@ -57,6 +59,8 @@ export interface BuildDocDataOpts {
   dialect: Dialect;
   columnNamingStrategy?: ColumnNamingStrategy;
   loadedRoot: MetaRoot;
+  /** Page-placement layout. Defaults to "flat" (back-compat: same-dir links). */
+  layout?: OutputLayout;
 }
 
 function isFieldRequired(field: MetaField): boolean {
@@ -288,6 +292,7 @@ export function buildEntityDocData(
   opts: BuildDocDataOpts,
 ): EntityDocData {
   const root = opts.loadedRoot;
+  const layout = opts.layout ?? "flat";
   const primary = entity.primaryIdentity();
   const pkFields = primary?.fields ?? [];
   const pkFieldNames = new Set<string>(pkFields);
@@ -362,11 +367,13 @@ export function buildEntityDocData(
     const ref = child.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
     if (typeof ref !== "string") continue;
     if (stripPackage(ref) !== entity.name) continue;
-    // Link to the template's own doc page. Task 3 emits the template page as
-    // `<TemplateName>.md` using the RAW node name (same convention as entity
-    // pages), so the href MUST use the raw name to resolve.
+    // Link to the template's own doc page. The href is derived from the SAME
+    // page-placement function used to write the template page, so it resolves
+    // in BOTH layouts (flat → `./<Tmpl>.md`; package → a correct relative path
+    // like `../comms/OrderEmail.md`).
+    const href = docPageHref(layout, docPageNode(entity), docPageNode(child));
     usedByMatches.push({
-      bullet: `[\`template.${child.subType} ${child.name}\`](./${child.name}.md) — uses \`${entity.name}\` as \`@payloadRef\``,
+      bullet: `[\`template.${child.subType} ${child.name}\`](${href}) — uses \`${entity.name}\` as \`@payloadRef\``,
     });
   }
   const usedBy = usedByMatches.length > 0 ? usedByMatches : undefined;

server/typescript/packages/codegen-ts/src/generators/docs-file.ts

@@ -22,7 +22,12 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
 import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_OUTPUT } from "@metaobjectsdev/metadata";
 import { render } from "@metaobjectsdev/render";
 import type { Generator, GeneratorFactory, EmittedFile } from "../generator.js";
-import { entityOutputPath } from "../import-path.js";
+import {
+  docPageOutputPath,
+  docPageNode,
+  assertNoDuplicateDocPaths,
+  type DocPagePlacement,
+} from "../docs-paths.js";
 import { projectProvider } from "../render-engine/framework-provider.js";
 import { buildEntityDocData } from "./docs-data-builder.js";
 import { buildTemplateDocData } from "./template-doc-builder.js";
@@ -47,13 +52,18 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
       const rc = ctx.renderContext;
       const provider = projectProvider(ctx.projectRoot ?? process.cwd());
       const layout = ctx.config.outputLayout ?? "flat";
+      // Track every (path, fqn) so we can hard-error on a collision (defense
+      // against silent doc-page overwrite) AFTER all pages are placed.
+      const placements: DocPagePlacement[] = [];
       const files: EmittedFile[] = ctx.loadedRoot
         .objects()
         .filter(ctx.matches)
         .map((entity: MetaObject) => {
-          const path = entityOutputPath(layout, entity.package, `${entity.name}.md`);
+          const path = docPageOutputPath(layout, docPageNode(entity));
+          placements.push({ path, fqn: entity.resolutionKey() });
           const payload = buildEntityDocData(entity, {
             dialect: rc.dialect,
+            layout,
             ...(rc.columnNamingStrategy !== undefined && {
               columnNamingStrategy: rc.columnNamingStrategy,
             }),
@@ -82,8 +92,9 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
       // (`<name>.md`), agreeing with the entity Used-by back-link target.
       for (const child of ctx.loadedRoot.ownChildren()) {
         if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
-        const path = entityOutputPath(layout, child.package, `${child.name}.md`);
-        const payload = buildTemplateDocData(child);
+        const path = docPageOutputPath(layout, docPageNode(child));
+        placements.push({ path, fqn: child.resolutionKey() });
+        const payload = buildTemplateDocData(child, { layout, loadedRoot: ctx.loadedRoot });
         let content: string;
         try {
           content = render({
@@ -102,6 +113,10 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
         files.push({ path, content });
       }
 
+      // Hard backstop against silent overwrite (ALL layouts): two nodes that
+      // resolve to the same output path → throw naming both FQNs + the path.
+      assertNoDuplicateDocPaths(placements);
+
       return files;
     },
   };