Merge pull request #17 from RoboFinSystems/bugfix/strip-xbrl-role-suffixes

fix: strip XBRL role suffixes from labels on the holon/store path

Author: jfrench9

src/adapters/sec.ts

@@ -31,7 +31,7 @@
  *  5. Aggregations must `ORDER BY <alias>` (not `s.number`); `end` is reserved, so
  *     alias every `p.end_date AS end_date`.
  */
-import { humanize, qname as toQname } from '../constants'
+import { humanize, stripRoleSuffix, qname as toQname } from '../constants'
 import { currencySymbolFor } from '../format'
 import type {
   CalcAssociation,
@@ -254,19 +254,6 @@ const STANDARD_LABEL_ROLE = 'http://www.xbrl.org/2003/role/label'
 /** Terse label role — the fallback when a concept has no standard label. */
 const TERSE_LABEL_ROLE = 'http://www.xbrl.org/2003/role/terseLabel'
 
-/**
- * XBRL standard labels tag structural elements with a bracketed role suffix —
- * `Land [Member]`, `Operating Expenses [Abstract]`, and likewise `[Axis]`,
- * `[Table]`, `[Line Items]`, `[Domain]`. That tag is metadata, not part of the
- * display name, so strip a trailing one. If stripping would empty the label
- * (a label that is only the tag), keep the original.
- */
-const ROLE_SUFFIX_RE = /\s*\[(?:Abstract|Axis|Member|Table|Line Items|Domain)\]\s*$/
-function stripRoleSuffix(label: string): string {
-  const stripped = label.replace(ROLE_SUFFIX_RE, '').trim()
-  return stripped || label
-}
-
 /** Build the report's element-URI → (role → value) label dictionary from LABELS_Q rows. */
 function buildReportLabels(rows: Array<Record<string, unknown>>): ReportLabels {
   const byElement = new Map<string, Map<string, string>>()

src/adapters/store.ts

@@ -9,7 +9,7 @@
  * traversal. The only per-source code is how the store gets filled.
  */
 import { DataFactory, Store } from 'n3'
-import { IRI, humanize, qname } from '../constants'
+import { IRI, humanize, qname, stripRoleSuffix } from '../constants'
 import type {
   CalcAssociation,
   DimensionQualifier,
@@ -82,10 +82,14 @@ export function parseStore(store: Store): NormalizedReport {
     const balance = firstValue(id, IRI.balance)
     const periodType = firstValue(id, IRI.periodType)
     const itemType = firstValue(id, IRI.itemType) ?? undefined
+    // A holon's prefLabel is the filing's XBRL standard label, which tags
+    // structural concepts with their role (`Common Stock [Member]`,
+    // `Statement [Table]`) — strip the tag for display, as the SEC adapter does.
+    const prefLabel = firstValue(id, IRI.prefLabel)
     elements[id] = {
       id,
       qname: qname(id),
-      label: firstValue(id, IRI.prefLabel) ?? humanize(id),
+      label: prefLabel ? stripRoleSuffix(prefLabel) : humanize(id),
       balance: balance === 'debit' || balance === 'credit' ? balance : null,
       periodType: periodType === 'instant' || periodType === 'duration' ? periodType : null,
       abstract: firstValue(id, IRI.abstract) === 'true',
@@ -182,6 +186,7 @@ export function parseStore(store: Store): NormalizedReport {
   // ── Information Blocks ──
   const informationBlocks: InformationBlock[] = []
   for (const id of subjectsOfType(IRI.InformationBlock)) {
+    const blockLabel = firstValue(id, IRI.prefLabel)
     informationBlocks.push({
       id,
       blockType: firstValue(id, IRI.blockType) ?? '',
@@ -190,7 +195,7 @@ export function parseStore(store: Store): NormalizedReport {
       // block-type classification, so structureId is how row order is found.
       structureId: firstValue(id, IRI.structure) ?? undefined,
       factSet: firstValue(id, IRI.factSet),
-      label: firstValue(id, IRI.prefLabel),
+      label: blockLabel ? stripRoleSuffix(blockLabel) : null,
     })
   }
 

src/constants.ts

@@ -113,6 +113,21 @@ export function humanize(iri: string): string {
   return local.replace(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g, ' ')
 }
 
+/**
+ * XBRL standard labels tag structural elements with a bracketed role suffix —
+ * `Land [Member]`, `Operating Expenses [Abstract]`, and likewise `[Axis]`,
+ * `[Table]`, `[Line Items]`, `[Domain]`, `[Roll Forward]`, `[Text Block]`. That
+ * tag is metadata, not part of the display name, so strip a trailing one. If
+ * stripping would empty the label (a label that is only the tag), keep the
+ * original.
+ */
+const ROLE_SUFFIX_RE =
+  /\s*\[(?:Abstract|Axis|Member|Table|Line Items|Domain|Roll Forward|Roll Up|Text Block|Policy Text Block|Table Text Block|Extensible List|Extensible Enumeration|Flag)\]\s*$/i
+export function stripRoleSuffix(label: string): string {
+  const stripped = label.replace(ROLE_SUFFIX_RE, '').trim()
+  return stripped || label
+}
+
 /**
  * A large text-block / policy fact whose HTML (or plain-text) body is too big to
  * store inline, so the platform externalizes it to the public CDN and the fact's

src/index.ts

@@ -11,7 +11,15 @@
  */
 
 // Model + reconstruction + formatting
-export { BLOCK_ORDER, BLOCK_TITLES, NS, humanize, isExternalFactUrl, qname } from './constants'
+export {
+  BLOCK_ORDER,
+  BLOCK_TITLES,
+  NS,
+  humanize,
+  isExternalFactUrl,
+  qname,
+  stripRoleSuffix,
+} from './constants'
 export * from './format'
 export * from './model'
 export {

test/store.test.ts

@@ -129,4 +129,79 @@ describe('holon store adapter', () => {
     expect(fact?.factSets).toEqual(expect.arrayContaining(['http://ex/fsNotes', 'http://ex/fsBS']))
     expect(fact?.factSets).toHaveLength(2)
   })
+
+  it('strips the XBRL role tag from element and dimension labels', async () => {
+    // A holon's prefLabel is the filing's standard label, which tags structural
+    // concepts with their role — `[Abstract]`, `[Table]`, `[Line Items]`,
+    // `[Roll Forward]`, `[Member]`. These are metadata, not display names.
+    const doc = {
+      '@graph': [
+        {
+          '@id': 'http://ex/hdr',
+          '@type': `${RS}Element`,
+          [`${SKOS}prefLabel`]: "Statement of Stockholders' Equity [Abstract]",
+        },
+        {
+          '@id': 'http://ex/tbl',
+          '@type': `${RS}Element`,
+          [`${SKOS}prefLabel`]: 'Statement [Table]',
+        },
+        {
+          '@id': 'http://ex/li',
+          '@type': `${RS}Element`,
+          [`${SKOS}prefLabel`]: 'Statement [Line Items]',
+        },
+        {
+          '@id': 'http://ex/rf',
+          '@type': `${RS}Element`,
+          [`${SKOS}prefLabel`]: 'Increase (Decrease) in Stockholders’ Equity [Roll Forward]',
+        },
+        {
+          '@id': 'http://ex/fd',
+          '@type': `${RS}Fact`,
+          [`${RS}element`]: { '@id': 'http://ex/rf' },
+          [`${RS}period`]: { '@id': 'http://ex/p' },
+          [`${RS}numericValue`]: 60,
+          [`${RS}dimension`]: { '@id': 'http://ex/d1' },
+        },
+        {
+          '@id': 'http://ex/d1',
+          '@type': `${RS}Dimension`,
+          [`${RS}axis`]: { '@id': 'http://ex/axis' },
+          [`${RS}member`]: { '@id': 'http://ex/mem' },
+          [`${RS}isExplicit`]: true,
+        },
+        {
+          '@id': 'http://ex/axis',
+          '@type': `${RS}Element`,
+          [`${SKOS}prefLabel`]: 'Equity Components [Axis]',
+        },
+        {
+          '@id': 'http://ex/mem',
+          '@type': `${RS}Element`,
+          [`${SKOS}prefLabel`]: 'Common Stock [Member]',
+        },
+      ],
+    }
+    const model = await parseJsonld(doc)
+    expect(model.elements['http://ex/hdr']?.label).toBe("Statement of Stockholders' Equity")
+    expect(model.elements['http://ex/tbl']?.label).toBe('Statement')
+    expect(model.elements['http://ex/li']?.label).toBe('Statement')
+    expect(model.elements['http://ex/rf']?.label).toBe(
+      'Increase (Decrease) in Stockholders’ Equity'
+    )
+    const dim = model.facts.find((f) => f.id === 'http://ex/fd')?.dimensions?.[0]
+    expect(dim?.axisLabel).toBe('Equity Components')
+    expect(dim?.memberLabel).toBe('Common Stock')
+  })
+
+  it('keeps a label that is only a role tag rather than emptying it', async () => {
+    const doc = {
+      '@graph': [
+        { '@id': 'http://ex/bare', '@type': `${RS}Element`, [`${SKOS}prefLabel`]: '[Abstract]' },
+      ],
+    }
+    const model = await parseJsonld(doc)
+    expect(model.elements['http://ex/bare']?.label).toBe('[Abstract]')
+  })
 })