@dforge-core/metadata 0.0.35 → 0.0.36

package/package.json

@@ -1,68 +1,67 @@
 {
-	"name": "@dforge-core/metadata",
-	"version": "0.0.35",
-	"description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
-	"license": "MIT",
-	"author": "dForge",
-	"homepage": "https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/iash44/dForge-core.git",
-		"directory": "clients/packages/metadata"
-	},
-	"bugs": {
-		"url": "https://github.com/iash44/dForge-core/issues"
-	},
-	"keywords": [
-		"dforge",
-		"metadata",
-		"field-type",
-		"trait",
-		"registry",
-		"low-code"
-	],
-	"publishConfig": {
-		"access": "public"
-	},
-	"type": "module",
-	"main": "./dist/index.js",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"source": "./src/index.ts",
-			"types": "./dist/index.d.ts",
-			"default": "./dist/index.js"
-		},
-		"./dsl": {
-			"source": "./src/dsl/index.ts",
-			"types": "./dist/dsl/index.d.ts",
-			"default": "./dist/dsl/index.js"
-		},
-		"./schemas/*": "./schemas/*",
-		"./package.json": "./package.json"
-	},
-	"sideEffects": false,
-	"files": [
-		"dist",
-		"src",
-		"schemas",
-		"CHANGELOG.md"
-	],
-	"scripts": {
-		"sync-schemas": "node scripts/sync-schemas.mjs",
-		"build": "tsup",
-		"dev": "tsup --watch",
-		"typecheck": "tsc -p tsconfig.build.json --noEmit",
-		"test": "vitest run",
-		"prepack": "pnpm sync-schemas && pnpm typecheck && pnpm build",
-		"package": "pnpm pack"
-	},
-	"devDependencies": {
-		"@types/node": "^25.9.4",
-		"ajv": "^8.20.0",
-		"tsup": "^8.5.1",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.10"
-	}
-}
+  "name": "@dforge-core/metadata",
+  "version": "0.0.36",
+  "description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
+  "license": "MIT",
+  "author": "dForge",
+  "homepage": "https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iash44/dForge-core.git",
+    "directory": "clients/packages/metadata"
+  },
+  "bugs": {
+    "url": "https://github.com/iash44/dForge-core/issues"
+  },
+  "keywords": [
+    "dforge",
+    "metadata",
+    "field-type",
+    "trait",
+    "registry",
+    "low-code"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dsl": {
+      "source": "./src/dsl/index.ts",
+      "types": "./dist/dsl/index.d.ts",
+      "default": "./dist/dsl/index.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "schemas",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.9.4",
+    "ajv": "^8.20.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "sync-schemas": "node scripts/sync-schemas.mjs",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run",
+    "package": "pnpm pack"
+  }
+}

package/src/index.ts

@@ -6,8 +6,10 @@
 //     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, translations,
-//     actions, diagrams), mirrored from the JSON schemas under docs/schemas/.
+//     roles, settings, registers, jobs, triggers, webhooks, print templates, seed data,
+//     translations, actions, diagrams), mirrored from the JSON schemas under docs/schemas/;
+//   • shared rules — the action-DSL analyzer (./dsl) and the register checks
+//     (checkRegisters / checkRegisterBinding), run by editors and validators alike.
 //
 // No runtime dependencies; safe to import from editors, the web app, the CLI,
 // the MCP server and the VS Code extension.
@@ -131,6 +133,37 @@ export type {
 	TranslatedWithOptions,
 } from "./translations";
 export type { SettingsFile, SettingDef, SettingBaseDatatype } from "./settings";
+export {
+	REGISTER_KINDS,
+	REGISTER_CODE,
+	REGISTER_COLUMN_NAME,
+	REGISTER_TOTALS_PERIODS,
+	isRegisterKind,
+	isPlainColumnRef,
+	registerDimensions,
+	registerResources,
+	registerCarrier,
+	registerResourceShape,
+	registerLineMode,
+	registerRefusedProps,
+	registerRequiredProps,
+	checkRegister,
+	checkRegisters,
+	checkRegisterBinding,
+	type RegisterKind,
+	type RegisterDef,
+	type RegistersFile,
+	type RegisterResourceDef,
+	type RegisterTotalsDef,
+	type RegisterTotalsPeriod,
+	type RegisterCompositionDef,
+	type RegisterBindingParams,
+	type RegisterMapValue,
+	type RegisterBindingTarget,
+	type RegisterIssue,
+	type RegisterEntityInfo,
+	type RegisterEntityLookup,
+} from "./registers";
 export type { JobsFile, JobDef } from "./jobs";
 export type { TriggersFile, TriggerDef, EntityEvent } from "./triggers";
 export type { WebhooksFile, WebhookSubscription, WebhookPayload } from "./webhooks";

package/src/registers/check-binding.ts

@@ -0,0 +1,233 @@
+// Checking an A / L column's `params` against the register it binds.
+
+import { createIssueReporter } from "./issues";
+import type { RegisterIssue, RegisterReporter } from "./issues";
+import { hasKey, isRecord, registerResourceShape, safeTrim, stringList } from "./read";
+import type { Raw } from "./read";
+import type { RegisterDef } from "./types";
+
+/** What a binding is checked against: the parts of a declaration it has to agree with. */
+export type RegisterBindingTarget = Pick<RegisterDef, "kind" | "dimensions" | "resources" | "recorder" | "lineMode" | "sideDimensions">;
+
+/** A reference path (`ref.column`), an expression (`=…`) or a quoted constant — not a plain column. */
+export const isPlainColumnRef = (value: string): boolean => !value.startsWith("=") && !value.startsWith("'") && !value.includes(".");
+
+interface BindingContext {
+	params: Raw;
+	register: RegisterBindingTarget;
+	qualified: string;
+	ledger: boolean;
+	error: RegisterReporter;
+}
+
+function checkPosting(params: Raw, ledger: boolean, error: RegisterReporter): void {
+	const lineEntity = safeTrim(params.lineEntity);
+	const locked = stringList(params.lockedFields);
+	const lockedLines = stringList(params.lockedLineFields);
+
+	if (!Array.isArray(params.lockedFields) || locked.length === 0) {
+		error(["lockedFields"], "register-locked-fields", "'lockedFields' is required: the document columns frozen while posted (or [\"*\"] for the whole row).");
+	}
+	if (lineEntity) {
+		if (!safeTrim(params.lineField)) {
+			error(["lineField"], "register-line", "A line posting needs 'lineField' — the line's key to the document.");
+		}
+		if (!Array.isArray(params.lockedLineFields) || lockedLines.length === 0) {
+			error(["lockedLineFields"], "register-locked-fields", "A line posting needs 'lockedLineFields' (or [\"*\"]).");
+		}
+	} else {
+		if (hasKey(params, "lineField")) {
+			error(["lineField"], "register-line", "'lineField' needs a 'lineEntity'.");
+		}
+		if (hasKey(params, "lockedLineFields")) {
+			error(["lockedLineFields"], "register-line", "'lockedLineFields' is for a line posting — name the 'lineEntity'.");
+		}
+		if (hasKey(params, "headerMap")) {
+			error(["headerMap"], "register-header-map", "'headerMap' is for a binding that posts from lines; a document posting reads every value from the document already.");
+		}
+		if (hasKey(params, "groupLinesBy")) {
+			error(["groupLinesBy"], "register-group-lines", "'groupLinesBy' needs lines to group — name the 'lineEntity'.");
+		}
+	}
+	if (ledger) {
+		if (!lineEntity) {
+			error(["lineEntity"], "register-line", "An L column posts lines: 'lineEntity' and 'lineField' are required.");
+		}
+		for (const key of ["headerMap", "skipPostingWhenEmpty", "dateTrunc", "groupLinesBy"]) {
+			if (hasKey(params, key)) {
+				error([key], "register-ledger-only", `'${key}' is read by A columns only.`);
+			}
+		}
+	}
+	const dateField = safeTrim(params.dateField);
+	if (hasKey(params, "dateTrunc") && !dateField) {
+		error(["dateTrunc"], "register-date", "'dateTrunc' needs a 'dateField'.");
+	}
+	if (dateField && !locked.includes("*") && isPlainColumnRef(dateField) && !locked.includes(dateField)) {
+		error(["dateField"], "register-date-unlocked", `'${dateField}' must be in 'lockedFields': a posted document re-dated would leave what it posted under the old date.`);
+	}
+}
+
+function checkInfoBinding({ params, register, qualified, error }: BindingContext): void {
+	if (!safeTrim(register.recorder)) {
+		error(["register"], "register-info-independent", `"${qualified}" is an independent information register (no 'recorder'): its records are written by data operations, not by posting — unposting could never find them.`);
+	}
+	for (const key of ["direction", "sign"]) {
+		if (hasKey(params, key)) {
+			error([key], "register-info-direction", `'${key}' is refused on a binding to an information register, which records values rather than quantities.`);
+		}
+	}
+}
+
+function checkLedgerAccounts({ params, register, error }: BindingContext): void {
+	if (register.lineMode === "compound") {
+		if (hasKey(params, "accountField")) {
+			error(["accountField"], "register-accounts", "A compound register takes 'debitAccountField' and 'creditAccountField', not 'accountField'.");
+		}
+		if (!safeTrim(params.debitAccountField) || !safeTrim(params.creditAccountField)) {
+			error(["register"], "register-accounts", "A binding to a compound register names 'debitAccountField' and 'creditAccountField'.");
+		}
+		return;
+	}
+	if (!safeTrim(params.accountField)) {
+		error(["register"], "register-accounts", "A binding to a classic register names the line's 'accountField'.");
+	}
+	for (const key of ["debitAccountField", "creditAccountField"]) {
+		if (hasKey(params, key)) {
+			error([key], "register-accounts", `'${key}' belongs to a compound register; a classic one takes 'accountField'.`);
+		}
+	}
+}
+
+/** A ledger `map` entry takes a column per side where the register keeps one per side. */
+function checkLedgerMapValue(ctx: BindingContext, key: string, value: unknown, resources: Raw): void {
+	const { register, error } = ctx;
+	const resource = resources[key];
+	const split = key in resources
+		? isRecord(resource) && registerResourceShape(resource) === "split"
+		: isRecord(register.sideDimensions) && key in register.sideDimensions;
+	if (split) {
+		if (!isRecord(value) || !safeTrim(value.debit) || !safeTrim(value.credit)) {
+			error(["map", key], "register-map-value", `"${key}" has a column per side; map both 'debit' and 'credit' to line columns.`);
+		}
+	} else if (!safeTrim(value)) {
+		error(["map", key], "register-map-value", `"${key}" is shared between the sides; map it to one line column.`);
+	}
+}
+
+/** Returns the names the binding maps, from `map` and `headerMap` alike. */
+function checkMaps(ctx: BindingContext, dimensions: string[], resources: Raw): Set<string> {
+	const { params, qualified, ledger, register, error } = ctx;
+	const known = new Set([...dimensions, ...Object.keys(resources)]);
+	const mapped = new Set<string>();
+	for (const mapKey of ["map", "headerMap"] as const) {
+		const map = isRecord(params[mapKey]) ? params[mapKey] : null;
+		if (!map) {
+			continue;
+		}
+		for (const key of Object.keys(map)) {
+			if (mapped.has(key)) {
+				error([mapKey, key], "register-map-key", `"${key}" is in both 'map' and 'headerMap' — one value cannot come from two places.`);
+			}
+			mapped.add(key);
+			if (!known.has(key)) {
+				error([mapKey, key], "register-map-key", `"${key}" is neither a dimension nor a resource of ${qualified} (dimensions: ${dimensions.join(", ") || "none"}; resources: ${Object.keys(resources).join(", ") || "none"}).`);
+			} else if (ledger && mapKey === "map") {
+				checkLedgerMapValue(ctx, key, map[key], resources);
+			} else if (mapKey === "headerMap" && key in resources && register.kind !== "info") {
+				error([mapKey, key], "register-header-map", `A resource ("${key}") can't come from the document on a line posting — it would be added once per line. Only an information register's records take it.`);
+			}
+		}
+	}
+	return mapped;
+}
+
+function checkMapping(ctx: BindingContext): void {
+	const { params, register, qualified, error } = ctx;
+	const dimensions = stringList(register.dimensions);
+	const resources: Raw = isRecord(register.resources) ? register.resources : {};
+	const mapped = checkMaps(ctx, dimensions, resources);
+
+	const unmapped = Object.entries(resources)
+		.filter(([resource, def]) => !mapped.has(resource) && !(isRecord(def) && def.required === false))
+		.map(([resource]) => resource);
+	if (unmapped.length > 0) {
+		error(
+			[hasKey(params, "map") ? "map" : "register"],
+			"register-unmapped-resource",
+			`Every required resource of ${qualified} must be mapped — missing: ${unmapped.join(", ")}. A writer that omitted one would post a silent zero.`,
+		);
+	}
+	stringList(params.skipPostingWhenEmpty).forEach((name, i) => {
+		if (!dimensions.includes(name)) {
+			error(["skipPostingWhenEmpty", i], "register-skip", `"${name}" isn't a dimension of ${qualified}; 'skipPostingWhenEmpty' names register dimensions.`);
+		}
+	});
+}
+
+/**
+ * Check an A / L column's `params` against the register it binds — paths
+ * relative to `params`. `register` is the resolved declaration, `undefined`
+ * when the module named declares no such register, `null` when that module
+ * can't be seen (every rule that needs the declaration then stands down).
+ */
+export function checkRegisterBinding(
+	columnType: "A" | "L",
+	rawParams: unknown,
+	register: RegisterBindingTarget | null | undefined,
+	options: { moduleCode?: string } = {},
+): RegisterIssue[] {
+	const out: RegisterIssue[] = [];
+	const error = createIssueReporter(out, "entity", "error");
+	if (!isRecord(rawParams)) {
+		return out;
+	}
+	const params = rawParams;
+	const qualified = safeTrim(params.register);
+	if (!qualified) {
+		return out;
+	}
+	const ledger = columnType === "L";
+
+	if (hasKey(params, "registries")) {
+		error(["registries"], "register-and-inline", "A column binds to a register OR restates one inline in 'registries' — keep one.");
+	}
+	if (!qualified.includes(".")) {
+		error(["register"], "register-unqualified", `A register is named as module.register, e.g. "${options.moduleCode ?? "module"}.${qualified}".`);
+		return out;
+	}
+	const dot = qualified.indexOf(".");
+	const moduleCode = qualified.slice(0, dot);
+	const registerCode = qualified.slice(dot + 1);
+
+	// Posting inputs are validated even when the target register cannot be resolved.
+	checkPosting(params, ledger, error);
+
+	if (register === null) {
+		return out;
+	}
+	if (!register) {
+		error(["register"], "unknown-register", `No register "${qualified}" — ${moduleCode}/registers.json doesn't declare "${registerCode}".`);
+		return out;
+	}
+	const kind = register.kind;
+	if (ledger && kind !== "accounting") {
+		error(["register"], "register-kind", `An L column posts to an accounting register; "${qualified}" is a ${kind || "?"} register — use an A column.`);
+		return out;
+	}
+	if (!ledger && kind === "accounting") {
+		error(["register"], "register-kind", `An A column posts to a balance, turnover or info register; "${qualified}" is an accounting register — use an L column.`);
+		return out;
+	}
+	const ctx: BindingContext = { params, register, qualified, ledger, error };
+	if (kind === "info") {
+		checkInfoBinding(ctx);
+	}
+	// No rule on a missing `direction`: the engine posts an increase by default
+	// (gl's VAT binding ships without one).
+	if (ledger) {
+		checkLedgerAccounts(ctx);
+	}
+	checkMapping(ctx);
+	return out;
+}