tieline

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

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

  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):

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:

tieline init

  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:

{
  "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:

tieline check

  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

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

{
  "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):

  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.

Register it with any MCP client (Claude Code, Claude Desktop, …):

{
  "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.

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

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

MIT © Segun Olumbe

---

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.