tieline

Static frontend↔backend contract-drift checker. Pact without writing a single contract test.

tieline demo

tieline reads the code you already wrote on both sides of an API boundary — the HTTP calls your frontend makes and the routes your backend exposes — and tells you where they disagree. No contract tests to author, no broker to run, no backend to boot. It finishes in well under a second and is built to run in CI as a gate.

Delete the LLM and a developer still installs it. tieline is a deterministic tool first; an agent reading its output is a bonus.

How it works

Code

  frontend code                                  backend code
  (axios, rtk-query, …)                          (express, nestjs, openapi, …)
        │                                                │
   client adapter                                   server adapter
        │            normalize  ${id} :id {id} → {}       │
        └───────────────►  join on (METHOD, path)  ◄──────┘
                                   │
              ✅ matched   ❌ drift   ⚠️ unverifiable   🟡 dead

Both sides are reduced to a canonical (METHOD, path) and joined. The matcher is adapter-agnostic — any client adapter pairs with any server adapter, so the same engine checks a React app against Express, an Angular app against Spring, or anything against an OpenAPI spec.

Result	Meaning
✅ matched	FE call resolves to a real BE route
❌ drift	FE call resolves but the BE has no such route/method — the bug bucket
⚠️ unverifiable	FE url is built at runtime — reported, never guessed
🟡 dead	BE route no resolvable FE call reaches (informational)

tieline vs alternatives

These tools solve neighbouring problems — pick by what you have and what you want guaranteed.

Tool	How it works	What it catches	What it needs	Reach for it when
tieline	Static analysis of FE call sites + BE route declarations, joined on `(METHOD, path)`	A frontend calling a route the backend doesn't expose (path/method drift), undocumented/phantom spec routes	Source code of both sides; nothing running, nothing authored	You want a sub-second CI gate with zero contract tests to write or maintain
Pact	Consumer-driven contract tests executed at runtime, shared via a broker	Request/response payload mismatches between specific consumer–provider pairs	Contract tests written on both sides, a Pact broker, provider verification builds	Independent teams need payload-level guarantees and a can-I-deploy workflow
openapi-diff	Diffs two OpenAPI documents	Breaking changes between two spec versions	Accurate specs for both versions; doesn't read source code	Your API surface is spec-first and you want to gate spec changes
Optic	Tracks your OpenAPI spec over time and diffs every change in CI	Breaking changes and style/standards violations in the spec's history	An OpenAPI spec kept in the repo	You govern an evolving spec and want each PR's API changes reviewed
Schemathesis	Property-based fuzzing of a running API against its OpenAPI/GraphQL schema	Server crashes, schema violations, undocumented responses at runtime	A bootable backend + a schema	You want runtime conformance and robustness testing of the implementation

They compose: tieline catches FE↔BE drift statically in every PR, tieline doctor keeps code↔spec honest, and a runtime tool like Pact or Schemathesis can guard the payload/behaviour layer underneath.

Quick start

Install (or run with npx):

Terminal

npm install -g @nugehs/tieline
# or, from a clone:  git clone … && cd tieline && npm link

Generate a tieline.config.json — init sniffs the surrounding directories (cwd, its children, and its siblings) for known stacks and writes a ready-to-run config:

bash

tieline init

Code

  tieline · init

  scanning ~/code for repos…
  ✔ client: rtk-query     → web   (roots: src/redux/apis)
  ✔ server: nestjs        → api   (roots: src)

  📝 wrote tieline.config.json

It detects adapters from package.json deps (@reduxjs/toolkit, axios, @angular/core, @nestjs/core, express, fastify, next), requirements.txt / pyproject.toml (fastapi, flask), pom.xml / build.gradle (spring), and any OpenAPI doc as a fallback. Anything it can't detect is written as a placeholder for you to edit. The file is always overwritten, so re-run it whenever your layout changes.

Or write it by hand — at the root of (or above) your repos:

JSON Config

{
  "client": { "adapter": "rtk-query", "repo": "../web", "roots": ["src/redux/apis"], "basePath": "/api/v1" },
  "server": { "adapter": "nestjs",    "repo": "../api", "roots": ["src"], "globalPrefix": "api/v1" },
  "failOn": ["drift"]
}

Run it:

bash

tieline check

Code

  tieline · contract check

  ❌  2 drift  (FE calls a route the backend does not expose)
     GET    /users/{}
            getUser  ·  web/src/redux/apis/user-api.ts:42
            → did you mean "user/{}"?            # plural vs singular — a guaranteed 404
     PUT    /orders/{}
            updateOrder  ·  web/src/redux/apis/order-api.ts:88
            → path exists but as GET, not PUT    # method mismatch

  ✅ 274 matched   ❌ 2 drift   ⚠️  6 unverifiable   🟡 31 unused backend routes

check exits non-zero when any failOn bucket is non-empty — drop it into CI and the build fails the moment the two sides disagree.

Commands

bash

tieline init       # auto-detect nearby repos and write tieline.config.json
tieline check      # FE↔BE drift; exits non-zero on drift (the CI gate)
tieline list       # the full resolved contract map (every endpoint + status)
tieline orphans    # backend routes no frontend call reaches
tieline doctor     # code↔spec drift (see below)

Flag	Effect
`--config <path>`	Path to `tieline.config.json` (default: searched upward from cwd)
`--json`	Machine-readable output
`--html <file>`	Self-contained visual report (see Visual report)
`--no-fail`	Always exit 0 (report only)

Supported stacks

Any client adapter pairs with any server adapter — the matcher never changes.

Client (calls)	Server (routes)
`rtk-query` — Redux Toolkit Query	`nestjs` — decorators
`axios-fetch` — axios / fetch, React Query & SWR `queryFn`s	`express` — `app.use()` mount graph, cross-file
`angular-http` — Angular `HttpClient`	`fastify` — verb shorthand + `route({})`
	`next` — file-based (app router + pages API)
	`fastapi` — `APIRouter` prefix + `include_router`
	`flask` — blueprints + `methods=[]`
	`spring` — `@RequestMapping` + `@*Mapping`
	`openapi` — universal: any OpenAPI 2/3 doc (file or URL)

That covers MERN (rtk/axios ↔ express), MEAN (angular ↔ express), MEVN (axios ↔ express), Next full-stack, Python (fastapi/flask), and enterprise (angular ↔ spring) — plus openapi for any backend that emits a spec (Express+swagger-jsdoc, FastAPI, Spring springdoc, .NET Swashbuckle, …).

Notes:

express walks the app.use() mount graph across require/import boundaries and nested routers; routers it can't reach are flagged, never dropped.
next is file-system routing — app-router files export GET/POST/…; pages-router handlers serve any verb (matched as ALL).
Runtime-built urls (e.g. `users/${id}?x=${q}`) are surfaced as unverifiable rather than guessed.

Configuration

tieline.config.json — repo paths resolve relative to the config file.

JSON Config

{
  "client": {
    "adapter": "rtk-query",      // rtk-query | axios-fetch | angular-http
    "repo": "../web",
    "roots": ["src/redux/apis"], // dirs to scan for call sites
    "basePath": "/api/v1"        // stripped from call sites before matching
  },
  "server": {
    "adapter": "nestjs",         // nestjs | express | fastify | next | fastapi | flask | spring | openapi
    "repo": "../api",
    "roots": ["src"],
    "globalPrefix": "api/v1",    // stripped from routes before matching
    "spec": "openapi.json"       // openapi adapter & `doctor` only — file path or URL
  },
  "ignore": ["internal/.*"],     // regexes on the normalized path
  "failOn": ["drift"]            // buckets that make `check` exit non-zero
}

Visual report

tieline check --html report.html writes one self-contained file (inline CSS/JS, no external assets) you can open in any browser or attach to a PR:

a contract-flow diagram — frontend resources on the left, backend on the right, curved links coloured green (matched) / red (drift), with a ∅ no route node catching calls that land nowhere; hover a resource to highlight its links
a health ring, summary cards, and live-filterable drift / unverifiable / unused tables

`tieline doctor` — does your code match your published docs?

doctor diffs routes parsed from source (a native adapter like nestjs) against the routes declared in your OpenAPI spec (server.spec):

Code

  tieline · doctor   code (nestjs)  ↔  spec (http://localhost:9999/doc-json)

  ❌  4 undocumented  (in code, missing from the published spec)
     GET    /billing/invoices       src/billing/billing.controller.ts:54
     POST   /webhooks/stripe        src/webhooks/webhooks.controller.ts:21
     ...
  👻  1 phantom  (in the spec, no matching route in code)

  ✅ 312 agree   ❌ 4 undocumented   👻 1 phantom   (316 code routes, 313 spec routes)

undocumented — working routes invisible to anyone generating an SDK or partner integration from the spec.
phantom — the spec promises a route the code no longer serves (stale docs).

Run it alongside check and your spec can never silently drift from your code.

Use as an MCP server

tieline ships an MCP server so an agent can ask "do these two repos still agree?" and get the same structured result the CLI produces — no LLM does the analysis, the deterministic engine does. It's still zero-dependency: the server is hand-rolled stdio JSON-RPC, no SDK.

JSON Config

{
  "mcpServers": {
    "tieline": { "command": "npx", "args": ["-y", "-p", "@nugehs/tieline", "tieline-mcp"] }
  }
}

Or, from a global install (npm i -g @nugehs/tieline), just "command": "tieline-mcp".

It exposes five tools, each returning JSON:

Tool	Args	Returns
`tieline_check`	`config?`	totals + `drift` + `unverifiable` (the drift gate)
`tieline_list`	`config?`	the full resolved contract map
`tieline_orphans`	`config?`	backend routes no frontend call reaches
`tieline_doctor`	`config?`	`undocumented` + `phantom` (code ↔ spec)
`tieline_init`	`cwd?`	auto-detect nearby repos, write a config

config defaults to searching upward from the server's working directory, exactly like the CLI — so an agent dropped into a repo with a tieline.config.json can just call tieline_check.

Architecture

Each side implements a single extractor; everything downstream is shared.

Code

ClientAdapter.extract() → Endpoint[] { method, rawPath, resolvable, file, line }
ServerAdapter.extract() → Route[]    { method, rawPath, file, line }

A new framework is a new adapter (~80 lines) — the normalizer, matcher, reporters, and CLI never change. Path-existence drift ships today; OpenAPI DTO-shape diffing (--deep) and SARIF/PR annotations are on the roadmap.

Tests

Terminal

npm test    # node --test — zero dependencies, nothing to install

71 tests on Node's built-in runner:

normalize — every param syntax (${id}/:id/<int:id>/[id]/{id}), query stripping, basePath, path joining
matcher — all four buckets, drift hints (method-mismatch, "did you mean"), ignore, ALL/ANY any-verb routes, cross-syntax param matching
adapters — every client + server adapter against a fixture, plus edge cases via throwaway temp repos (Express app.all + unmounted router, Next route groups
- catch-all, Spring @RequestMapping(method=…), Flask default-GET, runtime urls → unverifiable, non-HttpClient .get() ignored)
openapi — servers[].url prefix, Swagger 2 basePath, stripPrefix
doctor — undocumented / phantom / matched + hints
init — stack auto-detection (node deps, Python, Spring, OpenAPI fallback), dir-name bias, sibling/child scanning, placeholder fallback, config round-trip
integration — three cross-stack proofs (RTK↔Express, Angular↔Spring, axios↔FastAPI) and the real CLI (exit codes, --json, --html, doctor)
mcp — the stdio JSON-RPC server: handshake, tools/list, a real tieline_check over a fixture, in-band tool errors, method-not-found

Roadmap

SARIF output — inline drift annotations on GitHub PRs
--deep — diff request/response DTO shapes, not just paths, via OpenAPI (catches a renamed field or changed enum, where the expensive bugs live)
More adapters — react-query/swr first-class clients, koa/django servers
AST extraction — replace regex parsing for exotic declarations

Known limits today: regex-based extraction (robust on conventional code), one @Controller per file, path/method existence only. GraphQL is out of scope.

License

Part of the toolchain

tieline is one of four tools that form a deterministic trust layer for AI-assisted development. Each answers a question people keep handing to an LLM — with static analysis instead.

repoctx — context: what does this change actually touch?
tieline (this tool) — contracts: did the front end and back end quietly stop agreeing?
bouncer — compliance: could you defend this to Ofcom?
aiglare — governance: where can the model do something you can't undo?

More at segunolumbe.com. static analysis, never the model.

tieline

How it works

tieline vs alternatives

Quick start

Commands

Supported stacks

Configuration

Visual report

tieline doctor — does your code match your published docs?

Use as an MCP server

Architecture

Tests

Roadmap

License

Part of the toolchain

`tieline doctor` — does your code match your published docs?