@dforge-core/metadata 0.0.24 → 0.0.26

package/src/traits.ts

@@ -91,22 +91,93 @@ function applyTemplate(value: string, entity: string): string {
 	return value.replace(/\{entity\}/g, local).replace(/\{Entity\}/g, titleCaseEntity(entity));
 }
 
-function templateFields(fields: Record<string, FieldDef>, entity: string): Record<string, FieldDef> {
-	const out: Record<string, FieldDef> = {};
-	for (const [name, def] of Object.entries(fields)) {
-		const key = applyTemplate(name, entity);
-		const next: FieldDef = { ...def };
-		if (typeof next.description === "string") next.description = applyTemplate(next.description, entity);
-		out[key] = next;
+function templateField(def: FieldDef, entity: string): FieldDef {
+	const next: FieldDef = { ...def };
+	if (typeof next.description === "string") next.description = applyTemplate(next.description, entity);
+	return next;
+}
+
+/**
+ * The merged field map. Prototype-less: a field code is author-supplied, so on a
+ * plain object one named `constructor` would read back as a field already there
+ * and one named `__proto__` would not write at all.
+ */
+function emptyFields(): Record<string, FieldDef> {
+	return Object.create(null) as Record<string, FieldDef>;
+}
+
+/**
+ * The identity the installer compares on a key collision — `TryAddField` reads
+ * `ColumnType ?? DbDatatype ?? FieldTypeCd` and treats two definitions as the
+ * same field only when these match.
+ */
+function typeKeyOf(def: FieldDef): string | undefined {
+	return def.columnType ?? def.dbDatatype ?? def.fieldTypeCd;
+}
+
+/** 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.
+ */
+export 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;
+}
+
+interface MergeSink {
+	fields: Record<string, FieldDef>;
+	origin: Map<string, FieldOrigin>;
+	conflicts?: TraitFieldConflict[];
+}
+
+/**
+ * Merge one trait-contributed field in, the way the installer does: the FIRST
+ * definition wins, and a later one of a different type is a conflict rather
+ * than an overwrite. See `TraitExpander.TryAddField`.
+ */
+function addTraitField(sink: MergeSink, key: string, def: FieldDef): void {
+	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;
+	// Same type (or a conflict already recorded) — keep the first definition,
+	// which is what the installer does.
 }
 
 /**
  * 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
@@ -120,7 +191,9 @@ export function expandTrait(
 	entityName: string,
 	localTraits?: TraitsFile,
 ): Record<string, FieldDef> {
-	return expandTraitInner(traitCd, entityName, localTraits, new Set());
+	const sink: MergeSink = { fields: emptyFields(), origin: new Map() };
+	expandTraitInner(traitCd, entityName, localTraits, new Set(), sink);
+	return sink.fields;
 }
 
 function expandTraitInner(
@@ -128,7 +201,8 @@ function expandTraitInner(
 	entityName: string,
 	localTraits: TraitsFile | undefined,
 	path: Set<string>,
-): Record<string, FieldDef> {
+	sink: MergeSink,
+): void {
 	// `includes` is author-supplied once local traits are in play, so a cycle is
 	// reachable from a module file. Unguarded that is an editor hang, not a bad
 	// expansion.
@@ -137,20 +211,27 @@ function expandTraitInner(
 	// diamond — two includes that both reach a third — the third has to expand
 	// under each of them, or which definition wins a key collision would depend
 	// on which branch got there first.
-	if (path.has(traitCd)) return {};
+	if (path.has(traitCd)) return;
 	path.add(traitCd);
 
-	const trait = localTraits?.[traitCd] ?? byCd.get(traitCd);
-	const result: Record<string, FieldDef> = {};
+	// Own-property lookup: `localTraits` is parsed JSON, so a code like
+	// `constructor` would otherwise resolve to something off Object.prototype.
+	const trait =
+		localTraits && Object.hasOwn(localTraits, traitCd) ? localTraits[traitCd] : byCd.get(traitCd);
 	if (trait) {
 		for (const included of trait.includes ?? []) {
-			Object.assign(result, expandTraitInner(included, entityName, localTraits, path));
+			expandTraitInner(included, entityName, localTraits, path, sink);
+		}
+		// Each field is templated and merged on its own: two keys in one trait can
+		// resolve to the same code for a given entity (`{entity}_id` and `x_id`
+		// for entity `x`), and the installer, which resolves and adds one key at a
+		// time, sees that collision as a conflict.
+		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;
 }
 
 /** Expand several traits in order into one merged field map. */
@@ -159,9 +240,39 @@ export function expandTraits(
 	entityName: string,
 	localTraits?: TraitsFile,
 ): Record<string, FieldDef> {
-	const result: Record<string, FieldDef> = {};
+	const sink: MergeSink = { fields: emptyFields(), origin: new Map() };
+	for (const cd of traitCds) {
+		expandTraitInner(cd, entityName, localTraits, new Set(), sink);
+	}
+	return sink.fields;
+}
+
+/**
+ * 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.
+ */
+export function traitFieldConflicts(
+	traitCds: readonly string[],
+	entityName: string,
+	opts: { localTraits?: TraitsFile; fields?: Record<string, FieldDef> } = {},
+): TraitFieldConflict[] {
+	const sink: MergeSink = { fields: emptyFields(), origin: 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) {
-		Object.assign(result, expandTraitInner(cd, entityName, localTraits, new Set()));
+		expandTraitInner(cd, entityName, opts.localTraits, new Set(), sink);
 	}
-	return result;
+	return sink.conflicts!;
 }