axil verify
axil verify scans src/ for t* decorators, separates the ones @axiljs/runtime enforces from metadata-only ones, flags unwired classes and runs the tests with AXIL_INTENT_MODE=enforce.
On this page11
axil verify answers one question: does the code keep the promises its decorators declare? A decorator such as @tReadOnly() or @tIdempotent() is only a promise until something checks it. axil verify shows which decorators in your project are actually enforced, which classes are never wired, and runs your tests with intent checks switched to enforce.
Note
New in 0.3.5.
Options
| Option | Description |
|---|---|
[pattern] | Run only test files whose path contains pattern, as with axil test [pattern] |
--static | Scan only; do not run the tests |
--json | Print the report as JSON on stdout, with no other output |
--strict | Also exit with code 1 on unenforced behavioural decorators or classes that look unwired |
What it does
1. Static scan
Every src/**/*.ts file is scanned, excluding .d.ts, *.test.ts, *.spec.ts, node_modules and dot-directories. Comments and string contents are ignored, so a decorator mentioned in a comment does not count.
Each t* decorator is listed with its file:line locations and classified as:
- Enforced at runtime:
@axiljs/runtimehas an interceptor for it, so it changes behaviour once the class is wired. - Metadata only: it records metadata and nothing executes it.
The enforced set comes from the project's own @axiljs/runtime, through enforcedDecorators(), so custom interceptors you register at import time count too. When the runtime is not installed, a bundled list matching runtime 0.3.4 and later (26 decorators) is used, and the output says so.
A metadata-only decorator whose catalog category promises call-time behaviour (Security, Policy, Data, Reliability, Concurrency, Distributed, Messaging, Caching, Compliance, Runtime, Workflow, Execution, Observability) is marked not enforced. Decorators that only describe shape or routing, such as tHttp, show their category instead, and so do tRedact and tSensitive, which the runtime applies through redaction rather than interceptors.
2. Wiring (heuristic)
Interceptors only run on classes passed to wire() or reached by wireAll(). The scan flags classes that use enforced decorators but are never wired:
wireAll()anywhere insrc/counts as wiring every class.wire(Class),wire(new Class())andwire(this)inside the class count for that class.- A
wire(instance)through a variable is not visible to this check, so treat a flagged class as a hint.
3. Tests in enforce mode
The test suite runs exactly like axil test [pattern], in a child process with AXIL_INTENT_MODE=enforce. A broken promise therefore throws IntentViolationError and fails its test, even if your app would run in warn mode. Failures caused by a violation are collected in an Intent violations section with the target, the decorator, the detail and the test name.
Output
For a project with two services:
1export class OrdersService {
2 @tReadOnly()
3 @tTenantIsolated()
4 async list() { /* ... */ }
5
6 @tIdempotent({ key: 'header:idempotency-key' })
7 @tRetry({ attempts: 3, retryOn: ['ECONNRESET'] })
8 @tTimeout(2000)
9 async pay(orderId: string) { /* ... */ }
10}
11wire(OrdersService)
12
13// src/services/reports.service.ts
14export class ReportsService {
15 @tHttp({ method: 'GET', path: '/reports/revenue' })
16 @tCache({ key: 'revenue', ttl: 60_000 })
17 async revenue() { /* ... */ }
18
19 @tSaga('close-month')
20 async closeMonth() { /* ... */ }
21}axil verify --static prints:
┌ axil verify Do the decorators keep their promises?
│
● Scanned 2 file(s) in src/ enforced set: @axiljs/runtime 0.3.6, 26 decorator(s)
│
◆ Enforced at runtime
│ @tCache 1× src/services/reports.service.ts:5
│ @tIdempotent 1× src/services/orders.service.ts:9
│ @tReadOnly 1× src/services/orders.service.ts:5
│ @tRetry 1× src/services/orders.service.ts:10
│ @tTenantIsolated 1× src/services/orders.service.ts:6
│ @tTimeout 1× src/services/orders.service.ts:11
│
◆ Metadata only
│ @tHttp 1× HTTP src/services/reports.service.ts:4
│ @tSaga 1× not enforced src/services/reports.service.ts:8
● 1 decorator(s) promise runtime behaviour nothing enforces add an interceptor (registerInterceptor) or treat them as documentation
│
◆ Wiring (heuristic)
▲ ReportsService looks unwired ReportsService is never passed to wire()
│ src/services/reports.service.ts:3 uses @tCache
│ Interceptors only run on wired classes: wire(Class) or wireAll() at startup.
│
◆ Static checks passed
│
└ReportsService uses @tCache but is never wired, so revenue() is not cached at all. @tSaga promises behaviour that nothing in the runtime provides. Neither fails the run without --strict.
A broken promise
When a test calls a @tReadOnly() method that ends up in a @tSideEffect('db.write') method, the test section shows the failure and the violation:
◆ Tests
○ Running tests with AXIL_INTENT_MODE=enforce
■ Tests failed 1 passed, 1 failed
│ [AxilJS Test] Running tests...
│
│ Orders
│ ✗ lists orders without writing (3ms)
│ Orders.list violates tReadOnly: performed side effect db.write (Audit.record)
│ at violate (node_modules/@axiljs/runtime/dist/intent.js:104:15)
│ at reportSideEffect (node_modules/@axiljs/runtime/dist/intent.js:126:13)
│ ✓ passes (0ms)
│
│ ──────────────────────────────────────────────────
│ 1 passed, 1 failed (4ms)
│
◆ Intent violations
│ ✖ Orders.list violates @tReadOnly
│ performed side effect db.write (Audit.record)
│ in test: lists orders without writing
│
■ Verify failed
│ 1 intent violation(s)
│
└On an interactive terminal the ○ Running tests line is a spinner that is replaced by the result. Once every class is wired and the tests pass, the run ends with:
◆ Wiring (heuristic)
◇ Every class with enforced decorators reaches wire()
│
◆ Tests
○ Running tests with AXIL_INTENT_MODE=enforce
◇ Tests passed 2 passed
│
◆ Promises kept
│
└If no tests ran (no test files, or none matching the pattern), the test step shows a warning and the run ends with Static checks passed, no tests ran.
Exit codes
| Code | When |
|---|---|
0 | The tests passed (or --static was used), and with --strict there are no static findings |
1 | The tests failed, including failures caused by intent violations |
1 | With --strict: a metadata-only decorator promises runtime behaviour, or a class looks unwired |
With --strict, the closing line names the reasons, for example 1 unenforced decorator(s), 1 class(es) look unwired.
JSON report
axil verify --json prints only JSON on stdout, so it can be redirected or piped:
1{
2 "project": "/home/me/my-api",
3 "enforced": {
4 "source": "runtime",
5 "version": "0.3.6",
6 "decorators": ["tAudit", "tBulkhead", "tCache", "..."]
7 },
8 "files": 2,
9 "summary": { "uses": 8, "distinct": 8, "enforced": 6, "metadataOnly": 2 },
10 "decorators": [
11 {
12 "name": "tCache",
13 "category": "Caching",
14 "status": "enforced",
15 "runtimeSemantics": true,
16 "count": 1,
17 "locations": ["src/services/reports.service.ts:5"]
18 }
19 ],
20 "unenforced": ["tSaga"],
21 "wiring": [
22 {
23 "class": "ReportsService",
24 "file": "src/services/reports.service.ts",
25 "line": 3,
26 "decorators": ["tCache"],
27 "reason": "ReportsService is never passed to wire()"
28 }
29 ],
30 "tests": null,
31 "strict": false,
32 "ok": true
33}| Field | Description |
|---|---|
enforced | Where the enforced set came from (runtime or bundled), the runtime version, and the decorator names |
summary | Decorator uses, distinct decorators, and how many uses are enforced or metadata only |
decorators | One entry per decorator: status (enforced or metadata-only), runtimeSemantics, count, locations |
unenforced | Metadata-only decorators that promise runtime behaviour |
wiring | Classes that look unwired, with the enforced decorators they use |
tests | null with --static; otherwise ran, passed, exitCode, counts, violations (decorator, target, detail, test), and the captured output when the run failed |
ok | The overall verdict; the exit code is 1 when it is false |
In CI
- run: npm ci
- run: npx axil verify --strict--strict turns the static findings into failures, so a new decorator that nothing enforces, or a service someone forgot to wire, breaks the build instead of silently doing nothing.
Related
- Intent verification: what the runtime checks and the
AXIL_INTENT_MODEvariable - Resilience: every enforced decorator and its order
- Contract testing: HTTP-level checks to run inside the suite
- Decorator Commands: the decorator catalog
Was this page helpful?