Å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.
52 lines
2.3 KiB
Markdown
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.
|