@dforge-core/metadata 0.0.22 → 0.0.23

package/src/dsl/types.ts

@@ -0,0 +1,90 @@
+// 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;
+	};
+	/**
+	 * 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;
+}