@xml-auditfile/auditfile 0.0.0-stage → 0.0.2-alpha.3

package/src/definitions/dialect.js

@@ -0,0 +1,40 @@
+import { object, objects, optionalString, string, strings } from '../internal/json.js';
+import { LocalizedText } from './localized-text.js';
+import { DialectAction, oneOf } from './names.js';
+
+/** Corrections for a package that deviates from the standard, from dialects.json. */
+export class Dialect {
+    /** @internal */
+    constructor(json) {
+        const match = object(json, 'match');
+        /** Dialect name. */
+        this.name = string(json, 'name');
+        /** What the dialect is for. */
+        this.description = LocalizedText.from(object(json, 'description'));
+        /** Namespaces that select this dialect. */
+        this.namespaces = Object.freeze(match === null ? [] : strings(match, 'namespaces'));
+        /** Value of header/softwareDesc that selects this dialect. */
+        this.softwareDescription = match === null ? null : optionalString(match, 'softwareDesc');
+        /** Corrections to apply. */
+        this.corrections = Object.freeze(objects(json, 'corrections').map((c) => new DialectCorrection(c)));
+        Object.freeze(this);
+    }
+}
+
+/** One correction of a dialect. */
+export class DialectCorrection {
+    /** @internal */
+    constructor(json) {
+        /** Diagnostic code reported when the correction is applied. */
+        this.code = string(json, 'code');
+        /** What the correction does, one of {@link DialectAction}. */
+        this.action = oneOf(string(json, 'action'), DialectAction, 'dialect action');
+        /** XML paths the correction applies to. */
+        this.paths = Object.freeze(strings(json, 'paths'));
+        /** Original value (replaceNamespace). */
+        this.from = optionalString(json, 'from');
+        /** Replacement value (replaceNamespace). */
+        this.to = optionalString(json, 'to');
+        Object.freeze(this);
+    }
+}

package/src/definitions/element-definition.js

@@ -0,0 +1,27 @@
+import { isObject, object, string } from '../internal/json.js';
+import { LocalizedText } from './localized-text.js';
+
+/** Documentation of a table, column or flattened group, from definition.json. */
+export class ElementDefinition {
+    /** @internal */
+    constructor(json) {
+        /** "tr_line" (table), "tr_line.amnt" (column) or "tr_line.currency" (group). */
+        this.key = string(json, 'key');
+        /** "table", "column" or "group". */
+        this.kind = string(json, 'kind');
+        /** Official name, usually English only. */
+        this.label = LocalizedText.from(object(json, 'label'));
+        /** Meaning according to the official documentation. */
+        this.definition = LocalizedText.from(object(json, 'definition'));
+        /** Practical explanation. */
+        this.description = LocalizedText.from(object(json, 'description'));
+
+        /** @type {Map<string, LocalizedText>} Meaning of code values, e.g. "D" = Debit. */
+        this.codes = new Map();
+        for (const [code, text] of Object.entries(object(json, 'codes') ?? {})) {
+            this.codes.set(code, LocalizedText.from(isObject(text) ? text : null) ?? new LocalizedText(null, null));
+        }
+
+        Object.freeze(this);
+    }
+}

package/src/definitions/localized-text.js

@@ -0,0 +1,41 @@
+import { optionalString } from '../internal/json.js';
+
+/** Language for definitions and diagnostic messages. */
+export const TextLanguage = Object.freeze({
+    /** Dutch: the official language of the Belastingdienst publications. */
+    Dutch: 'nl',
+    /** English; falls back to Dutch where no translation exists. */
+    English: 'en',
+});
+
+/** A text in Dutch and English. English falls back to Dutch when empty. */
+export class LocalizedText {
+    /**
+     * @param {string | null} dutch
+     * @param {string | null} english
+     */
+    constructor(dutch, english) {
+        /** Dutch text, or null. */
+        this.dutch = dutch ? dutch : null;
+        /** English text, or null. */
+        this.english = english ? english : null;
+        Object.freeze(this);
+    }
+
+    /**
+     * The text in the requested language, falling back to the other language.
+     * @param {'nl' | 'en'} [language]
+     */
+    get(language = TextLanguage.Dutch) {
+        return language === TextLanguage.English ? this.english ?? this.dutch : this.dutch ?? this.english;
+    }
+
+    toString() {
+        return this.get(TextLanguage.Dutch) ?? '';
+    }
+
+    /** @internal */
+    static from(json) {
+        return json === null || json === undefined ? null : new LocalizedText(optionalString(json, 'nl'), optionalString(json, 'en'));
+    }
+}

package/src/definitions/manifest.js

@@ -0,0 +1,160 @@
+import { int, object, objects, optionalInt, optionalString, string, strings } from '../internal/json.js';
+
+/** Logical type of a column; the values are the type names of auditfile-spec. */
+export const ColumnType = Object.freeze({
+    /** Text (`string`). */
+    String: 'string',
+    /** Exact decimal number (`Decimal`). */
+    Decimal: 'decimal',
+    /** Whole number (`number`, always a safe integer). */
+    Integer: 'integer',
+    /** Date without time (`Date` at midnight UTC). */
+    Date: 'date',
+    /** Date and time (`Date`; a value without time zone is taken as UTC). */
+    DateTime: 'datetime',
+    /** Time of day (`string` "HH:MM:SS"). */
+    Time: 'time',
+    /** True or false (`boolean`). */
+    Boolean: 'boolean',
+});
+
+const COLUMN_TYPES = new Set(Object.values(ColumnType));
+
+/** @param {string} type */
+export function parseColumnType(type) {
+    if (!COLUMN_TYPES.has(type)) {
+        throw new SyntaxError(`Unknown column type '${type}'.`);
+    }
+
+    return type;
+}
+
+/** The structure of one audit file version, from manifest.json. */
+export class AuditfileManifest {
+    #byName;
+
+    /** @internal */
+    constructor(json) {
+        /** Format version of manifest.json. */
+        this.formatVersion = int(json, 'formatVersion');
+        if (this.formatVersion !== 1) {
+            throw new Error(`Manifest format version ${this.formatVersion} is not supported by this reader.`);
+        }
+
+        /** Audit file type, e.g. "xaf". */
+        this.standard = string(json, 'standard');
+        /** Version, e.g. "3.2". */
+        this.version = string(json, 'version');
+        /** Official namespace. */
+        this.namespace = string(json, 'namespace');
+        /** Name of the root element. */
+        this.rootElement = string(json, 'rootElement');
+        /** SHA-256 of the official XSD. */
+        this.xsdSha256 = optionalString(object(json, 'xsd') ?? {}, 'sha256') ?? '';
+        /** Tables required by the XSD. */
+        this.requiredTables = Object.freeze(strings(json, 'requiredTables'));
+        /** Tables optional in the XSD but expected in practice. */
+        this.expectedTables = Object.freeze(strings(json, 'expectedTables'));
+        /** All tables in document order. */
+        this.tables = Object.freeze(objects(json, 'tables').map((t, i) => new ManifestTable(t, i)));
+        this.#byName = new Map(this.tables.map((t) => [t.name, t]));
+        Object.freeze(this);
+    }
+
+    /**
+     * Finds a table by name, or returns null.
+     * @param {string} name
+     */
+    findTable(name) {
+        return this.#byName.get(name) ?? null;
+    }
+}
+
+/** A table of the manifest. */
+export class ManifestTable {
+    /** @internal */
+    constructor(json, index) {
+        /** Position in the manifest. */
+        this.index = index;
+        /** Table name, e.g. "tr_line". */
+        this.name = string(json, 'name');
+        /** Element name, e.g. "trLine". */
+        this.xmlName = string(json, 'xmlName');
+        /** Full XML path, e.g. "auditfile/company/transactions/journal/transaction/trLine". */
+        this.path = string(json, 'path');
+        /** Name of the parent table, or null for the root. */
+        this.parent = optionalString(json, 'parent');
+        /** Minimum occurrences relative to the XML parent element. */
+        this.minOccurs = int(json, 'minOccurs');
+        /** Maximum occurrences relative to the XML parent element; null means unbounded. */
+        this.maxOccurs = optionalInt(json, 'maxOccurs');
+        /** Natural keys. */
+        this.keys = Object.freeze(objects(json, 'keys').map((k) => new ManifestKey(string(k, 'name'), strings(k, 'columns'))));
+        /** References to keys of other tables. */
+        this.references = Object.freeze(objects(json, 'references').map((r) =>
+            new ManifestReference(string(r, 'name'), strings(r, 'columns'), string(r, 'table'), string(r, 'key'))));
+        /** Columns in XSD order. */
+        this.columns = Object.freeze(objects(json, 'columns').map((c, i) => new ManifestColumn(c, i)));
+        Object.freeze(this);
+    }
+}
+
+/** A column of a manifest table. */
+export class ManifestColumn {
+    /** @internal */
+    constructor(json, index) {
+        /** Position within the table. */
+        this.index = index;
+        /** Column name, e.g. "amnt". */
+        this.name = string(json, 'name');
+        /** Element or attribute name. */
+        this.xmlName = string(json, 'xmlName');
+        /** Path relative to the table element: "amnt", "currency/curCode", "@attr" or ".". */
+        this.path = string(json, 'path');
+        /** "element" or "attribute". */
+        this.kind = string(json, 'kind');
+        /** Logical type, one of {@link ColumnType}. */
+        this.type = parseColumnType(string(json, 'type'));
+        /** Name of the XSD type. */
+        this.xsdType = string(json, 'xsdType');
+        /** Minimum occurrences relative to the XML parent element. */
+        this.minOccurs = int(json, 'minOccurs');
+        Object.freeze(this);
+    }
+}
+
+/** A natural key: the column values are unique within an import. */
+export class ManifestKey {
+    /**
+     * @param {string} name
+     * @param {string[]} columns
+     */
+    constructor(name, columns) {
+        /** Key name from the XSD. */
+        this.name = name;
+        /** Key columns. */
+        this.columns = Object.freeze([...columns]);
+        Object.freeze(this);
+    }
+}
+
+/** A reference from columns of one table to a key of another table. */
+export class ManifestReference {
+    /**
+     * @param {string} name
+     * @param {string[]} columns
+     * @param {string} table
+     * @param {string} key
+     */
+    constructor(name, columns, table, key) {
+        /** Reference name from the XSD. */
+        this.name = name;
+        /** Referencing columns. */
+        this.columns = Object.freeze([...columns]);
+        /** Referenced table. */
+        this.table = table;
+        /** Referenced key. */
+        this.key = key;
+        Object.freeze(this);
+    }
+}

package/src/definitions/names.js

@@ -0,0 +1,42 @@
+/** What a dialect correction does. Unknown actions are refused when the definitions are loaded. */
+export const DialectAction = Object.freeze({
+    /** Read a file in `from` as the official namespace. */
+    ReplaceNamespace: 'replaceNamespace',
+    /** A decimal comma becomes a point. */
+    DecimalComma: 'decimalComma',
+    /** The time is removed from a date. */
+    DateFromDateTime: 'dateFromDateTime',
+});
+
+/** How a view column aggregates its values. Unknown aggregates are refused when the definitions are loaded. */
+export const ViewAggregate = Object.freeze({
+    Sum: 'sum',
+    Count: 'count',
+    Min: 'min',
+    Max: 'max',
+});
+
+/** How a view column gets its value from an input row. Unknown operators are refused when the definitions are loaded. */
+export const ViewOperator = Object.freeze({
+    /** The value of the column. */
+    Column: 'column',
+    /** The value when `by` is one of the codes, otherwise null. */
+    Only: 'only',
+    /** The value, negated when `by` is one of the codes. */
+    Signed: 'signed',
+});
+
+/**
+ * A name from the JSON definitions, checked against the known names.
+ * @internal
+ * @param {string} value
+ * @param {Readonly<Record<string, string>>} allowed
+ * @param {string} what
+ */
+export function oneOf(value, allowed, what) {
+    if (!Object.values(allowed).includes(value)) {
+        throw new SyntaxError(`Embedded JSON: unknown ${what} '${value}'.`);
+    }
+
+    return value;
+}

package/src/definitions/resources.js

@@ -0,0 +1,29 @@
+import { files } from '../generated/spec.js';
+import { parseObject } from '../internal/json.js';
+
+/** The files from auditfile-spec/generated/ that are embedded in this package (tools/embed-spec.mjs). */
+
+/** @param {string} name */
+export function exists(name) {
+    return files.has(name);
+}
+
+/** @param {string} name */
+export function readText(name) {
+    const text = files.get(name);
+    if (text === undefined) {
+        throw new Error(`Embedded definition '${name}' is missing. Was auditfile-spec/generated/ present when the package was built?`);
+    }
+
+    return text;
+}
+
+/** @param {string} name */
+export function readJson(name) {
+    return parseObject(readText(name), name);
+}
+
+/** The bytes of an embedded file as published. */
+export function readBytes(name) {
+    return new TextEncoder().encode(readText(name));
+}

package/src/definitions/view-definition.js

@@ -0,0 +1,160 @@
+import { array, isObject, object, objects, optionalString, string, strings } from '../internal/json.js';
+import { runView } from '../views/view-runner.js';
+import { exists, readJson } from './resources.js';
+import { LocalizedText, TextLanguage } from './localized-text.js';
+import { oneOf, ViewAggregate, ViewOperator } from './names.js';
+
+/**
+ * A view from views/<type>.json: a report over the rows of an import, such as a trial balance.
+ * Run it with {@link ViewDefinition#run} on any store that can hand out the rows of a table.
+ */
+export class ViewDefinition {
+    /** @internal */
+    constructor(json) {
+        /** View name, e.g. "trial_balance". */
+        this.name = string(json, 'name');
+        /** Display name. */
+        this.label = LocalizedText.from(object(json, 'label'));
+        /** What the view shows. */
+        this.description = LocalizedText.from(object(json, 'description'));
+        /** The table with one input row per row of the view (before grouping). */
+        this.source = string(json, 'source');
+        /** Tables joined to the source: an ancestor of the source, or a lookup on key columns. */
+        this.joins = Object.freeze(objects(json, 'joins').map((j) => new ViewJoin(j)));
+        /** Optional filters. */
+        this.parameters = Object.freeze(objects(json, 'parameters').map((p) => new ViewParameter(p)));
+        /** Output columns. When any column aggregates, the other columns group. */
+        this.columns = Object.freeze(objects(json, 'columns').map((c) => new ViewColumn(c)));
+        /** Output column names to sort by, ascending. */
+        this.orderBy = Object.freeze(strings(json, 'orderBy'));
+        Object.freeze(this);
+    }
+
+    /** True when at least one column aggregates. */
+    get isAggregated() {
+        return this.columns.some((c) => c.aggregate !== null);
+    }
+
+    /**
+     * Runs the view. `rows` returns the rows of a table by name.
+     * `parameters` holds filter values by parameter name; null and undefined values are ignored.
+     * @param {import('../schema/schema.js').AuditfileSchema} schema
+     * @param {(table: string) => Iterable<import('../reading/row.js').AuditfileRow>} rows
+     * @param {Record<string, unknown> | Map<string, unknown> | null} [parameters]
+     * @param {'nl' | 'en'} [language]
+     * @returns {import('../views/view-result.js').ViewResult}
+     * @throws {TypeError} A parameter is unknown or its value cannot be converted.
+     */
+    run(schema, rows, parameters = null, language = TextLanguage.Dutch) {
+        if (schema === null || schema === undefined) {
+            throw new TypeError('schema is required.');
+        }
+
+        if (typeof rows !== 'function') {
+            throw new TypeError('rows must be a function that returns the rows of a table.');
+        }
+
+        return runView(this, schema, rows, parameters, language);
+    }
+
+    toString() {
+        return this.name;
+    }
+
+    /** @internal */
+    static load(type) {
+        const name = `views/${type}.json`;
+        return exists(name) ? Object.freeze(objects(readJson(name), 'views').map((v) => new ViewDefinition(v))) : Object.freeze([]);
+    }
+}
+
+/** A table joined to the source of a view. */
+export class ViewJoin {
+    /** @internal */
+    constructor(json) {
+        /** Table name. */
+        this.table = string(json, 'table');
+        /** Equality conditions; empty means {@link ViewJoin#table} is an ancestor of the source. */
+        this.on = Object.freeze(array(json, 'on').map((pair) => {
+            if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== 'string' || typeof pair[1] !== 'string') {
+                throw new SyntaxError('Embedded JSON: a join condition must be a pair of column references.');
+            }
+
+            return new ViewJoinCondition(pair[0], pair[1]);
+        }));
+        Object.freeze(this);
+    }
+}
+
+/** One equality condition of a join, as "table.column" references. */
+export class ViewJoinCondition {
+    constructor(left, right) {
+        /** Column of the source or an earlier join. */
+        this.left = left;
+        /** Column of the joined table. */
+        this.right = right;
+        Object.freeze(this);
+    }
+}
+
+/** An optional filter of a view. */
+export class ViewParameter {
+    /** @internal */
+    constructor(json) {
+        /** Parameter name, e.g. "period_from". */
+        this.name = string(json, 'name');
+        /** Display name. */
+        this.label = LocalizedText.from(object(json, 'label'));
+        /** The filtered column, as "table.column". */
+        this.column = string(json, 'column');
+        /** "=", "<", "<=", ">" or ">=". */
+        this.operator = string(json, 'operator');
+        Object.freeze(this);
+    }
+}
+
+/** An output column of a view. */
+export class ViewColumn {
+    /** @internal */
+    constructor(json) {
+        /** Column name. */
+        this.name = string(json, 'name');
+        /** Display name. */
+        this.label = LocalizedText.from(object(json, 'label'));
+        /** The aggregate, one of {@link ViewAggregate}, or null for a grouping column. */
+        const aggregate = optionalString(json, 'aggregate');
+        this.aggregate = aggregate === null ? null : oneOf(aggregate, ViewAggregate, 'view aggregate');
+        /** The value per input row; null for a row count. */
+        this.value = Object.prototype.hasOwnProperty.call(json, 'value') && json.value !== null ? ViewValue.from(json.value) : null;
+        Object.freeze(this);
+    }
+}
+
+/** How a view column gets its value from an input row. */
+export class ViewValue {
+    constructor(operator, column, by, codes) {
+        /** How the value is taken from `column`, one of {@link ViewOperator}. */
+        this.operator = operator;
+        /** The value column, as "table.column". */
+        this.column = column;
+        /** The column holding the code, as "table.column". */
+        this.by = by;
+        /** Codes for "only" (in) or "signed" (negative). */
+        this.codes = Object.freeze([...codes]);
+        Object.freeze(this);
+    }
+
+    /** @internal */
+    static from(json) {
+        if (typeof json === 'string') {
+            return new ViewValue(ViewOperator.Column, json, null, []);
+        }
+
+        if (isObject(json)) {
+            return new ViewValue(oneOf(string(json, 'op'), ViewOperator, 'view value operator'), string(json, 'value'), optionalString(json, 'by'),
+                [...strings(json, 'in'), ...strings(json, 'negative')]);
+        }
+
+        throw new SyntaxError('Embedded JSON: invalid view column value.');
+    }
+}

package/src/diagnostics/collector.js

@@ -0,0 +1,139 @@
+import { LocalizedText } from '../definitions/localized-text.js';
+import { readJson } from '../definitions/resources.js';
+import { Decimal } from '../internal/decimal.js';
+import { object, objects, string } from '../internal/json.js';
+import { toText } from '../reading/value-converter.js';
+import { Diagnostic, DiagnosticSeverity } from './diagnostic.js';
+
+/** Where a diagnostic applies. */
+export class Location {
+    constructor(part = null, line = null, position = null, path = null) {
+        this.part = part;
+        this.line = line;
+        this.position = position;
+        this.path = path;
+        Object.freeze(this);
+    }
+
+    static NONE = new Location();
+}
+
+const SEVERITIES = new Set(Object.values(DiagnosticSeverity));
+
+/** @type {Map<string, object> | null} */
+let catalog = null;
+
+function entry(code) {
+    catalog ??= new Map(objects(readJson('diagnostics.json'), 'codes').map((c) => [string(c, 'code'), c]));
+    const found = catalog.get(code);
+    if (found === undefined) {
+        throw new Error(`Diagnostic code ${code} is not defined in diagnostics.json.`);
+    }
+
+    return found;
+}
+
+function severityOf(json) {
+    const severity = string(json, 'severity');
+    return SEVERITIES.has(severity) ? severity : DiagnosticSeverity.Fatal;
+}
+
+function format(value) {
+    return value instanceof Decimal ? value.toString() : toText(value);
+}
+/**
+ * Collects diagnostics, formats messages from diagnostics.json and caps the list.
+ * The counts per severity cover every diagnostic, also the ones left out of a full list,
+ * and a full list makes room for an error by dropping an info or warning, so errors are never hidden behind them.
+ */
+export class DiagnosticCollector {
+    #language;
+    #maximum;
+    /** @type {Diagnostic | null} */
+    #capped = null;
+    /** @type {Diagnostic[]} */
+    #items = [];
+    /** Number of diagnostics per severity, including the ones left out. */
+    counts = { info: 0, warning: 0, error: 0, fatal: 0 };
+
+    constructor(language, maximum) {
+        this.#language = language;
+        this.#maximum = maximum;
+    }
+
+    /** @type {Diagnostic[]} The kept diagnostics, followed by XAF-X900 when some were left out. */
+    get items() {
+        return this.#capped === null ? this.#items : [...this.#items, this.#capped];
+    }
+
+    get hasFatal() {
+        return this.counts.fatal > 0;
+    }
+
+    get hasErrors() {
+        return this.hasFatal || this.counts.error > 0;
+    }
+
+    /** True when diagnostics were left out of {@link DiagnosticCollector#items}. */
+    get isTruncated() {
+        return this.#capped !== null;
+    }
+
+    /**
+     * @param {string} code
+     * @param {Location} location
+     * @param {Record<string, unknown>} [args]
+     */
+    add(code, location, args = {}) {
+        const json = entry(code);
+        const severity = severityOf(json);
+        this.counts[severity]++;
+
+        if (this.#items.length >= this.#maximum && !this.#makeRoomFor(severity)) {
+            this.#capped ??= this.#create('XAF-X900', Location.NONE, { max: this.#maximum });
+            return;
+        }
+
+        this.#items.push(this.#create(code, location, args));
+    }
+
+    /**
+     * A fatal diagnostic is always kept. An error replaces the last info or warning in the list;
+     * a dropped diagnostic still counts, and the list is marked as truncated.
+     */
+    #makeRoomFor(severity) {
+        if (severity === DiagnosticSeverity.Fatal) {
+            return true;
+        }
+
+        if (severity !== DiagnosticSeverity.Error) {
+            return false;
+        }
+
+        let index = this.#items.findLastIndex((d) => d.severity === DiagnosticSeverity.Info);
+        if (index < 0) {
+            index = this.#items.findLastIndex((d) => d.severity === DiagnosticSeverity.Warning);
+        }
+
+        if (index < 0) {
+            return false;
+        }
+
+        this.#items.splice(index, 1);
+        this.#capped ??= this.#create('XAF-X900', Location.NONE, { max: this.#maximum });
+        return true;
+    }
+
+    #create(code, location, args) {
+        const json = entry(code);
+        let message = LocalizedText.from(object(json, 'message'))?.get(this.#language) ?? code;
+        for (const [name, value] of Object.entries(args)) {
+            // A replacer function: values come from the file and must never be read as replacement patterns ($&, $1).
+            const text = format(value);
+            message = message.replaceAll(`{${name}}`, () => text);
+        }
+
+        return new Diagnostic(code, string(json, 'layer'), severityOf(json), message,
+            location.part, location.line, location.position, location.path);
+    }
+}