@fin.cx/opendata 4.7.0 → 4.8.0

package/ts/financialstatements/parse.esef.ts

@@ -0,0 +1,394 @@
+import * as plugins from './plugins.js';
+import { FinancialStatementError } from './classes.financialstatementerror.js';
+import { maxEsefFacts, maxEsefPackageEntries, maxStatementBytes } from './constants.js';
+import type { IEsefFact, IEsefPeriod, IEsefStatement, IKeyFigures, IStatementPeriod, TIsoDate } from './interfaces.js';
+
+type TXmlDocument = plugins.smartxmlXpath.dom.Document;
+type TXmlElement = plugins.smartxmlXpath.dom.Element;
+
+const ixNamespace = 'http://www.xbrl.org/2013/inlineXBRL';
+const xbrliNamespace = 'http://www.xbrl.org/2003/instance';
+const xbrldiNamespace = 'http://xbrl.org/2006/xbrldi';
+const xsiNamespace = 'http://www.w3.org/2001/XMLSchema-instance';
+const xmlNamespace = 'http://www.w3.org/XML/1998/namespace';
+const leiScheme = 'http://standards.iso.org/iso/17442';
+const transformationNamespacePrefix = 'http://www.xbrl.org/inlineXBRL/transformation/';
+const ifrsNamespacePattern = /^https?:\/\/xbrl\.ifrs\.org\/taxonomy\/[^/]+\/ifrs-full$/;
+
+/** a report in an ESEF package: `<package root>/reports/<report>.xhtml` */
+const reportPathPattern = /^[^/]+\/reports\/[^/]+\.x?html?$/i;
+
+/** the formats of the Inline XBRL transformation registry read here, by local name */
+const formatReaders: Record<string, (textArg: string) => string | null> = {
+  'num-dot-decimal': (textArg) => decimalIn(textArg, '.'),
+  numdotdecimal: (textArg) => decimalIn(textArg, '.'),
+  'num-comma-decimal': (textArg) => decimalIn(textArg, ','),
+  numcommadecimal: (textArg) => decimalIn(textArg, ','),
+  'fixed-zero': () => '0',
+  zerodash: () => '0',
+};
+
+/** a number written with a decimal separator and any group separators, as a plain decimal string */
+const decimalIn = (textArg: string, separatorArg: '.' | ','): string | null => {
+  const text = textArg.replace(/[\s']/g, '').replace(separatorArg === '.' ? /,/g : /\./g, '');
+  const [whole, fraction, ...rest] = text.split(separatorArg);
+  if (rest.length > 0 || !/^\d+$/.test(whole) || (fraction !== undefined && !/^\d+$/.test(fraction))) {
+    return null;
+  }
+  return fraction === undefined ? whole : `${whole}.${fraction}`;
+};
+
+/** a decimal string with its decimal point moved `scaleArg` places to the right */
+const scaleDecimal = (valueArg: string, scaleArg: number): string => {
+  const [whole, fraction = ''] = valueArg.split('.');
+  let digits = whole + fraction;
+  let point = whole.length + scaleArg;
+  if (point > digits.length) {
+    digits = digits.padEnd(point, '0');
+  }
+  if (point < 0) {
+    digits = '0'.repeat(-point) + digits;
+    point = 0;
+  }
+  const integer = digits.slice(0, point).replace(/^0+(?=\d)/, '') || '0';
+  const decimals = digits.slice(point).replace(/0+$/, '');
+  return decimals === '' ? integer : `${integer}.${decimals}`;
+};
+
+/** a decimal string rounded to `decimalsArg` places, half away from zero, in units of that place */
+const roundedTo = (valueArg: string, decimalsArg: number): bigint => {
+  const negative = valueArg.startsWith('-');
+  const [whole, fraction = ''] = scaleDecimal(negative ? valueArg.slice(1) : valueArg, decimalsArg).split('.');
+  const magnitude = BigInt(whole) + (fraction !== '' && fraction[0] >= '5' ? 1n : 0n);
+  return negative ? -magnitude : magnitude;
+};
+
+/** whether two facts for one concept and context state the same figure within their precision */
+const factsAgree = (leftArg: IEsefFact, rightArg: IEsefFact): boolean => {
+  if (leftArg.value === rightArg.value) {
+    return true;
+  }
+  if (leftArg.value === null || rightArg.value === null) {
+    return false;
+  }
+  const precisions = [leftArg.decimals, rightArg.decimals]
+    .filter((decimalsArg) => decimalsArg !== null && decimalsArg !== 'INF')
+    .map(Number);
+  if (precisions.length === 0 || precisions.some((precisionArg) => !Number.isInteger(precisionArg))) {
+    return false;
+  }
+  const decimals = Math.min(...precisions);
+  return roundedTo(leftArg.value, decimals) === roundedTo(rightArg.value, decimals);
+};
+
+const childrenNamed = (elementArg: TXmlElement, namespaceArg: string, localNameArg: string): TXmlElement[] =>
+  elementArg.getElementsByTagNameNS(namespaceArg, localNameArg);
+
+const trimmedText = (elementArg: TXmlElement | undefined): string | null => {
+  const text = elementArg?.textContent?.trim();
+  return text ? text : null;
+};
+
+interface IContext {
+  period: IEsefPeriod;
+  dimensions: Record<string, string>;
+  lei: string | null;
+}
+
+const readContexts = (documentArg: TXmlDocument): Map<string, IContext> => {
+  const contexts = new Map<string, IContext>();
+  for (const context of documentArg.getElementsByTagNameNS(xbrliNamespace, 'context')) {
+    const id = context.getAttribute('id');
+    const period = childrenNamed(context, xbrliNamespace, 'period')[0];
+    if (!id || !period) {
+      continue;
+    }
+    const dateOf = (nameArg: string): TIsoDate | null => trimmedText(childrenNamed(period, xbrliNamespace, nameArg)[0])?.slice(0, 10) ?? null;
+    const instant = dateOf('instant');
+    const end = instant ?? dateOf('endDate');
+    if (!end) {
+      continue;
+    }
+    const dimensions: Record<string, string> = {};
+    for (const member of [
+      ...childrenNamed(context, xbrldiNamespace, 'explicitMember'),
+      ...childrenNamed(context, xbrldiNamespace, 'typedMember'),
+    ]) {
+      const dimension = member.getAttribute('dimension');
+      if (dimension) {
+        dimensions[dimension] = trimmedText(member) ?? '';
+      }
+    }
+    const identifier = childrenNamed(context, xbrliNamespace, 'identifier')[0];
+    contexts.set(id, {
+      period: { start: instant ? null : dateOf('startDate'), end },
+      dimensions,
+      lei: identifier?.getAttribute('scheme') === leiScheme ? trimmedText(identifier) : null,
+    });
+  }
+  return contexts;
+};
+
+/** a measure without its prefix: `iso4217:EUR` is `EUR` */
+const measureName = (elementArg: TXmlElement): string => (trimmedText(elementArg) ?? '').replace(/^[^:]*:/, '');
+
+const readUnits = (documentArg: TXmlDocument): Map<string, string> => {
+  const units = new Map<string, string>();
+  for (const unit of documentArg.getElementsByTagNameNS(xbrliNamespace, 'unit')) {
+    const id = unit.getAttribute('id');
+    if (!id) {
+      continue;
+    }
+    const numerator = childrenNamed(unit, xbrliNamespace, 'unitNumerator')[0];
+    const denominator = childrenNamed(unit, xbrliNamespace, 'unitDenominator')[0];
+    const measures = (elementArg: TXmlElement) => childrenNamed(elementArg, xbrliNamespace, 'measure').map(measureName).join('*');
+    units.set(id, numerator && denominator ? `${measures(numerator)}/${measures(denominator)}` : measures(unit));
+  }
+  return units;
+};
+
+/** counts what was left out, so that a note names each reason once */
+class Skips {
+  private counts = new Map<string, number>();
+
+  public add(reasonArg: string) {
+    this.counts.set(reasonArg, (this.counts.get(reasonArg) ?? 0) + 1);
+  }
+
+  public notes(): string[] {
+    return [...this.counts].map(([reason, count]) => `${count} ${count === 1 ? 'fact was' : 'facts were'} left out: ${reason}.`);
+  }
+}
+
+const readFacts = (documentArg: TXmlDocument, contextsArg: Map<string, IContext>, unitsArg: Map<string, string>, skipsArg: Skips): IEsefFact[] => {
+  const elements = documentArg.getElementsByTagNameNS(ixNamespace, 'nonFraction');
+  if (elements.length > maxEsefFacts) {
+    throw new FinancialStatementError('too_large', `The report tags ${elements.length} numeric facts, more than the ${maxEsefFacts} read here.`);
+  }
+  const facts: IEsefFact[] = [];
+  for (const element of elements) {
+    const name = element.getAttribute('name') ?? '';
+    const [prefix, localName] = name.includes(':') ? name.split(':', 2) : [null, name];
+    const namespace = localName ? element.lookupNamespaceURI(prefix) : null;
+    if (!namespace) {
+      skipsArg.add(`a concept name whose prefix the report does not declare`);
+      continue;
+    }
+    const contextId = element.getAttribute('contextRef') ?? '';
+    const context = contextsArg.get(contextId);
+    if (!context) {
+      skipsArg.add('a context the report does not define');
+      continue;
+    }
+    const unitRef = element.getAttribute('unitRef');
+    const unit = unitRef ? (unitsArg.get(unitRef) ?? null) : null;
+    if (unitRef && unit === null) {
+      skipsArg.add('a unit the report does not define');
+      continue;
+    }
+    let value: string | null = null;
+    if (element.getAttributeNS(xsiNamespace, 'nil') !== 'true') {
+      const text = element.textContent ?? '';
+      const format = element.getAttribute('format');
+      if (format) {
+        const [formatPrefix, formatName] = format.includes(':') ? format.split(':', 2) : [null, format];
+        const reader = formatReaders[formatName];
+        if (!(element.lookupNamespaceURI(formatPrefix) ?? '').startsWith(transformationNamespacePrefix) || !reader) {
+          skipsArg.add(`the format "${format}", which is not read here`);
+          continue;
+        }
+        value = reader(text);
+      } else {
+        value = decimalIn(text, '.');
+      }
+      const scale = Number(element.getAttribute('scale') ?? '0');
+      if (value === null || !Number.isInteger(scale) || Math.abs(scale) > 30) {
+        skipsArg.add('a value that does not read as a number in its format');
+        continue;
+      }
+      value = scaleDecimal(value, scale);
+      if (element.getAttribute('sign') === '-' && value !== '0') {
+        value = `-${value}`;
+      }
+    }
+    facts.push({
+      concept: name,
+      namespace,
+      contextId,
+      period: context.period,
+      dimensions: context.dimensions,
+      unit,
+      value,
+      decimals: element.getAttribute('decimals'),
+      id: element.getAttribute('id'),
+    });
+  }
+  return facts;
+};
+
+const keyConcepts = { totalAssets: 'Assets', equity: 'Equity', netIncome: 'ProfitLoss', revenue: 'Revenue' } as const;
+type TKeyFigure = keyof typeof keyConcepts;
+
+/**
+ * Reads an ESEF report, the XHTML of its inline XBRL, on its own: its numeric facts and the key
+ * figures of its consolidated statements. Throws `unreadable` where it is not well-formed XML and
+ * `too_large` where it tags more than `maxEsefFacts` facts.
+ */
+export const parseEsefReport = (bytesArg: Uint8Array, reportPathArg: string | null = null): IEsefStatement => {
+  const start = bytesArg[0] === 0xef && bytesArg[1] === 0xbb && bytesArg[2] === 0xbf ? 3 : 0;
+  const declared = /^<\?xml[^>]*\bencoding\s*=\s*["']([\w.-]+)["']/i.exec(
+    new TextDecoder('windows-1252').decode(bytesArg.subarray(start, start + 200))
+  )?.[1];
+  if (declared && !/^utf-?8$/i.test(declared)) {
+    throw new FinancialStatementError('unreadable', `The report declares the encoding "${declared}", which is not read here.`);
+  }
+  let document: TXmlDocument;
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytesArg.subarray(start));
+    document = plugins.smartxmlXpath.parseXmlDocument(text);
+  } catch (error) {
+    throw new FinancialStatementError('unreadable', 'The report is not well-formed XML in UTF-8.', { cause: error });
+  }
+  const skips = new Skips();
+  const contexts = readContexts(document);
+  const facts = readFacts(document, contexts, readUnits(document), skips);
+  const notes = skips.notes();
+
+  const leis = new Set([...contexts.values()].map((contextArg) => contextArg.lei).filter((leiArg) => leiArg !== null));
+  if (leis.size > 1) {
+    notes.push(`The report's contexts identify more than one issuer (${[...leis].join(', ')}).`);
+  }
+
+  const keyFacts = facts.filter(
+    (factArg) =>
+      ifrsNamespacePattern.test(factArg.namespace) &&
+      Object.keys(factArg.dimensions).length === 0 &&
+      factArg.value !== null &&
+      factArg.unit !== null &&
+      /^[A-Z]{3}$/.test(factArg.unit)
+  );
+  const conceptOf = (factArg: IEsefFact) => factArg.concept.slice(factArg.concept.indexOf(':') + 1);
+  const currencies = new Set(keyFacts.map((factArg) => factArg.unit as string));
+  let currency: string | null = currencies.size === 1 ? [...currencies][0] : null;
+  if (currencies.size > 1) {
+    notes.push(`The key figures are tagged in more than one currency (${[...currencies].join(', ')}), so none was read.`);
+  }
+
+  const durations = keyFacts.filter(
+    (factArg) => factArg.period.start !== null && (conceptOf(factArg) === 'ProfitLoss' || conceptOf(factArg) === 'Revenue')
+  );
+  const instants = keyFacts.filter((factArg) => factArg.period.start === null && conceptOf(factArg) === 'Assets');
+  const basis = durations.length > 0 ? durations : instants;
+  const ends = [...new Set(basis.map((factArg) => factArg.period.end))].sort().reverse();
+  const periodEndingOn = (endArg: TIsoDate | undefined): IEsefPeriod | null => {
+    if (!endArg) {
+      return null;
+    }
+    const starts = basis
+      .filter((factArg) => factArg.period.end === endArg && factArg.period.start !== null)
+      .map((factArg) => factArg.period.start as TIsoDate)
+      .sort();
+    return { start: starts[0] ?? null, end: endArg };
+  };
+  const current = currency ? periodEndingOn(ends[0]) : null;
+  const prior = currency ? periodEndingOn(ends[1]) : null;
+  if (currency && !current) {
+    notes.push('The report tags no key figures of its consolidated statements (IFRS) without dimensions.');
+    currency = null;
+  }
+
+  const keyFiguresOf = (periodArg: IEsefPeriod): IKeyFigures => {
+    const figure = (keyArg: TKeyFigure): string | null => {
+      const instant = keyArg === 'totalAssets' || keyArg === 'equity';
+      const matching = keyFacts.filter(
+        (factArg) =>
+          conceptOf(factArg) === keyConcepts[keyArg] &&
+          factArg.period.end === periodArg.end &&
+          (instant ? factArg.period.start === null : factArg.period.start !== null && factArg.period.start === periodArg.start)
+      );
+      if (matching.length === 0) {
+        return null;
+      }
+      if (!matching.every((factArg) => factsAgree(factArg, matching[0]))) {
+        notes.push(`The report tags ifrs-full:${keyConcepts[keyArg]} for ${periodArg.end} with values that differ, so it was left out.`);
+        return null;
+      }
+      const precision = (factArg: IEsefFact) =>
+        factArg.decimals === 'INF' ? Number.POSITIVE_INFINITY : Number(factArg.decimals ?? Number.NEGATIVE_INFINITY);
+      return [...matching].sort((leftArg, rightArg) => precision(rightArg) - precision(leftArg))[0].value;
+    };
+    return {
+      totalAssets: figure('totalAssets'),
+      equity: figure('equity'),
+      netIncome: figure('netIncome'),
+      revenue: figure('revenue'),
+    };
+  };
+  const statementPeriod = (periodArg: IEsefPeriod | null): IStatementPeriod => ({
+    heading: null,
+    start: periodArg?.start ?? null,
+    end: periodArg?.end ?? null,
+  });
+
+  const root = document.documentElement;
+  return {
+    standard: 'esef',
+    lei: leis.size === 1 ? [...leis][0] : null,
+    reportPath: reportPathArg,
+    language: root?.getAttributeNS(xmlNamespace, 'lang') ?? root?.getAttribute('lang') ?? null,
+    currency,
+    periods: { current: statementPeriod(current), prior: prior ? statementPeriod(prior) : null },
+    keyFigures: {
+      current: current ? keyFiguresOf(current) : { totalAssets: null, equity: null, netIncome: null, revenue: null },
+      prior: prior ? keyFiguresOf(prior) : null,
+    },
+    facts,
+    notes,
+  };
+};
+
+const tooLargeZipCodes = new Set<string>([
+  plugins.smartarchiveZip.ZIP_ERROR_CODES.ARCHIVE_SIZE_LIMIT,
+  plugins.smartarchiveZip.ZIP_ERROR_CODES.ENTRY_COUNT_LIMIT,
+  plugins.smartarchiveZip.ZIP_ERROR_CODES.COMPRESSED_SIZE_LIMIT,
+  plugins.smartarchiveZip.ZIP_ERROR_CODES.UNCOMPRESSED_SIZE_LIMIT,
+  plugins.smartarchiveZip.ZIP_ERROR_CODES.TOTAL_UNCOMPRESSED_SIZE_LIMIT,
+]);
+
+/**
+ * Reads an ESEF report package (`.zip` or `.xbri`): the one report under `reports/`, by
+ * `parseEsefReport`. Throws `invalid_package` where the package is not a readable ZIP, is encrypted
+ * or does not hold exactly one report, and `too_large` where it or its report exceeds the limits.
+ */
+export const parseEsefPackage = async (zipBytesArg: Uint8Array): Promise<IEsefStatement> => {
+  let entries: Array<{ path: string; content: Uint8Array }>;
+  try {
+    entries = await new plugins.smartarchiveZip.ZipTools().extractSelectedZipEntries(zipBytesArg, {
+      filter: (entryArg) => entryArg.isFile && reportPathPattern.test(entryArg.path),
+      maxArchiveBytes: maxStatementBytes,
+      maxEntries: maxEsefPackageEntries,
+      maxSelectedEntries: 1,
+      maxCompressedEntryBytes: maxStatementBytes,
+      maxUncompressedEntryBytes: maxStatementBytes,
+      maxTotalUncompressedBytes: maxStatementBytes,
+    });
+  } catch (error) {
+    if (!(error instanceof plugins.smartarchiveZip.ZipError) || error.code === plugins.smartarchiveZip.ZIP_ERROR_CODES.INVALID_LIMIT) {
+      throw error;
+    }
+    if (tooLargeZipCodes.has(error.code)) {
+      throw new FinancialStatementError('too_large', `The package exceeds the limits read here: ${error.message}`, { cause: error });
+    }
+    const reason =
+      error.code === plugins.smartarchiveZip.ZIP_ERROR_CODES.SELECTED_ENTRY_COUNT_LIMIT
+        ? 'holds more than one report under reports/'
+        : error.code === plugins.smartarchiveZip.ZIP_ERROR_CODES.ENCRYPTED
+          ? 'is encrypted'
+          : `is not a readable ZIP (${error.message})`;
+    throw new FinancialStatementError('invalid_package', `The package ${reason}.`, { cause: error });
+  }
+  if (entries.length === 0) {
+    throw new FinancialStatementError('invalid_package', 'The package holds no report under reports/.');
+  }
+  return parseEsefReport(entries[0].content, entries[0].path);
+};