@metaobjectsdev/codegen-ts 0.5.0-rc.1

package/src/import-path.ts

@@ -0,0 +1,153 @@
+// Package-driven output placement — path + import-specifier computation.
+// In "flat" mode every function returns exactly today's value, so flat
+// output is byte-identical. See
+// docs/superpowers/specs/2026-05-18-phase4d-package-output-placement-design.md.
+
+import { relative as posixRelative } from "node:path/posix";
+import { PACKAGE_SEPARATOR } from "@metaobjectsdev/metadata";
+import { withExt, type ExtStyle } from "./render-context.js";
+
+export type OutputLayout = "flat" | "package";
+
+/** "a::b::c" → "a/b/c"; undefined / "" → "". */
+export function packageToPath(pkg: string | undefined): string {
+  if (pkg === undefined || pkg === "") return "";
+  return pkg.split(PACKAGE_SEPARATOR).join("/");
+}
+
+/** Output path (relative to outDir) for an entity's generated file. */
+export function entityOutputPath(
+  layout: OutputLayout,
+  pkg: string | undefined,
+  filename: string,
+): string {
+  if (layout === "flat") return filename;
+  const dir = packageToPath(pkg);
+  return dir === "" ? filename : `${dir}/${filename}`;
+}
+
+/** Relative dir prefix (ending in "/") from `fromDir` to `toDir`, both
+ *  POSIX paths relative to outDir. Same dir → "./". */
+function relativeDirPrefix(fromDir: string, toDir: string): string {
+  let rel = posixRelative(fromDir, toDir);
+  if (rel === "") rel = ".";
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return `${rel}/`;
+}
+
+/** Module specifier to import `toEntity` (in `toPkg`) from a file in `fromPkg`.
+ *  Flat → always "./<toEntity>". */
+export function crossEntitySpecifier(
+  layout: OutputLayout,
+  fromPkg: string | undefined,
+  toPkg: string | undefined,
+  toEntity: string,
+  extStyle: ExtStyle,
+): string {
+  if (layout === "flat") return withExt(`./${toEntity}`, extStyle);
+  const prefix = relativeDirPrefix(packageToPath(fromPkg), packageToPath(toPkg));
+  return withExt(`${prefix}${toEntity}`, extStyle);
+}
+
+/** Barrel (at outDir root) re-export specifier for an entity.
+ *  Equivalent to crossEntitySpecifier with fromPkg=undefined (barrel is always at root). */
+export function barrelEntrySpecifier(
+  layout: OutputLayout,
+  pkg: string | undefined,
+  entity: string,
+  extStyle: ExtStyle,
+): string {
+  return crossEntitySpecifier(layout, undefined, pkg, entity, extStyle);
+}
+
+/** A `dbImport` (or any module specifier) adjusted for a file at the given
+ *  package depth. A non-relative specifier (alias / package) is depth-invariant
+ *  and returned unchanged; a relative one gets extra "../" per package segment.
+ *  Caller contract: a relative moduleSpec must be relative to outDir root (as
+ *  dbImport is). */
+export function relativeModuleSpecifier(
+  layout: OutputLayout,
+  pkg: string | undefined,
+  moduleSpec: string,
+): string {
+  if (layout === "flat") return moduleSpec;
+  const isRelative = moduleSpec.startsWith("./") || moduleSpec.startsWith("../");
+  if (!isRelative) return moduleSpec;
+  const dir = packageToPath(pkg);
+  const depth = dir === "" ? 0 : dir.split("/").length;
+  if (depth === 0) return moduleSpec;
+  const extra = "../".repeat(depth);
+  return moduleSpec.startsWith("./") ? extra + moduleSpec.slice(2) : extra + moduleSpec;
+}
+
+/** A fully-resolved output destination. Import-identity belongs to the
+ *  destination, not the generator. */
+export interface ResolvedTarget {
+  name: string;
+  outDir: string;
+  /** Package-specifier prefix others use to import modules produced here.
+   *  Required only when another target imports from this one. */
+  importBase: string | undefined;
+  outputLayout: OutputLayout;
+  dbImport: string;
+}
+
+/** importBase + (package path when package layout) + entity, extension-less. */
+function crossTargetEntityPath(
+  entityTarget: ResolvedTarget,
+  entityPkg: string | undefined,
+  entityName: string,
+): string {
+  const base = entityTarget.importBase;
+  if (base === undefined) {
+    throw new Error(
+      `Cannot emit cross-target import: target "${entityTarget.name}" has no importBase. ` +
+      `Set importBase on the target that holds the entity modules.`,
+    );
+  }
+  const pkgPath = entityTarget.outputLayout === "package" ? packageToPath(entityPkg) : "";
+  return pkgPath === "" ? `${base}/${entityName}` : `${base}/${pkgPath}/${entityName}`;
+}
+
+/** Specifier to import entity `entityName` (in `entityPkg`, produced into
+ *  `entityTarget`) from a file emitted into `selfTarget`. Same target → relative
+ *  (extStyle honored); cross target → extension-less importBase path. */
+export function entityModuleSpecifier(
+  selfTarget: ResolvedTarget,
+  entityTarget: ResolvedTarget,
+  entityPkg: string | undefined,
+  entityName: string,
+  extStyle: ExtStyle,
+): string {
+  if (selfTarget.name === entityTarget.name) {
+    return crossEntitySpecifier(entityTarget.outputLayout, entityPkg, entityPkg, entityName, extStyle);
+  }
+  return crossTargetEntityPath(entityTarget, entityPkg, entityName);
+}
+
+/** A same-target sibling module (e.g. "<Entity>.columns"). Always relative,
+ *  package-layout aware, extStyle honored. */
+export function siblingSpecifier(
+  selfTarget: ResolvedTarget,
+  entityPkg: string | undefined,
+  basename: string,
+  extStyle: ExtStyle,
+): string {
+  return crossEntitySpecifier(selfTarget.outputLayout, entityPkg, entityPkg, basename, extStyle);
+}
+
+/** Barrel re-export specifier. Barrel sits at its target root, so same-target
+ *  uses fromPkg=undefined (barrelEntrySpecifier); cross-target is the
+ *  extension-less importBase path. */
+export function barrelModuleSpecifier(
+  selfTarget: ResolvedTarget,
+  entityTarget: ResolvedTarget,
+  entityPkg: string | undefined,
+  entityName: string,
+  extStyle: ExtStyle,
+): string {
+  if (selfTarget.name === entityTarget.name) {
+    return barrelEntrySpecifier(entityTarget.outputLayout, entityPkg, entityName, extStyle);
+  }
+  return crossTargetEntityPath(entityTarget, entityPkg, entityName);
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// Public API surface for @metaobjectsdev/codegen-ts.
+//
+// Architecture: Vite-style plugin model.
+// See docs/superpowers/specs/2026-05-12-pluggable-generators-design.md.
+
+export { runGen } from "./runner.js";
+export type { RunGenOpts, RunGenResult } from "./runner.js";
+
+export type { Generator, GenContext, EmittedFile, GeneratorFactory } from "./generator.js";
+export { perEntity, oncePerRun } from "./generator.js";
+
+export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy } from "./metaobjects-config.js";
+export { defineConfig, normalizeConfig } from "./metaobjects-config.js";
+
+export type { ColumnSpec, DefaultExpr } from "./column-mapper.js";
+export { mapColumnType } from "./column-mapper.js";
+
+export type { PkInfo } from "./pk-resolver.js";
+export { buildPkMap } from "./pk-resolver.js";
+
+export type { RelationEntry, RelationMap } from "./relation-resolver.js";
+export { buildRelationMap } from "./relation-resolver.js";
+
+export type { RenderContext } from "./render-context.js";
+export { makeRenderContext } from "./render-context.js";
+
+export type { WriteStatus, WriteResult, MergeStrategy } from "./overwrite-policy.js";
+export { decideAndWrite } from "./overwrite-policy.js";
+
+export { CodegenError } from "./errors.js";
+export { GENERATED_HEADER, EXTRA_SUFFIX, DEFAULT_OUT_DIR } from "./constants.js";
+
+export { formatTs } from "./format.js";
+
+export { pluralize, columnNameFromField, tableNameFromEntity, viewNameFromProjection } from "./naming.js";
+
+export { packageToPath, entityOutputPath, crossEntitySpecifier, barrelEntrySpecifier, relativeModuleSpecifier, entityModuleSpecifier, siblingSpecifier, barrelModuleSpecifier } from "./import-path.js";
+export type { OutputLayout, ResolvedTarget } from "./import-path.js";
+
+export { isProjection, isWriteThrough } from "./projection/projection-detector.js";
+export { extractViewSpec } from "./projection/extract-view-spec.js";
+export type { ExtractContext } from "./projection/extract-view-spec.js";
+export { emitViewDdl } from "./projection/view-ddl-emit.js";
+export type { EmitOptions as ViewDdlEmitOptions } from "./projection/view-ddl-emit.js";
+export type { JoinNode, JoinTree, SelectColumn, SelectSpec, ViewSpec } from "./projection/view-spec.js";

package/src/metaobjects-config.ts

@@ -0,0 +1,95 @@
+import type { Generator } from "./generator.js";
+import type { ExtStyle } from "./render-context.js";
+import type { OutputLayout, ResolvedTarget } from "./import-path.js";
+
+export type Dialect = "sqlite" | "postgres";
+export type ColumnNamingStrategy = "snake_case" | "literal" | "kebab-case";
+export type { ExtStyle };
+export type { OutputLayout };
+export type { ResolvedTarget };
+
+/** The implicit target synthesized from top-level config (outDir/outputLayout/dbImport). */
+export const DEFAULT_TARGET_NAME = "default";
+
+/** User-facing per-target output config. */
+export interface TargetConfig {
+  outDir: string;
+  importBase?: string;
+  outputLayout?: OutputLayout;
+  dbImport?: string;
+}
+
+/** Subset of MetaobjectsGenConfig surfaced to generators via GenContext. */
+export interface ResolvedGenConfig {
+  outDir: string;
+  extStyle: ExtStyle;
+  dbImport: string;
+  dialect: Dialect;
+  /** "flat" (default) — all files in outDir; "package" — files placed in a sub-path derived from each entity's metadata package. */
+  outputLayout?: OutputLayout;
+}
+
+export interface MetaobjectsGenConfig extends ResolvedGenConfig {
+  generators: Generator[];
+  /** How field names map to DB column names when @dbColumn is omitted. Defaults to "snake_case". */
+  columnNamingStrategy?: ColumnNamingStrategy;
+  /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
+  apiPrefix?: string;
+  /** Named output destinations. Generators reference one via `target`. */
+  targets?: Record<string, TargetConfig>;
+  /** importBase for the default target (top-level outDir). */
+  importBase?: string;
+}
+
+/** MetaobjectsGenConfig after applying defaults. All fields required.
+ *  `targets` is Omitted from the base so it can narrow from the user-facing
+ *  TargetConfig to the fully-resolved ResolvedTarget (incompatible under
+ *  exactOptionalPropertyTypes otherwise). */
+export interface NormalizedMetaobjectsGenConfig extends Omit<MetaobjectsGenConfig, "targets"> {
+  columnNamingStrategy: ColumnNamingStrategy;
+  apiPrefix: string;
+  outputLayout: OutputLayout;
+  targets: Record<string, ResolvedTarget>;
+}
+
+/** Identity passthrough; exists for IDE type-inference + autocomplete. */
+export function defineConfig(config: MetaobjectsGenConfig): MetaobjectsGenConfig {
+  return config;
+}
+
+/** Synthesize the implicit "default" target from top-level fields and resolve
+ *  each named target (outputLayout + dbImport fall back to top-level;
+ *  importBase does NOT inherit — it is a per-target identity). */
+export function resolveTargets(config: MetaobjectsGenConfig): Record<string, ResolvedTarget> {
+  const layout: OutputLayout = config.outputLayout ?? "flat";
+  const out: Record<string, ResolvedTarget> = {
+    [DEFAULT_TARGET_NAME]: {
+      name: DEFAULT_TARGET_NAME,
+      outDir: config.outDir,
+      importBase: config.importBase,
+      outputLayout: layout,
+      dbImport: config.dbImport,
+    },
+  };
+  for (const [name, t] of Object.entries(config.targets ?? {})) {
+    out[name] = {
+      name,
+      outDir: t.outDir,
+      importBase: t.importBase,
+      outputLayout: t.outputLayout ?? layout,
+      dbImport: t.dbImport ?? config.dbImport,
+    };
+  }
+  return out;
+}
+
+/** Apply defaults to a MetaobjectsGenConfig, returning a NormalizedMetaobjectsGenConfig. */
+export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobjectsGenConfig {
+  return {
+    ...config,
+    columnNamingStrategy: config.columnNamingStrategy ?? "snake_case",
+    apiPrefix: config.apiPrefix ?? "",
+    outputLayout: config.outputLayout ?? "flat",
+    targets: resolveTargets(config),
+  };
+}

package/src/naming.ts

@@ -0,0 +1,84 @@
+// Naming helpers — case conversion + pluralization for codegen output.
+// All functions are pure.
+
+import type { ColumnNamingStrategy } from "./metaobjects-config.js";
+
+/**
+ * Convert PascalCase or camelCase to snake_case.
+ * Treats consecutive capitals (e.g., "APIKey") as a single word: "api_key".
+ */
+export function toSnakeCase(s: string): string {
+  return s
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+/** Convert PascalCase or camelCase to kebab-case. */
+function toKebabCase(s: string): string {
+  return toSnakeCase(s).replace(/_/g, "-");
+}
+
+/** Apply a ColumnNamingStrategy to a name. */
+function applyStrategy(name: string, strategy: ColumnNamingStrategy): string {
+  switch (strategy) {
+    case "snake_case": return toSnakeCase(name);
+    case "literal":    return name;
+    case "kebab-case": return toKebabCase(name);
+  }
+}
+
+/**
+ * Convert snake_case to camelCase. Preserves already-camelCase input.
+ */
+export function toCamelCase(s: string): string {
+  return s.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * Simple English pluralization. Documented imperfection per design §13 #1:
+ * irregular plurals (Person → Persons, not People) are not handled.
+ * Users override via source[dbTable]@name in metadata.
+ */
+export function pluralize(s: string): string {
+  if (/(s|x|z|ch|sh)$/i.test(s)) return s + "es";
+  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + "ies";
+  return s + "s";
+}
+
+/** PascalCase entity → strategy-applied plural for DB table name. */
+export function tableNameFromEntity(
+  entityName: string,
+  strategy: ColumnNamingStrategy = "snake_case",
+): string {
+  return applyStrategy(pluralize(entityName), strategy);
+}
+
+/** camelCase or PascalCase field → strategy-applied DB column name. */
+export function columnNameFromField(
+  fieldName: string,
+  strategy: ColumnNamingStrategy = "snake_case",
+): string {
+  return applyStrategy(fieldName, strategy);
+}
+
+/**
+ * PascalCase projection name → "v_" prefix + strategy applied (not pluralized).
+ * E.g. "ProgramSummary" + snake_case → "v_program_summary".
+ * With kebab-case the separator prefix is "v-" to stay consistent.
+ */
+export function viewNameFromProjection(
+  projectionName: string,
+  strategy: ColumnNamingStrategy,
+): string {
+  switch (strategy) {
+    case "snake_case": return "v_" + toSnakeCase(projectionName);
+    case "literal":    return "v_" + projectionName;
+    case "kebab-case": return "v-" + toKebabCase(projectionName);
+  }
+}
+
+/** PascalCase entity → camelCase plural for the Drizzle table variable. */
+export function variableNameFromEntity(entityName: string): string {
+  return pluralize(toCamelCase(entityName.charAt(0).toLowerCase() + entityName.slice(1)));
+}

package/src/overwrite-policy.ts

@@ -0,0 +1,39 @@
+// Overwrite policy: drives the per-file write decision based on the @generated header.
+// Per design §8 — read-only generated files; refuse to clobber hand-written code.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { GENERATED_HEADER } from "./constants.js";
+
+export type WriteStatus = "new" | "overwrite" | "refused" | "skipped";
+export type MergeStrategy = "overwrite" | "skip-existing";
+
+export interface WriteResult {
+  path: string;
+  status: WriteStatus;
+}
+
+export function decideAndWrite(
+  path: string,
+  content: string,
+  strategy: MergeStrategy = "overwrite",
+): WriteResult {
+  // 'skip-existing' only skips overwrites, not new files.
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    return { path, status: "new" };
+  }
+
+  const current = readFileSync(path, "utf-8");
+  if (!current.includes(GENERATED_HEADER)) {
+    return { path, status: "refused" };
+  }
+
+  if (strategy === "skip-existing") {
+    return { path, status: "skipped" };
+  }
+
+  writeFileSync(path, content);
+  return { path, status: "overwrite" };
+}

package/src/pk-resolver.ts

@@ -0,0 +1,47 @@
+// PK resolver — pre-pass over the loaded metadata to build a name → PK info map.
+// codegen uses this when emitting FK columns (per design §13 #2).
+
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import {
+  FIELD_SUBTYPE_LONG,
+  IDENTITY_ATTR_FIELDS,
+  IDENTITY_ATTR_GENERATION,
+} from "@metaobjectsdev/metadata";
+
+export interface PkInfo {
+  /** Field name within the entity (e.g., "id"). */
+  fieldName: string;
+  /** Field subType (e.g., "long", "string", "int"). */
+  fieldSubType: string;
+  /** Generation strategy: 'increment' | 'uuid' | 'assigned' (or undefined). */
+  generation?: string;
+}
+
+/**
+ * Walk the loaded metadata root, find each object's primary identity,
+ * resolve the referenced field's subType, and build a name → PkInfo map.
+ *
+ * Used by FK column emission: when Post.authorId references User, codegen
+ * looks up User's PK info to choose the matching FK column type.
+ */
+export function buildPkMap(root: MetaRoot): Map<string, PkInfo> {
+  const result = new Map<string, PkInfo>();
+  for (const obj of root.objects()) {
+    // primaryIdentity() resolves the primary identity across the super-chain.
+    const primary = obj.primaryIdentity();
+    if (!primary) continue;
+    const fields = primary.ownAttr(IDENTITY_ATTR_FIELDS);
+    if (!Array.isArray(fields) && typeof fields !== "string") continue;
+    const fieldsList = Array.isArray(fields) ? fields : [fields];
+    if (fieldsList.length === 0) continue;
+    const pkFieldName = String(fieldsList[0]);
+    // findField() resolves the field across the super-chain (handles extends:).
+    const pkField = obj.findField(pkFieldName);
+    const fieldSubType = pkField?.subType ?? FIELD_SUBTYPE_LONG; // sane default
+    const generation = primary.ownAttr(IDENTITY_ATTR_GENERATION);
+    const info: PkInfo = { fieldName: pkFieldName, fieldSubType };
+    if (typeof generation === "string") info.generation = generation;
+    result.set(obj.name, info);
+  }
+  return result;
+}