CLI

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.

7 min readUpdated DocumentationEdit this page
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.

Terminal
❯axil verify # static scan + tests with AXIL_INTENT_MODE=enforce
❯axil verify payments # only test files matching "payments"
❯axil verify --static # scan only, do not run the tests
❯axil verify --strict # also fail on unenforced behavioural decorators / unwired classes
❯axil verify --json # pure JSON report on stdout (for CI)

Options

OptionDescription
[pattern]Run only test files whose path contains pattern, as with axil test [pattern]
--staticScan only; do not run the tests
--jsonPrint the report as JSON on stdout, with no other output
--strictAlso 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/runtime has 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 in src/ counts as wiring every class.
  • wire(Class), wire(new Class()) and wire(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:

orders.service.ts
TS
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:

Output
TXT
  ┌  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:

Output
TXT
  ◆  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:

Output
TXT
  ◆  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

CodeWhen
0The tests passed (or --static was used), and with --strict there are no static findings
1The tests failed, including failures caused by intent violations
1With --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:

Terminal
❯axil verify --json > verify.json
JSON
JSON
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}
FieldDescription
enforcedWhere the enforced set came from (runtime or bundled), the runtime version, and the decorator names
summaryDecorator uses, distinct decorators, and how many uses are enforced or metadata only
decoratorsOne entry per decorator: status (enforced or metadata-only), runtimeSemantics, count, locations
unenforcedMetadata-only decorators that promise runtime behaviour
wiringClasses that look unwired, with the enforced decorators they use
testsnull with --static; otherwise ran, passed, exitCode, counts, violations (decorator, target, detail, test), and the captured output when the run failed
okThe overall verdict; the exit code is 1 when it is false

In CI

YAML
YAML
- 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.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY