feat(invariants): shared format contracts + upgrade-path CI (#1364)

* feat(invariants): centralise shared format contracts, reconcile the org-number paths The same format rules were written out independently across the codebase, and where they disagreed the disagreement was invisible until a filing failed. Worst case, now fixed: four Skatteverket- and Bolagsverket-bound export paths each had their own idea of a valid organisationsnummer. lib/skatteverket/format.ts strip '-' only threw on any input with a space lib/salary/ku/ku10-generator.ts replace('-', '') first hyphen only, spaces survived lib/salary/agi/xml-generator.ts strip non-digits stray letters passed the length check lib/bokslut/ixbrl/validate /^\d{6}-?\d{4}$/ rejected the 12-digit form, no Luhn A company stored with a space or in 12-digit form could file AGI all year and then fail at the arsredovisning deadline with a message that did not say why. lib/invariants/ now owns account number, ISO date, four-digit fiscal year and org number, each with the rationale recorded next to the rule. normalizeOrgNumber moves here from lib/company-lookup/ and isSaneDateString from lib/utils.ts; both old paths re-export, so no caller changes. lib/api/schemas.ts builds its primitives on the module, so ~100 schemas inherit any correction. The arsredovisning check-digit verdict is a warn, not an error: a wrong Luhn digit is almost certainly a typo worth surfacing, but whether every org number Bolagsverket accepts satisfies Luhn is a Swedish domain question we have not verified against a primary source, and an error there blocks Skicka in. We do not block a statutory filing on an unverified assumption. KU10 still passes a 12-digit stored org number through unfolded. That is pre-existing, and whether the KU10 schema wants 10 or 12 digits is not covered by the swedish-payroll skill, so it is pinned by a test rather than changed silently. Guard 8 (hand-rolled-invariant) tracks the remaining 114 inline copies as a ratchet that may only go down, same mechanism as the roundOre guard. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(ci): add an upgrade-path job that applies new migrations against real data The pg-real job applies all 548 migrations to an EMPTY database. Empty means zero rows, so a migration that adds a NOT NULL, adds a CHECK, creates a unique index or backfills passes trivially in CI and can still fail on production, where the rows exist. CI proved that a fresh install works; nothing proved that an existing install upgrades. The new pg-upgrade job: apply the schema as it stands at the merge base, seed a small real company (three posted verifikat, balanced lines, one ore-level amount), then apply ONLY the migrations this PR adds, then assert the data survived (entries still posted, lines intact, ledger still balances, ore unchanged, voucher numbers sequential). A PR with no migration no-ops. Verified locally against supabase/postgres:15.8.1.060 rather than assumed, with three deliberately bad migrations: rescale money on posted lines empty: would pass seeded: ERROR (immutability trigger) CHECK violating the ore row empty: exit 0 seeded: exit 3 NOT NULL on a populated column empty: exit 0 seeded: exit 3 Base migrations are read out of the merge-base git tree, not the working tree, so a PR that edits an already-shipped migration still gets the original applied and the edit surfaces as a failure here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: record the invariants and upgrade-CI decisions Two entries covering what this PR changes and, more importantly, the calls that are not obvious from the diff: why the arsredovisning check-digit verdict is a warning rather than an error, why KU10's 12-digit passthrough is pinned instead of fixed, and why the ROT/RUT brf org-number schemas stay on their own rule. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(test): mark the upgrade fixture as CI-only, never a production template The fixture writes posted journal_entries and their lines directly, bypassing the engine and the atomic commit RPC. That is the only way to hand a migration pre-existing posted rows to break, and it is safe against a throwaway CI database, but it reads like a sanctioned pattern to anyone who finds it later. Says so explicitly, with the reason it is confined here (no voucher sequence to keep gapless, no retention obligation on a database destroyed with the job) and a pointer back to Hard Rule 2 for anything touching a real database. Raised by the Swedish compliance review bot on #1364. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-03 16:30:14 +02:00
parent ef237351b6
commit 16fbcefbbc
24 changed files with 1291 additions and 81 deletions
@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest'
+import { isAccountNumber, accountClass, ACCOUNT_NUMBER_RE } from '@/lib/invariants/account-number'
+import { isIsoDateShaped, isSaneDateString, ISO_DATE_RE } from '@/lib/invariants/iso-date'
+import { isFiscalYear, FISCAL_YEAR_RE } from '@/lib/invariants/fiscal-year'
+import { isSaneDateString as isSaneDateStringFromUtils } from '@/lib/utils'
+
+describe('account number', () => {
+  it('accepts exactly four digits, as a string', () => {
+    expect(isAccountNumber('1930')).toBe(true)
+    expect(isAccountNumber('0000')).toBe(true)
+  })
+
+  it('rejects anything else', () => {
+    expect(isAccountNumber('193')).toBe(false)
+    expect(isAccountNumber('19300')).toBe(false)
+    expect(isAccountNumber('19a0')).toBe(false)
+    expect(isAccountNumber(' 1930')).toBe(false)
+    expect(isAccountNumber('')).toBe(false)
+    expect(isAccountNumber(null)).toBe(false)
+    expect(isAccountNumber(undefined)).toBe(false)
+  })
+
+  it('reads the BAS account class off the leading digit', () => {
+    expect(accountClass('1930')).toBe(1)
+    expect(accountClass('2440')).toBe(2)
+    expect(accountClass('3001')).toBe(3)
+    expect(accountClass('8910')).toBe(8)
+    expect(accountClass('nope')).toBeNull()
+  })
+})
+
+describe('iso date', () => {
+  it('shape check accepts the right shape, including impossible dates', () => {
+    expect(isIsoDateShaped('2026-01-31')).toBe(true)
+    // Shape only: this is the documented difference from isSaneDateString.
+    expect(isIsoDateShaped('2026-02-31')).toBe(true)
+    expect(isIsoDateShaped('2026-1-31')).toBe(false)
+    expect(isIsoDateShaped('31/01/2026')).toBe(false)
+    expect(isIsoDateShaped(null)).toBe(false)
+  })
+
+  it('sane check rejects impossible and out-of-range dates', () => {
+    expect(isSaneDateString('2026-01-31')).toBe(true)
+    expect(isSaneDateString('2026-02-31')).toBe(false)
+    expect(isSaneDateString('2024-13-40')).toBe(false)
+    // The native <input type="date"> 6-digit-year corruption.
+    expect(isSaneDateString('202403-02-05')).toBe(false)
+    expect(isSaneDateString('1899-12-31')).toBe(false)
+    expect(isSaneDateString('2101-01-01')).toBe(false)
+  })
+
+  it('is the same function utils re-exports, not a second copy', () => {
+    expect(isSaneDateStringFromUtils).toBe(isSaneDateString)
+  })
+})
+
+describe('fiscal year', () => {
+  it('accepts a four-digit year in range', () => {
+    expect(isFiscalYear('2026')).toBe(true)
+    expect(isFiscalYear(2026)).toBe(true)
+    expect(isFiscalYear('1900')).toBe(true)
+  })
+
+  it('rejects out-of-range and wrong shapes', () => {
+    expect(isFiscalYear('1899')).toBe(false)
+    expect(isFiscalYear('2201')).toBe(false)
+    expect(isFiscalYear('26')).toBe(false)
+    expect(isFiscalYear('')).toBe(false)
+    expect(isFiscalYear(null)).toBe(false)
+  })
+})
+
+describe('the deliberate regex collision', () => {
+  /**
+   * `account-number` and `fiscal-year` share a byte-identical regex and mean
+   * entirely different things. This test exists so that anyone tempted to
+   * "deduplicate" them has to read why they are separate first.
+   */
+  it('account number and fiscal year share a pattern but not a rule', () => {
+    expect(ACCOUNT_NUMBER_RE.source).toBe(FISCAL_YEAR_RE.source)
+
+    // '1930' is a real bank account and an absurd fiscal year in our range,
+    // '2026' is a real fiscal year and a valid BAS account number. Only the
+    // named rules can tell a caller which one it is holding.
+    expect(isAccountNumber('1930')).toBe(true)
+    expect(isFiscalYear('1930')).toBe(true)
+    expect(isFiscalYear('0000')).toBe(false)
+    expect(isAccountNumber('0000')).toBe(true)
+  })
+
+  it('the iso-date pattern is not the four-digit pattern', () => {
+    expect(ISO_DATE_RE.source).not.toBe(ACCOUNT_NUMBER_RE.source)
+  })
+})
@@ -0,0 +1,194 @@
+import { describe, it, expect } from 'vitest'
+import { formatRedovisare } from '@/lib/skatteverket/format'
+import { generateKU10Xml } from '@/lib/salary/ku/ku10-generator'
+import { generateAGIXml } from '@/lib/salary/agi/xml-generator'
+import { runPreflightChecks } from '@/lib/bokslut/ixbrl/validate/rules'
+import type { IxbrlArsredovisningInput } from '@/lib/bokslut/ixbrl/types'
+
+/**
+ * The four Skatteverket- and Bolagsverket-bound export paths must agree about
+ * what a valid org number is.
+ *
+ * Before `lib/invariants/org-number.ts` they did not: the SRU converter stripped
+ * hyphens only and threw on a space, KU10 stripped the first hyphen only, AGI
+ * stripped every non-digit (so stray letters passed), and the årsredovisning
+ * validator rejected the 12-digit form and skipped the check digit. A company
+ * stored in one of the awkward forms could file AGI for a year and then fail at
+ * the årsredovisning deadline with a message that did not say why.
+ *
+ * This test is the guard on that agreement. If a future change makes one path
+ * accept an input the others reject, it fails here rather than at a customer's
+ * deadline.
+ */
+
+const AB_10 = '5560125790'
+
+/** The input forms a Swedish user or a provider API actually produces. */
+const EQUIVALENT_FORMS = ['5560125790', '556012-5790', '556012 5790', '165560125790']
+
+/** The subset that is already 10 digits, ignoring separators. */
+const TEN_DIGIT_FORMS = ['5560125790', '556012-5790', '556012 5790']
+
+function ku10CompanyFixture(orgNumber: string) {
+  return {
+    orgNumber,
+    companyName: 'Testbolaget AB',
+    year: 2025,
+    contactName: 'Test Testsson',
+    contactPhone: '0700000000',
+    contactEmail: 'test@example.com',
+  }
+}
+
+function agiCompanyFixture(orgNumber: string) {
+  return {
+    orgNumber,
+    companyName: 'Testbolaget AB',
+    periodYear: 2025,
+    periodMonth: 3,
+    contactName: 'Test Testsson',
+    contactPhone: '0700000000',
+    contactEmail: 'test@example.com',
+  }
+}
+
+function ixbrlInputFixture(orgNumber: string): IxbrlArsredovisningInput {
+  // Only the org-number rule (code 1035) is asserted below. The remaining
+  // fields exist so the other preflight rules can run without throwing; their
+  // verdicts are filtered out.
+  return {
+    company: { name: 'Testbolaget AB', orgNumber },
+    period: { start: '2025-01-01', end: '2025-12-31' },
+    isFirstFiscalYear: false,
+    forvaltningsberattelse: {
+      allmantOmVerksamheten: 'Bolaget bedriver konsultverksamhet.',
+      resultatdisposition: { balanseratResultat: 0, aretsResultat: 0, summa: 0 },
+    },
+    faststallelseintyg: {
+      arsstammaDatum: '2026-05-15',
+      genereratDatum: '2026-05-20',
+      resultatdispositionDecision: 'enligt_forslag',
+      resultatdispositionOutcome: 'balanseras_i_ny_rakning',
+      signerFirstName: 'Test',
+      signerLastName: 'Testsson',
+    },
+    underskrifter: {
+      dateringsdatum: '2026-05-10',
+      signers: [{ firstName: 'Test', lastName: 'Testsson', role: 'Styrelseledamot' }],
+    },
+    totals: {
+      aretsResultat: { current: 0, previous: 0 },
+      egetKapitalSkulder: { current: 0, previous: 0 },
+      tillgangar: { current: 0, previous: 0 },
+    },
+    rr: [],
+    br: [],
+    warnings: [],
+  } as unknown as IxbrlArsredovisningInput
+}
+
+/** Does the årsredovisning preflight raise the org-number issue (code 1035)? */
+function ixbrlRejects(orgNumber: string): boolean {
+  const result = runPreflightChecks(ixbrlInputFixture(orgNumber))
+  return result.issues.some((i) => i.code === '1035')
+}
+
+/** Does the SRU redovisare conversion throw? */
+function redovisareRejects(orgNumber: string): boolean {
+  try {
+    formatRedovisare(orgNumber, 'aktiebolag')
+    return false
+  } catch {
+    return true
+  }
+}
+
+/** Does the AGI generator refuse to build for this org number? */
+function agiRejects(orgNumber: string): boolean {
+  try {
+    generateAGIXml(
+      agiCompanyFixture(orgNumber),
+      [],
+      { totalTax: 0, totalAvgifterBasis: 0, totalAvgifterAmount: 0, totalSjuklonekostnad: 0 } as never,
+    )
+    return false
+  } catch {
+    return true
+  }
+}
+
+describe('org number: the four export paths agree', () => {
+  it.each(EQUIVALENT_FORMS)('accepts %s everywhere', (form) => {
+    expect(redovisareRejects(form), 'SRU redovisare conversion').toBe(false)
+    expect(ixbrlRejects(form), 'årsredovisning preflight').toBe(false)
+    expect(agiRejects(form), 'AGI generator').toBe(false)
+    expect(() => generateKU10Xml(ku10CompanyFixture(form), []), 'KU10 generator').not.toThrow()
+  })
+
+  it('produces the same redovisare identity from every equivalent form', () => {
+    const identities = EQUIVALENT_FORMS.map((f) => formatRedovisare(f, 'aktiebolag'))
+    expect(new Set(identities).size, `got ${JSON.stringify(identities)}`).toBe(1)
+    expect(identities[0]).toBe('165560125790')
+  })
+
+  it('emits a separator-free identity into the KU10 file', () => {
+    for (const form of TEN_DIGIT_FORMS) {
+      const xml = generateKU10Xml(ku10CompanyFixture(form), [])
+      const match = xml.match(/<Organisationsnummer>([^<]*)<\/Organisationsnummer>/)
+      // Guard against a vacuous assertion: the element must actually be there.
+      expect(match, `input form ${form}: no <Organisationsnummer> in output`).not.toBeNull()
+      expect(match?.[1], `input form ${form}`).toBe(AB_10)
+    }
+  })
+
+  /**
+   * OPEN QUESTION, deliberately pinned rather than changed.
+   *
+   * KU10 strips separators but does not fold the 12-digit form down to the
+   * canonical 10 digits, so a company stored as `165560125790` files with 12
+   * digits. Whether Skatteverket's KU10 schema wants 10 or 12 here is a Swedish
+   * domain question that the `swedish-payroll` skill does not cover, and
+   * CLAUDE.md forbids answering it from training data.
+   *
+   * This is pre-existing behaviour (the old `replace('-', '')` did the same);
+   * this test pins it so the answer, when we get it, is a deliberate change with
+   * a failing test to update rather than a silent drift.
+   */
+  it('PINNED: KU10 passes a 12-digit stored org number through unfolded', () => {
+    const xml = generateKU10Xml(ku10CompanyFixture('165560125790'), [])
+    const match = xml.match(/<Organisationsnummer>([^<]*)<\/Organisationsnummer>/)
+    expect(match?.[1]).toBe('165560125790')
+  })
+
+  it.each([
+    ['5560125790x', 'stray characters'],
+    ['55601', 'too short'],
+  ])('rejects %s (%s) on every path that validates', (bad) => {
+    expect(redovisareRejects(bad), 'SRU redovisare conversion').toBe(true)
+    expect(ixbrlRejects(bad), 'årsredovisning preflight').toBe(true)
+    expect(agiRejects(bad), 'AGI generator').toBe(true)
+  })
+
+  it('surfaces a bad check digit without blocking the filing', () => {
+    const badCheckDigit = '5560125791'
+    const result = runPreflightChecks(ixbrlInputFixture(badCheckDigit))
+    const orgIssues = result.issues.filter((i) => i.code === '1035')
+
+    expect(orgIssues).toHaveLength(1)
+    // Warn, not error: a wrong check digit is surfaced to the user, but we do
+    // not block Skicka in on a domain assumption we have not verified against a
+    // primary source. See the rationale in validate/rules.ts.
+    expect(orgIssues[0].severity).toBe('warn')
+    // The org-number verdict must not be among the errors that block Skicka in.
+    // (`result.ok` is not asserted here: this fixture is minimal and trips other
+    // unrelated rules. The org-number rule's own severity is the contract.)
+    expect(result.errors.some((i) => i.code === '1035')).toBe(false)
+
+    // Export-time conversion stays permissive by design: see org-number.ts.
+    expect(redovisareRejects(badCheckDigit), 'SRU redovisare conversion').toBe(false)
+  })
+
+  it('the canonical form is what the display helper round-trips to', () => {
+    expect(formatRedovisare(AB_10, 'aktiebolag')).toBe('165560125790')
+  })
+})
@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest'
+import {
+  normalizeOrgNumber,
+  isValidOrgNumber,
+  isOrgNumberShaped,
+  hasInvalidOrgNumberCheckDigit,
+  stripOrgNumberFormatting,
+  formatOrgNumberDisplay,
+  toRedovisare12,
+} from '@/lib/invariants/org-number'
+
+// Real-shaped numbers with correct Luhn check digits.
+const AB_10 = '5560125790'
+const EF_10 = '8001011231'
+
+describe('stripOrgNumberFormatting', () => {
+  it('removes hyphens and spaces, nothing else', () => {
+    expect(stripOrgNumberFormatting('556012-5790')).toBe(AB_10)
+    expect(stripOrgNumberFormatting('556012 5790')).toBe(AB_10)
+    expect(stripOrgNumberFormatting(' 556012 - 5790 ')).toBe(AB_10)
+    // Letters are preserved so the caller's shape check can reject them,
+    // instead of a digit-strip silently making garbage look valid.
+    expect(stripOrgNumberFormatting('5560125790x')).toBe('5560125790x')
+  })
+})
+
+describe('normalizeOrgNumber', () => {
+  it('accepts the forms users actually type', () => {
+    expect(normalizeOrgNumber(AB_10)).toBe(AB_10)
+    expect(normalizeOrgNumber('556012-5790')).toBe(AB_10)
+    expect(normalizeOrgNumber('556012 5790')).toBe(AB_10)
+  })
+
+  it('strips the century prefix from the 12-digit form', () => {
+    expect(normalizeOrgNumber('165560125790')).toBe(AB_10)
+    expect(normalizeOrgNumber('198001011231')).toBe(EF_10)
+    expect(normalizeOrgNumber('19800101-1231')).toBe(EF_10)
+  })
+
+  it('rejects wrong length, non-digits and a bad check digit', () => {
+    expect(normalizeOrgNumber('55601257')).toBeNull()
+    expect(normalizeOrgNumber('5560125790x')).toBeNull()
+    expect(normalizeOrgNumber('5560125791')).toBeNull() // check digit off by one
+    expect(normalizeOrgNumber('')).toBeNull()
+    expect(normalizeOrgNumber(null)).toBeNull()
+    expect(normalizeOrgNumber(undefined)).toBeNull()
+  })
+})
+
+describe('shape versus check digit', () => {
+  it('separates "wrong format" from "wrong last digit"', () => {
+    expect(isOrgNumberShaped('5560125791')).toBe(true)
+    expect(isValidOrgNumber('5560125791')).toBe(false)
+    expect(hasInvalidOrgNumberCheckDigit('5560125791')).toBe(true)
+
+    // Wrong shape is not a check-digit problem.
+    expect(hasInvalidOrgNumberCheckDigit('55601')).toBe(false)
+    // A valid number is neither.
+    expect(hasInvalidOrgNumberCheckDigit(AB_10)).toBe(false)
+  })
+})
+
+describe('formatOrgNumberDisplay', () => {
+  it('renders NNNNNN-NNNN from any accepted input form', () => {
+    expect(formatOrgNumberDisplay(AB_10)).toBe('556012-5790')
+    expect(formatOrgNumberDisplay('556012 5790')).toBe('556012-5790')
+    expect(formatOrgNumberDisplay('165560125790')).toBe('556012-5790')
+  })
+
+  it('passes through anything that is not org-number shaped', () => {
+    expect(formatOrgNumberDisplay('nonsense')).toBe('nonsense')
+    expect(formatOrgNumberDisplay('')).toBe('')
+  })
+})
+
+describe('toRedovisare12', () => {
+  it('prefixes 16 for aktiebolag', () => {
+    expect(toRedovisare12(AB_10, 'aktiebolag')).toBe('165560125790')
+    expect(toRedovisare12('556012-5790', 'aktiebolag')).toBe('165560125790')
+  })
+
+  it('prefixes the century for enskild firma', () => {
+    // 80 is above the current two-digit year, so it belongs to the 1900s.
+    expect(toRedovisare12(EF_10, 'enskild_firma')).toBe('198001011231')
+  })
+
+  it('passes an already 12-digit value through untouched', () => {
+    expect(toRedovisare12('165560125790', 'aktiebolag')).toBe('165560125790')
+  })
+
+  it('accepts spaces, which the previous hyphen-only strip did not', () => {
+    expect(toRedovisare12('556012 5790', 'aktiebolag')).toBe('165560125790')
+  })
+
+  it('throws on a length it cannot interpret', () => {
+    expect(() => toRedovisare12('55601', 'aktiebolag')).toThrow(/Ogiltigt organisationsnummer/)
+  })
+
+  it('stays permissive about the check digit', () => {
+    // Export-time conversion must not start rejecting numbers that are already
+    // stored and filing: a failed export at a deadline is worse than letting
+    // Skatteverket reject it with its own message. See the module docblock.
+    expect(toRedovisare12('5560125791', 'aktiebolag')).toBe('165560125791')
+  })
+})