@dforge-core/metadata 0.0.22 → 0.0.24

package/src/dsl/types.ts

@@ -0,0 +1,98 @@
+// Host-agnostic types for the DSL checker.
+//
+// The checker reports OFFSETS plus a 1-indexed line/column, and never an editor
+// range: a language server turns offsets into `Position`s with its own document
+// model, while a validator prints `logic/actions/x.dsl:12`. Emitting both keeps
+// either host from having to re-derive the other.
+
+import type { ActionExecutionMode } from "../actions";
+
+export type DslSeverity = "error" | "warning" | "info";
+
+/** One reported problem. `rule` is stable — hosts filter and suppress on it. */
+export interface DslIssue {
+	/** Stable rule id, namespaced: `dsl/unknown-column`. */
+	rule: string;
+	severity: DslSeverity;
+	message: string;
+	/** Byte offsets into the source, for range-based hosts. */
+	start: number;
+	end: number;
+	/** 1-indexed position of `start`, for line-based reporters. */
+	line: number;
+	column: number;
+}
+
+/**
+ * Column membership test. Structurally satisfied by both `Set<string>` and
+ * `Map<string, unknown>`, so a host that already holds a column map passes it
+ * straight in rather than copying it into a set on every check.
+ */
+export interface ColumnLookup {
+	has(name: string): boolean;
+	readonly size: number;
+	/**
+	 * The column names, if the lookup can enumerate them — `Set` and `Map` both
+	 * can. Matching is case-insensitive at the other end (`EntityColumnLookup`
+	 * builds an OrdinalIgnoreCase set) and a mixed-case column name is legal, so
+	 * the checker folds case itself when it can read the keys.
+	 *
+	 * Without it, a lookup that is not already case-insensitive will report a
+	 * spelling the server accepts. A host that cannot expose keys should make
+	 * `has` case-insensitive instead.
+	 */
+	keys?(): Iterable<string>;
+}
+
+/** The resolved entity a script's record context refers to. */
+export interface EntityShape {
+	/** Module-qualified, e.g. `fin.invoice` — used in messages. */
+	qualified: string;
+	/**
+	 * Every declared name on the entity, **trait-expanded** — built-in traits
+	 * and the module's own `traits.json` alike — and including the virtual
+	 * columns (reference, set, formula), exactly as `EntityColumnLookup` builds
+	 * the compiler's set.
+	 *
+	 * Handing over an unexpanded set is the one mistake that turns this rule
+	 * into a wall of false errors: the identity PK and `[status]` live in
+	 * traits, not in `fields`. When in doubt pass `currentEntity: null` — a
+	 * skipped check costs an install round trip, a wrong one blocks a pack.
+	 */
+	columns: ColumnLookup;
+}
+
+/**
+ * What the checker knows about the script's surroundings. Every field is
+ * optional and every rule that reads one FAILS OPEN: with an empty context the
+ * text-only rules still run and the rest stand down silently.
+ *
+ * That is deliberate. A false "unknown column" on a correct script is far more
+ * damaging than a missed one — an editor would underline working code, and a
+ * validator would block a pack — so a rule that cannot resolve what it needs
+ * reports nothing.
+ */
+export interface DslContext {
+	/** Owning module code, for the qualify-your-entity-codes message. */
+	moduleCode?: string;
+	/** The action this script implements, from `ui/actions.json`. */
+	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
+	 * can't be resolved — a bridge module acting on another module's entity —
+	 * and then every column rule stands down. A partial set is worse than
+	 * none: pass `null`, not the fragment. See `EntityShape.columns`.
+	 */
+	currentEntity?: EntityShape | null;
+}

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;