@metaobjectsdev/codegen-ts 0.24.5 → 1.0.0-rc.1

package/src/index.ts

@@ -37,8 +37,16 @@ export {
 } from "./generator-registry.js";
 export type { GeneratorRegistryEntry, GeneratorTier } from "./generator-registry.js";
 
-export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider, GeneratorSpec, DocsConfig, ResolvedDocsConfig, DocsSurface, ApiSurface } from "./metaobjects-config.js";
+export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider, GeneratorSpec, DocsConfig, ResolvedDocsConfig, DocsSurface, ApiSurface, VerifyConfig } from "./metaobjects-config.js";
 export { defineConfig, normalizeConfig, resolveGenerators, resolveDocsConfig } from "./metaobjects-config.js";
+// The dialect every generator falls back to when a config declares none. Exported because
+// `meta docs` must apply the SAME default `normalizeConfig` does — a command that resolved
+// the dialect differently would document a schema the toolchain does not produce.
+export { DEFAULT_DIALECT } from "./metaobjects-config.js";
+// The runner's own "does this model need a dialect?" guard. `meta docs` must ask it rather
+// than defaulting, because DEFAULT_DIALECT is inert and a DB project with no dialect is one
+// `meta gen` REFUSES — documenting it as sqlite states an answer the toolchain never gave.
+export { dbEmittingObjects, missingDialectMessage } from "./db-emitting.js";
 export { apiLabel } from "./generators/api-label.js";
 
 export type { ColumnSpec, DefaultExpr } from "./column-mapper.js";
@@ -70,7 +78,8 @@ export { decideAndWrite, GitMissingError } from "./overwrite-policy.js";
 export { contentHash, readGeneratedHash, listGeneratedPaths } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
-export { GENERATED_HEADER, EXTRA_SUFFIX, DEFAULT_OUT_DIR, CODEGEN_ATTR_EMIT_TANSTACK, CODEGEN_ATTR_EMIT_GRID, CODEGEN_ATTR_EMIT_FORM, CODEGEN_ATTR_EMIT_ROUTES } from "./constants.js";
+export { GENERATED_HEADER, DEFAULT_OUT_DIR, RETIRED_CODEGEN_ATTRS, type RetiredCodegenAttr } from "./constants.js";
+export { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 
 export { formatTs } from "./format.js";
 
@@ -90,14 +99,30 @@ export type { DocPageNode, DocPagePlacement } from "./docs-paths.js";
 export { isProjection, isWriteThrough } from "./projection/projection-detector.js";
 export { isAbstract, emitsInstanceArtifacts, emitsWriteArtifacts } from "./instance-artifacts.js";
 // The UI tier asks THESE — "is there an endpoint?" — never the storage predicates.
-export { servesReadApi, servesWriteApi } from "./api-surface.js";
+export { hasGeneratedForm, restPath, servesReadApi, servesWriteApi } from "./api-surface.js";
+// #356 — every emitter selects a field's view by the SURFACE it renders, never by
+// declaration position. An owned generator (FR-040) composing the render layer must
+// use this too, or it reinstates the order-dependence in its own copy.
+export { viewForContext, VIEW_CONTEXT_FORM, VIEW_CONTEXT_GRID } from "./view-context.js";
+// The shared per-field UI derivation. `valueObjectFor` is the predicate the React form
+// generator and the `agent/ui.md` docs page must both ask — it decides whether a field is
+// rendered as an input at all — and `humanize` is the one body behind every generated
+// label. Both are exported so the react tier reads them rather than keeping a copy.
+export { humanize, inferViewKind, labelFor, currencyMetaFor, valueObjectFor } from "./templates/field-meta.js";
 // The DB-free descriptor module the UI tier imports from (see entity-meta-file.ts).
 export { renderEntityMetaFile, entityMetaFileName, entityMetaSpecifier } from "./templates/entity-meta-file.js";
 // FR-017 TPH helpers — used by the per-framework codegen packages (tanstack,
 // react) to dispatch polymorphic/per-subtype emission and skip subtype files.
 export { isTphDiscriminatorBase, tphConcreteSubtypes, collectTphSubtypeFields, tphPlan, tphRouteSegment } from "./templates/tph-discriminator.js";
 export type { TphPlan, TphSubtypePlan } from "./templates/tph-discriminator.js";
-export { isTphSubtype, tphDiscriminatorPin } from "./templates/zod-validators.js";
+export { isTphSubtype, tphDiscriminatorBase, tphDiscriminatorPin } from "./templates/zod-validators.js";
+
+// The ONE sortability rule. It builds the server-side `<Entity>SortAllowlist` and the
+// client-side sort union, and it is public so a UI-tier generator (a data-grid column
+// emitter, say) marks a column sortable by ASKING the server's rule rather than
+// reimplementing its three branches out of tree. A hand-copied predicate is how the
+// grid came to offer headers the allowlist rejects (#352/#354).
+export { isSortableField, sortableFields } from "./templates/filter-shared.js";
 
 // ADR-0034 reference-template composition helpers. Promoted to the public engine
 // surface so a COPIED reference generator (src/reference/*.ts → consumer's
@@ -131,12 +156,19 @@ export {
   renderFindByIdFn,
   renderListFn,
   renderCreateFn,
+  // #203 — the `insertPreserving<Entity>` escape hatch, emitted only for an entity with an
+  // `@autoSet` timestamp. Public because an OWNED queries generator must be able to emit it:
+  // without this primitive (and `hasAutoSetFields` below) an ejected copy silently drops the
+  // escape hatch on exactly the entities that have one, and the caller loses the only
+  // generated way to insert a row preserving its own `@autoSet` values.
+  renderInsertPreservingFn,
   renderUpdateFn,
   renderDeleteByIdFn,
   renderReverseFinderFns,
   reverseFksFor,
   getPkInfo,
 } from "./templates/queries.js";
+export { hasAutoSetFields } from "./templates/zod-validators.js";
 
 // Built-in template render functions — the composition seam for adopters who
 // want to call a built-in template, then post-process / append to its output
@@ -160,9 +192,27 @@ export { renderFilterType } from "./templates/filter-type.js";
 export { renderFilterAllowlist, renderSortAllowlist } from "./templates/filter-allowlist.js";
 export { renderEntityConstants, resourcePath } from "./templates/entity-constants.js";
 export { renderQueriesFile } from "./templates/queries-file.js";
+// #348 — which CRUD verbs a generated routes file mounts. Public because an OWNED
+// routes generator (ADR-0034) composes the same render call and needs the same option.
+export { CRUD_VERBS, resolveExpose, intersectExpose, exposeLine } from "./routes-expose.js";
+export type { CrudVerb, ExposeOption } from "./routes-expose.js";
 export { renderRoutesFile } from "./templates/routes-file.js";
 export { renderRoutesFileHono } from "./templates/routes-file-hono.js";
 export { renderValueObjectFile } from "./templates/value-object-file.js";
+export { renderNamesDecl } from "./templates/names-decl.js";
+export type { NamesDeclOpts } from "./templates/names-decl.js";
+export {
+  resolveObjectNames,
+  resolveSuperFragmentNames,
+  namesArtifactSuperOf,
+  namesRef,
+  namesConstArg,
+  physicalNameExpr,
+  columnExpr,
+  type ObjectNames,
+  type FieldNames,
+  type SuperNames,
+} from "./names.js";
 export { renderProjectionDecl } from "./templates/projection-decl.js";
 export type { ProjectionDeclOpts } from "./templates/projection-decl.js";
 export { extractViewSpec } from "./projection/extract-view-spec.js";
@@ -211,6 +261,16 @@ export { buildTemplateDocData } from "./generators/template-doc-builder.js";
 // worse than the bug report this is meant to avoid.
 export { requirementTests } from "./generators/requirement-tests.js";
 export { requirementsFile } from "./generators/requirements-file.js";
+// The `agent` docs surface. `AgentSchemaInput` is exported because the CLI SUPPLIES it —
+// codegen-ts deliberately does not compute the physical schema (see agent-schema-input.ts).
+export { agentDocsFile } from "./generators/agent-docs-file.js";
+export type { AgentDocsFileOpts } from "./generators/agent-docs-file.js";
+export type {
+  AgentSchemaInput,
+  SchemaColumnLike,
+  SchemaTableLike,
+  SchemaViewLike,
+} from "./generators/agent-schema-input.js";
 export type { RequirementRow } from "./generators/requirements-view.js";
 // The projection itself, not just its type: it is the authority on WHICH doc slots a
 // requirement surface actually renders, and `meta verify`'s authoring lint tells an

package/src/metaobjects-config.ts

@@ -55,6 +55,14 @@ export interface ResolvedGenConfig {
    *  api-docs reads this to AUTO-DETECT whether to document the Hono CRUD surface
    *  (it otherwise mirrors the default Fastify-only suite). Undefined ⇒ false. */
   includeHonoRoutes?: boolean;
+  /** §A6 — whether the OPT-IN names generator (namesFile) is active in the run,
+   *  aggregated by the runner from the suite's `emitsNames` markers. A generator that
+   *  wants to REFERENCE `<Entity>Names` reads this to know the artifact will exist:
+   *  the names generator is opt-in under ADR-0034 scaffold-and-own, so an
+   *  unconditional import would break every project that has not enabled it.
+   *  Undefined ⇒ false. Templates read the same fact off `RenderContext.includeNames`,
+   *  which the runner sets from this same aggregation. */
+  includeNames?: boolean;
   /**
    * FR-019 / ADR-0026: the module specifier from which an externally-PROVIDED
    * shared enum (`@provided: true` on an abstract package-level `field.enum`) is
@@ -171,6 +179,9 @@ export interface MetaobjectsGenConfig extends Omit<ResolvedGenConfig, "dbImport"
   emitAbstractShapes?: boolean;
   /** Docs-output config consumed by the `meta docs` door. See {@link DocsConfig}. */
   docs?: DocsConfig;
+  /** `meta verify` / `meta gen` advisory settings. Nothing here affects codegen.
+   *  See {@link VerifyConfig}. */
+  verify?: VerifyConfig;
   /** Named output destinations. Generators reference one via `target`. */
   targets?: Record<string, TargetConfig>;
   /** importBase for the default target (top-level outDir). */
@@ -221,7 +232,7 @@ export interface NormalizedMetaobjectsGenConfig
   targets: Record<string, ResolvedTarget>;
 }
 
-export type DocsSurface = "model" | "api" | "requirements";
+export type DocsSurface = "model" | "api" | "requirements" | "agent";
 
 export interface ApiSurface {
   lang: string;
@@ -232,6 +243,33 @@ export interface ApiSurface {
 /** The single docs-output config: where ALL doc surfaces go, how pages are laid
  *  out, and which surfaces to emit. Read by the `meta docs` door (and, when the
  *  api surface fans out, by each port's docs command). */
+/**
+ * `meta verify` settings. Nothing here changes what codegen emits.
+ *
+ * This block existed once before, for `verify.testFiles`, and was removed in 0.24.0 with
+ * the `@verifiedBy` vocabulary it served. It returns for exactly the reason it was added:
+ * the advisory scans carry a list of conventions that is, unavoidably, a guess about
+ * someone else's repository. Built-in defaults for the layouts that demonstrably exist,
+ * PLUS a project-declared list, is the shape that survives being wrong.
+ */
+export interface VerifyConfig {
+  /**
+   * Path globs the "you hand-rolled what MetaObjects models" advisory skips entirely.
+   * Relative to the project root, forward-slash, `**` spans separators; a glob matching a
+   * directory prunes the whole subtree. ADDS to the built-in exclusions rather than
+   * replacing them.
+   *
+   *   verify: { antiPatternIgnore: ["db/changelog/**", "vendor/sql/**"] }
+   *
+   * Reach for this when the advisory reports a file you cannot act on — a vendored SQL
+   * archive, read-only reference DDL, a migration tool whose naming the built-ins do not
+   * recognise. It is deliberately narrower than `--no-antipatterns`: silencing the whole
+   * scan to quiet one directory is how a useful advisory gets switched off wholesale, the
+   * same failure `--no-requirement-lint` was carved out to avoid.
+   */
+  antiPatternIgnore?: string[];
+}
+
 export interface DocsConfig {
   outDir?: string;
   layout?: OutputLayout;
@@ -264,7 +302,15 @@ export function resolveDocsConfig(
     // files for a project declaring no `requirement.*` node — not an empty page. A
     // project without a ledger sees byte-identical output to before the surface
     // existed; see requirements-file.ts.
-    surfaces: cli.surfaces ?? block?.surfaces ?? ["model", "api", "requirements"],
+    //
+    // `agent` defaults ON for the same reason and under the same discipline: each of
+    // its three pages renders "" when its tier has nothing to describe, and an empty
+    // render emits no file. It is additionally gated on a loadable gen config, exactly
+    // as `api` is — physical names, the dialect and view dispatch all come from there,
+    // so without one there is nothing true to say. Turning it on by default is what
+    // makes the always-on agent-context pointer able to name the files: a pointer to a
+    // page an adopter has to opt into is a pointer at nothing.
+    surfaces: cli.surfaces ?? block?.surfaces ?? ["model", "api", "requirements", "agent"],
     apiSurfaces: cli.apiSurfaces ?? block?.apiSurfaces ?? [{ lang: "ts", subDir: "api" }],
   };
 }