api-tracer-kit 1.0.0

package/cli/report.mjs

@@ -0,0 +1,346 @@
+/**
+ * Builds the report model from what the tracker already knows. Pure functions:
+ * everything comes in as arguments so this can be tested without a server, and
+ * so the same model feeds the UI, the Markdown export and the JSON export.
+ */
+
+import { flatten } from './shape.mjs';
+
+const pct = (n, of) => (of ? Math.round((n / of) * 100) : 0);
+
+/** failures may be reported in the envelope, so the useful text is in the body */
+function messageOf(failure) {
+  if (!failure) return undefined;
+  if (failure.error) return failure.error;
+  try {
+    const body = JSON.parse(failure.body ?? '');
+    return body.message ?? body.error ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function coverage(endpoints, samples) {
+  const scanned = endpoints.filter((e) => !e.uncatalogued);
+  const byModule = new Map();
+
+  for (const ep of scanned) {
+    const row = byModule.get(ep.module) ?? { module: ep.module, total: 0, seen: 0 };
+    row.total++;
+    if (samples[ep.id]) row.seen++;
+    byModule.set(ep.module, row);
+  }
+
+  const rows = [...byModule.values()]
+    .map((r) => ({ ...r, pct: pct(r.seen, r.total) }))
+    .sort((a, b) => b.pct - a.pct || a.module.localeCompare(b.module));
+
+  const seen = scanned.filter((e) => samples[e.id]).length;
+  return {
+    total: scanned.length,
+    seen,
+    pct: pct(seen, scanned.length),
+    modules: rows,
+    untouched: rows.filter((r) => !r.seen).map((r) => r.module),
+  };
+}
+
+function health(endpoints, results) {
+  const withResult = endpoints.filter((e) => results[e.id]);
+  const failing = withResult
+    .filter((e) => !results[e.id].ok)
+    .map((e) => {
+      const r = results[e.id];
+      return {
+        id: e.id,
+        module: e.module,
+        method: e.method,
+        url: r.url,
+        status: r.status,
+        innerCode: r.innerCode,
+        message: messageOf(r.failure),
+        at: r.at,
+        failedInReplay: Boolean(r.failedInReplay),
+        regression: Boolean(r.wasOk),
+        lastOkAt: r.lastOkAt,
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const byModule = new Map();
+  for (const e of withResult) {
+    const row = byModule.get(e.module) ?? { module: e.module, passed: 0, failed: 0 };
+    row[results[e.id].ok ? 'passed' : 'failed']++;
+    byModule.set(e.module, row);
+  }
+
+  const byMethod = {};
+  for (const e of withResult) {
+    const m = (byMethod[e.method] ??= { passed: 0, failed: 0 });
+    m[results[e.id].ok ? 'passed' : 'failed']++;
+  }
+
+  return {
+    run: withResult.length,
+    passed: withResult.filter((e) => results[e.id].ok).length,
+    failed: failing.length,
+    failing,
+    regressions: failing.filter((f) => f.regression),
+    modules: [...byModule.values()].sort((a, b) => b.failed - a.failed),
+    methods: byMethod,
+  };
+}
+
+function drift(endpoints, results, contracts) {
+  return endpoints
+    .filter((e) => results[e.id]?.drift)
+    .map((e) => ({
+      id: e.id,
+      module: e.module,
+      summary: results[e.id].drift.summary,
+      fields: results[e.id].drift.count,
+      baselineAt: contracts[e.id]?.at,
+    }))
+    .sort((a, b) => b.fields - a.fields);
+}
+
+function authSurface(endpoints) {
+  const pick = (fn) => endpoints.filter(fn).map((e) => e.id).sort();
+  return {
+    accessToken: pick((e) => e.customToken === 'ACCESS_TOKEN'),
+    secretToken: pick((e) => e.customToken === 'SECRET_TOKEN'),
+    csToken: pick((e) => e.customToken === 'CS token'),
+    thirdParty: pick((e) => e.absolute),
+    standard: endpoints.filter((e) => !e.customToken && !e.absolute).length,
+  };
+}
+
+function hygiene(endpoints, samples) {
+  const seen = new Map();
+  for (const ep of endpoints) {
+    if (ep.uncatalogued) continue;
+    const key = `${ep.method} ${ep.subUrl}`;
+    seen.set(key, [...(seen.get(key) ?? []), ep.id]);
+  }
+
+  return {
+    unused: endpoints.filter((e) => e.usedIn === 0).map((e) => ({ id: e.id, file: e.file, line: e.line })),
+    duplicates: [...seen.entries()]
+      .filter(([, ids]) => ids.length > 1)
+      .map(([route, ids]) => ({ route, ids })),
+    dynamicUrl: endpoints.filter((e) => e.dynamicUrl).map((e) => e.id),
+    uncatalogued: endpoints
+      .filter((e) => e.uncatalogued)
+      .map((e) => ({ id: e.id, from: samples[e.id]?.from })),
+  };
+}
+
+const WRITE = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+function risks(endpoints, samples, results) {
+  const captured = (e) => Boolean(samples[e.id]);
+  return {
+    untestedWrites: endpoints
+      .filter((e) => WRITE.has(e.method) && !captured(e) && !e.uncatalogued)
+      .map((e) => e.id),
+    capturedDeletes: endpoints.filter((e) => e.method === 'DELETE' && captured(e)).map((e) => e.id),
+    redactedPayloads: endpoints
+      .filter((e) => JSON.stringify(samples[e.id]?.data ?? {}).includes('<redacted>'))
+      .map((e) => e.id),
+    // a 2xx carrying an error code is the failure a status check misses
+    envelopeErrors: endpoints
+      .map((e) => ({ id: e.id, r: results[e.id] }))
+      .filter(({ r }) => r && r.status >= 200 && r.status < 300 && !r.ok)
+      .map(({ id, r }) => ({ id, status: r.status, innerCode: r.innerCode })),
+  };
+}
+
+function performance(endpoints, samples, results) {
+  const rows = endpoints
+    .map((e) => ({ id: e.id, module: e.module, ms: results[e.id]?.ms ?? samples[e.id]?.ms }))
+    .filter((r) => typeof r.ms === 'number')
+    .sort((a, b) => b.ms - a.ms);
+
+  const values = rows.map((r) => r.ms).sort((a, b) => a - b);
+  const at = (p) => (values.length ? values[Math.min(values.length - 1, Math.floor((p / 100) * values.length))] : 0);
+
+  return {
+    samples: rows.length,
+    median: at(50),
+    p95: at(95),
+    slowest: rows.slice(0, 10),
+    // one measurement per endpoint is a hint, not a benchmark
+    caveat: 'one measurement per endpoint, from its most recent call',
+  };
+}
+
+/** request and response field lists, straight from real traffic */
+function inventory(endpoints, samples, contracts) {
+  return endpoints
+    .filter((e) => samples[e.id])
+    .map((e) => {
+      const s = samples[e.id];
+      return {
+        id: e.id,
+        module: e.module,
+        method: e.method,
+        path: e.subUrl,
+        bodyType: s.bodyType ?? 'json',
+        params: Object.keys(s.params ?? {}),
+        body: Object.keys(s.data ?? {}),
+        response: contracts[e.id] ? Object.keys(flatten(contracts[e.id].shape)) : [],
+        seenAt: s.seenAt,
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** coverage and pass rate over previous runs, for the trend line */
+function trends(runs) {
+  return runs.slice(-30).map((r) => ({
+    at: r.at,
+    ran: r.ran,
+    passed: r.passed,
+    failed: r.failed,
+    passRate: pct(r.passed, r.ran),
+    captured: r.captured,
+    coverage: r.coveragePct,
+  }));
+}
+
+export function buildReport({ catalog, endpoints, samples, results, contracts, runs = [], env }) {
+  return {
+    generatedAt: new Date().toISOString(),
+    authHeader: catalog.auth?.header ?? 'Authorization',
+    sourceLabel: catalog.sourceLabel ?? 'the source',
+    env,
+    baseUrl: catalog.baseUrls?.[env],
+    scannedAt: catalog.scannedAt,
+    coverage: coverage(endpoints, samples),
+    health: health(endpoints, results),
+    drift: drift(endpoints, results, contracts),
+    auth: authSurface(endpoints),
+    hygiene: hygiene(endpoints, samples),
+    risks: risks(endpoints, samples, results),
+    performance: performance(endpoints, samples, results),
+    inventory: inventory(endpoints, samples, contracts),
+    trends: trends(runs),
+  };
+}
+
+/* ------------------------------------------------------------------ markdown */
+
+const list = (items, fmt = (x) => x) =>
+  items.length ? items.map((i) => `- ${fmt(i)}`).join('\n') : '_none_';
+
+export function toMarkdown(r) {
+  const c = r.coverage;
+  const h = r.health;
+
+  return `# API report
+
+**${r.env}** · \`${r.baseUrl ?? ''}\` · generated ${new Date(r.generatedAt).toLocaleString()}
+Catalog scanned ${new Date(r.scannedAt).toLocaleString()}
+
+| | |
+| --- | --- |
+| Endpoints | ${c.total} across ${c.modules.length} modules |
+| Exercised | ${c.seen} (${c.pct}%) |
+| Passing | ${h.passed} of ${h.run} run |
+| Failing | ${h.failed}${h.regressions.length ? ` (${h.regressions.length} regressions)` : ''} |
+| Contract drift | ${r.drift.length} |
+| Never exercised | ${c.total - c.seen} |
+
+## Coverage by module
+
+| Module | Exercised | Total | % |
+| --- | ---: | ---: | ---: |
+${c.modules.map((m) => `| ${m.module} | ${m.seen} | ${m.total} | ${m.pct}% |`).join('\n')}
+
+Untouched modules (${c.untouched.length}): ${c.untouched.join(', ') || '_none_'}
+
+## Failing endpoints
+
+${
+  h.failing.length
+    ? `| Endpoint | Method | Status | Body code | Message |
+| --- | --- | ---: | ---: | --- |
+${h.failing
+  .map(
+    (f) =>
+      `| ${f.id}${f.regression ? ' ⚠️' : ''} | ${f.method} | ${f.status ?? '—'} | ${
+        f.innerCode ?? '—'
+      } | ${(f.message ?? '').replace(/\|/g, '\\|')} |`,
+  )
+  .join('\n')}
+
+⚠️ = was passing before this run`
+    : '_nothing failing_'
+}
+
+## Contract drift
+
+${
+  r.drift.length
+    ? r.drift.map((d) => `- **${d.id}** — \`${d.summary}\``).join('\n')
+    : '_no response shapes have changed_'
+}
+
+## Risks
+
+- Writes never exercised (${r.risks.untestedWrites.length}): ${r.risks.untestedWrites.slice(0, 15).join(', ') || '_none_'}${r.risks.untestedWrites.length > 15 ? `, and ${r.risks.untestedWrites.length - 15} more` : ''}
+- Captured DELETEs (${r.risks.capturedDeletes.length}): ${r.risks.capturedDeletes.join(', ') || '_none_'}
+- 2xx carrying an error code (${r.risks.envelopeErrors.length}): ${r.risks.envelopeErrors.map((e) => `${e.id} (${e.innerCode})`).join(', ') || '_none_'}
+- Payloads with stripped secrets (${r.risks.redactedPayloads.length}): ${r.risks.redactedPayloads.join(', ') || '_none_'}
+
+## Auth surface
+
+- Signed \`ACCESS_TOKEN\` (${r.auth.accessToken.length}): ${r.auth.accessToken.join(', ') || '_none_'}
+- \`SECRET_TOKEN\` (${r.auth.secretToken.length}): ${r.auth.secretToken.join(', ') || '_none_'}
+- CS token (${r.auth.csToken.length}): ${r.auth.csToken.join(', ') || '_none_'}
+- Third-party, no token sent (${r.auth.thirdParty.length}): ${r.auth.thirdParty.join(', ') || '_none_'}
+- Standard \`${r.authHeader}\`: ${r.auth.standard}
+
+## Hygiene
+
+**Referenced nowhere (${r.hygiene.unused.length})**
+${list(r.hygiene.unused, (u) => `\`${u.id}\` — ${u.file}:${u.line}`)}
+
+**Duplicate routes (${r.hygiene.duplicates.length})**
+${list(r.hygiene.duplicates, (d) => `\`${d.route}\` — ${d.ids.join(', ')}`)}
+
+**Called but not found in ${r.sourceLabel} (${r.hygiene.uncatalogued.length})**
+${list(r.hygiene.uncatalogued, (u) => `\`${u.from ?? u.id}\``)}
+
+## Latency
+
+Median ${r.performance.median}ms · p95 ${r.performance.p95}ms · ${r.performance.samples} endpoints
+_${r.performance.caveat}_
+
+${list(r.performance.slowest, (s) => `${s.ms}ms — ${s.id}`)}
+
+## Request and response inventory
+
+${r.inventory
+  .map(
+    (i) =>
+      `### ${i.method} ${i.path}\n\`${i.id}\`${i.bodyType !== 'json' ? ` · ${i.bodyType}` : ''}\n\n` +
+      `- params: ${i.params.join(', ') || '_none_'}\n` +
+      `- body: ${i.body.join(', ') || '_none_'}\n` +
+      `- response: ${i.response.slice(0, 25).join(', ') || '_not recorded_'}${
+        i.response.length > 25 ? `, and ${i.response.length - 25} more` : ''
+      }`,
+  )
+  .join('\n\n')}
+${
+  r.trends.length
+    ? `\n## Trend\n\n| When | Ran | Passed | Failed | Pass rate | Coverage |\n| --- | ---: | ---: | ---: | ---: | ---: |\n${r.trends
+        .map(
+          (t) =>
+            `| ${new Date(t.at).toLocaleString()} | ${t.ran} | ${t.passed} | ${t.failed} | ${t.passRate}% | ${t.coverage ?? '—'}% |`,
+        )
+        .join('\n')}`
+    : ''
+}
+`;
+}

package/cli/scan.mjs

@@ -0,0 +1,142 @@
+/**
+ * Reads a codebase and writes the endpoint catalog.
+ *
+ * The catalog is the thing everything else hangs off: the console lists it, the
+ * recorder's traffic is matched back against it, and the report measures
+ * coverage against it. It is a plain JSON file, so a deployed console needs no
+ * source and no build — just the file that shipped with it.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
+import { PRESETS, holesIn, lineOf, stripComments } from './presets.mjs';
+import { collectFiles, defaults, guessAuth, guessBaseUrls, guessPreset } from './config.mjs';
+
+/**
+ * Files, other than its own, that mention this name.
+ *
+ * ponytail: a plain substring count, so `import * as services` or a re-export
+ * would hide a real usage. Confirm with a grep before deleting anything; switch
+ * to an import graph if that ever bites.
+ */
+function usageCount(name, sources, ownFile) {
+  const re = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+  let n = 0;
+  for (const src of sources) {
+    if (src.file === ownFile) continue;
+    if (re.test(src.text)) n++;
+  }
+  return n;
+}
+
+/** which token a call carries beyond the standard one, when the source says so */
+function customTokenIn(chunk) {
+  const hit = chunk.match(/\b(customJWToken|CSToken|secretToken|accessToken|ACCESS_TOKEN|SECRET_TOKEN|CS_TOKEN)\b/);
+  if (!hit) return null;
+  return { customJWToken: 'ACCESS_TOKEN', accessToken: 'ACCESS_TOKEN', ACCESS_TOKEN: 'ACCESS_TOKEN', CSToken: 'CS token', CS_TOKEN: 'CS token', secretToken: 'SECRET_TOKEN', SECRET_TOKEN: 'SECRET_TOKEN' }[hit[1]] ?? null;
+}
+
+/**
+ * Builds the catalog. Everything is passed in, so this runs the same way from
+ * the CLI, from a test, or from another tool.
+ */
+export function scanProject(root, config = defaults) {
+  const files = collectFiles(root, config);
+  const preset = config.preset ?? guessPreset(files, config).preset;
+  const parse = config.parse ?? (preset ? PRESETS[preset] : null);
+  if (!parse) {
+    return { preset: null, endpoints: [], files, baseUrls: {}, auth: guessAuth(files) };
+  }
+
+  const sources = files.map((file) => {
+    try {
+      return { file, text: readFileSync(file, 'utf8') };
+    } catch {
+      return { file, text: '' };
+    }
+  });
+
+  const endpoints = [];
+  const seen = new Set();
+
+  for (const { file, text } of sources) {
+    const src = stripComments(text);
+    const moduleName = config.moduleOf
+      ? config.moduleOf(file, root)
+      : basename(file, extname(file));
+
+    let found;
+    try {
+      found = parse(src, config);
+    } catch {
+      continue; // one unparseable file must not sink the scan
+    }
+
+    for (const hit of found) {
+      const id = `${moduleName}.${hit.name}`;
+      /*
+       * Two service functions can legitimately call the same route with
+       * different payloads, so the fingerprint includes the function name --
+       * keying on method+path alone silently collapses them into one.
+       */
+      const fingerprint = `${hit.method} ${hit.subUrl} ${id}`;
+      if (seen.has(fingerprint)) continue;
+      seen.add(fingerprint);
+
+      endpoints.push({
+        id,
+        module: moduleName,
+        name: hit.name,
+        method: hit.method,
+        subUrl: hit.subUrl,
+        dynamicUrl: hit.dynamicUrl || undefined,
+        holes: holesIn(hit.subUrl),
+        usesParams: Boolean(hit.usesParams),
+        usesData: Boolean(hit.usesData),
+        absolute: Boolean(hit.absolute),
+        customToken: customTokenIn(hit.chunk ?? ''),
+        file: relative(root, file),
+        line: lineOf(src, hit.index ?? 0),
+      });
+    }
+  }
+
+  endpoints.sort((a, b) => a.id.localeCompare(b.id));
+  for (const ep of endpoints) {
+    ep.usedIn = usageCount(ep.name, sources, resolve(root, ep.file));
+  }
+
+  return {
+    preset,
+    endpoints,
+    files,
+    baseUrls: Object.keys(config.baseUrls ?? {}).length ? config.baseUrls : guessBaseUrls(files),
+    auth: config.auth?.header && config.auth.header !== defaults.auth.header ? config.auth : guessAuth(files),
+  };
+}
+
+/** writes the catalog, keeping an existing one when there is no source to read */
+export function writeCatalog(out, catalog) {
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${JSON.stringify(catalog, null, 2)}\n`);
+}
+
+export function scanToFile(root, config, out) {
+  const result = scanProject(root, config);
+
+  // a deployed console ships with a catalog and no app source
+  if (!result.endpoints.length && existsSync(out)) {
+    const kept = JSON.parse(readFileSync(out, 'utf8'));
+    return { ...kept, kept: true, preset: result.preset };
+  }
+
+  const catalog = {
+    scannedAt: new Date().toISOString(),
+    preset: result.preset,
+    baseUrls: result.baseUrls,
+    auth: result.auth,
+    envelope: config.envelope ?? defaults.envelope,
+    endpoints: result.endpoints,
+  };
+  writeCatalog(out, catalog);
+  return catalog;
+}