tieline

tieline

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

[npm] [CI] [license: MIT] [node] [tests] [dependencies]

[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

  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.

tieline vs alternatives

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

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.jsontieline 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 reachestieline doctor     # code↔spec drift (see below)

Supported stacks

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

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:

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.