@dforge-core/metadata 0.0.34 → 0.0.36

package/src/registers/check-declaration.ts

@@ -0,0 +1,425 @@
+// Checking one declaration of `registers.json`, and the file as a whole.
+// Every rule FAILS OPEN: what cannot be resolved is not reported.
+
+import { createEntityChecks } from "./entities";
+import type { EntityChecks, RegisterEntityLookup, ResolvedRegisterEntity } from "./entities";
+import { createIssueReporter } from "./issues";
+import type { IssuePath, RegisterIssue, RegisterReporter } from "./issues";
+import {
+	KIND_LABEL, hasKey, isRecord, registerCarrier, registerDimensions, registerLineMode, registerRefusedProps,
+	registerRequiredProps, registerResourceShape, registerResources, safeTrim, stringList,
+} from "./read";
+import type { Raw } from "./read";
+import { REGISTER_CODE, REGISTER_COLUMN_NAME, REGISTER_TOTALS_PERIODS, isRegisterKind } from "./types";
+import type { RegisterKind } from "./types";
+
+const MAX_DIMENSIONS = 8;
+const MAX_RESOURCES = 64;
+const MAX_ANALYTIC_SLOTS = 8;
+const MAX_REGISTERS = 100;
+
+interface Context extends EntityChecks {
+	def: Raw;
+	kind: RegisterKind;
+	error: RegisterReporter;
+	warning: RegisterReporter;
+	journalCode?: string;
+	journal: ResolvedRegisterEntity;
+	carrierCode?: string;
+	carrier: ResolvedRegisterEntity;
+	dimensions: string[];
+	sides: Raw;
+	resources: ReturnType<typeof registerResources>;
+}
+
+/** Two columns that must both be named and must differ — a debit/credit pair. */
+function checkColumnPair(
+	error: RegisterReporter,
+	code: string,
+	first: string | undefined,
+	second: string | undefined,
+	where: { missing: IssuePath; missingMessage: string; same: IssuePath; sameMessage: string },
+): void {
+	if (!first || !second) {
+		error(where.missing, code, where.missingMessage);
+	}
+	if (first && first === second) {
+		error(where.same, code, where.sameMessage);
+	}
+}
+
+/** Report each of `keys` the declaration carries, with the same message. */
+function refuseKeys(def: Raw, keys: readonly string[], error: RegisterReporter, code: string, message: (key: string) => string): void {
+	for (const key of keys) {
+		if (hasKey(def, key)) {
+			error([key], code, message(key));
+		}
+	}
+}
+
+function checkProperties({ def, kind, error }: Pick<Context, "def" | "kind" | "error">): void {
+	for (const key of registerRequiredProps(kind)) {
+		if (safeTrim(def[key]) === undefined) {
+			error([key], "required", `${KIND_LABEL[kind].sentence} needs '${key}'.`);
+		}
+	}
+	refuseKeys(def, registerRefusedProps(kind), error, "refused", (key) => `'${key}' isn't allowed on ${KIND_LABEL[kind].inline}.`);
+	if ((safeTrim(def.journalDirection) || safeTrim(def.journalDate)) && !safeTrim(def.journal)) {
+		error(["journal"], "journal-stamps", "'journalDirection' and 'journalDate' are columns of the journal — name the journal entity.");
+	}
+	if (kind === "info" && def.recordChangesOnly === true && !safeTrim(def.recorder)) {
+		error(["recordChangesOnly"], "record-changes-only", "'recordChangesOnly' needs a 'recorder' — only a document's record can be compared with the slice in effect.");
+	}
+}
+
+function resolveEntities(
+	def: Raw,
+	kind: RegisterKind,
+	checks: EntityChecks,
+): Pick<Context, "journalCode" | "journal" | "carrierCode" | "carrier"> {
+	const { entityAt, columnAt } = checks;
+	const entityCode = safeTrim(def.entity);
+	const journalCode = safeTrim(def.journal);
+	const carriedByEntity = kind === "balance" || kind === "info";
+	const entity = carriedByEntity ? entityAt(["entity"], entityCode, "Entity") : null;
+	const journal = kind !== "info" ? entityAt(["journal"], journalCode, "Journal") : null;
+	if (kind === "accounting") {
+		entityAt(["chart"], safeTrim(def.chart), "Chart");
+	}
+
+	columnAt(["journalDirection"], journal, journalCode, def.journalDirection, "Journal direction column");
+	columnAt(["journalDate"], journal, journalCode, def.journalDate, "Journal date column");
+	columnAt(["period"], entity, entityCode, def.period, "Period column");
+	columnAt(["recorder"], entity, entityCode, def.recorder, "Recorder column");
+
+	return { journalCode, journal, carrierCode: registerCarrier(def), carrier: carriedByEntity ? entity : journal };
+}
+
+function checkDimensions({ def, dimensions, sides, carrier, carrierCode, columnAt, error }: Context): void {
+	if (!Array.isArray(def.dimensions) || dimensions.length === 0) {
+		error(["dimensions"], "dimensions", "A register needs at least one dimension.");
+	}
+	if (dimensions.length > MAX_DIMENSIONS) {
+		error(["dimensions"], "dimensions", `At most ${MAX_DIMENSIONS} dimensions.`);
+	}
+	const twice = dimensions.filter((name, index) => dimensions.indexOf(name) !== index);
+	if (twice.length > 0) {
+		error(["dimensions"], "dimensions", `Dimension listed more than once: ${[...new Set(twice)].join(", ")}.`);
+	}
+	dimensions.forEach((name, i) => {
+		// A two-sided dimension lives in its side columns, not under its own name.
+		if (!(name in sides)) {
+			columnAt(["dimensions", i], carrier, carrierCode, name, "Dimension");
+		}
+	});
+}
+
+/** The shape a resource's columns take, per kind and line mode. */
+function checkResourceShape(ctx: Context, name: string, resource: Raw, path: (key?: string) => IssuePath): void {
+	const { def, kind, error } = ctx;
+	const field = safeTrim(resource.field);
+	const debit = safeTrim(resource.debitField);
+	const credit = safeTrim(resource.creditField);
+	const split = registerResourceShape(resource) === "split";
+	const classic = kind === "accounting" && registerLineMode(def) === "classic";
+	if (split && hasKey(resource, "field")) {
+		error(path("field"), "resource-shape", `Resource '${name}': either 'field' or 'debitField' + 'creditField', not both.`);
+	}
+	if (classic && !split) {
+		error(path(), "resource-shape", `Resource '${name}': on a classic accounting register every resource is split — 'debitField' and 'creditField'.`);
+	} else if (kind !== "accounting" && split) {
+		error(path(), "resource-shape", `Resource '${name}': 'debitField' / 'creditField' belong to an accounting register — name one 'field'.`);
+	} else if (split) {
+		checkColumnPair(error, "resource-shape", debit, credit, {
+			missing: path(),
+			missingMessage: `Resource '${name}' needs both 'debitField' and 'creditField'.`,
+			same: path("creditField"),
+			sameMessage: `Resource '${name}': the debit and credit columns must differ.`,
+		});
+	} else if (!field) {
+		error(path(), "resource-shape", `Resource '${name}' needs its column ('field').`);
+	}
+}
+
+function checkResources(ctx: Context): void {
+	const { def, kind, resources, dimensions, carrier, carrierCode, columnAt, error } = ctx;
+	if (!isRecord(def.resources) || resources.length === 0) {
+		error(["resources"], "resources", "A register needs at least one resource.");
+	}
+	if (resources.length > MAX_RESOURCES) {
+		error(["resources"], "resources", `At most ${MAX_RESOURCES} resources.`);
+	}
+	const takesAbsentAs = kind === "info" && !!safeTrim(def.recorder) && def.recordChangesOnly === true;
+	const storage = new Map<string, string>();
+	for (const { name, def: resource } of resources) {
+		const path = (key?: string): IssuePath => (key ? ["resources", name, key] : ["resources", name]);
+		if (!REGISTER_COLUMN_NAME.test(name)) {
+			error(path(), "resource-name", `Resource '${name}' isn't a name (lowercase letters, digits and '_').`);
+		}
+		checkResourceShape(ctx, name, resource, path);
+		for (const key of ["field", "debitField", "creditField"] as const) {
+			const column = safeTrim(resource[key]);
+			if (!column) {
+				continue;
+			}
+			columnAt(path(key), carrier, carrierCode, column, `Resource '${name}' column`);
+			const other = storage.get(column);
+			if (other && other !== name) {
+				error(path(key), "resource-column-shared", `Resources '${other}' and '${name}' both store into '${column}' — posting would add both into one column.`);
+			}
+			storage.set(column, name);
+		}
+		const field = safeTrim(resource.field);
+		if (field && dimensions.includes(field)) {
+			error(path("field"), "resource-is-dimension", `'${field}' is both a dimension and resource '${name}'.`);
+		}
+		if (hasKey(resource, "absentAs") && !takesAbsentAs) {
+			error(path("absentAs"), "absent-as", `Resource '${name}': 'absentAs' needs 'recordChangesOnly' on a subordinate information register.`);
+		}
+	}
+}
+
+function checkAnalyticSlotColumns(ctx: Context, key: string, columns: string[]): void {
+	columns.forEach((column, i) => ctx.columnAt([key, i], ctx.journal, ctx.journalCode, column, "Analytic slot column"));
+}
+
+function checkSideDimensions(ctx: Context): void {
+	const { dimensions, sides, journal, journalCode, columnAt, error } = ctx;
+	for (const [name, side] of Object.entries(sides)) {
+		const base: IssuePath = ["sideDimensions", name];
+		if (!dimensions.includes(name)) {
+			error(base, "side-dimension", `Two-sided dimension '${name}' must also be listed in 'dimensions'.`);
+		}
+		const sideDef = isRecord(side) ? side : {};
+		const debitField = safeTrim(sideDef.debitField);
+		const creditField = safeTrim(sideDef.creditField);
+		checkColumnPair(error, "side-dimension", debitField, creditField, {
+			missing: base,
+			missingMessage: `Two-sided dimension '${name}' needs 'debitField' and 'creditField'.`,
+			same: [...base, "creditField"],
+			sameMessage: `Two-sided dimension '${name}': the two columns must differ.`,
+		});
+		columnAt([...base, "debitField"], journal, journalCode, debitField, `Dimension '${name}' debit column`);
+		columnAt([...base, "creditField"], journal, journalCode, creditField, `Dimension '${name}' credit column`);
+	}
+}
+
+/** Returns whether the register declares analytic slots. */
+function checkCompoundAccounts(ctx: Context): boolean {
+	const { def, journal, journalCode, columnAt, error } = ctx;
+	refuseKeys(def, ["account", "analyticFields"], error, "line-mode", (key) => `'${key}' belongs to a classic register; a compound one names 'debitAccount' and 'creditAccount'.`);
+	const debit = safeTrim(def.debitAccount);
+	const credit = safeTrim(def.creditAccount);
+	checkColumnPair(error, "accounts", debit, credit, {
+		missing: ["debitAccount"],
+		missingMessage: "A compound register needs 'debitAccount' and 'creditAccount'.",
+		same: ["creditAccount"],
+		sameMessage: "'debitAccount' and 'creditAccount' must differ — one column would record no correspondence.",
+	});
+	columnAt(["debitAccount"], journal, journalCode, debit, "Debit account column");
+	columnAt(["creditAccount"], journal, journalCode, credit, "Credit account column");
+
+	const debitSlots = stringList(def.debitAnalyticFields);
+	const creditSlots = stringList(def.creditAnalyticFields);
+	if (debitSlots.length > MAX_ANALYTIC_SLOTS || creditSlots.length > MAX_ANALYTIC_SLOTS) {
+		error(["debitAnalyticFields"], "analytic-slots", `At most ${MAX_ANALYTIC_SLOTS} analytic slots per side.`);
+	}
+	const shared = debitSlots.filter((column) => creditSlots.includes(column));
+	if (shared.length > 0) {
+		error(["creditAnalyticFields"], "analytic-slots", `Analytic slot column on both sides: ${shared.join(", ")}.`);
+	}
+	checkAnalyticSlotColumns(ctx, "debitAnalyticFields", debitSlots);
+	checkAnalyticSlotColumns(ctx, "creditAnalyticFields", creditSlots);
+	const needsComposition = debitSlots.length > 0 || creditSlots.length > 0;
+	checkSideDimensions(ctx);
+	return needsComposition;
+}
+
+/** Returns whether the register declares analytic slots. */
+function checkClassicAccounts(ctx: Context): boolean {
+	const { def, journal, journalCode, columnAt, error } = ctx;
+	refuseKeys(def, ["debitAccount", "creditAccount", "debitAnalyticFields", "creditAnalyticFields", "sideDimensions"], error, "line-mode", (key) => `'${key}' belongs to a compound register.`);
+	if (!safeTrim(def.account)) {
+		error(["account"], "accounts", "A classic register names the posting's account column ('account').");
+	}
+	columnAt(["account"], journal, journalCode, safeTrim(def.account), "Account column");
+	const slots = stringList(def.analyticFields);
+	if (slots.length > MAX_ANALYTIC_SLOTS) {
+		error(["analyticFields"], "analytic-slots", `At most ${MAX_ANALYTIC_SLOTS} analytic slots.`);
+	}
+	checkAnalyticSlotColumns(ctx, "analyticFields", slots);
+	return slots.length > 0;
+}
+
+function checkComposition(ctx: Context, needsComposition: boolean): void {
+	const { def, entityAt, columnAt, error } = ctx;
+	const composition = isRecord(def.composition) ? def.composition : undefined;
+	if (needsComposition && !composition) {
+		error(["composition"], "composition", "Analytic slots need a 'composition' — where the chart says which analytic each account takes in which slot.");
+	}
+	if (!needsComposition && composition) {
+		error(["composition"], "composition", "'composition' is for a register with analytic slots; this one declares none.");
+	}
+	if (!composition) {
+		return;
+	}
+	for (const key of ["entity", "account", "slot", "analytic"]) {
+		if (!safeTrim(composition[key])) {
+			error(["composition", key], "composition", `'composition' needs '${key}'.`);
+		}
+	}
+	const code = safeTrim(composition.entity);
+	const entity = entityAt(["composition", "entity"], code, "Composition entity");
+	for (const key of ["account", "slot", "analytic"]) {
+		columnAt(["composition", key], entity, code, composition[key], `Composition '${key}' column`);
+	}
+}
+
+function checkAccounting(ctx: Context): void {
+	const { def, kind, error } = ctx;
+	if (kind !== "accounting") {
+		return;
+	}
+	const mode = safeTrim(def.lineMode);
+	if (mode && mode !== "classic" && mode !== "compound") {
+		error(["lineMode"], "line-mode", "'lineMode' is 'classic' or 'compound'.");
+	}
+	checkComposition(ctx, mode === "compound" ? checkCompoundAccounts(ctx) : checkClassicAccounts(ctx));
+}
+
+function checkTotals(ctx: Context): void {
+	const { def, kind, dimensions, resources, entityAt, columnAt, error } = ctx;
+	const totals = isRecord(def.totals) ? def.totals : undefined;
+	if (!totals || kind === "info") {
+		return;
+	}
+	const totalsCode = safeTrim(totals.entity);
+	if (!totalsCode) {
+		error(["totals", "entity"], "totals", "The totals cache needs its entity.");
+	}
+	const totalsEntity = entityAt(["totals", "entity"], totalsCode, "Totals entity");
+	const period = safeTrim(totals.period);
+	if (!period || !(REGISTER_TOTALS_PERIODS as readonly string[]).includes(period)) {
+		error(["totals", "period"], "totals", "The totals cache needs a period: day, month, quarter or year.");
+	}
+	if (!safeTrim(totals.periodField)) {
+		error(["totals", "periodField"], "totals", "The totals cache needs 'periodField' — the column holding each period's first date.");
+	}
+	columnAt(["totals", "periodField"], totalsEntity, totalsCode, safeTrim(totals.periodField), "Totals period column");
+	if (kind === "accounting") {
+		if (!safeTrim(totals.accountField)) {
+			error(["totals", "accountField"], "totals", "An accounting register's cache needs 'accountField'.");
+		}
+		columnAt(["totals", "accountField"], totalsEntity, totalsCode, safeTrim(totals.accountField), "Totals account column");
+		stringList(totals.dimensions).forEach((name, i) => {
+			if (!dimensions.includes(name)) {
+				error(["totals", "dimensions", i], "totals", `Totals dimension '${name}' isn't a dimension of the register.`);
+			}
+		});
+	} else {
+		if (hasKey(totals, "accountField")) {
+			error(["totals", "accountField"], "totals", "'accountField' belongs to an accounting register's cache.");
+		}
+		if (hasKey(totals, "dimensions")) {
+			error(["totals", "dimensions"], "totals", "A cache grouped by fewer dimensions is for an accounting register only.");
+		}
+	}
+	const cached = isRecord(totals.resources) ? totals.resources : {};
+	const pair = kind === "accounting" ? ["debitField", "creditField"] : ["inField", "outField"];
+	for (const { name } of resources) {
+		const entry = cached[name];
+		if (!isRecord(entry)) {
+			error(["totals", "resources"], "totals", `The totals cache must cover every resource — '${name}' is missing.`);
+			continue;
+		}
+		for (const key of pair) {
+			if (!safeTrim(entry[key])) {
+				error(["totals", "resources", name], "totals", `Totals resource '${name}' needs '${key}'.`);
+			}
+			columnAt(["totals", "resources", name, key], totalsEntity, totalsCode, safeTrim(entry[key]), `Totals '${name}' ${key}`);
+		}
+	}
+	for (const name of Object.keys(cached)) {
+		if (!resources.some((resource) => resource.name === name)) {
+			error(["totals", "resources", name], "totals", `Totals cache names '${name}', which isn't a resource of the register.`);
+		}
+	}
+}
+
+function checkWarnings({ def, kind, journalCode, warning }: Context): void {
+	if (!safeTrim(def.label)) {
+		warning(["label"], "label", "No label — the query builder shows the code.");
+	}
+	if (kind === "balance") {
+		if (!journalCode) {
+			warning(["journal"], "no-journal", "No journal: unposting has to recompute from the document, and as-of-date reads are refused.");
+		} else if (!safeTrim(def.journalDirection) || !safeTrim(def.journalDate)) {
+			warning(["journal"], "journal-stamps", "Declare both journal stamps (direction and date) from the start — rows journalled without them can't be backfilled.");
+		}
+	}
+}
+
+/**
+ * Check one declaration against the schema's per-kind rules and the installer's
+ * — paths relative to the declaration. With a lookup, the entities it names are
+ * checked to exist and the columns it names to be stored on them.
+ */
+export function checkRegister(raw: unknown, lookup?: RegisterEntityLookup): RegisterIssue[] {
+	const out: RegisterIssue[] = [];
+	const error = createIssueReporter(out, "registers", "error");
+	const warning = createIssueReporter(out, "registers", "warning");
+	if (!isRecord(raw)) {
+		error([], "shape", "A register declaration is a JSON object.");
+		return out;
+	}
+	const def = raw;
+	if (!isRegisterKind(def.kind)) {
+		error(["kind"], "kind", "Pick a kind: balance, turnover, info or accounting.");
+		return out;
+	}
+	const kind = def.kind;
+	checkProperties({ def, kind, error });
+	const checks = createEntityChecks(lookup, error, warning);
+	const ctx: Context = {
+		def, kind, error, warning, ...checks,
+		...resolveEntities(def, kind, checks),
+		dimensions: registerDimensions(def),
+		sides: isRecord(def.sideDimensions) ? def.sideDimensions : {},
+		resources: registerResources(def),
+	};
+	checkDimensions(ctx);
+	checkResources(ctx);
+	checkAccounting(ctx);
+	checkTotals(ctx);
+	checkWarnings(ctx);
+	return out;
+}
+
+/**
+ * Check a whole `registers.json`: every declaration (paths prefixed by its
+ * code), plus the codes themselves and the file's limits.
+ */
+export function checkRegisters(file: unknown, lookup?: RegisterEntityLookup): RegisterIssue[] {
+	const out: RegisterIssue[] = [];
+	const error = createIssueReporter(out, "registers", "error");
+	if (!isRecord(file)) {
+		error([], "shape", "registers.json is an object of register declarations.");
+		return out;
+	}
+	const codes = Object.keys(file).filter((code) => !code.startsWith("$"));
+	if (codes.length === 0) {
+		error([], "empty", "A module with no registers has no registers.json — the file needs at least one.");
+	}
+	if (codes.length > MAX_REGISTERS) {
+		error([], "limit", `A module declares at most ${MAX_REGISTERS} registers.`);
+	}
+	for (const code of codes) {
+		if (!REGISTER_CODE.test(code)) {
+			error([code], "code", `'${code}': lowercase letters, digits and '_', starting with a letter — a binding names it as module.code.`);
+		}
+		for (const issue of checkRegister(file[code], lookup)) {
+			out.push({ ...issue, path: [code, ...issue.path] });
+		}
+	}
+	return out;
+}

package/src/registers/entities.ts

@@ -0,0 +1,79 @@
+// Resolving the entities and columns a declaration names, through the caller's lookup.
+
+import { REGISTER_COLUMN_NAME } from "./types";
+import type { IssuePath, RegisterReporter } from "./issues";
+
+/**
+ * What an entity a declaration names looks like, as far as the caller knows.
+ * `columns` is left undefined when they can't be listed (a dependency known
+ * only from its contract), and no column rule runs against it.
+ */
+export interface RegisterEntityInfo {
+	columns?: Iterable<string>;
+}
+
+/**
+ * Resolves an entity code as `registers.json` writes it — bare for the module's
+ * own, `module.entity` for another's. Returns `null` when nothing can be known
+ * (the module named isn't available: the rule stands down) and `undefined` when
+ * the module is known and has no such entity.
+ */
+export type RegisterEntityLookup = (code: string) => RegisterEntityInfo | null | undefined;
+
+export type ResolvedRegisterEntity = RegisterEntityInfo | null | undefined;
+
+export interface EntityChecks {
+	/** Resolve `code`, reporting `unknown-entity` when the module is known and has no such entity. */
+	entityAt: (path: IssuePath, code: string | undefined, what: string) => ResolvedRegisterEntity;
+	/** Check a column name, and that `entity` stores it. A non-string or blank column is skipped. */
+	columnAt: (path: IssuePath, entity: ResolvedRegisterEntity, entityCode: string | undefined, column: unknown, what: string) => void;
+}
+
+export function createEntityChecks(
+	lookup: RegisterEntityLookup | undefined,
+	error: RegisterReporter,
+	warning: RegisterReporter,
+): EntityChecks {
+	const resolved = new Map<string, ResolvedRegisterEntity>();
+	const columnSets = new WeakMap<RegisterEntityInfo, Set<string> | null>();
+
+	const entityAt: EntityChecks["entityAt"] = (path, code, what) => {
+		if (!code || !lookup) {
+			return null;
+		}
+		if (!resolved.has(code)) {
+			resolved.set(code, lookup(code));
+		}
+		const found = resolved.get(code);
+		if (found === undefined) {
+			error(path, "unknown-entity", `${what} '${code}' isn't an entity this module can see.`);
+		}
+		return found;
+	};
+
+	const columnsOf = (entity: ResolvedRegisterEntity): Set<string> | null => {
+		if (!entity) {
+			return null;
+		}
+		if (!columnSets.has(entity)) {
+			columnSets.set(entity, entity.columns ? new Set(entity.columns) : null);
+		}
+		return columnSets.get(entity) ?? null;
+	};
+
+	const columnAt: EntityChecks["columnAt"] = (path, entity, entityCode, column, what) => {
+		if (typeof column !== "string" || !column.trim()) {
+			return;
+		}
+		if (!REGISTER_COLUMN_NAME.test(column)) {
+			error(path, "column-name", `${what} '${column}' isn't a column name (lowercase letters, digits and '_').`);
+			return;
+		}
+		const columns = columnsOf(entity);
+		if (columns && !columns.has(column)) {
+			warning(path, "unknown-column", `${what} '${column}' isn't a stored column of ${entityCode}.`);
+		}
+	};
+
+	return { entityAt, columnAt };
+}

package/src/registers/index.ts

@@ -0,0 +1,17 @@
+// Registers — the authoring shape of `registers.json` and the rules the installer
+// holds a declaration and a document's binding to.
+//
+// The rules live here, once, so an editor can run them as the author types, a
+// language server can report them on the file, and a validator can refuse a pack
+// — the same way the DSL rules are shared.
+
+export * from "./types";
+export {
+	registerDimensions, registerResources, registerCarrier, registerResourceShape, registerLineMode,
+	registerRefusedProps, registerRequiredProps,
+} from "./read";
+export type { RegisterIssue } from "./issues";
+export type { RegisterEntityInfo, RegisterEntityLookup } from "./entities";
+export { checkRegister, checkRegisters } from "./check-declaration";
+export { checkRegisterBinding, isPlainColumnRef } from "./check-binding";
+export type { RegisterBindingTarget } from "./check-binding";

package/src/registers/issues.ts

@@ -0,0 +1,25 @@
+// Findings: what a check reports, and the reporters that collect them.
+
+export type IssuePath = Array<string | number>;
+
+/** One finding, addressed by a JSON path relative to what was checked. */
+export interface RegisterIssue {
+	path: IssuePath;
+	message: string;
+	/** `error`: install refuses it. `warning`: worth a look. */
+	severity: "error" | "warning";
+	/** Stable id, namespaced `registers/*` for a declaration and `entity/register-*` for a binding. */
+	code: string;
+}
+
+export type RegisterReporter = (path: IssuePath, code: string, message: string) => void;
+
+export function createIssueReporter(
+	issues: RegisterIssue[],
+	namespace: "registers" | "entity",
+	severity: RegisterIssue["severity"],
+): RegisterReporter {
+	return (path, code, message) => {
+		issues.push({ path, code: `${namespace}/${code}`, message, severity });
+	};
+}

package/src/registers/read.ts

@@ -0,0 +1,81 @@
+// Reading a declaration: the loose-JSON helpers every check shares, and what each
+// kind requires and refuses.
+
+import type { RegisterDef, RegisterKind, RegisterResourceDef } from "./types";
+
+export type Raw = Record<string, unknown>;
+
+export const isRecord = (value: unknown): value is Raw =>
+	!!value && typeof value === "object" && !Array.isArray(value);
+
+export const safeTrim = (value: unknown): string | undefined => (typeof value === "string" && value.trim() ? value : undefined);
+
+export const stringList = (value: unknown): string[] =>
+	Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+
+/** A key present but undefined is an editor's draft, not a declaration. */
+export const hasKey = (obj: Raw, key: string): boolean => obj[key] !== undefined;
+
+/** A declaration's dimension names, only the ones that are strings. */
+export const registerDimensions = (def: RegisterDef | Raw): string[] => stringList(def.dimensions);
+
+/** A declaration's resources in file order, each with its definition object. */
+export const registerResources = (def: RegisterDef | Raw): Array<{ name: string; def: Raw }> =>
+	!isRecord(def.resources)
+		? []
+		: Object.entries(def.resources).map(([name, raw]) => ({ name, def: isRecord(raw) ? raw : {} }));
+
+/** The entity the dimensions, resources and stamps are columns of. */
+export function registerCarrier(def: RegisterDef | Raw): string | undefined {
+	switch (def.kind) {
+		case "balance":
+		case "info":
+			return safeTrim(def.entity);
+		case "turnover":
+		case "accounting":
+			return safeTrim(def.journal);
+		default:
+			return undefined;
+	}
+}
+
+/** How a resource names its column: one shared column, or one per side. */
+export const registerResourceShape = (resource: RegisterResourceDef | Raw): "field" | "split" =>
+	"debitField" in resource || "creditField" in resource ? "split" : "field";
+
+export const registerLineMode = (def: RegisterDef | Raw): "classic" | "compound" =>
+	def.lineMode === "compound" ? "compound" : "classic";
+
+const INFO_PROPERTIES = ["period", "recorder", "recordChangesOnly"] as const;
+const ACCOUNTING_PROPERTIES = [
+	"chart", "composition", "analyticFields", "lineMode", "account",
+	"debitAccount", "creditAccount", "debitAnalyticFields", "creditAnalyticFields", "sideDimensions",
+] as const;
+const BALANCE_PROPERTIES = ["allowNegative", "autoCreate"] as const;
+
+/** Properties each kind refuses — the schema's `false` properties, which install fails on. */
+const REFUSED: Record<RegisterKind, readonly string[]> = {
+	balance: [...INFO_PROPERTIES, ...ACCOUNTING_PROPERTIES],
+	turnover: ["entity", ...INFO_PROPERTIES, ...ACCOUNTING_PROPERTIES, ...BALANCE_PROPERTIES],
+	info: ["journal", "journalDirection", "journalDate", ...ACCOUNTING_PROPERTIES, "totals", ...BALANCE_PROPERTIES],
+	accounting: ["entity", ...INFO_PROPERTIES, "journalDirection", ...BALANCE_PROPERTIES],
+};
+
+/** Properties each kind requires beside `kind`, `dimensions` and `resources`. */
+const REQUIRED: Record<RegisterKind, readonly string[]> = {
+	balance: ["entity"],
+	turnover: ["journal", "journalDirection", "journalDate"],
+	info: ["entity"],
+	accounting: ["chart", "journal", "journalDate", "lineMode"],
+};
+
+export const registerRefusedProps = (kind: RegisterKind): readonly string[] => REFUSED[kind];
+export const registerRequiredProps = (kind: RegisterKind): readonly string[] => REQUIRED[kind];
+
+/** "A balance register" / "a balance register", for the start and the middle of a message. */
+export const KIND_LABEL: Record<RegisterKind, { sentence: string; inline: string }> = {
+	balance: { sentence: "A balance register", inline: "a balance register" },
+	turnover: { sentence: "A turnover register", inline: "a turnover register" },
+	info: { sentence: "An information register", inline: "an information register" },
+	accounting: { sentence: "An accounting register", inline: "an accounting register" },
+};