api-tracer-kit 1.0.1 → 1.1.0

package/cli/setup.mjs

@@ -0,0 +1,182 @@
+/**
+ * `api-tracer setup` — wire the tracer into an application.
+ *
+ * Writing this file by hand is three decisions people get wrong: where the
+ * entry point is, which environment flag the bundler will actually fold, and
+ * that `init()` must be called from exactly one place. So the command makes all
+ * three, and is safe to re-run.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+
+/** the frameworks we can tell apart, and how each one gates a dev-only import */
+const FRAMEWORKS = {
+  cra: {
+    label: 'Create React App',
+    /*
+     * REACT_APP_ENV, not NODE_ENV: a dev or stage deploy is a production build,
+     * so gating on NODE_ENV would compile the tracer out of exactly the
+     * environments it is meant for. Compared directly rather than through a
+     * variable so DefinePlugin substitutes the literal and the branch folds.
+     */
+    gate: `const isEnabled =\n  process.env.REACT_APP_ENV === "dev" || process.env.REACT_APP_ENV === "stage";`,
+    envLabel: 'process.env.REACT_APP_ENV',
+    consoleUrl: `process.env.REACT_APP_API_CONSOLE_URL ||\n  process.env.REACT_APP_TRACKER_URL ||\n  "http://localhost:4400"`,
+    entries: ['src/index.js', 'src/index.jsx', 'src/index.tsx', 'src/index.ts'],
+  },
+  vite: {
+    label: 'Vite',
+    gate: `const isEnabled = import.meta.env.DEV;`,
+    envLabel: 'import.meta.env.MODE',
+    consoleUrl: `import.meta.env.VITE_API_CONSOLE_URL || "http://localhost:4400"`,
+    entries: ['src/main.ts', 'src/main.tsx', 'src/main.js', 'src/main.jsx'],
+  },
+  next: {
+    label: 'Next.js',
+    gate: `const isEnabled = process.env.NODE_ENV === "development";`,
+    envLabel: 'process.env.NODE_ENV',
+    consoleUrl: `process.env.NEXT_PUBLIC_API_CONSOLE_URL || "http://localhost:4400"`,
+    entries: ['app/layout.tsx', 'app/layout.jsx', 'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.js'],
+  },
+  node: {
+    label: 'Node / plain JavaScript',
+    gate: `const isEnabled = process.env.NODE_ENV !== "production";`,
+    envLabel: 'process.env.NODE_ENV',
+    consoleUrl: `process.env.API_CONSOLE_URL || "http://localhost:4400"`,
+    entries: ['src/index.js', 'src/index.ts', 'index.js', 'index.mjs', 'src/main.js'],
+  },
+};
+
+/** which framework this project is, from what it actually depends on */
+export function detectFramework(root) {
+  let pkg = {};
+  try {
+    pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  } catch {
+    return 'node';
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps.next) return 'next';
+  if (deps['react-scripts']) return 'cra';
+  if (deps.vite) return 'vite';
+  return 'node';
+}
+
+export const usesAxios = (root) => {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }.axios);
+  } catch {
+    return false;
+  }
+};
+
+export const usesTypeScript = (root) =>
+  existsSync(join(root, 'tsconfig.json'));
+
+/** the first entry file that exists, so the import lands somewhere that runs */
+export function findEntry(root, framework) {
+  for (const candidate of FRAMEWORKS[framework].entries) {
+    if (existsSync(join(root, candidate))) return candidate;
+  }
+  return null;
+}
+
+/**
+ * The module that does the wiring. It is a file rather than a line in the entry
+ * point so that the gate, the console URL and the axios hand-over live together
+ * and are obvious to the next person.
+ */
+export function recorderSource({ framework, axios, envelope }) {
+  const f = FRAMEWORKS[framework];
+  const importAxios = axios ? 'import axios from "axios";\n' : '';
+  const attachAxios = axios
+    ? `  apiTracer.useAxios(axios);\n`
+    : '';
+  const transports = axios
+    ? `    // axios is attached below; the XHR it rides on must not be traced twice\n    transports: [],\n`
+    : '';
+  const envelopeLine = envelope
+    ? `    // this API answers 200 and puts the real verdict in the envelope\n    envelope: { codeFields: ["status", "code"], okField: "success", failFrom: 400 },\n`
+    : '';
+
+  return `/**
+ * Streams every API call this app makes to the API console.
+ *
+ * Generated by \`api-tracer setup\`. Imported once from the entry point.
+ *
+ * This is the only place the tracer is configured. \`init()\` is idempotent: a
+ * second call from somewhere else keeps this configuration and warns about the
+ * options it ignored, which is a confusing way to find out you have two.
+ *
+ * Credentials never leave the browser -- header values and credential-looking
+ * fields are replaced before anything is posted.
+ */
+${importAxios}import { apiTracer } from "api-tracer-kit";
+
+const CONSOLE_URL =
+  ${f.consoleUrl};
+
+${f.gate}
+
+if (isEnabled) {
+  apiTracer.init({
+    reportTo: CONSOLE_URL,
+${envelopeLine}${transports}  });
+${attachAxios}  // eslint-disable-next-line no-console
+  console.info(\`[api-tracer] \${${f.envLabel}}: streaming API calls to \${CONSOLE_URL}\`);
+}
+
+export default isEnabled;
+`;
+}
+
+/** adds the import to the entry file, after the last import already there */
+export function addImport(source, specifier) {
+  if (source.includes(specifier)) return { source, added: false };
+
+  const lines = source.split('\n');
+  let last = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(import\s|const\s+\w+\s*=\s*require\()/.test(lines[i])) last = i;
+    // stop at the first real statement: a later import is inside a function
+    if (last !== -1 && /^\s*(function|class|export default|ReactDOM|createRoot)/.test(lines[i])) break;
+  }
+
+  const line = `import "${specifier}";`;
+  const comment = '// dev only: streams API calls to the console, dropped from a production build';
+  if (last === -1) lines.unshift(comment, line, '');
+  else lines.splice(last + 1, 0, comment, line);
+
+  return { source: lines.join('\n'), added: true };
+}
+
+/** the tracer must be configured in one place; find anyone else doing it */
+export function findExistingInits(root, files) {
+  const hits = [];
+  for (const file of files) {
+    try {
+      const text = readFileSync(join(root, file), 'utf8');
+      if (/\bapiTracer\s*\.\s*init\s*\(|\binitApiTracer\s*\(/.test(text)) hits.push(file);
+    } catch {
+      /* unreadable file is not a conflict */
+    }
+  }
+  return hits;
+}
+
+export function ensureGitignore(root) {
+  const file = join(root, '.gitignore');
+  let text = '';
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    /* no .gitignore yet */
+  }
+  if (/^\.api-tracer\/?$/m.test(text)) return false;
+  const addition = `${text.endsWith('\n') || !text ? '' : '\n'}\n# api-tracer-kit console captures: real request and response bodies\n.api-tracer/\n`;
+  writeFileSync(file, text + addition);
+  return true;
+}
+
+export { FRAMEWORKS };

package/cli/test.mjs

@@ -14,6 +14,7 @@ import { guessAuth, guessBaseUrls, guessPreset, collectFiles, defaults } from '.
 import { importHar, importCurl, matchEndpoint, parseQuery, toComparablePath } from './import.mjs';
 import { shapeOf, diffShapes, summarizeDrift } from './shape.mjs';
 import { buildReport, toMarkdown } from './report.mjs';
+import { addImport, detectFramework, findEntry, findExistingInits, recorderSource, usesAxios, usesTypeScript } from './setup.mjs';
 
 let checks = 0;
 const check = (name, fn) => {
@@ -335,6 +336,102 @@ check('the markdown export renders without a run history', () => {
   assert.match(md, /Standard `X_AUTH`/);
 });
 
+/* --- setup: wiring the tracer into an app ----------------------------- */
+
+const app = (deps, files) => {
+  const dir = mkdtempSync(join(tmpdir(), 'api-tracer-setup-'));
+  mkdirSync(join(dir, 'src'), { recursive: true });
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'x', dependencies: deps }));
+  for (const [name, text] of Object.entries(files)) {
+    mkdirSync(join(dir, name.split('/').slice(0, -1).join('/') || '.'), { recursive: true });
+    writeFileSync(join(dir, name), text);
+  }
+  return dir;
+};
+
+check('the framework is detected from what the project depends on', () => {
+  assert.equal(detectFramework(app({ 'react-scripts': '5' }, {})), 'cra');
+  assert.equal(detectFramework(app({ vite: '5' }, {})), 'vite');
+  assert.equal(detectFramework(app({ next: '14' }, {})), 'next');
+  assert.equal(detectFramework(app({}, {})), 'node');
+  // Next ships React too, so the more specific answer has to win
+  assert.equal(detectFramework(app({ next: '14', react: '18' }, {})), 'next');
+});
+
+check('axios and TypeScript are detected rather than assumed', () => {
+  assert.equal(usesAxios(app({ axios: '1' }, {})), true);
+  assert.equal(usesAxios(app({}, {})), false);
+  assert.equal(usesTypeScript(app({}, { 'tsconfig.json': '{}' })), true);
+  assert.equal(usesTypeScript(app({}, {})), false);
+});
+
+check('the entry file is the first one that actually exists', () => {
+  assert.equal(findEntry(app({}, { 'src/index.js': '' }), 'cra'), 'src/index.js');
+  assert.equal(findEntry(app({}, { 'src/main.tsx': '' }), 'vite'), 'src/main.tsx');
+  assert.equal(findEntry(app({}, { 'pages/_app.tsx': '' }), 'next'), 'pages/_app.tsx');
+  assert.equal(findEntry(app({}, {}), 'cra'), null, 'a project with no entry says so');
+});
+
+check('the CRA gate folds away in a production build', () => {
+  const src = recorderSource({ framework: 'cra', axios: true, envelope: true });
+  // compared directly, not through a variable, so DefinePlugin can substitute it
+  assert.match(src, /process\.env\.REACT_APP_ENV === "dev"/);
+  assert.ok(!/NODE_ENV/.test(src), 'NODE_ENV would compile it out of dev and stage deploys');
+});
+
+check('axios is attached only when the project uses it', () => {
+  assert.match(recorderSource({ framework: 'cra', axios: true }), /useAxios\(axios\)/);
+  assert.match(recorderSource({ framework: 'cra', axios: true }), /transports: \[\]/);
+  const without = recorderSource({ framework: 'cra', axios: false });
+  assert.ok(!/useAxios/.test(without));
+  assert.ok(!/from "axios"/.test(without), 'no import of a package that is not there');
+});
+
+check('each framework gets the gate and env convention that works for it', () => {
+  assert.match(recorderSource({ framework: 'vite', axios: false }), /import\.meta\.env\.DEV/);
+  assert.match(recorderSource({ framework: 'vite', axios: false }), /VITE_API_CONSOLE_URL/);
+  assert.match(recorderSource({ framework: 'next', axios: false }), /NEXT_PUBLIC_API_CONSOLE_URL/);
+  assert.match(recorderSource({ framework: 'node', axios: false }), /NODE_ENV !== "production"/);
+});
+
+check('the envelope is included unless the API is said not to need it', () => {
+  assert.match(recorderSource({ framework: 'cra', axios: false, envelope: true }), /envelope:/);
+  assert.ok(!/envelope:/.test(recorderSource({ framework: 'cra', axios: false, envelope: false })));
+});
+
+check('the import goes in after the last top-level import', () => {
+  const entry = 'import React from "react";\nimport App from "./App";\n\nReactDOM.render(<App />, root);\n';
+  const { source, added } = addImport(entry, './apiTracer');
+  assert.equal(added, true);
+  const lines = source.split('\n');
+  assert.match(lines[2], /^\/\//, 'a comment explains why it is there');
+  assert.equal(lines[3], 'import "./apiTracer";');
+  assert.ok(source.indexOf('import "./apiTracer"') < source.indexOf('ReactDOM.render'));
+});
+
+check('running setup twice does not import twice', () => {
+  const entry = 'import React from "react";\n';
+  const once = addImport(entry, './apiTracer').source;
+  const twice = addImport(once, './apiTracer');
+  assert.equal(twice.added, false);
+  assert.equal(twice.source, once);
+});
+
+check('an entry file with no imports still gets one', () => {
+  const { source, added } = addImport('console.log("hi");\n', './apiTracer');
+  assert.equal(added, true);
+  assert.match(source.split('\n')[1], /^import "/);
+});
+
+check('a stray init() somewhere else is found and reported', () => {
+  const dir = app({}, {
+    'src/services/index.js': 'import { apiTracer } from "api-tracer-kit";\napiTracer.init();\n',
+    'src/clean.js': 'export const x = 1;\n',
+  });
+  const found = findExistingInits(dir, ['src/services/index.js', 'src/clean.js', 'src/missing.js']);
+  assert.deepEqual(found, ['src/services/index.js'], 'the exact mistake that leaves a tracer reporting nowhere');
+});
+
 rmSync(project, { recursive: true, force: true });
 rmSync(other, { recursive: true, force: true });
 rmSync(fetchy, { recursive: true, force: true });

package/docs/architecture.md

@@ -0,0 +1,136 @@
+# Architecture
+
+```
+api-tracer-kit
+├── src/                    the runtime tracer (TypeScript)
+│   ├── core/
+│   │   ├── tracer.ts       the instance: options, storage, subscribers, adapters
+│   │   ├── types.ts        the public data model
+│   │   ├── env.ts          runtime detection and trace ids
+│   │   ├── global.ts       the cross-bundle registry
+│   │   ├── redact.ts       credential redaction
+│   │   ├── body.ts         reading bodies without breaking them
+│   │   ├── url.ts          absolute URLs, axios-style query serialization
+│   │   └── envelope.ts     reading a verdict out of a 2xx body
+│   ├── adapters/
+│   │   ├── fetch.ts        global fetch
+│   │   ├── xhr.ts          XMLHttpRequest prototype
+│   │   ├── axios.ts        an axios instance and everything it creates
+│   │   └── suppress.ts     stops axios-on-XHR being counted twice
+│   ├── storage/memory.ts   the capped in-memory default
+│   ├── transport/report.ts posting finished traces to a console
+│   ├── ui/index.tsx        the React panel
+│   ├── index.ts            api-tracer-kit
+│   ├── axios.ts            api-tracer-kit/axios
+│   └── react.ts            api-tracer-kit/react
+└── cli/                    the console (plain ESM, no build step)
+    ├── bin/api-tracer.mjs  the command
+    ├── presets.mjs         how to find endpoints in a codebase
+    ├── config.mjs          defaults, and guessing what was not configured
+    ├── scan.mjs            source -> endpoint catalog
+    ├── server.mjs          forwards calls, replays, exports, records
+    ├── import.mjs          HAR and cURL, matched back to the catalog
+    ├── shape.mjs           response shapes and drift diffing
+    ├── report.mjs          the report model and its Markdown export
+    └── web/                the dashboard: no framework, no build
+```
+
+## The two halves
+
+The **tracer** is framework-free and knows nothing about any application. It
+records what happened and hands it to whoever asked.
+
+The **console** knows nothing about any application either: the catalog supplies
+the endpoints, base URLs, auth header and envelope convention, and the config
+file supplies the sign-in flow. Everything project-specific lives in generated
+data or in your config, never in the code.
+
+They are useful separately. The tracer with no console is an in-app panel and a
+subscriber API. The console with no tracer still scans your source, still lets
+you fire endpoints, and still imports a HAR.
+
+## Design constraints
+
+Three rules shaped most of the code.
+
+### It must never change what the application sees
+
+Every adapter is written around this. Responses are read from a `clone()` after
+the original has been returned, never before. Request bodies that are streams
+are described rather than consumed. Errors are rethrown as they arrived. XHR is
+observed with `addEventListener`, never by taking `onload` — that property
+belongs to the caller. A subscriber that throws is caught, because a bad
+listener must not be able to break a request.
+
+Where a body cannot be read safely — a stream, a huge payload, a binary blob —
+it is recorded as omitted with a reason, rather than read anyway.
+
+### It must never grow without limit
+
+The default store is a capped ring. Bodies over a size limit are recorded as
+omitted rather than copied. The reporter gives up after six consecutive
+failures. A tracer that leaks is worse than no tracer.
+
+### It must be removable
+
+`destroy()` restores every patched global and every axios adapter, including
+instances created through the patched `create()`. `fetch` is only restored if
+nothing else has patched it since — clobbering another tool's interceptor on the
+way out would be worse than leaving ours in place.
+
+## Two problems worth explaining
+
+### The cross-bundle registry
+
+A package with several entry points is bundled once per entry. So
+`api-tracer-kit` and `api-tracer-kit/axios` would each get their own copy of the
+module graph — and their own "shared" tracer, which is not shared at all.
+`useAxios()` would attach to an instance `getTraces()` never reads from. Two
+versions of the package in one dependency tree cause the same thing.
+
+`src/core/global.ts` anchors the instance on
+`globalThis[Symbol.for('api-tracer-kit.registry')]`, the one place every copy can
+agree on.
+
+### Counting an axios call once
+
+In a browser axios rides on `XMLHttpRequest`, so a call would be seen by both
+adapters. axios builds and opens its XHR **synchronously** inside its adapter, so
+the axios adapter raises a counter around the adapter call: it is still up when
+`open` and `send` run, and down again before anything else can start a request.
+That makes the suppression exact rather than time-based.
+
+The axios adapter wraps the instance's *adapter* rather than only its
+interceptors, because the adapter is the one place both the request and the raw
+response are available — and it is where the XHR is created, which is what makes
+the suppression possible. The property is installed as an accessor, so an
+application that later assigns `axios.defaults.adapter` replaces what the wrapper
+calls rather than the wrapper itself.
+
+## The scanner
+
+Regex-based, per preset, and honest about it. A parser would need a dependency
+per language and per flavour of syntax and would still not understand a template
+literal assembled from three variables.
+
+Which preset applies is decided by **running every preset over a sample of the
+codebase and keeping whichever finds the most**. Guessing by looking for marker
+strings was tried first and was wrong often enough to matter — a project can
+import axios and still not use it for its API layer. Running the presets asks
+the only question that counts: which one actually reads this code?
+
+The sample is weighted towards paths that look like an API layer, so the guess
+is made on the code that matters rather than the first hundred components in
+alphabetical order.
+
+What the scanner misses, live recording covers: a call no endpoint explains is
+adopted as an endpoint of its own rather than dropped.
+
+## The dashboard
+
+Vanilla JavaScript, no framework, no build step — it is served as static files
+straight from the package. JSON editors are syntax highlighted by a coloured
+layer behind a transparent textarea, so even that needs no editor library.
+
+This is deliberate. A dev tool that needs its own toolchain to be maintained is
+a dev tool nobody maintains.