@metaobjectsdev/cli 1.0.10 → 1.0.12

package/src/lib/fmt-engine.ts

@@ -0,0 +1,179 @@
+// server/typescript/packages/cli/src/lib/fmt-engine.ts
+//
+// `meta fmt` (#304) orchestration: resolve the project's own metadata files
+// (resolveCollection — never a hardcoded `metaobjects/`), format each one
+// standalone (@metaobjectsdev/metadata's formatMetadataFile — own-mode,
+// declared-here layer only), and gate every rewrite behind a whole-project
+// reload-and-compare safety check before it ever touches disk.
+//
+// The safety check (design rule 4): swap a candidate in via an in-memory
+// source carrying the SAME file id the real load would use, reload the WHOLE
+// project, and require both that it loads with no errors AND that its
+// canonical serialization is byte-identical to the untouched baseline. Only
+// then is the candidate written — so `--check` (which skips the write) and a
+// real run share one code path, and a bug in the formatter can only ever
+// leave a file unchanged plus an error, never a corrupted file.
+import { basename, extname, resolve as resolvePath } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import type { MetaDataTypeProvider } from "@metaobjectsdev/metadata";
+import {
+  composeRegistry,
+  MetaDataLoader,
+  InMemoryStringSource,
+  canonicalSerialize,
+  formatMetadataFile,
+} from "@metaobjectsdev/metadata";
+import { FileSource } from "@metaobjectsdev/metadata/core";
+import { resolveCollection, defaultLoadMemoryProviders, type Collection } from "@metaobjectsdev/sdk";
+import { loadMetaobjectsConfig, loadMemoryOptionsFrom } from "./load-metaobjects-config.js";
+
+export type FmtFileStatus =
+  | "formatted"
+  | "would-format"
+  | "unchanged"
+  | "skipped-yaml"
+  | "skipped-overlay"
+  | "error";
+
+export interface FmtFileReport {
+  readonly path: string;
+  readonly status: FmtFileStatus;
+  readonly detail?: string;
+}
+
+export interface FmtRunResult {
+  readonly files: readonly FmtFileReport[];
+  /** Set when the run could not even start — an unresolvable collection, an
+   *  explicit file argument outside the project's sources, or metadata that
+   *  does not currently load cleanly. Nothing was attempted. */
+  readonly fatal?: string;
+}
+
+export interface FmtRunOptions {
+  readonly projectRoot: string;
+  readonly check: boolean;
+  /** Explicit paths (cwd-relative or absolute) narrowing the run. Omit/empty
+   *  for every file the project owns. */
+  readonly files?: readonly string[];
+}
+
+async function projectProviders(collection: Collection): Promise<readonly MetaDataTypeProvider[]> {
+  try {
+    const cfg = await loadMetaobjectsConfig(collection.configDir);
+    return loadMemoryOptionsFrom(cfg).providers ?? [];
+  } catch {
+    // No metaobjects.config.ts (common for a non-TS-server project running
+    // `meta fmt` just for schema-neutral formatting) — format against the
+    // core vocabulary only, exactly like a project with no custom providers.
+    return [];
+  }
+}
+
+export async function runFmt(opts: FmtRunOptions): Promise<FmtRunResult> {
+  let collection: Collection;
+  try {
+    collection = await resolveCollection(opts.projectRoot);
+  } catch (err) {
+    return { files: [], fatal: err instanceof Error ? err.message : String(err) };
+  }
+
+  const providers = await projectProviders(collection);
+  const registry = composeRegistry([...defaultLoadMemoryProviders, ...providers]);
+
+  let targets: readonly string[];
+  if (opts.files !== undefined && opts.files.length > 0) {
+    const want = new Set(opts.files.map((f) => resolvePath(opts.projectRoot, f)));
+    const owned = new Set(collection.ownFiles);
+    const missing = [...want].filter((f) => !owned.has(f));
+    if (missing.length > 0) {
+      return {
+        files: [],
+        fatal:
+          `not among this project's resolved metadata sources: ${missing.join(", ")}\n` +
+          "meta fmt only formats files resolveCollection() already resolves — pass no " +
+          "arguments to format every one of them.",
+      };
+    }
+    targets = collection.ownFiles.filter((f) => want.has(f));
+  } else {
+    targets = collection.ownFiles;
+  }
+
+  const sourceId = (p: string): string => collection.fileIds.get(p) ?? basename(p);
+
+  const libSources =
+    collection.libraries.length > 0
+      ? (await import("@metaobjectsdev/metadata/library")).librarySources([...collection.libraries])
+      : [];
+
+  const buildSources = (overridePath?: string, overrideText?: string) => [
+    ...libSources,
+    ...collection.files.map((p) => {
+      const id = sourceId(p);
+      return overridePath !== undefined && p === overridePath
+        ? new InMemoryStringSource(overrideText ?? "", { id })
+        : new FileSource(p, { id });
+    }),
+  ];
+
+  const baseline = await new MetaDataLoader({ registry }).load(buildSources());
+  if (baseline.errors.length > 0) {
+    return {
+      files: [],
+      fatal:
+        "this project's metadata does not currently load cleanly — fix the error(s) below, " +
+        "then re-run fmt:\n" +
+        baseline.errors.map((e) => `  ${e.message}`).join("\n"),
+    };
+  }
+  const baselineCanonical = canonicalSerialize(baseline.root);
+
+  const reports: FmtFileReport[] = [];
+  for (const path of targets) {
+    const ext = extname(path).toLowerCase();
+    if (ext === ".yaml" || ext === ".yml") {
+      reports.push({
+        path,
+        status: "skipped-yaml",
+        detail: "no canonical YAML emitter exists (ADR-0006: JSON is the canonical interchange form) — left untouched",
+      });
+      continue;
+    }
+
+    const content = await readFile(path, "utf8");
+    const formatted = formatMetadataFile(content, { registry, sourceId: sourceId(path) });
+    if (!formatted.ok) {
+      reports.push(
+        formatted.overlay
+          ? { path, status: "skipped-overlay", detail: formatted.message }
+          : { path, status: "error", detail: formatted.message },
+      );
+      continue;
+    }
+
+    if (formatted.text === content) {
+      reports.push({ path, status: "unchanged" });
+      continue;
+    }
+
+    const testLoad = await new MetaDataLoader({ registry }).load(buildSources(path, formatted.text));
+    const safe = testLoad.errors.length === 0 && canonicalSerialize(testLoad.root) === baselineCanonical;
+    if (!safe) {
+      reports.push({
+        path,
+        status: "error",
+        detail: "formatting this file would change the loaded model's meaning — left unchanged",
+      });
+      continue;
+    }
+
+    if (opts.check) {
+      reports.push({ path, status: "would-format" });
+    } else {
+      await writeFile(path, formatted.text, "utf8");
+      reports.push({ path, status: "formatted" });
+    }
+  }
+
+  return { files: reports };
+}

package/src/lib/name-lint.ts

@@ -0,0 +1,106 @@
+// `meta verify` — the node-name AUTHORING lint.
+//
+// The loader accepts any string as a node `name`, on every port. An adopter's metadata
+// carried a field named `"defaultCurrencyId "` (a trailing space, copied from legacy XML)
+// and an identity named `"account_defaultCurrencyId _fk"`; both loaded with no error.
+//
+// WHY THIS IS A WARNING AND NOT A LOAD ERROR. It was weighed against the correction bar
+// in docs/compatibility-policy.md and does not pass it: whitespace names WORK today on
+// the core path — `meta migrate` emits a quoted column (`"default_currency_id "`) and the
+// ObjectManager round-trips the key — and multi-word requirement names are documented to
+// load. Refusing them at load would break metadata that does what its author asked, so
+// the honest instrument is an advisory that names the edit.
+//
+// EVERY FINDING IS A WARNING, BY CONSTRUCTION — the same rule, and the same reasoning,
+// as requirement-lint.ts's header. Nothing here reaches the exit code.
+//
+// REQUIREMENTS ARE NOT LINTED HERE. A requirement's name is its dotted ADDRESS and the
+// requirement lint already owns it (WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE reports
+// leading/trailing whitespace; a short multi-word label such as "Order Recording" is
+// deliberately NOT reported, because renaming one moves its address and its emitted
+// stub file for no gain). Reporting the same name twice under two codes would make
+// one edit look like two problems.
+//
+// IT READS THE LOADED MODEL, NEVER THE FILES — and walks DECLARATIONS (see `walk`).
+
+import { PACKAGE_SEPARATOR, TYPE_FIELD, TYPE_REQUIREMENT, type MetaData } from "@metaobjectsdev/metadata";
+import type { Diagnostic } from "./requirement-check.js";
+
+/** Leading or trailing whitespace — the strong finding. */
+export const WARN_NAME_SURROUNDING_WHITESPACE = "WARN_NAME_SURROUNDING_WHITESPACE";
+/** Whitespace inside an otherwise trimmed name — the plain advisory. */
+export const WARN_NAME_INTERNAL_WHITESPACE = "WARN_NAME_INTERNAL_WHITESPACE";
+
+/**
+ * What counts as whitespace: the ECMAScript `\s` class. That is ASCII space, tab, LF,
+ * CR, VT and FF, plus U+00A0 (no-break space), U+FEFF, U+1680, U+2000–U+200A, U+2028,
+ * U+2029, U+202F, U+205F and U+3000. The non-ASCII members matter for this lint's
+ * actual source of input: a no-break space survives a copy out of a document or a
+ * legacy export and is invisible in every editor.
+ */
+const WHITESPACE = /\s/u;
+
+function warn(path: string, code: string, message: string): Diagnostic {
+  return { severity: "warn", code, path, message };
+}
+
+/** One segment of a node's address. A name with whitespace is quoted so the
+ *  whitespace is visible in the printed path rather than vanishing into it. */
+function segment(name: string): string {
+  return WHITESPACE.test(name) ? JSON.stringify(name) : name;
+}
+
+function check(node: MetaData, path: string, out: Diagnostic[]): void {
+  const name = node.name;
+  if (name === "" || !WHITESPACE.test(name)) return;
+
+  const kind = `${node.type}.${node.subType}`;
+  const quoted = JSON.stringify(name);
+  // @column is a FIELD attribute. Advising an object or identity author to pin it
+  // would send them looking for a slot that does not exist on the node.
+  const pin = node.type === TYPE_FIELD ? ", and pin @column if the physical column must keep its name" : "";
+  const trimmed = name.trim();
+
+  if (trimmed !== name) {
+    const inner = WHITESPACE.test(trimmed) ? " It also contains whitespace inside it." : "";
+    const target = trimmed === "" ? "" : ` (to ${JSON.stringify(trimmed)}, presumably)`;
+    out.push(warn(path, WARN_NAME_SURROUNDING_WHITESPACE,
+      `${kind} name ${quoted} has leading or trailing whitespace, which is almost certainly ` +
+      `unintended — rename it${target}${pin}. The whitespace is carried into every identifier, ` +
+      `column and wire key derived from the name.${inner}`));
+    return;
+  }
+
+  out.push(warn(path, WARN_NAME_INTERNAL_WHITESPACE,
+    `${kind} name ${quoted} contains whitespace. A name is an identifier: derived column names ` +
+    `and wire keys carry the space, and generated code cannot use it as one. Consider ` +
+    `renaming it${pin}.`));
+}
+
+/** A root-level node's address: package-qualified the way `resolutionKey()` is, so the
+ *  path reads like every other reference to the node. */
+function topLevelAddress(node: MetaData): string {
+  const pkg = node.package ?? node.fileDefaultPackage;
+  return pkg !== undefined && pkg !== "" ? `${pkg}${PACKAGE_SEPARATOR}${segment(node.name)}` : segment(node.name);
+}
+
+/**
+ * Lint the name of every named node in the loaded model, requirements excepted.
+ * Returns `[]` for a model with no whitespace in any name.
+ */
+export function lintNodeNames(root: MetaData): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const walk = (n: MetaData, prefix: string): void => {
+    // OWN-ONLY (ADR-0039 sanctioned case): this reports each DECLARATION once, at the
+    // node that declares it. A field inherited through `extends` is one declaration and
+    // one rename; the resolving `children()` would repeat it on every subtype.
+    for (const c of n.ownChildren()) {
+      if (c.type === TYPE_REQUIREMENT) continue; // owned by requirement-lint.ts — see header
+      const path = prefix === "" ? topLevelAddress(c) : `${prefix}.${segment(c.name)}`;
+      check(c, path, out);
+      walk(c, path);
+    }
+  };
+  walk(root, "");
+  return out;
+}

package/src/lib/runtime-boundary-advisory.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { OWNED_RUNTIME_DIR, HTTP_RUNTIME_PACKAGE } from "@metaobjectsdev/codegen-ts";
+
+/**
+ * Generated code that imports the owned HTTP-adapter copy from OUTSIDE its own
+ * workspace package.
+ *
+ * Since 1.0.9 an ejected `entity` / `routes` / `routes-hono` generator points its output
+ * at `codegen/runtime/` (the adapter source `meta eject` copied) by a path relative to
+ * the output directory. In a single-package project that is exactly right. In a monorepo
+ * whose output sits inside a workspace package (`apps/api/src/generated`), the path climbs
+ * out of that package: `tsc` rejects the file (`TS6059 … is not under 'rootDir'`), and the
+ * copy's own bare imports (`qs`, `fastify`) do not resolve from the repository root. The
+ * `meta gen` run itself is green; the adopter's build is the first thing that disagrees.
+ *
+ * Found upgrading a pnpm monorepo. This names the package and the two ways out. It is a
+ * warning and never changes an exit code.
+ */
+export interface RuntimeBoundaryFinding {
+  /** Project-relative directory of the workspace package the generated file sits in. */
+  packageDir: string;
+  /** One generated file (project-relative) that crosses the boundary. */
+  example: string;
+}
+
+const IMPORT_SPEC = /\bfrom\s+["'](\.{1,2}\/[^"']+)["']/g;
+
+function nearestPackageDir(fileDir: string, projectRoot: string): string | undefined {
+  for (let d = fileDir; ; d = dirname(d)) {
+    if (d === projectRoot || !d.startsWith(projectRoot + sep)) return undefined;
+    if (existsSync(join(d, "package.json"))) return d;
+  }
+}
+
+function isInside(child: string, parent: string): boolean {
+  return child === parent || child.startsWith(parent + sep);
+}
+
+export function findRuntimeBoundaryCrossings(
+  projectRoot: string,
+  generatedFiles: readonly string[],
+): RuntimeBoundaryFinding[] {
+  const root = resolve(projectRoot);
+  const runtimeRoot = join(root, OWNED_RUNTIME_DIR);
+  const byPackage = new Map<string, RuntimeBoundaryFinding>();
+  for (const file of generatedFiles) {
+    if (!/\.(ts|tsx|mts)$/.test(file) || !existsSync(file)) continue;
+    const abs = resolve(file);
+    const pkgDir = nearestPackageDir(dirname(abs), root);
+    if (pkgDir === undefined || isInside(runtimeRoot, pkgDir) || byPackage.has(pkgDir)) continue;
+    const text = readFileSync(abs, "utf8");
+    for (const m of text.matchAll(IMPORT_SPEC)) {
+      if (isInside(resolve(dirname(abs), m[1]!), runtimeRoot)) {
+        byPackage.set(pkgDir, {
+          packageDir: relative(root, pkgDir).split(sep).join("/"),
+          example: relative(root, abs).split(sep).join("/"),
+        });
+        break;
+      }
+    }
+  }
+  return [...byPackage.values()];
+}
+
+export function runtimeBoundaryWarnings(findings: readonly RuntimeBoundaryFinding[]): string[] {
+  return findings.map((f) =>
+    `generated code in ${f.packageDir}/ imports the owned HTTP adapter from ${OWNED_RUNTIME_DIR}/, ` +
+    `outside that workspace package (e.g. ${f.example}); its build will not resolve it. ` +
+    `Either keep importing the published adapter — pass \`runtimeImport: "${HTTP_RUNTIME_PACKAGE}"\` ` +
+    `to the ejected entity/routes generators — or move ${OWNED_RUNTIME_DIR}/ inside ${f.packageDir}/ ` +
+    `and point \`runtimeImport\` at it.`,
+  );
+}