@dforge-core/metadata 0.0.25 → 0.0.27

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to `@dforge-core/metadata` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.26] — 2026-09-15
+
+### Added
+
+- **`traitFieldConflicts()` and the `TraitFieldConflict` type** report the collisions
+  that make the installer refuse an entity: a trait contributing a field the entity
+  already has under a different type identity (`columnType ?? dbDatatype ??
+  fieldTypeCd`, the identity `TraitExpander.TryAddField` compares). Install throws on
+  one, so a module that hits it cannot install — offline readers now name the field,
+  both types, and whether the definition being kept is an authored field or another
+  trait's. Expansion itself stays total, so an editor can still draw a field list.
+
+### Fixed
+
+- **A field code that names an inherited property is a field like any other.** The
+  merge read `sink.fields[key]` against a plain object, so a trait defining
+  `constructor` found `Object.prototype`'s, contributed no column, and reported a
+  conflict against a type identity read off a function. Own-property lookups
+  throughout, on a prototype-less merge map — which also fixes the write side, where a
+  field named `__proto__` set the prototype instead of a key — and on the
+  `localTraits` lookup, which is parsed JSON with the same hazard.
+
+- **Two templated keys that collide on one entity are a conflict, not a silent
+  overwrite.** A trait defining both `{entity}_id` and `x_id` collapsed them while
+  templating, for entity `x`, before the merge ever saw them: the later definition won
+  and nothing was reported, while install rejected the entity. Each field is now
+  resolved and merged on its own, the way the installer resolves and adds one key at a
+  time — the first definition wins, the second is reported.
+
 ## [0.0.25] — 2026-09-15
 
 ### Added

package/dist/index.d.ts

@@ -442,11 +442,33 @@ declare function getColumnType(cd: string): ColumnTypeDef | undefined;
 declare const traits: readonly TraitDef[];
 /** Look up a trait by code. */
 declare function getTrait(cd: string): TraitDef | undefined;
+/** Where a field already in the merge came from, for conflict wording. */
+type FieldOrigin = "field" | "trait";
+/**
+ * A trait contributing a field the entity already has under a DIFFERENT type.
+ * The installer throws on this (`Field 'x' conflicts with trait: ...`), so a
+ * module that hits one cannot install — offline readers report it instead.
+ */
+interface TraitFieldConflict {
+    /** Column code, after `{entity}` / `{Entity}` resolution. */
+    field: string;
+    /** Whether the definition being kept is an authored field or a trait's. */
+    existingFrom: FieldOrigin;
+    /** Type identity of the definition being kept. */
+    existingType?: string;
+    /** Type identity of the trait definition being dropped. */
+    traitType?: string;
+}
 /**
  * Expand a trait (and any traits it includes) into the concrete fields it adds
  * for `entityName`, with `{entity}` / `{Entity}` tokens resolved. Returns an
  * empty object for unknown or marker traits. Field order follows include-depth
- * first, then declaration order; later definitions win on key collisions.
+ * first, then declaration order.
+ *
+ * The FIRST definition of a key wins, mirroring the installer's
+ * `TraitExpander.TryAddField`. A later definition of the same key under a
+ * different type is one the installer refuses to expand at all — see
+ * {@link traitFieldConflicts}, which reports those without throwing.
  *
  * `localTraits` is a module's own `traits.json`. A module may declare traits of
  * its own, and an entity in it names them exactly like a platform trait — so a
@@ -458,6 +480,24 @@ declare function getTrait(cd: string): TraitDef | undefined;
 declare function expandTrait(traitCd: string, entityName: string, localTraits?: TraitsFile): Record<string, FieldDef>;
 /** Expand several traits in order into one merged field map. */
 declare function expandTraits(traitCds: readonly string[], entityName: string, localTraits?: TraitsFile): Record<string, FieldDef>;
+/**
+ * The collisions that make the installer refuse an entity: a trait contributing
+ * a field the entity already has under a different type identity.
+ *
+ * `fields` is the entity's own authored fields. The installer seeds its merge
+ * with them and expands traits into it (`TraitExpander.ExpandAll`), so an
+ * authored field can conflict with a trait's exactly as two traits can — and
+ * either way install fails with `Field 'x' conflicts with trait`. Omit it to
+ * check the traits against each other alone.
+ *
+ * Returns one entry per field, in the order the conflicts are reached. An empty
+ * array means the expansion the installer performs is the one
+ * {@link expandTraits} returns.
+ */
+declare function traitFieldConflicts(traitCds: readonly string[], entityName: string, opts?: {
+    localTraits?: TraitsFile;
+    fields?: Record<string, FieldDef>;
+}): TraitFieldConflict[];
 
 /** Total digits used when building a `numeric(total, scale)` type. */
 declare const NUMERIC_TOTAL = 18;
@@ -633,8 +673,8 @@ interface AccumulationConfig {
     sign?: SignConfig;
     autoCreateBalance?: boolean;
     allowNegative?: boolean;
-    /** Document fields locked once posted. */
-    lockedFields?: string[];
+    /** Document fields locked once posted. Required; `["*"]` freezes the whole row. */
+    lockedFields: string[];
 }
 /** One registry target within an L-column's `registries` array. */
 interface LedgerRegistryEntry {
@@ -668,6 +708,8 @@ interface EntityDef {
     viewSql?: string;
     /** Display pattern using column placeholders, e.g. "{first_name} {last_name}". */
     toString?: string;
+    /** Records of this entity accept comments (composer + thread on the card). */
+    comments?: boolean;
     /** Traits expanded at install time. */
     traits?: TraitCd[];
     /** Column definitions keyed by column code. Optional when a trait (e.g. `period`) supplies all columns. */
@@ -716,7 +758,7 @@ declare function getIdentityKeys(entity: EntityDef, entityCode: string): string[
 declare function getPrimaryKeys(entity: EntityDef, entityCode: string): string[];
 
 /** `viewType` values for `ui/data_views.json`. Source: data_views.schema.json. */
-type ViewType = "grid" | "list" | "kanban" | "calendar" | "gallery" | "tree-grid" | "diagram" | "master-detail" | "library" | "matrix";
+type ViewType = "grid" | "list" | "kanban" | "calendar" | "gallery" | "tree-grid" | "diagram" | "library" | "matrix";
 /** Friendly picker list of the view kinds. */
 declare const dataViewKinds: readonly NamedKind[];
 /** A column in a data source: shorthand string code or a configured object. */
@@ -736,7 +778,7 @@ interface DataSource {
     entityCode: string;
     /** Nesting level (0 = root, 1+ = detail). */
     level?: number;
-    /** Human-readable label (used in master-detail tabs). */
+    /** Human-readable label for this data source. */
     label?: string;
     /** Column configuration. */
     columns?: ViewColumn[];
@@ -795,7 +837,7 @@ interface DataViewDef {
     /** Bootstrap icon class (e.g. 'bi-bounding-box'). */
     icon?: string;
     description?: string;
-    /** Data sources (at least one; master-detail needs two). */
+    /** Data sources (at least one). Only the first is rendered today. */
     dataSources: DataSource[];
     /** Default filter applied to all sources unless one declares its own. */
     filter?: Filter;
@@ -1024,6 +1066,8 @@ interface ManifestDef {
     dependencies?: Record<string, ModuleDependency>;
     /** Default audit history mode for this module's entities. */
     auditHistory?: "none" | "minimal" | "full";
+    /** Default for `comments` on this module's entities; each entity may override. */
+    comments?: boolean;
     /** Entity code → relative path of its JSON file (dotted keys = extensions). */
     entities?: Record<string, string>;
     /** Module category for display (e.g. 'Integration', 'Finance'). */
@@ -1382,6 +1426,95 @@ interface PrintTemplateDef {
 /** A `ui/print_templates.json` file: template_cd → definition. */
 type PrintTemplatesFile = Record<string, PrintTemplateDef>;
 
+/** A field in a card section — either a bare column code or pixel sizing with it. */
+type CardFieldEntry = string | CardFieldDef;
+interface CardFieldDef {
+    column_cd: string;
+    /** Field width in px. */
+    width?: number;
+    /** Field height in px — for multiline/textarea fields. */
+    height?: number;
+}
+/** A group of fields laid out in 1, 2 or 3 columns. */
+interface ColumnGroupSection {
+    type: "columnGroup";
+    code: string;
+    /** Section heading, in the module's authoring language. The installer gives it an
+     *  `entity_column_group` row keyed on this section's `code`, so
+     *  `translations/<locale>.json` localizes it under
+     *  `entities.<entity>.columnGroups.<code>.label` and the card renders that instead. */
+    label?: string;
+    columns: CardFieldEntry[];
+    /** Field columns across the group (1-3). Defaults to the card's own setting. */
+    cols?: number;
+}
+/**
+ * An embedded detail grid for a 1:N set column — the master/detail building
+ * block. The label comes from the set column's own metadata.
+ */
+interface SetSection {
+    type: "set";
+    code: string;
+    /** Set column code on this entity (columnType 'S'). */
+    setField: string;
+}
+/** Reference to a tab item: a columnGroup section's code, or a set column's code. */
+interface CardTabRef {
+    type: "section" | "set";
+    code: string;
+}
+/** A tab bar whose tabs are other sections — several detail grids without one long form. */
+interface TabGroupSection {
+    type: "tabGroup";
+    code: string;
+    tabs: CardTabRef[];
+}
+type CardSection = ColumnGroupSection | SetSection | TabGroupSection;
+/** Per-set-field renderer choice, keyed by the set column code. */
+interface CardSetConfig {
+    viewType?: "grid" | "list";
+    /** Opaque per-renderer options, passed verbatim to the set registration. */
+    options?: Record<string, unknown>;
+}
+/** The layout body, stored verbatim into `dForge.entity_view_layout.layout`. */
+interface CardLayout {
+    sections: CardSection[];
+    sets?: Record<string, CardSetConfig>;
+}
+/**
+ * A module-shipped card layout (value in the card_layouts map; the key is the
+ * layout name).
+ *
+ * Rows written from here carry `module_id`, so the installer recreates them on
+ * every install and removes them on uninstall. A layout the tenant drew in the
+ * card editor has `module_id` NULL and is never touched.
+ */
+interface CardLayoutDef {
+    /**
+     * Entity code the layout belongs to. Unqualified means this module owns the
+     * entity; `module.entity` targets another module's (the bridge case).
+     */
+    entity: string;
+    /**
+     * Entity view the layout hangs off. Defaults to `"default"` — the same
+     * fallback the runtime uses for an entity with no folder binding of its own.
+     * Matched against the entity's declared views case-insensitively, and filed
+     * under their spelling.
+     */
+    view?: string;
+    /**
+     * Whether this layout opens by default. Honoured on FIRST install only, and
+     * only when the view has no default yet: once a tenant has chosen their own,
+     * an upgrade does not take it back.
+     */
+    isDefault?: boolean;
+    /** Human-readable note for the package author. Not stored. */
+    description?: string;
+    layout: CardLayout;
+}
+/** `ui/card_layouts.json` — layout name → definition. */
+type CardLayoutsFile = Record<string, CardLayoutDef>;
+
 /** A seed-data file: records to insert into one entity. */
 interface SeedDataFile {
     /** Target entity code. */
@@ -1395,4 +1528,4 @@ declare const flagDefs: readonly {
     label: string;
 }[];
 
-export { AGG_TYPE_LIST, type AccumulationConfig, AggType, type AlignType, type BaseDatatypeCd, type CalendarViewConfig, type ColumnDef, type ColumnTypeCd, type ColumnTypeDef, DEP_COLUMN_TYPES, type DataSource, type DataViewDef, type DataViewsFile, type Dataset, type DepColumn, type DepColumnMode, type DepColumnType, type DepEntity, type DepProvenance, type DepProvenanceKind, type DepsFile, type DeriveOptions, type DiagramViewConfig, type DomainDef, type DomainsFile, type EntityDef, type EntityEvent, type EntityReference, type EntityViewColumnDef, type EntityViewDef, FILTER_GROUP_OPERATORS, FILTER_OPERATORS, type FieldDef, type FieldLink, type FieldOption, type FieldTypeCd, type FieldTypeDef, type Filter, type FilterCondition, type FilterGroup, type FilterGroupOperator, type FilterOperator, type FlagCd, type FolderDef, type FolderEntityBinding, type FoldersFile, type JobDef, type JobsFile, type KanbanViewConfig, type LedgerRegistryEntry, type ListLevelConfig, type ListViewConfig, type ManifestAuthor, type ManifestDef, type MenuDef, type MenuItemDef, type MenuItemType, type MenusFile, type ModuleDependency, type ModuleFeature, NUMERIC_TOTAL, type NamedKind, type NumberSequenceDef, type ParamDef, type ParamDefBase, type PeriodConfig, type PrintMargins, type PrintPageSettings, type PrintTemplateDef, type PrintTemplatesFile, type ReportDef, type ReportEntityAttachment, type ReportLayout, type ReportPanel, type ReportQuery, type ReportsFile, type RoleDef, type RolesFile, type SeedDataFile, type SettingBaseDatatype, type SettingDef, type SettingsFile, type SignConfig, type SortClause, type TraitCd, type TraitDef, type TraitsFile, type TreeGridViewConfig, type TriggerDef, type TriggersFile, type ViewColumn, type ViewType, type VizType, type WebhookPayload, type WebhookSubscription, type WebhooksFile, baseDatatypes, baseToDbDatatype, chartTypes, columnTypes, dataViewKinds, defaultParams, deriveBaseDatatype, deriveDbDatatype, expandTrait, expandTraits, fieldTypeCds, fieldTypes, fieldTypesByColumnType, flagDefs, getColumnType, getFieldType, getIdentityKeys, getLinks, getPrimaryKeys, getTrait, isFieldTypeCd, traits, vizTypes };
+export { AGG_TYPE_LIST, type AccumulationConfig, AggType, type AlignType, type BaseDatatypeCd, type CalendarViewConfig, type CardFieldDef, type CardFieldEntry, type CardLayout, type CardLayoutDef, type CardLayoutsFile, type CardSection, type CardSetConfig, type CardTabRef, type ColumnDef, type ColumnGroupSection, type ColumnTypeCd, type ColumnTypeDef, DEP_COLUMN_TYPES, type DataSource, type DataViewDef, type DataViewsFile, type Dataset, type DepColumn, type DepColumnMode, type DepColumnType, type DepEntity, type DepProvenance, type DepProvenanceKind, type DepsFile, type DeriveOptions, type DiagramViewConfig, type DomainDef, type DomainsFile, type EntityDef, type EntityEvent, type EntityReference, type EntityViewColumnDef, type EntityViewDef, FILTER_GROUP_OPERATORS, FILTER_OPERATORS, type FieldDef, type FieldLink, type FieldOption, type FieldTypeCd, type FieldTypeDef, type Filter, type FilterCondition, type FilterGroup, type FilterGroupOperator, type FilterOperator, type FlagCd, type FolderDef, type FolderEntityBinding, type FoldersFile, type JobDef, type JobsFile, type KanbanViewConfig, type LedgerRegistryEntry, type ListLevelConfig, type ListViewConfig, type ManifestAuthor, type ManifestDef, type MenuDef, type MenuItemDef, type MenuItemType, type MenusFile, type ModuleDependency, type ModuleFeature, NUMERIC_TOTAL, type NamedKind, type NumberSequenceDef, type ParamDef, type ParamDefBase, type PeriodConfig, type PrintMargins, type PrintPageSettings, type PrintTemplateDef, type PrintTemplatesFile, type ReportDef, type ReportEntityAttachment, type ReportLayout, type ReportPanel, type ReportQuery, type ReportsFile, type RoleDef, type RolesFile, type SeedDataFile, type SetSection, type SettingBaseDatatype, type SettingDef, type SettingsFile, type SignConfig, type SortClause, type TabGroupSection, type TraitCd, type TraitDef, type TraitFieldConflict, type TraitsFile, type TreeGridViewConfig, type TriggerDef, type TriggersFile, type ViewColumn, type ViewType, type VizType, type WebhookPayload, type WebhookSubscription, type WebhooksFile, baseDatatypes, baseToDbDatatype, chartTypes, columnTypes, dataViewKinds, defaultParams, deriveBaseDatatype, deriveDbDatatype, expandTrait, expandTraits, fieldTypeCds, fieldTypes, fieldTypesByColumnType, flagDefs, getColumnType, getFieldType, getIdentityKeys, getLinks, getPrimaryKeys, getTrait, isFieldTypeCd, traitFieldConflicts, traits, vizTypes };

package/dist/index.js

@@ -182,39 +182,73 @@ function applyTemplate(value, entity) {
   const local = entity.split(".").pop() ?? entity;
   return value.replace(/\{entity\}/g, local).replace(/\{Entity\}/g, titleCaseEntity(entity));
 }
-function templateFields(fields, entity) {
-  const out = {};
-  for (const [name, def] of Object.entries(fields)) {
-    const key = applyTemplate(name, entity);
-    const next = { ...def };
-    if (typeof next.description === "string") next.description = applyTemplate(next.description, entity);
-    out[key] = next;
+function templateField(def, entity) {
+  const next = { ...def };
+  if (typeof next.description === "string") next.description = applyTemplate(next.description, entity);
+  return next;
+}
+function emptyFields() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function typeKeyOf(def) {
+  return def.columnType ?? def.dbDatatype ?? def.fieldTypeCd;
+}
+function addTraitField(sink, key, def) {
+  const existing = sink.fields[key];
+  if (!Object.hasOwn(sink.fields, key)) {
+    sink.fields[key] = def;
+    sink.origin.set(key, "trait");
+    return;
+  }
+  if (sink.conflicts && !sink.conflicts.some((c) => c.field === key)) {
+    const existingType = typeKeyOf(existing);
+    const traitType = typeKeyOf(def);
+    if (existingType !== traitType) {
+      sink.conflicts.push({
+        field: key,
+        existingFrom: sink.origin.get(key) ?? "trait",
+        existingType,
+        traitType
+      });
+    }
   }
-  return out;
 }
 function expandTrait(traitCd, entityName, localTraits) {
-  return expandTraitInner(traitCd, entityName, localTraits, /* @__PURE__ */ new Set());
+  const sink = { fields: emptyFields(), origin: /* @__PURE__ */ new Map() };
+  expandTraitInner(traitCd, entityName, localTraits, /* @__PURE__ */ new Set(), sink);
+  return sink.fields;
 }
-function expandTraitInner(traitCd, entityName, localTraits, path) {
-  if (path.has(traitCd)) return {};
+function expandTraitInner(traitCd, entityName, localTraits, path, sink) {
+  if (path.has(traitCd)) return;
   path.add(traitCd);
-  const trait = localTraits?.[traitCd] ?? byCd3.get(traitCd);
-  const result = {};
+  const trait = localTraits && Object.hasOwn(localTraits, traitCd) ? localTraits[traitCd] : byCd3.get(traitCd);
   if (trait) {
     for (const included of trait.includes ?? []) {
-      Object.assign(result, expandTraitInner(included, entityName, localTraits, path));
+      expandTraitInner(included, entityName, localTraits, path, sink);
+    }
+    for (const [name, def] of Object.entries(trait.fields ?? {})) {
+      addTraitField(sink, applyTemplate(name, entityName), templateField(def, entityName));
     }
-    Object.assign(result, templateFields(trait.fields ?? {}, entityName));
   }
   path.delete(traitCd);
-  return result;
 }
 function expandTraits(traitCds, entityName, localTraits) {
-  const result = {};
+  const sink = { fields: emptyFields(), origin: /* @__PURE__ */ new Map() };
   for (const cd of traitCds) {
-    Object.assign(result, expandTraitInner(cd, entityName, localTraits, /* @__PURE__ */ new Set()));
+    expandTraitInner(cd, entityName, localTraits, /* @__PURE__ */ new Set(), sink);
   }
-  return result;
+  return sink.fields;
+}
+function traitFieldConflicts(traitCds, entityName, opts = {}) {
+  const sink = { fields: emptyFields(), origin: /* @__PURE__ */ new Map(), conflicts: [] };
+  for (const [key, def] of Object.entries(opts.fields ?? {})) {
+    sink.fields[key] = def;
+    sink.origin.set(key, "field");
+  }
+  for (const cd of traitCds) {
+    expandTraitInner(cd, entityName, opts.localTraits, /* @__PURE__ */ new Set(), sink);
+  }
+  return sink.conflicts;
 }
 
 // src/derive.ts
@@ -332,7 +366,6 @@ var dataViewKinds = [
   { cd: "gallery", name: "Gallery" },
   { cd: "tree-grid", name: "Tree Grid" },
   { cd: "diagram", name: "Diagram" },
-  { cd: "master-detail", name: "Master / Detail" },
   { cd: "library", name: "Library" },
   { cd: "matrix", name: "Matrix" }
 ];
@@ -422,6 +455,7 @@ export {
   getPrimaryKeys,
   getTrait,
   isFieldTypeCd,
+  traitFieldConflicts,
   traits,
   vizTypes
 };