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

package/src/validation/xaf-rules.js

@@ -0,0 +1,167 @@
+import { ColumnType } from '../definitions/manifest.js';
+import { Location } from '../diagnostics/collector.js';
+import { Decimal } from '../internal/decimal.js';
+
+/** Audit file type these rules apply to. */
+export const XAF = 'xaf';
+
+const AMOUNT = 'amnt';
+const AMOUNT_TYPE = 'amnt_tp';
+const DEBIT = 'D';
+const CREDIT = 'C';
+
+/**
+ * A table of lines with an amount and a debit/credit indicator, with its columns looked up once.
+ * Null when the table or a column does not exist, or has another type, in this version.
+ */
+function findLines(table) {
+    const amount = table?.findColumn(AMOUNT) ?? null;
+    const amountType = table?.findColumn(AMOUNT_TYPE) ?? null;
+    if (amount === null || amountType === null || ![ColumnType.Decimal, ColumnType.Integer].includes(amount.type)
+        || amountType.type !== ColumnType.String) {
+        return null;
+    }
+
+    return { table, amount, amountType };
+}
+
+/** Line count and debit and credit totals. */
+class Totals {
+    count = 0;
+    debit = Decimal.ZERO;
+    credit = Decimal.ZERO;
+
+    add(row, lines) {
+        this.count++;
+        const amount = row.getDecimal(lines.amount);
+        if (amount === null) {
+            return;
+        }
+
+        const type = row.getString(lines.amountType);
+        if (type === DEBIT) {
+            this.debit = this.debit.add(amount);
+        } else if (type === CREDIT) {
+            this.credit = this.credit.add(amount);
+        }
+    }
+}
+
+function get(map, key) {
+    let totals = map.get(key);
+    if (totals === undefined) {
+        totals = new Totals();
+        map.set(key, totals);
+    }
+
+    return totals;
+}
+
+/** Compares a header value with the total of the lines. */
+function compare(row, field, expected, actual, diagnostics) {
+    if (expected === null || expected === undefined) {
+        return;
+    }
+
+    const equal = expected instanceof Decimal ? expected.equals(actual) : expected === actual;
+    if (!equal) {
+        diagnostics.add('XAF-R002', new Location(row.part, null, null, row.table.path),
+            { field, table: row.table.name, expected: String(expected), actual: String(actual) });
+    }
+}
+
+/** Header counts and totals of one kind of line, e.g. the transaction lines against company/transactions. */
+class TotalsRule {
+    #byParent = new Map();
+    #all = new Totals();
+
+    constructor(lines, owner, perParent, count, debit, credit) {
+        this.lines = lines;
+        this.owner = owner;
+        this.perParent = perParent;
+        this.count = count;
+        this.debit = debit;
+        this.credit = credit;
+    }
+
+    onRow(row, diagnostics) {
+        if (row.table === this.lines.table) {
+            const totals = this.perParent && row.parentId !== null ? get(this.#byParent, row.parentId) : this.#all;
+            totals.add(row, this.lines);
+            return;
+        }
+
+        if (row.table !== this.owner) {
+            return;
+        }
+
+        let actual = this.#all;
+        if (this.perParent) {
+            actual = this.#byParent.get(row.id) ?? new Totals();
+            this.#byParent.delete(row.id);
+        }
+
+        compare(row, this.count.name, row.getInteger(this.count), actual.count, diagnostics);
+        compare(row, this.debit.name, row.getDecimal(this.debit), actual.debit, diagnostics);
+        compare(row, this.credit.name, row.getDecimal(this.credit), actual.credit, diagnostics);
+    }
+}
+
+/**
+ * Business rules for Auditfile Financieel (XAF):
+ * every transaction balances, and the counts and totals in the headers match the lines.
+ * Rules whose tables or columns do not exist in a version are skipped. Columns are looked up once, not per row.
+ */
+export class XafRules {
+    #diagnostics;
+    #transactions = new Map();
+    #rules = [];
+    #lines;
+    #transaction;
+    #transactionNumber;
+
+    constructor(schema, diagnostics) {
+        this.#diagnostics = diagnostics;
+        this.#lines = findLines(schema.findTable('tr_line'));
+        this.#transaction = schema.findTable('transaction');
+        this.#transactionNumber = this.#transaction?.findColumn('nr') ?? null;
+
+        this.#addRule(schema, 'tr_line', 'company', false, 'transactions_lines_count', 'transactions_total_debit', 'transactions_total_credit');
+        this.#addRule(schema, 'ob_line', 'company', false, 'opening_balance_lines_count', 'opening_balance_total_debit', 'opening_balance_total_credit');
+        this.#addRule(schema, 'sb_line', 'subledger', true, 'lines_count', 'total_debit', 'total_credit');
+        this.#addRule(schema, 'ob_sb_line', 'ob_subledger', true, 'lines_count', 'total_debit', 'total_credit');
+    }
+
+    onRow(row) {
+        if (this.#lines !== null && row.table === this.#lines.table && row.parentId !== null) {
+            get(this.#transactions, row.parentId).add(row, this.#lines);
+        } else if (row.table === this.#transaction && this.#transactions.has(row.id)) {
+            const lines = this.#transactions.get(row.id);
+            this.#transactions.delete(row.id);
+            if (!lines.debit.equals(lines.credit)) {
+                this.#diagnostics.add('XAF-R001', new Location(row.part, null, null, row.table.path),
+                    { transaction: this.#transactionNumber === null ? null : row.get(this.#transactionNumber), debit: lines.debit, credit: lines.credit });
+            }
+        }
+
+        for (const rule of this.#rules) {
+            rule.onRow(row, this.#diagnostics);
+        }
+    }
+
+    onEnd() {}
+
+    #addRule(schema, child, owner, perParent, count, debit, credit) {
+        const lines = findLines(schema.findTable(child));
+        const ownerTable = schema.findTable(owner);
+        const countColumn = ownerTable?.findColumn(count) ?? null;
+        const debitColumn = ownerTable?.findColumn(debit) ?? null;
+        const creditColumn = ownerTable?.findColumn(credit) ?? null;
+        if (lines === null || countColumn?.type !== ColumnType.Integer
+            || debitColumn?.type !== ColumnType.Decimal || creditColumn?.type !== ColumnType.Decimal) {
+            return;
+        }
+
+        this.#rules.push(new TotalsRule(lines, ownerTable, perParent, countColumn, debitColumn, creditColumn));
+    }
+}

package/src/versioning/version-resolver.js

@@ -0,0 +1,119 @@
+import { DialectAction } from '../definitions/names.js';
+import { Location } from '../diagnostics/collector.js';
+import { VersionSource } from '../schema/schema.js';
+import { AuditfileVersion } from './version.js';
+
+/** The outcome of version resolution. */
+export class Resolution {
+    constructor(version, source, fileNamespace, dialect) {
+        /** @type {AuditfileVersion} */
+        this.version = version;
+        this.source = source;
+        this.fileNamespace = fileNamespace;
+        /** @type {import('../definitions/dialect.js').Dialect | null} Set later when header/softwareDesc selects a dialect. */
+        this.dialect = dialect;
+    }
+
+    get needsMapping() {
+        return this.fileNamespace !== this.version.namespace;
+    }
+
+    /**
+     * Recognizes a dialect by the software description in the header, when none was recognized by namespace.
+     * Returns true when a dialect was found.
+     * @param {string} software
+     * @param {boolean} applyDialects
+     */
+    useSoftware(software, applyDialects) {
+        if (this.dialect !== null || !applyDialects) {
+            return false;
+        }
+
+        this.dialect = this.version.dialects.find((d) => d.softwareDescription === software) ?? null;
+        return this.dialect !== null;
+    }
+}
+
+/**
+ * Determines the version: forced by the caller, then the registry (official namespace, alias or dialect),
+ * then optionally the resolver. Anything else is fatal.
+ * @returns {Resolution | null}
+ */
+export function resolveVersion(rootName, fileNamespace, options, diagnostics) {
+    const resolution = find(fileNamespace, options, diagnostics);
+    if (resolution === null) {
+        diagnostics.add('XAF-V001', Location.NONE, { namespace: fileNamespace });
+        return null;
+    }
+
+    const version = resolution.version;
+    if (rootName !== version.rootElement) {
+        diagnostics.add('XAF-V005', Location.NONE, { element: rootName, expected: version.rootElement });
+        return null;
+    }
+
+    if (!version.hasOfficialXsd) {
+        diagnostics.add('XAF-V006', Location.NONE, { version: version.key });
+    }
+
+    const replace = resolution.dialect?.corrections.find((c) => c.action === DialectAction.ReplaceNamespace && c.from === fileNamespace);
+    if (replace !== undefined) {
+        diagnostics.add(replace.code, Location.NONE, { from: fileNamespace, to: version.namespace });
+    }
+
+    return resolution;
+}
+
+function find(fileNamespace, options, diagnostics) {
+    const forced = options.version;
+    if (forced !== null) {
+        if (fileNamespace !== forced.namespace) {
+            diagnostics.add('XAF-V003', Location.NONE, { version: forced.key, namespace: fileNamespace });
+        }
+
+        return new Resolution(forced, VersionSource.Forced, fileNamespace, findDialect(forced, fileNamespace, options));
+    }
+
+    for (const version of AuditfileVersion.all) {
+        if (version.namespace === fileNamespace) {
+            return new Resolution(version, VersionSource.Official, fileNamespace, null);
+        }
+    }
+
+    for (const version of AuditfileVersion.all) {
+        const dialect = findDialect(version, fileNamespace, options);
+        if (version.aliases.includes(fileNamespace) || dialect !== null) {
+            diagnostics.add('XAF-V002', Location.NONE, { namespace: fileNamespace, version: version.key });
+            return new Resolution(version, VersionSource.Alias, fileNamespace, dialect);
+        }
+    }
+
+    if (options.useResolver) {
+        const derived = derive(fileNamespace);
+        if (derived !== null) {
+            diagnostics.add('XAF-V004', Location.NONE, { version: derived.key, namespace: fileNamespace });
+            return new Resolution(derived, VersionSource.Resolved, fileNamespace, null);
+        }
+    }
+
+    return null;
+}
+
+function findDialect(version, fileNamespace, options) {
+    return options.applyDialects ? version.dialects.find((d) => d.namespaces.includes(fileNamespace)) ?? null : null;
+}
+
+const digits = (value) => value.replace(/\D/g, '');
+
+/**
+ * Derives type and version from the namespace segments, e.g. ".../XAF/3.2/" or ".../xaf/3_2".
+ * Returns a version only when exactly one matches.
+ */
+function derive(fileNamespace) {
+    const segments = fileNamespace.toLowerCase().split(/[/:#]/).filter((s) => s.length > 0);
+    const candidates = AuditfileVersion.all.filter((v) =>
+        segments.includes(v.type)
+        && segments.some((s) => digits(s).length > 0 && digits(s) === digits(v.version) && /^[\d._]+$/.test(s)));
+
+    return candidates.length === 1 ? candidates[0] : null;
+}

package/src/versioning/version.js

@@ -0,0 +1,217 @@
+import { Dialect } from '../definitions/dialect.js';
+import { ElementDefinition } from '../definitions/element-definition.js';
+import { AuditfileManifest } from '../definitions/manifest.js';
+import { exists, readBytes, readJson, readText } from '../definitions/resources.js';
+import { ViewDefinition } from '../definitions/view-definition.js';
+import { objects, string } from '../internal/json.js';
+import { Sha256 } from '../internal/sha256.js';
+import { SchemaSet } from '../xsd/schema-set.js';
+
+/** @type {AuditfileVersion[] | null} */
+let registry = null;
+
+function lazy(factory) {
+    let value;
+    let created = false;
+    return () => {
+        if (!created) {
+            value = factory();
+            created = true;
+        }
+
+        return value;
+    };
+}
+
+/**
+ * One audit file type and version, with its manifest, XSD, definitions and dialects.
+ * Use the constants, e.g. `AuditfileVersion.Financial.V3_2`, or {@link AuditfileVersion.parse} with "xaf/3.2".
+ */
+export class AuditfileVersion {
+    #manifest;
+    #definitions;
+    #dialects;
+    #views;
+    #schemaSet;
+
+    /** @internal */
+    constructor(json) {
+        /** Registry key, e.g. "xaf/3.2". */
+        this.key = string(json, 'key');
+        /** Audit file type, e.g. "xaf". */
+        this.type = string(json, 'type');
+        /** Type name used for version objects, e.g. "financial". */
+        this.typeName = string(json, 'typeName');
+        /** Version, e.g. "3.2". */
+        this.version = string(json, 'version');
+        /** Folder of the definitions, e.g. "standards/xaf/3_2". */
+        this.folder = string(json, 'folder');
+        /** Name of the root element. */
+        this.rootElement = string(json, 'rootElement');
+        /** "official" or "reconstructed". */
+        this.provenance = string(json, 'provenance');
+
+        const namespaces = objects(json, 'namespaces');
+        const official = namespaces.find((n) => string(n, 'kind') === 'official');
+        if (official === undefined) {
+            throw new SyntaxError(`registry.json: ${this.key} has no official namespace.`);
+        }
+
+        /** The official namespace. */
+        this.namespace = string(official, 'uri');
+        /** @type {readonly string[]} Other namespaces known to be used for this version. */
+        this.aliases = Object.freeze(namespaces.filter((n) => string(n, 'kind') === 'alias').map((n) => string(n, 'uri')));
+
+        const folder = this.folder;
+        this.#manifest = lazy(() => new AuditfileManifest(readJson(`${folder}/manifest.json`)));
+        this.#definitions = lazy(() => new Map(objects(readJson(`${folder}/definition.json`), 'entries')
+            .map((e) => new ElementDefinition(e)).map((d) => [d.key, d])));
+        this.#dialects = lazy(() => Object.freeze(objects(readJson(`${folder}/dialects.json`), 'dialects').map((d) => new Dialect(d))));
+        this.#views = lazy(() => ViewDefinition.load(this.type));
+        this.#schemaSet = lazy(() => AuditfileVersion.compileSchemaSet(`${folder}/auditfile.xsd`, (name) => (exists(name) ? readText(name) : undefined)));
+        Object.freeze(this);
+    }
+
+    /** @type {readonly AuditfileVersion[]} All versions this reader knows, in registry order. */
+    static get all() {
+        registry ??= Object.freeze(objects(readJson('registry.json'), 'standards').map((s) => new AuditfileVersion(s)));
+        return registry;
+    }
+
+    /** True when the XSD is the official one published by the Belastingdienst. */
+    get hasOfficialXsd() {
+        return this.provenance === 'official';
+    }
+
+    /** @type {AuditfileManifest} Structure: tables and columns. */
+    get manifest() {
+        return this.#manifest();
+    }
+
+    /** @type {ReadonlyMap<string, ElementDefinition>} Definitions by key ("tr_line", "tr_line.amnt"). */
+    get definitions() {
+        return this.#definitions();
+    }
+
+    /** @type {readonly Dialect[]} Known dialects of this version. */
+    get dialects() {
+        return this.#dialects();
+    }
+
+    /** @type {readonly ViewDefinition[]} Views of this audit file type, e.g. the trial balance. Shared by all versions of the type. */
+    get views() {
+        return this.#views();
+    }
+
+    /**
+     * Finds a view by name, or returns null.
+     * @param {string} name
+     */
+    findView(name) {
+        return this.views.find((v) => v.name === name) ?? null;
+    }
+
+    /**
+     * Finds a version by key, e.g. "xaf/3.2" (case-insensitive). Returns null when unknown.
+     * @param {string} key
+     */
+    static find(key) {
+        const lower = String(key).toLowerCase();
+        return AuditfileVersion.all.find((v) => v.key.toLowerCase() === lower) ?? null;
+    }
+
+    /**
+     * Returns the version for a key such as "xaf/3.2".
+     * @param {string} key
+     * @throws {RangeError} The key is unknown.
+     */
+    static parse(key) {
+        if (typeof key !== 'string') {
+            throw new TypeError('key must be a string.');
+        }
+
+        const version = AuditfileVersion.find(key);
+        if (version === null) {
+            throw new RangeError(`Unknown audit file version '${key}'.`);
+        }
+
+        return version;
+    }
+
+    /** The bytes of the XSD of this version. */
+    openXsd() {
+        return readBytes(`${this.folder}/auditfile.xsd`);
+    }
+
+    /** The compiled XSD of this version, ready for validation. Compiled once and shared; it is immutable. */
+    createSchemaSet() {
+        return this.#schemaSet();
+    }
+
+    toString() {
+        return this.key;
+    }
+
+    /**
+     * @internal
+     * Compiles an XSD. Includes and imports are resolved only through `load`, never from disk or network.
+     * @param {string} name
+     * @param {(name: string) => string | undefined} load
+     */
+    static compileSchemaSet(name, load) {
+        return SchemaSet.compile(name, load);
+    }
+
+    /** @internal */
+    static sha256(bytes) {
+        return Sha256.hex(bytes);
+    }
+}
+
+function constant(key) {
+    return { enumerable: true, get: () => AuditfileVersion.parse(key) };
+}
+
+// The version constants. A test checks that every registry entry has a constant here and vice versa.
+// Names follow the registry: version with underscores, e.g. V3_2 for 3.2.
+
+/** Auditfile Financieel (XAF). */
+AuditfileVersion.Financial = Object.freeze(Object.defineProperties({}, {
+    /** XAF 3.2 (2014, supplemented in 2017). */
+    V3_2: constant('xaf/3.2'),
+    /** XAF 4.0.3. */
+    V4_0_3: constant('xaf/4.0.3'),
+}));
+
+/** Auditfile Afrekensystemen (XAA). */
+AuditfileVersion.CashRegister = Object.freeze(Object.defineProperties({}, {
+    V3_2: constant('xaa/3.2'),
+}));
+
+/** Auditfile Boordcomputer Taxi (XAB). */
+AuditfileVersion.TaxiOnboardComputer = Object.freeze(Object.defineProperties({}, {
+    V1_0: constant('xab/1.0'),
+}));
+
+/** Auditfile Ritregistratie (XAR). */
+AuditfileVersion.TripRegistration = Object.freeze(Object.defineProperties({}, {
+    V1_2: constant('xar/1.2'),
+    V2_3_6_1: constant('xar/2.3.6.1'),
+}));
+
+/** Auditfile Salaris (XAS). */
+AuditfileVersion.Payroll = Object.freeze(Object.defineProperties({}, {
+    V2018_1_0: constant('xas/2018.1.0'),
+    V2019_1_0: constant('xas/2019.1.0'),
+    V2020_1_0: constant('xas/2020.1.0'),
+    V2021_1_1: constant('xas/2021.1.1'),
+    V2022_1_1: constant('xas/2022.1.1'),
+    V2023_1_0: constant('xas/2023.1.0'),
+    V2024_1_0: constant('xas/2024.1.0'),
+    V2025_1_0: constant('xas/2025.1.0'),
+    V2026_1_0: constant('xas/2026.1.0'),
+    V2027_1_0: constant('xas/2027.1.0'),
+}));
+
+/** The groups of version constants, for the test that compares them with the registry. */
+export const VERSION_GROUPS = Object.freeze(['Financial', 'CashRegister', 'TaxiOnboardComputer', 'TripRegistration', 'Payroll']);

package/src/views/view-result.js

@@ -0,0 +1,20 @@
+/** The outcome of running a {@link ViewDefinition}. */
+export class ViewResult {
+    /** @internal */
+    constructor(view, isAvailable, rows, diagnostics) {
+        /** @type {import('../definitions/view-definition.js').ViewDefinition} The view that was run. */
+        this.view = view;
+        /** False when the version lacks a table or column the view needs (XAF-Q001); there are no rows then. */
+        this.isAvailable = isAvailable;
+        /** @type {readonly (readonly unknown[])[]} Result rows, sorted by the view's orderBy; one value per column. */
+        this.rows = Object.freeze(rows.map((row) => Object.freeze(row)));
+        /** @type {readonly import('../diagnostics/diagnostic.js').Diagnostic[]} Findings while running the view. */
+        this.diagnostics = Object.freeze([...diagnostics]);
+        Object.freeze(this);
+    }
+
+    /** Output columns; each row has one value per column, in this order. */
+    get columns() {
+        return this.view.columns;
+    }
+}