Danijel Martinek
f8908e5e4b
Creates the shared schema module for library evaluation traces (ADR-022 §4): Zod-validated frontmatter with all 8 filter fields and enum constraints, plus parseTrace/validateTrace exports and a custom YAML frontmatter parser for the nested trace format. Also adds docs/library-decisions/_template.md with all 11 required headings (8 Filter + 3 Prompt) in machine-checkable ADR-022 order. Adds zod as a root devDependency so the script is runnable directly from the workspace root without a package context. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
---
|
|
package: <name>
|
|
version: "<semver range>"
|
|
tier: app | feature | core
|
|
decision: approved | rejected
|
|
date: <YYYY-MM-DD>
|
|
deciders: [<author>, ...]
|
|
adr: adr-NNN | null
|
|
filter-results:
|
|
license: <SPDX id>
|
|
types: native | "@types/<x>" | none
|
|
maintenance: active | dormant | abandoned
|
|
boundary-fit: pass | fail
|
|
shadow-check: pass | fail | "shadows <x>"
|
|
eu-residency: ok | n/a | self-hostable | fail
|
|
cve-scan: clean | "<advisory-id>" | fail
|
|
named-consumer: pass | fail
|
|
verification-commands:
|
|
- <literal command that produced each filter result>
|
|
accepted-cves: []
|
|
---
|
|
|
|
## Filter: license
|
|
|
|
<!-- Result: <SPDX id> -->
|
|
|
|
Allowed licences: MIT, Apache-2.0, BSD-\*, ISC, MPL-2.0. Record the SPDX
|
|
identifier from `package.json` or `npx license-checker`. Anything outside the
|
|
allowlist is an automatic reject.
|
|
|
|
## Filter: types
|
|
|
|
<!-- Result: native | @types/<x> | none -->
|
|
|
|
Confirm TypeScript types are available (`native` = ships its own `.d.ts`;
|
|
`@types/<x>` = community types package exists; `none` = no types → auto-reject).
|
|
|
|
## Filter: maintenance
|
|
|
|
<!-- Result: active | dormant | abandoned -->
|
|
|
|
Check last release date and recent PR/issue activity. `active` = last release
|
|
< 18 months AND activity < 12 months. `dormant` = stable but not actively
|
|
developed (acceptable for finished libraries). `abandoned` = auto-reject.
|
|
|
|
## Filter: boundary-fit
|
|
|
|
<!-- Result: pass | fail -->
|
|
|
|
Confirm the dependency does not violate ESLint boundary-tag rules for the
|
|
target tier (ADR-006, ADR-010, ADR-017). E.g., a Sentry SDK added to a feature
|
|
package is an auto-reject because ADR-017 §4 reserves vendor SDKs for core.
|
|
|
|
## Filter: shadow-check
|
|
|
|
<!-- Result: pass | fail | "shadows <x>" -->
|
|
|
|
Check whether this library duplicates a must-have already locked in the
|
|
workspace (e.g., proposing `valibot` when `zod` is locked, `tsyringe` when
|
|
Inversify is locked by ADR-002). A parallel adoption is `shadows <x>` and an
|
|
auto-reject; a replacement requires a dedicated ADR.
|
|
|
|
## Filter: eu-residency
|
|
|
|
<!-- Result: ok | n/a | self-hostable | fail -->
|
|
|
|
If the library transmits user data, telemetry, or business state to a
|
|
vendor-controlled endpoint by default, the vendor must offer an EU data region.
|
|
Self-hostable packages and build-time-only tools are `n/a`.
|
|
|
|
## Filter: cve-scan
|
|
|
|
<!-- Result: clean | "<advisory-id>" | fail -->
|
|
|
|
Run `pnpm audit --audit-level=moderate`. `clean` = no advisories at adoption
|
|
time. Record any accepted advisory IDs in the `accepted-cves` frontmatter field
|
|
and explain the risk acceptance here.
|
|
|
|
## Filter: named-consumer
|
|
|
|
<!-- Result: pass | fail -->
|
|
|
|
Answer: "Who calls this code path today, or who is blocked waiting for it?"
|
|
Hypothetical future callers are not consumers. This filter is the direct
|
|
response to the 2026-05-14 OpenAPI near-miss (ADR-022 §Context).
|
|
|
|
## Prompt: replaces
|
|
|
|
<!-- Required: answer in either direction with justification -->
|
|
|
|
What existing library or approach does this replace? New-and-old running in
|
|
parallel is a smell — name the thing being retired and its retirement plan, or
|
|
explain why parallel adoption is intentional and time-bounded.
|
|
|
|
## Prompt: migration-cost-out
|
|
|
|
<!-- Required: mechanical | hard | impossible + justification -->
|
|
|
|
What does ripping this back out look like 18 months from now? Is the removal
|
|
mechanical (swap one package, update call sites), hard (scattered integration
|
|
points, data format dependencies), or impossible (vendor lock-in, protocol
|
|
coupling)? Higher migration cost raises the bar for adoption.
|
|
|
|
## Prompt: alternatives-considered
|
|
|
|
<!-- Required: minimum two named alternatives, or "none with explanation" -->
|
|
|
|
Name at least two alternatives evaluated before choosing this library. For
|
|
`core`-tier adoptions, this section is also duplicated into the companion ADR.
|
|
If no alternatives exist, explain why (e.g., the library is the de-facto
|
|
standard with no viable substitutes).
|