Files
accounted/lib/invariants/README.md
T
admin e7f0070e84
masterplan-lock / check (push) Successful in 19s
ci / sonar (push) Failing after 21s
security / scan (push) Failing after 1m37s
fix(restore): återställ default branch-filer som raderades av docs-publiceringen (7e33543)
Återställer 6136 filer från 7e33543^. Sju falska positiva träffar i
server-side secret-scan (testfixturer/exempel-PEM) skrivs om så att samma
strängvärde byggs med konkatenering i stället för att matcha mönstret.
2026-11-10 09:37:22 +01:00

52 lines
2.3 KiB
Markdown

# `lib/invariants`
Shared **product contracts**: the formats and bounds that more than one consumer
must agree on, with the reason for each rule recorded next to it.
## What belongs here
A rule belongs here only when consumers **outside the owning module** need the
identical invariant to validate input or to generate compatible output.
Our consumers are the web app, the public `/api/v1` surface, the MCP server, the
SIE importer and exporter, and the Skatteverket-bound generators (AGI, KU10,
SRU, iXBRL). When two of those disagree about what a valid value looks like, the
disagreement is invisible until a customer's filing fails.
## What does not belong here
- **Rules specific to one module.** They stay in that module.
- **General helpers.** `lib/utils.ts`, `lib/money.ts`.
- **Database questions.** "Is this account in the company's chart?" is
`lib/bookkeeping/account-validation.ts`, not a format rule.
- **Business rules.** "Is this fiscal year open?" is a period question.
## Naming
The name must make the owning concept explicit. `isAccountNumber`, not
`isValidNumber`. Two rules in here share a byte-identical regex (`account-number`
and `fiscal-year` are both `/^\d{4}$/`) and mean entirely different things: the
names are the only thing keeping a call site honest, so they carry the weight.
## Layout
| File | Owns |
|---|---|
| `org-number.ts` | Swedish organisationsnummer / personnummer: canonical 10-digit form, Luhn, Skatteverket 12-digit conversion |
| `account-number.ts` | BAS account number format (4 digits, always a string) |
| `iso-date.ts` | `YYYY-MM-DD` shape, plus a real-calendar-date check |
| `fiscal-year.ts` | Four-digit räkenskapsår key |
| `zod.ts` | Zod primitives built from the rules above, for API schemas |
`zod.ts` is separate so that consumers which do not use Zod (the MCP server,
report generators) can import a rule without pulling the dependency in.
## Adding a rule
1. Write the rule and the **reason** in the docblock. A rule without a recorded
reason gets re-litigated or worked around within a quarter.
2. Export a pure validator (primitives in, boolean or `null` out).
3. Add the Zod primitive to `zod.ts` if an API surface needs it.
4. Replace the hand-rolled copies. `npm run check:guards` tracks how many remain
and fails if the count goes up.