@dforge-core/metadata 0.0.31 → 0.0.33

package/src/dsl/lexer.ts

@@ -366,11 +366,12 @@ export function stringValue(token: Token): string {
 /**
  * The literal text of one template chunk, delimiters removed. A chunk opens on
  * a backtick or on the `}` that closed the hole before it, and closes on a
- * backtick, on the `${` of the next hole, or on the end of the file.
+ * backtick, on the `${` of the next hole, or on the end of the file. A line
+ * break in it reads as \n, as JavaScript reads a template written with CRLF.
  */
 export function templateChunkValue(token: Token): string {
 	if (token.kind !== "template") return token.text;
-	const body = token.text.slice(1);
+	const body = token.text.slice(1).replace(/\r\n?/g, "\n");
 	if (body.endsWith("${")) return unescape(body.slice(0, -2));
 	if (body.endsWith("`")) return unescape(body.slice(0, -1));
 	return unescape(body);
@@ -379,16 +380,40 @@ export function templateChunkValue(token: Token): string {
 // A switch, not a lookup table: the escaped character comes out of the script,
 // and an object would answer `\c` from Object.prototype.
 function unescape(body: string): string {
-	return body.replace(/\\(.)/g, (_, ch: string) => {
-		switch (ch) {
-			case "n":
-				return "\n";
-			case "t":
-				return "\t";
-			case "r":
-				return "\r";
-			default:
-				return ch;
-		}
-	});
+	return body.replace(
+		/\\(u\{[0-9a-fA-F]+\}|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|\r\n|[\s\S])/g,
+		(_, esc: string) => {
+			switch (esc[0]) {
+				case "n":
+					return "\n";
+				case "t":
+					return "\t";
+				case "r":
+					return "\r";
+				case "b":
+					return "\b";
+				case "f":
+					return "\f";
+				case "v":
+					return "\v";
+				case "0":
+					return "\0";
+				case "\r":
+				case "\n":
+				case "\u2028":
+				case "\u2029":
+					return "";
+				case "u":
+				case "x":
+					if (esc.length > 1) {
+						const hex = esc[1] === "{" ? esc.slice(2, -1) : esc.slice(1);
+						const cp = parseInt(hex, 16);
+						return cp <= 0x10ffff ? String.fromCodePoint(cp) : esc;
+					}
+					return esc;
+				default:
+					return esc;
+			}
+		},
+	);
 }

package/src/dsl/messages.ts

@@ -0,0 +1,196 @@
+// The messages of a script's info / warn / error / exit calls — what the server's
+// ActionDslCompiler extracts on CompileResult.Messages, for the editor and the MCP.
+// The two must agree: test/fixtures/dsl-messages.json is run by both test suites.
+
+import type { Token } from "./lexer";
+import { stringValue, templateChunkValue } from "./lexer";
+import type { DslDocument, Span } from "./parse";
+
+export type DslMessageKind = "literal" | "concatenated" | "dynamic";
+
+export interface DslMessage {
+	builtin: "info" | "warn" | "error" | "exit";
+	kind: DslMessageKind;
+	/** The message text for `literal`, exactly as the runtime receives it; otherwise undefined. */
+	text?: string;
+	/** Keys of the placeholder-values object; empty without one, null when it is not an object literal. */
+	valueNames: string[] | null;
+	/** The first argument. */
+	span: Span;
+}
+
+// Built-in → position of its placeholder-values argument.
+const VALUES_INDEX = new Map([
+	["info", 1],
+	["warn", 1],
+	["error", 1],
+	["exit", 2],
+]);
+
+/** Message calls in `execute:` and `onBeforeStart:`, in source order. */
+export function extractMessages(doc: DslDocument): DslMessage[] {
+	const out: DslMessage[] = [];
+	const { tokens } = doc;
+	for (let i = 0; i < tokens.length - 1; i++) {
+		const t = tokens[i]!;
+		const valuesIndex = VALUES_INDEX.get(t.text);
+		if (t.kind !== "ident" || valuesIndex === undefined || tokens[i + 1]!.text !== "(") continue;
+		if (tokens[i - 1]?.text === ".") continue;
+		const block = doc.blocks.find((b) => t.start >= b.body.start && t.start < b.body.end)?.kind;
+		if (block !== "execute" && block !== "onBeforeStart") continue;
+
+		const args = splitArgs(tokens, i + 1);
+		if (!args[0]?.length) continue;
+		const [kind, text] = classify(args[0]!);
+		const valuesArg = args[valuesIndex];
+		out.push({
+			builtin: t.text as DslMessage["builtin"],
+			kind,
+			text,
+			valueNames: valuesArg ? valueNames(valuesArg) : [],
+			span: { start: args[0]![0]!.start, end: args[0]![args[0]!.length - 1]!.end },
+		});
+	}
+	return out;
+}
+
+/** The top-level arguments of the call whose `(` is at `open`, each as its tokens. */
+function splitArgs(tokens: Token[], open: number): Token[][] {
+	const args: Token[][] = [];
+	let current: Token[] = [];
+	let depth = 0;
+	for (let j = open + 1; j < tokens.length; j++) {
+		const t = tokens[j]!;
+		if (t.kind === "comment") continue;
+		if (depth === 0 && t.kind === "punct" && closes(t)) break;
+		if (depth === 0 && t.kind === "punct" && t.text === ",") {
+			args.push(current);
+			current = [];
+			continue;
+		}
+		depth += depthDelta(t);
+		current.push(t);
+	}
+	if (current.length > 0) args.push(current);
+	return args;
+}
+
+
+const isWholeTemplate = (t: Token): boolean =>
+	t.kind === "template" && t.text.length > 1 && t.text.startsWith("`") && t.text.endsWith("`");
+
+// Mirrors the compiler's classification of the parsed argument: a lone string or
+// hole-free template is literal, a template with holes or a `+` joining text is
+// concatenated, anything else (`'a'.trim()`, a call, a variable) is dynamic.
+function classify(arg: Token[]): [DslMessageKind, string?] {
+	const t = unwrap(arg);
+	if (t.length === 1 && t[0]!.kind === "string") return ["literal", stringValue(t[0]!)];
+	if (t.length === 1 && isWholeTemplate(t[0]!)) return ["literal", templateChunkValue(t[0]!)];
+	return [joinsText(t) ? "concatenated" : "dynamic"];
+}
+
+// The compiler's JoinsText: text, or a `+` whose operand joins text. The root of an
+// expression is its last top-level operator of the loosest precedence, so
+// `'a' + x - 1` is a subtraction and `x == 'a' + y` a comparison.
+function joinsText(tokens: Token[]): boolean {
+	const t = unwrap(tokens);
+	if ((t.length === 1 && t[0]!.kind === "string") || isTemplate(t)) return true;
+	let depth = 0;
+	let root = -1;
+	for (let j = 0; j < t.length; j++) {
+		const tok = t[j]!;
+		if (depth === 0) {
+			if (isLooserThanPlus(t, j)) return false;
+			if (tok.kind === "punct" && (tok.text === "+" || tok.text === "-") && endsOperand(t[j - 1])) root = j;
+		}
+		depth += depthDelta(tok);
+	}
+	if (root < 0 || t[root]!.text === "-") return false;
+	return joinsText(t.slice(0, root)) || joinsText(t.slice(root + 1));
+}
+
+const LOOSER_THAN_PLUS = new Set([
+	"?", ":", "&&", "||", "=", "==", "!=", "===", "!==", "<", ">", "<=", ">=", "&", "|", "^", ",",
+	"=>", "+=", "-=", "*=", "/=", "%=",
+]);
+
+function isLooserThanPlus(t: Token[], j: number): boolean {
+	const tok = t[j]!;
+	if (tok.kind === "ident") return tok.text === "in" || tok.text === "instanceof";
+	if (tok.kind !== "punct" || !LOOSER_THAN_PLUS.has(tok.text)) return false;
+	return !(tok.text === "?" && t[j + 1]?.text === "."); // `?.` is member access
+}
+
+// Whether a `+` / `-` after this token is binary rather than a sign.
+function endsOperand(prev: Token | undefined): boolean {
+	if (!prev) return false;
+	switch (prev.kind) {
+		case "number":
+		case "string":
+		case "regex":
+			return true;
+		case "ident":
+			return !["return", "typeof", "void", "delete", "new", "in", "instanceof", "case"].includes(prev.text);
+		case "template":
+			return prev.text.endsWith("`");
+		case "punct":
+			return [")", "]", "}", "++", "--"].includes(prev.text);
+		default:
+			return false;
+	}
+}
+
+// One template literal, holes included, and nothing after it.
+function isTemplate(tokens: Token[]): boolean {
+	if (tokens[0]?.kind !== "template" || !tokens[0].text.startsWith("`")) return false;
+	let depth = 0;
+	for (let j = 0; j < tokens.length; j++) {
+		depth += depthDelta(tokens[j]!);
+		if (depth === 0) return j === tokens.length - 1;
+	}
+	return false;
+}
+
+// Nesting: brackets, and a template chunk that opens (`a${`) or closes (`}b`) a hole.
+const opens = (t: Token) => (t.kind === "punct" ? "([{".includes(t.text) : t.kind === "template" && t.text.endsWith("${"));
+const closes = (t: Token) => (t.kind === "punct" ? ")]}".includes(t.text) : t.kind === "template" && t.text.startsWith("}"));
+const depthDelta = (t: Token) => Number(opens(t)) - Number(closes(t));
+
+// `('Done')` is the literal the parser sees.
+function unwrap(tokens: Token[]): Token[] {
+	while (tokens[0]?.text === "(" && isGroup(tokens)) tokens = tokens.slice(1, -1);
+	return tokens;
+}
+
+// Whether the bracket that opens `tokens` is closed by its last token.
+function isGroup(tokens: Token[]): boolean {
+	if (tokens.length < 2 || !opens(tokens[0]!)) return false;
+	let depth = 0;
+	for (let j = 0; j < tokens.length; j++) {
+		depth += depthDelta(tokens[j]!);
+		if (depth === 0) return j === tokens.length - 1;
+	}
+	return false;
+}
+
+// The keys of an object literal, as the compiler reads them: `({ n: 1 })` is one,
+// and a name inside a nested value or a `${…}` is not a key.
+function valueNames(arg: Token[]): string[] | null {
+	const t = unwrap(arg);
+	if (t[0]?.text !== "{" || !isGroup(t)) return null;
+	const names: string[] = [];
+	let depth = 0;
+	for (let j = 0; j < t.length; j++) {
+		const tok = t[j]!;
+		const at = depth;
+		depth += depthDelta(tok);
+		if (at !== 1 || (tok.kind !== "ident" && tok.kind !== "string")) continue;
+		const prev = t[j - 1]!.text;
+		const next = t[j + 1]?.text;
+		if ((prev === "{" || prev === ",") && (next === ":" || next === "," || next === "}")) {
+			const name = tok.kind === "string" ? stringValue(tok) : tok.text;
+			if (name !== "links") names.push(name);
+		}
+	}
+	return names;
+}

package/src/dsl/types.ts

@@ -95,4 +95,11 @@ export interface DslContext {
 	 * none: pass `null`, not the fragment. See `EntityShape.columns`.
 	 */
 	currentEntity?: EntityShape | null;
+	/**
+	 * Each non-English locale the manifest lists in `supportedLocales` → the
+	 * `messages` block of its `translations/<locale>.json` (`{}` when the file has
+	 * none). Absent, the untranslated and concatenated message rules stand down,
+	 * exactly as install only reports them for a module that declares locales.
+	 */
+	messageTranslations?: Record<string, Record<string, string>>;
 }

package/src/entity.ts

@@ -19,6 +19,9 @@ export type TraitCd =
 	| "period"
 	| "file-library";
 
+/** Audit trail level (`auditHistory` on an entity or manifest); omitted = off. */
+export type AuditHistoryLevel = "basic" | "fields" | "full";
+
 /** Referential action for a FK's ON DELETE / ON UPDATE clause (omitted = noAction). */
 export type ReferentialAction = "cascade" | "setNull" | "restrict" | "noAction";
 
@@ -159,14 +162,12 @@ export interface EntityDef {
 	description?: string;
 	/** Database schema name override (defaults to module schema). */
 	schema?: string;
-	/** Database table/view name (defaults to entity code). */
+	/** Database table name (defaults to entity code). */
 	dbObject?: string;
-	/** When true, maps to a SQL view (read-only, no DDL). */
-	isView?: boolean;
-	/** SELECT statement for view-backed entities (`isView=true`). */
-	viewSql?: string;
 	/** Display pattern using column placeholders, e.g. "{first_name} {last_name}". */
 	toString?: string;
+	/** Audit trail level; overrides the manifest's `auditHistory`. */
+	auditHistory?: AuditHistoryLevel;
 	/** Records of this entity accept comments (composer + thread on the card). */
 	comments?: boolean;
 	/** Traits expanded at install time. */
@@ -186,9 +187,8 @@ export interface EntityDef {
 	params?: { restricted?: boolean } & Record<string, unknown>;
 	/**
 	 * Entity views keyed by view name — the platform's column-level security.
-	 * Unrelated to `isView`/`viewSql` above (a SQL-view-backed entity) and to
-	 * `ui/data_views.json` (grids, kanban, calendars), both of which the word
-	 * "view" also names in this platform. A
+	 * Unrelated to `ui/data_views.json` (grids, kanban, calendars), which the
+	 * word "view" also names in this platform. A
 	 * folder binds one view per entity through `ui/folders.json`
 	 * (`entities.<code>.viewName`); users working in that folder see ONLY the
 	 * columns the view lists. An entity without views (or a folder naming the

package/src/index.ts

@@ -6,7 +6,7 @@
 //     from a friendly field-type choice;
 //   • structural types — the authoring shape of every module-package file
 //     (manifest, entities, data views, reports, stored procedures, menus, folders,
-//     roles, settings, jobs, triggers, webhooks, print templates, seed data,
+//     roles, settings, jobs, triggers, webhooks, print templates, seed data, translations,
 //     actions, diagrams), mirrored from the JSON schemas under docs/schemas/.
 //
 // No runtime dependencies; safe to import from editors, the web app, the CLI,
@@ -69,6 +69,7 @@ export type {
 	SignConfig,
 	LedgerRegistryEntry,
 	TraitCd,
+	AuditHistoryLevel,
 } from "./entity";
 
 // Entity introspection helpers (primary keys, identity keys, reference links).
@@ -120,6 +121,15 @@ export type { MenusFile, MenuDef, MenuItemDef, MenuItemType } from "./menus";
 export type { FoldersFile, FolderDef, FolderEntityBinding } from "./folders";
 export type { DiagramFile, DiagramDef, DiagramEntity, DiagramDetail, DiagramRelation } from "./diagrams";
 export type { RolesFile, RoleDef } from "./roles";
+export type {
+	TranslationsFile,
+	TranslatedAction,
+	TranslatedEntity,
+	TranslatedMenu,
+	TranslatedOption,
+	TranslatedReport,
+	TranslatedWithOptions,
+} from "./translations";
 export type { SettingsFile, SettingDef, SettingBaseDatatype } from "./settings";
 export type { JobsFile, JobDef } from "./jobs";
 export type { TriggersFile, TriggerDef, EntityEvent } from "./triggers";

package/src/manifest.ts

@@ -1,6 +1,8 @@
 // Module manifest — authoring shape of `manifest.json`.
 // Mirror of manifest.schema.json.
 
+import type { AuditHistoryLevel } from "./entity";
+
 /** Author block on a manifest. */
 export interface ManifestAuthor {
 	name: string;
@@ -42,8 +44,8 @@ export interface ManifestDef {
 	license?: string;
 	/** Module code → semver range or partial-dep object. */
 	dependencies?: Record<string, ModuleDependency>;
-	/** Default audit history mode for this module's entities. */
-	auditHistory?: "none" | "minimal" | "full";
+	/** Default audit history level for this module's entities; each entity may override. */
+	auditHistory?: AuditHistoryLevel;
 	/** 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). */

package/src/translations.ts

@@ -0,0 +1,61 @@
+// Translations — authoring shape of `translations/<locale>.json`. Mirror of translations.schema.json.
+
+/** A translated option: the label alone, or label with icon / color overrides. */
+export type TranslatedOption = string | { label?: string; icon?: string; color?: string };
+
+/** A label with optional option translations (fields, domains, params). */
+export interface TranslatedWithOptions {
+	label?: string;
+	/** Option value (stored code) → translation. */
+	options?: Record<string, TranslatedOption>;
+}
+
+export interface TranslatedEntity {
+	label?: string;
+	desc?: string;
+	/** Column code → label and option labels. */
+	fields?: Record<string, TranslatedWithOptions>;
+	/** Card-layout section code → heading. */
+	columnGroups?: Record<string, { label?: string }>;
+	/** Constraint name → violation message. */
+	constraints?: Record<string, { message?: string }>;
+}
+
+export interface TranslatedMenu {
+	label?: string;
+	/** Item code → label. Flat, even when ui/menus.json nests the items. */
+	items?: Record<string, { label?: string }>;
+}
+
+export interface TranslatedReport {
+	label?: string;
+	/** Dataset code → caption. */
+	datasets?: Record<string, { caption?: string }>;
+	params?: Record<string, TranslatedWithOptions>;
+}
+
+export interface TranslatedAction {
+	label?: string;
+	/** Tooltip. */
+	desc?: string;
+	params?: Record<string, TranslatedWithOptions>;
+}
+
+/** A `translations/<locale>.json` file. Every key is optional; a gap falls back to the base text. */
+export interface TranslationsFile {
+	entities?: Record<string, TranslatedEntity>;
+	domains?: Record<string, TranslatedWithOptions>;
+	/** Folder code (flat, not the path) → label. */
+	folders?: Record<string, { label?: string }>;
+	views?: Record<string, { label?: string; desc?: string }>;
+	menus?: Record<string, TranslatedMenu>;
+	settings?: Record<string, { label?: string; desc?: string }>;
+	/** Module-qualified role code → label. */
+	roles?: Record<string, { label?: string }>;
+	reports?: Record<string, TranslatedReport>;
+	actions?: Record<string, TranslatedAction>;
+	/** Accepted, not applied at install yet. */
+	print_templates?: Record<string, { label?: string }>;
+	/** Exact text of a DSL info / warn / error / exit call → translation. */
+	messages?: Record<string, string>;
+}