api-tracer-kit 1.0.0

package/cli/shape.mjs

@@ -0,0 +1,90 @@
+/**
+ * Response contracts: reduce a response body to its shape, then compare shapes
+ * across runs.
+ *
+ * The point is the failure a status check cannot see. This API answers 200 for
+ * almost everything, so a backend that quietly drops `data[].pinned` or turns an
+ * id from a number into a string still looks green. Comparing shapes catches it.
+ */
+
+/** the shape of one value: primitives become their type name, containers recurse */
+export function shapeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) {
+    if (!value.length) return { '[]': 'empty' };
+    // union across elements, so a field missing from the first row is not lost
+    return { '[]': value.map(shapeOf).reduce(mergeShapes) };
+  }
+  if (typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => [k, shapeOf(v)]),
+    );
+  }
+  return typeof value;
+}
+
+/** two shapes for the same slot; disagreement is recorded rather than resolved */
+function mergeShapes(a, b) {
+  if (a === b) return a;
+  if (typeof a === 'string' || typeof b === 'string') {
+    if (a === 'null') return b;
+    if (b === 'null') return a;
+    return typeof a === 'string' && typeof b === 'string' ? [a, b].sort().join('|') : a;
+  }
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) out[k] = k in out ? mergeShapes(out[k], v) : v;
+  return out;
+}
+
+/** nested shape -> { 'data[].id': 'number' }, which is what a human reads in a diff */
+export function flatten(shape, prefix = '') {
+  if (typeof shape === 'string') return { [prefix || '.']: shape };
+  const out = {};
+  for (const [key, value] of Object.entries(shape)) {
+    const path = key === '[]' ? `${prefix}[]` : prefix ? `${prefix}.${key}` : key;
+    if (typeof value === 'string') out[path] = value;
+    else Object.assign(out, flatten(value, path));
+  }
+  return out;
+}
+
+/**
+ * What changed between a baseline response and a new one. Ignores values
+ * entirely -- only the presence and type of each field matters.
+ */
+export function diffShapes(baseline, current) {
+  const a = flatten(baseline);
+  const b = flatten(current);
+
+  const removed = Object.keys(a).filter((k) => !(k in b));
+  const added = Object.keys(b).filter((k) => !(k in a));
+  const changed = Object.keys(a)
+    .filter((k) => k in b && a[k] !== b[k])
+    .map((path) => ({ path, from: a[path], to: b[path] }));
+
+  return { added, removed, changed, drifted: Boolean(added.length || removed.length || changed.length) };
+}
+
+/** a one-line summary for a badge: -data.pinned, +data.author */
+export function summarizeDrift(diff, limit = 4) {
+  const parts = [
+    ...diff.removed.map((p) => `-${p}`),
+    ...diff.added.map((p) => `+${p}`),
+    ...diff.changed.map((c) => `${c.path}: ${c.from}->${c.to}`),
+  ];
+  return parts.length > limit
+    ? `${parts.slice(0, limit).join(', ')} and ${parts.length - limit} more`
+    : parts.join(', ');
+}
+
+/** parses a body and returns its shape, or null when it is not JSON */
+export function shapeOfBody(text) {
+  if (typeof text !== 'string' || !text.trim()) return null;
+  try {
+    return shapeOf(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}

package/cli/test.mjs

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+/**
+ * One runnable check over the console: what gets sent, what counts as healthy,
+ * what the scanner reads, and what happens to traffic that is imported.
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { buildUrl, fillVars, pluck, verdict, useCatalog } from './server.mjs';
+import { scanProject } from './scan.mjs';
+import { guessAuth, guessBaseUrls, guessPreset, collectFiles, defaults } from './config.mjs';
+import { importHar, importCurl, matchEndpoint, parseQuery, toComparablePath } from './import.mjs';
+import { shapeOf, diffShapes, summarizeDrift } from './shape.mjs';
+import { buildReport, toMarkdown } from './report.mjs';
+
+let checks = 0;
+const check = (name, fn) => {
+  fn();
+  checks++;
+  process.stdout.write(`  ok ${name}\n`);
+};
+
+/*
+ * The server builds URLs from the catalog it holds, so the tests give it a
+ * known one rather than depending on whatever was last scanned.
+ */
+useCatalog({ baseUrls: { dev: 'https://api.example.com/v1' }, auth: { header: 'AUTH_TOKEN' }, endpoints: [] });
+
+const ep = (over = {}) => ({
+  subUrl: '/appointments/${data.id}.json',
+  holes: [{ expr: 'data.id', label: 'id' }],
+  absolute: false,
+  ...over,
+});
+
+/* --- query params ------------------------------------------------------ */
+
+const plain = ep({ subUrl: '/x', holes: [] });
+check('arrays and nested objects serialize the axios way', () => {
+  assert.equal(
+    buildUrl(plain, {}, { page: 1, ids: [3, 4], filter: { status: 'new' } }),
+    'https://api.example.com/v1/x?page=1&ids%5B%5D=3&ids%5B%5D=4&filter%5Bstatus%5D=new',
+  );
+});
+check('empty and null params are dropped, but 0 is kept', () => {
+  assert.equal(buildUrl(plain, {}, { skip: '', gone: null, keep: 0 }), 'https://api.example.com/v1/x?keep=0');
+});
+check('raw mode passes the string through without re-encoding', () => {
+  assert.equal(buildUrl(plain, {}, {}, '?a=1&q=a b&enc=%2Bx'), 'https://api.example.com/v1/x?a=1&q=a b&enc=%2Bx');
+});
+check('stringified mode puts the whole object in one encoded param', () => {
+  assert.equal(buildUrl(plain, {}, { page: 1 }, '', 'params'), 'https://api.example.com/v1/x?params=%7B%22page%22%3A1%7D');
+});
+
+/* --- path holes -------------------------------------------------------- */
+
+check('a path hole is filled from the supplied value', () => {
+  assert.equal(buildUrl(ep(), { 'data.id': '4821' }), 'https://api.example.com/v1/appointments/4821.json');
+});
+check('an unfilled hole leaves a blank rather than the literal template', () => {
+  assert.equal(buildUrl(ep(), {}), 'https://api.example.com/v1/appointments/.json');
+});
+check('an absolute endpoint ignores the base URL', () => {
+  const third = ep({ subUrl: 'https://api.postcodes.test/lookup', holes: [], absolute: true });
+  assert.equal(buildUrl(third, {}, { q: 'SW1' }), 'https://api.postcodes.test/lookup?q=SW1');
+});
+check('a missing base URL is reported rather than producing a broken URL', () => {
+  useCatalog({ baseUrls: {}, endpoints: [] });
+  assert.throws(() => buildUrl(ep({ subUrl: '/x', holes: [] })), /base URL/);
+  useCatalog({ baseUrls: { dev: 'https://api.example.com/v1' }, auth: { header: 'AUTH_TOKEN' }, endpoints: [] });
+});
+
+/* --- variables --------------------------------------------------------- */
+
+check('an unknown variable is left visible rather than blanked', () => {
+  assert.equal(fillVars('/a/{{nope}}/b'), '/a/{{nope}}/b');
+});
+
+/* --- reading values out of a response ---------------------------------- */
+
+check('a dotted path walks objects and arrays', () => {
+  assert.equal(pluck({ data: [{ id: 9 }] }, 'data.0.id'), 9);
+  assert.equal(pluck({ data: null }, 'data.0.id'), undefined);
+});
+
+/* --- healthy or not ---------------------------------------------------- */
+
+const envelope = { codeFields: ['status', 'code'], okField: 'success', failFrom: 400 };
+check('a 2xx carrying an error code is a failure', () => {
+  assert.equal(verdict(true, { status: 801, success: false }, envelope).ok, false);
+  assert.equal(verdict(true, { status: 801, success: false }, envelope).innerCode, 801);
+});
+check('a 2xx with a good envelope passes', () => {
+  assert.equal(verdict(true, { status: 200, success: true }, envelope).ok, true);
+});
+check('a non-2xx fails whatever the body says', () => {
+  assert.equal(verdict(false, { status: 200, success: true }, envelope).ok, false);
+});
+check('with no envelope configured the HTTP status decides alone', () => {
+  assert.equal(verdict(true, { status: 801, success: false }, false).ok, true);
+});
+
+/* --- the scanner ------------------------------------------------------- */
+
+const project = mkdtempSync(join(tmpdir(), 'api-tracer-'));
+mkdirSync(join(project, 'src', 'services'), { recursive: true });
+writeFileSync(
+  join(project, 'src', 'services', 'index.js'),
+  `export const authTokenKey = "X_AUTH";
+   const apiBaseUrls = { dev: "https://dev.example.com/api", prod: "https://example.com/api" };`,
+);
+writeFileSync(
+  join(project, 'src', 'services', 'patients.js'),
+  `import { get, post, deletee } from "./index";
+
+   // subUrl: \`/old/patients.json\`,
+   export const getPatients = (params) => {
+     const request = { subUrl: \`/v1/patients.json\`, params };
+     return get(request);
+   };
+
+   export const getPatient = (data) => {
+     const request = { subUrl: \`/v1/patients/\${data.id}.json\` };
+     return get(request);
+   };
+
+   export const createPatient = (data) => {
+     const request = { subUrl: \`/v1/patients.json\`, data };
+     return post(request);
+   };
+
+   export const removePatient = (data) => {
+     const request = { subUrl: \`/v1/patients/\${data.id}.json\` };
+     return deletee(request);
+   };
+
+   export const NOT_AN_ENDPOINT = 42;`,
+);
+writeFileSync(join(project, 'src', 'Page.jsx'), `import { getPatients } from "./services/patients";\ngetPatients();`);
+
+const scanned = scanProject(project, { ...defaults, sources: ['src'] });
+
+check('the preset is guessed rather than configured', () => {
+  assert.equal(scanned.preset, 'service-object');
+});
+check('every service function becomes an endpoint, and nothing else does', () => {
+  assert.deepEqual(
+    scanned.endpoints.map((e) => e.id).sort(),
+    ['patients.createPatient', 'patients.getPatient', 'patients.getPatients', 'patients.removePatient'],
+  );
+});
+check('the verb, path and path holes are read correctly', () => {
+  const one = scanned.endpoints.find((e) => e.id === 'patients.getPatient');
+  assert.equal(one.method, 'GET');
+  assert.equal(one.subUrl, '/v1/patients/${data.id}.json');
+  assert.deepEqual(one.holes, [{ expr: 'data.id', label: 'id' }]);
+});
+check('a commented-out URL directly above the live one is not taken', () => {
+  assert.equal(scanned.endpoints.find((e) => e.id === 'patients.getPatients').subUrl, '/v1/patients.json');
+});
+check('params and body are told apart', () => {
+  assert.equal(scanned.endpoints.find((e) => e.id === 'patients.getPatients').usesParams, true);
+  assert.equal(scanned.endpoints.find((e) => e.id === 'patients.createPatient').usesData, true);
+});
+check('two functions on the same route are both kept', () => {
+  const sameRoute = scanned.endpoints.filter((e) => e.subUrl === '/v1/patients.json');
+  assert.equal(sameRoute.length, 2, 'a method+path fingerprint alone would collapse these');
+});
+check('an endpoint nothing references is flagged', () => {
+  assert.equal(scanned.endpoints.find((e) => e.id === 'patients.getPatients').usedIn, 1);
+  assert.equal(scanned.endpoints.find((e) => e.id === 'patients.removePatient').usedIn, 0);
+});
+check('base URLs and the auth header are read from the source', () => {
+  assert.deepEqual(scanned.baseUrls, { dev: 'https://dev.example.com/api', prod: 'https://example.com/api' });
+  assert.equal(scanned.auth.header, 'X_AUTH');
+});
+
+/* --- the other presets ------------------------------------------------- */
+
+const other = mkdtempSync(join(tmpdir(), 'api-tracer-'));
+mkdirSync(join(other, 'src'), { recursive: true });
+writeFileSync(
+  join(other, 'src', 'api.js'),
+  `import axios from "axios";
+   export const listUsers = () => axios.get("/api/users", { params: { page: 1 } });
+   export const addUser = (body) => axios.post(\`/api/users/\${body.id}\`, body);`,
+);
+check('the axios-direct preset reads plain axios calls', () => {
+  const found = scanProject(other, { ...defaults, sources: ['src'], preset: 'axios-direct' });
+  assert.equal(found.endpoints.length, 2);
+  assert.deepEqual(found.endpoints.map((e) => e.method).sort(), ['GET', 'POST']);
+  assert.equal(found.endpoints.find((e) => e.method === 'POST').holes.length, 1);
+});
+check('guessing picks the preset that actually reads the code', () => {
+  assert.equal(guessPreset(collectFiles(other, defaults), defaults).preset, 'axios-direct');
+});
+
+const fetchy = mkdtempSync(join(tmpdir(), 'api-tracer-'));
+mkdirSync(join(fetchy, 'src'), { recursive: true });
+writeFileSync(
+  join(fetchy, 'src', 'client.js'),
+  `export const load = () => fetch("/api/things");
+   export const save = (b) => fetch("/api/things", { method: "POST", body: JSON.stringify(b) });`,
+);
+check('the fetch-direct preset reads plain fetch calls', () => {
+  const found = scanProject(fetchy, { ...defaults, sources: ['src'], preset: 'fetch-direct' });
+  assert.equal(found.endpoints.length, 2);
+  assert.deepEqual(found.endpoints.map((e) => e.method).sort(), ['GET', 'POST']);
+});
+
+check('an empty project scans to nothing instead of throwing', () => {
+  const empty = mkdtempSync(join(tmpdir(), 'api-tracer-'));
+  const found = scanProject(empty, defaults);
+  assert.deepEqual(found.endpoints, []);
+  rmSync(empty, { recursive: true, force: true });
+});
+
+/* --- matching real traffic back to the catalog ------------------------- */
+
+const ctx = { baseUrls: { dev: 'https://dev.example.com/api' }, endpoints: scanned.endpoints };
+
+check('a concrete URL is matched back to its template', () => {
+  const hit = matchEndpoint('GET', '/v1/patients/4821.json', scanned.endpoints);
+  assert.equal(hit.endpoint.id, 'patients.getPatient');
+  assert.deepEqual(hit.pathValues, { 'data.id': '4821' });
+});
+check('a literal path is not swallowed by a greedier template', () => {
+  const hit = matchEndpoint('GET', '/v1/patients.json', scanned.endpoints);
+  assert.equal(hit.endpoint.subUrl, '/v1/patients.json');
+});
+check('a URL on another host is not ours', () => {
+  assert.equal(toComparablePath('https://elsewhere.test/v1/patients.json', ctx.baseUrls), null);
+});
+check('the axios query shapes are parsed back', () => {
+  assert.deepEqual(parseQuery('a=1&b[]=2&b[]=3&f[x]=9'), { a: '1', b: ['2', '3'], f: { x: '9' } });
+});
+
+const har = JSON.stringify({
+  log: {
+    entries: [
+      {
+        request: {
+          method: 'POST',
+          url: 'https://dev.example.com/api/v1/patients.json?ref=x',
+          postData: { mimeType: 'application/json', text: '{"name":"a","password":"hunter2"}' },
+        },
+      },
+      { request: { method: 'GET', url: 'https://dev.example.com/api/v1/nothing.json' } },
+    ],
+  },
+});
+
+check('a HAR import matches what it can and reports what it cannot', () => {
+  const out = importHar(har, ctx);
+  assert.equal(out.matched, 1);
+  assert.deepEqual(out.unmatched, ['no endpoint matches GET /v1/nothing.json']);
+  assert.equal(out.unmatchedCalls.length, 1, 'an unexplained call is still kept');
+});
+check('a secret in imported traffic never reaches the sample', () => {
+  const sample = Object.values(importHar(har, ctx).samples)[0];
+  assert.equal(sample.data.password, '<redacted>');
+  assert.equal(sample.data.name, 'a', 'the surrounding shape survives');
+  assert.deepEqual(sample.params, { ref: 'x' });
+});
+check('a copied cURL command is imported the same way', () => {
+  const out = importCurl(`curl 'https://dev.example.com/api/v1/patients/99.json' -H 'AUTH_TOKEN: secret'`, ctx);
+  assert.equal(out.matched, 1);
+  assert.equal(Object.values(out.samples)[0].pathValues['data.id'], '99');
+});
+check('a cURL with a body is treated as a POST, as curl itself would', () => {
+  const out = importCurl(
+    `curl 'https://dev.example.com/api/v1/patients.json' --data-raw '{"name":"a","token":"t"}'`,
+    ctx,
+  );
+  assert.equal(out.matched, 1);
+  const sample = Object.values(out.samples)[0];
+  assert.equal(sample.data.name, 'a');
+  assert.equal(sample.data.token, '<redacted>');
+});
+
+/* --- response contracts ------------------------------------------------ */
+
+check('a shape ignores values and keeps types', () => {
+  assert.deepEqual(shapeOf({ id: 1, name: 'a' }), { id: 'number', name: 'string' });
+});
+check('an array shape is the union of its rows, so a sparse first row loses nothing', () => {
+  assert.deepEqual(shapeOf([{ a: 1 }, { a: 1, b: 't' }]), { '[]': { a: 'number', b: 'string' } });
+});
+check('drift reports what was added, removed and retyped', () => {
+  const diff = diffShapes(shapeOf({ id: 1, pinned: true }), shapeOf({ id: 'x', author: 'a' }));
+  assert.equal(diff.drifted, true);
+  assert.deepEqual(diff.removed, ['pinned']);
+  assert.deepEqual(diff.added, ['author']);
+  assert.deepEqual(diff.changed, [{ path: 'id', from: 'number', to: 'string' }]);
+  assert.equal(summarizeDrift(diff), '-pinned, +author, id: number->string');
+});
+check('an identical shape does not drift', () => {
+  assert.equal(diffShapes(shapeOf({ a: [1] }), shapeOf({ a: [2] })).drifted, false);
+});
+
+/* --- the report -------------------------------------------------------- */
+
+const report = buildReport({
+  catalog: { baseUrls: { dev: 'https://dev.example.com/api' }, auth: { header: 'X_AUTH' }, scannedAt: new Date().toISOString() },
+  endpoints: scanned.endpoints,
+  samples: { 'patients.getPatients': { params: { page: 1 }, data: {}, seenAt: new Date().toISOString() } },
+  results: { 'patients.getPatients': { ok: false, status: 200, innerCode: 801, ms: 12, failure: { body: '{"message":"no token"}' } } },
+  contracts: {},
+  runs: [],
+  env: 'dev',
+});
+
+check('the report measures coverage against the catalog', () => {
+  assert.equal(report.coverage.total, 4);
+  assert.equal(report.coverage.seen, 1);
+  assert.equal(report.coverage.pct, 25);
+});
+check('a 2xx carrying an error code is called out as a risk', () => {
+  assert.deepEqual(report.risks.envelopeErrors, [{ id: 'patients.getPatients', status: 200, innerCode: 801 }]);
+});
+check('the failure message is pulled out of the envelope', () => {
+  assert.equal(report.health.failing[0].message, 'no token');
+});
+check('writes nobody has exercised are listed', () => {
+  assert.ok(report.risks.untestedWrites.includes('patients.createPatient'));
+});
+check('duplicate routes are reported', () => {
+  assert.equal(report.hygiene.duplicates.length, 0, 'different methods on one path are not duplicates');
+});
+check('the markdown export renders without a run history', () => {
+  const md = toMarkdown(report);
+  assert.match(md, /# API report/);
+  assert.match(md, /Standard `X_AUTH`/);
+});
+
+rmSync(project, { recursive: true, force: true });
+rmSync(other, { recursive: true, force: true });
+rmSync(fetchy, { recursive: true, force: true });
+
+console.log(`\n${checks} checks passed`);