@dforge-core/metadata 0.0.23 → 0.0.25

package/src/dsl/types.ts

@@ -79,6 +79,14 @@ export interface DslContext {
 	action?: {
 		code: string;
 		executionMode?: ActionExecutionMode;
+		/**
+		 * True when a scheduled job invokes this action. A job runs as the
+		 * system user with no current record, so record context is a hard
+		 * error there even in a mode that would otherwise allow it. Only a
+		 * reader that has the module's jobs can know this, so it is the host's
+		 * to supply; absent, the rule stands down like every other.
+		 */
+		viaJob?: boolean;
 	};
 	/**
 	 * Entity behind the record context (`[field]`). `null` or absent when it

package/src/index.ts

@@ -28,6 +28,7 @@ export type {
 	FlagCd,
 	NamedKind,
 	TraitDef,
+	TraitsFile,
 } from "./types";
 
 export { AggType, AGG_TYPE_LIST } from "./aggregation";

package/src/traits.ts

@@ -6,7 +6,7 @@
 // these as checkboxes and previews the expanded fields, so authors never
 // hand-write `created_date` / `{entity}_id` etc.
 
-import type { FieldDef, TraitDef } from "./types";
+import type { FieldDef, TraitDef, TraitsFile } from "./types";
 
 export const traits: readonly TraitDef[] = [
 	{
@@ -107,21 +107,61 @@ function templateFields(fields: Record<string, FieldDef>, entity: string): Recor
  * 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.
+ *
+ * `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
+ * reader that knows only this registry sees an entity missing columns that
+ * install will give it. Pass the file and those traits resolve; a code declared
+ * in both wins locally, mirroring the installer, which overlays the module's
+ * traits on the platform ones (`TraitExpanderFactory.ForPackage`).
  */
-export function expandTrait(traitCd: string, entityName: string): Record<string, FieldDef> {
-	const trait = byCd.get(traitCd);
-	if (!trait) return {};
+export function expandTrait(
+	traitCd: string,
+	entityName: string,
+	localTraits?: TraitsFile,
+): Record<string, FieldDef> {
+	return expandTraitInner(traitCd, entityName, localTraits, new Set());
+}
+
+function expandTraitInner(
+	traitCd: string,
+	entityName: string,
+	localTraits: TraitsFile | undefined,
+	path: Set<string>,
+): Record<string, FieldDef> {
+	// `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.
+	//
+	// The guard is the current path, not every trait already visited: in a
+	// 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 {};
+	path.add(traitCd);
+
+	const trait = localTraits?.[traitCd] ?? byCd.get(traitCd);
 	const result: Record<string, FieldDef> = {};
-	for (const included of trait.includes ?? []) {
-		Object.assign(result, expandTrait(included, entityName));
+	if (trait) {
+		for (const included of trait.includes ?? []) {
+			Object.assign(result, expandTraitInner(included, entityName, localTraits, path));
+		}
+		Object.assign(result, templateFields(trait.fields ?? {}, entityName));
 	}
-	Object.assign(result, templateFields(trait.fields, entityName));
+
+	path.delete(traitCd);
 	return result;
 }
 
 /** Expand several traits in order into one merged field map. */
-export function expandTraits(traitCds: readonly string[], entityName: string): Record<string, FieldDef> {
+export function expandTraits(
+	traitCds: readonly string[],
+	entityName: string,
+	localTraits?: TraitsFile,
+): Record<string, FieldDef> {
 	const result: Record<string, FieldDef> = {};
-	for (const cd of traitCds) Object.assign(result, expandTrait(cd, entityName));
+	for (const cd of traitCds) {
+		Object.assign(result, expandTraitInner(cd, entityName, localTraits, new Set()));
+	}
 	return result;
 }

package/src/types.ts

@@ -179,6 +179,21 @@ export interface TraitDef {
 	references?: Record<string, unknown>;
 }
 
+/**
+ * A module's own `traits.json`, keyed by trait code — the key is the `cd`, so a
+ * definition here is otherwise a {@link TraitDef} with everything optional
+ * (a marker trait declares no fields at all).
+ */
+export interface TraitsFile {
+	[traitCd: string]: {
+		description?: string;
+		includes?: string[];
+		fields?: Record<string, FieldDef>;
+		references?: Record<string, unknown>;
+		constraints?: Record<string, unknown>;
+	};
+}
+
 /** Description of a column kind for friendly pickers. */
 export interface ColumnTypeDef {
 	cd: ColumnTypeCd;