@dforge-core/metadata 0.0.30 → 0.0.32

package/schemas/translations.schema.json

@@ -0,0 +1,267 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/translations.schema.json",
+	"title": "dForge Translations",
+	"description": "A module's translations/<locale>.json, e.g. de-DE.json. English is the base text authored in the other module files, so an en-* file is not applied at install. Every key is optional: a missing entry falls back to the base text. Labels are required only for the locales the manifest lists in supportedLocales (constraint messages and DSL messages are warned about, never required).",
+	"type": "object",
+	"additionalProperties": false,
+	"properties": {
+		"$schema": {
+			"type": "string"
+		},
+		"entities": {
+			"type": "object",
+			"description": "Entity code → labels for the entity, its fields, card sections and constraint messages.",
+			"additionalProperties": {
+				"$ref": "#/$defs/entity"
+			}
+		},
+		"domains": {
+			"type": "object",
+			"description": "Column domain code (domains.json) → label and option labels, translated once for every column that uses the domain.",
+			"additionalProperties": {
+				"$ref": "#/$defs/withOptions"
+			}
+		},
+		"folders": {
+			"type": "object",
+			"description": "Folder code → label. A sub-folder is keyed by its own flat code, not its path.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"views": {
+			"type": "object",
+			"description": "Data view code → label.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"menus": {
+			"type": "object",
+			"description": "Menu code → label and item labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/menu"
+			}
+		},
+		"settings": {
+			"type": "object",
+			"description": "Setting code (settings.json) → label and description.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelDesc"
+			}
+		},
+		"roles": {
+			"type": "object",
+			"description": "Module-qualified role code (e.g. \"crm.admin\") → label.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"reports": {
+			"type": "object",
+			"description": "Report code → label, dataset captions and parameter labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/report"
+			}
+		},
+		"actions": {
+			"type": "object",
+			"description": "Action code (ui/actions.json) → label, tooltip and parameter labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/action"
+			}
+		},
+		"print_templates": {
+			"type": "object",
+			"description": "Print template code → label. Accepted, but not applied at install yet.",
+			"additionalProperties": {
+				"$ref": "#/$defs/labelOnly"
+			}
+		},
+		"messages": {
+			"type": "object",
+			"description": "Text of a DSL info() / warn() / error() / exit() call, exactly as written in the .dsl file → its translation. {name} placeholders are filled from the call's values and may be reordered. See docs/business-logic/message-localization.md.",
+			"propertyNames": {
+				"minLength": 1
+			},
+			"additionalProperties": {
+				"type": "string",
+				"minLength": 1
+			}
+		}
+	},
+	"$defs": {
+		"label": {
+			"type": "string",
+			"description": "Translated display label."
+		},
+		"labelOnly": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				}
+			}
+		},
+		"labelDesc": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string",
+					"description": "Translated description or tooltip."
+				}
+			}
+		},
+		"option": {
+			"description": "A translated option: the label alone, or the label with an icon and color override.",
+			"oneOf": [
+				{
+					"type": "string"
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"properties": {
+						"label": {
+							"type": "string"
+						},
+						"icon": {
+							"type": "string"
+						},
+						"color": {
+							"type": "string"
+						}
+					}
+				}
+			]
+		},
+		"options": {
+			"type": "object",
+			"description": "Option value (the stored code) → its translation.",
+			"additionalProperties": {
+				"$ref": "#/$defs/option"
+			}
+		},
+		"withOptions": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"options": {
+					"$ref": "#/$defs/options"
+				}
+			}
+		},
+		"entity": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string"
+				},
+				"fields": {
+					"type": "object",
+					"description": "Column code → label and, for dropdown / radio / flags columns, option labels.",
+					"additionalProperties": {
+						"$ref": "#/$defs/withOptions"
+					}
+				},
+				"columnGroups": {
+					"type": "object",
+					"description": "Card-layout section code → heading.",
+					"additionalProperties": {
+						"$ref": "#/$defs/labelOnly"
+					}
+				},
+				"constraints": {
+					"type": "object",
+					"description": "Check / unique constraint name → violation message.",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"message": {
+								"type": "string"
+							}
+						}
+					}
+				}
+			}
+		},
+		"menu": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"items": {
+					"type": "object",
+					"description": "Menu item code → label. Flat even when ui/menus.json nests items under children: a group and its children are siblings here.",
+					"additionalProperties": {
+						"$ref": "#/$defs/labelOnly"
+					}
+				}
+			}
+		},
+		"params": {
+			"type": "object",
+			"description": "Parameter code → label and dropdown option labels.",
+			"additionalProperties": {
+				"$ref": "#/$defs/withOptions"
+			}
+		},
+		"report": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"datasets": {
+					"type": "object",
+					"description": "Dataset code → caption.",
+					"additionalProperties": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"caption": {
+								"type": "string"
+							}
+						}
+					}
+				},
+				"params": {
+					"$ref": "#/$defs/params"
+				}
+			}
+		},
+		"action": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"label": {
+					"$ref": "#/$defs/label"
+				},
+				"desc": {
+					"type": "string",
+					"description": "Translated tooltip."
+				},
+				"params": {
+					"$ref": "#/$defs/params"
+				}
+			}
+		}
+	}
+}

package/src/dsl/builtins.ts

@@ -74,22 +74,27 @@ export const BUILTINS: Builtin[] = [
 	// Messaging
 	{
 		name: "error",
-		signature: "error(message)",
+		signature: "error(message, values?)",
 		returns: "never",
-		doc: "Abort the action and show an error. Rolls back all changes.",
+		doc: "Abort the action and show an error. Rolls back all changes. The text is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`.",
+	},
+	{
+		name: "warn",
+		signature: "warn(message, values?, opts?)",
+		returns: "void",
+		doc: "Show a warning and continue. The text is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`.",
 	},
-	{ name: "warn", signature: "warn(message)", returns: "void", doc: "Show a warning and continue." },
 	{
 		name: "info",
-		signature: "info(message)",
+		signature: "info(message, values?, opts?)",
 		returns: "void",
-		doc: "Show an informational message — a receipt for work the action did, not a way to publish a computed value.",
+		doc: "Show an informational message — a receipt for work the action did, not a way to publish a computed value. The text is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`. `opts.links` adds record links.",
 	},
 	{
 		name: "exit",
-		signature: "exit(message?, level?)",
+		signature: "exit(message?, level?, values?)",
 		returns: "never",
-		doc: "Stop the script early **without** error, keeping changes made so far. Level `'info'` (default) or `'warn'`. This is the DSL's early return — the block compiles to a bare script, so a `return` outside a function is a syntax error wherever it sits.",
+		doc: "Stop the script early **without** error, keeping changes made so far. Level `'info'` (default), `'warning'`, `'danger'` or `'success'`. The message is looked up in the module's `messages` translations; `{name}` placeholders are filled from `values`. This is the DSL's early return — the block compiles to a bare script, so a `return` outside a function is a syntax error wherever it sits.",
 	},
 	{
 		name: "notify",

package/src/dsl/check.ts

@@ -11,6 +11,7 @@
 // omits, and the rules that depend on it stand down. See ./types.
 
 import { BUILTIN_BY_NAME } from "./builtins";
+import { extractMessages } from "./messages";
 import { CONTROL_KEYWORDS, type Token } from "./lexer";
 import {
 	type BlockKind,
@@ -25,7 +26,7 @@ import type { ColumnLookup, DslContext, DslIssue, DslSeverity } from "./types";
  * Check a DSL body. Returns [] for a clean script.
  *
  * Issues come back in source-feature order (field reads, params, execution
- * mode, block spelling, built-ins, top-level returns, inline assignments)
+ * mode, block spelling, built-ins, top-level returns, inline assignments, messages)
  * rather than sorted by position — a host that wants them in file order can
  * sort on `start`.
  */
@@ -573,9 +574,49 @@ export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
 	}
 
 	out.push(...inlineAssignmentIssues(parsed, positionAt));
+
+	// ── messages ─────────────────────────────────────────────────────
+	// Install reports the same, module-wide (ActionMessageScanner).
+	const locales = Object.entries(ctx.messageTranslations ?? {});
+	for (const m of extractMessages(parsed)) {
+		if (m.kind === "concatenated" && locales.length > 0) {
+			add(
+				m.span,
+				`This ${m.builtin}() message joins text and values, so it cannot be translated. Put the values in {placeholders}: ${m.builtin}('Only {n} left', ${m.builtin === "exit" ? "'warning', " : ""}{ n: qty }).`,
+				"warning",
+				"dsl/message-concatenated",
+			);
+		}
+		if (m.text === undefined) continue;
+
+		// A call without values keeps a literal "{x}" as text, as before placeholders existed.
+		if (m.valueNames && m.valueNames.length > 0) {
+			for (const name of placeholders(m.text)) {
+				if (!m.valueNames.includes(name))
+					add(m.span, `{${name}} has no value in this call, so it shows as written.`, "warning", "dsl/message-placeholder");
+			}
+		}
+
+		// A blank translation is dropped at install, so the message still shows in English.
+		const missing = locales
+			.filter(([, messages]) => !(Object.hasOwn(messages, m.text!) && messages[m.text!]?.trim()))
+			.map(([locale]) => locale);
+		if (missing.length > 0) {
+			add(
+				m.span,
+				`No ${missing.join(", ")} translation for this message — add it to "messages" in translations/<locale>.json, keyed by the exact text.`,
+				"warning",
+				"dsl/message-untranslated",
+			);
+		}
+	}
 	return out;
 }
 
+function placeholders(text: string): string[] {
+	return [...new Set([...text.matchAll(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g)].map((x) => x[1]!))];
+}
+
 /**
  * Column matching is case-insensitive at the other end — `EntityColumnLookup`
  * hands the compiler an OrdinalIgnoreCase set — but a host passes us whatever

package/src/dsl/index.ts

@@ -27,6 +27,9 @@ export type {
 export { BUILTINS, BUILTIN_BY_NAME, BUILTIN_VALUES } from "./builtins";
 export type { Builtin } from "./builtins";
 
+export { extractMessages } from "./messages";
+export type { DslMessage, DslMessageKind } from "./messages";
+
 export { checkDsl } from "./check";
 export type {
 	ColumnLookup,

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";
 
@@ -167,6 +170,8 @@ export interface EntityDef {
 	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. */