trimcode 0.0.0-stage → 0.1.0

package/src/index.js

@@ -0,0 +1,794 @@
+import { builtinModules } from 'node:module';
+import { readFile } from 'node:fs/promises';
+import { parseSource, ParseError } from './parse.js';
+import { walk } from './walk.js';
+import {
+  propKey,
+  propName,
+  memberPath,
+  calleeName,
+  stringArg,
+  snippet,
+  patternNames,
+  isRequireCall,
+  jsdocSummary,
+} from './util.js';
+
+export { ParseError };
+export const SCHEMA_VERSION = 1;
+
+const BUILTINS = new Set(builtinModules);
+const FUNCTION_TYPES = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
+const CLASS_TYPES = new Set(['ClassDeclaration', 'ClassExpression']);
+const COMPLEXITY_TYPES = new Set([
+  'IfStatement',
+  'ConditionalExpression',
+  'ForStatement',
+  'ForInStatement',
+  'ForOfStatement',
+  'WhileStatement',
+  'DoWhileStatement',
+  'CatchClause',
+]);
+const NESTING_TYPES = new Set([
+  'IfStatement',
+  'ForStatement',
+  'ForInStatement',
+  'ForOfStatement',
+  'WhileStatement',
+  'DoWhileStatement',
+  'SwitchStatement',
+  'TryStatement',
+]);
+// Boundaries when looking for the statement a JSDoc comment is attached to.
+const DOC_BOUNDARY = new Set([
+  'Program',
+  'BlockStatement',
+  'ClassBody',
+  'ObjectExpression',
+  'ArrayExpression',
+  ...FUNCTION_TYPES,
+]);
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'all', 'use']);
+const ROUTER_LIKE = /^(app|router|routes?|server|fastify|express|\w*Router|\w*App)$/i;
+const HTTP_CLIENTS = new Set([
+  'axios', 'fetch', 'http', 'https', 'got', 'ky', 'request', 'superagent', 'supertest', 'agent', 'client', '$http', '$',
+]);
+
+const CONNECTION_CLASSES = new Set(['Pool', 'Client', 'MongoClient', 'Sequelize', 'PrismaClient', 'Redis', 'WebSocket']);
+const SERVER_CLASSES = new Set(['WebSocketServer']);
+const CHILD_PROCESS_FNS = new Set(['exec', 'execSync', 'execFile', 'execFileSync', 'spawn', 'spawnSync', 'fork']);
+const FS_OPERATION =
+  /(Sync$)|^(readFile|writeFile|appendFile|mkdir|mkdtemp|rm|rmdir|unlink|rename|copyFile|cp|readdir|stat|access|truncate|chmod|chown|symlink|createReadStream|createWriteStream|watch|watchFile)$/;
+
+const SIDE_EFFECT_PHRASES = {
+  'server-listen': 'starts a server',
+  'server-create': 'creates a server',
+  connection: 'opens connections',
+  'env-load': 'loads environment variables from a file',
+  'process-handler': 'registers process event handlers',
+  'process-exit': 'can exit the process',
+  timer: 'schedules timers',
+  filesystem: 'touches the filesystem',
+  'child-process': 'spawns child processes',
+  'console-output': 'writes to the console',
+  'global-mutation': 'modifies globals',
+  'top-level-await': 'awaits at the top level',
+};
+
+// ---------------------------------------------------------------------------
+// Imports
+// ---------------------------------------------------------------------------
+
+function classifySpecifier(specifier) {
+  if (specifier.startsWith('node:')) return { kind: 'builtin', name: specifier.slice(5) };
+  if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('#')) {
+    return { kind: 'local', name: specifier };
+  }
+  if (BUILTINS.has(specifier)) return { kind: 'builtin', name: specifier };
+  const parts = specifier.split('/');
+  const name = specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+  return { kind: 'package', name };
+}
+
+function makeImport(source, style, line, { binding, names } = {}) {
+  const entry = { source };
+  if (source === null) {
+    entry.kind = 'dynamic';
+  } else {
+    const c = classifySpecifier(source);
+    entry.kind = c.kind;
+    if (c.kind === 'package') entry.package = c.name;
+  }
+  entry.style = style;
+  if (binding) entry.binding = binding;
+  if (names?.length) entry.names = names;
+  entry.line = line;
+  return entry;
+}
+
+/** First pass: every import/require/import(), plus a map from local names to module specifiers. */
+function collectImports(ast) {
+  const imports = [];
+  const bindings = new Map();
+
+  const register = (entry, locals) => {
+    imports.push(entry);
+    if (entry.source !== null) for (const name of locals) bindings.set(name, entry.source);
+  };
+
+  walk(ast, {
+    enter(node, anc) {
+      const parent = anc[anc.length - 1];
+
+      if (node.type === 'ImportDeclaration') {
+        const locals = [];
+        const names = [];
+        let binding;
+        for (const spec of node.specifiers) {
+          locals.push(spec.local.name);
+          if (spec.type === 'ImportSpecifier') names.push(spec.imported.name ?? String(spec.imported.value));
+          else binding = spec.local.name;
+        }
+        register(makeImport(node.source.value, 'import', node.loc.start.line, { binding, names }), locals);
+        return;
+      }
+
+      if (node.type === 'ImportExpression') {
+        register(makeImport(stringArg(node.source), 'dynamic-import', node.loc.start.line), []);
+        return;
+      }
+
+      if (isRequireCall(node)) {
+        let binding;
+        let names;
+        let locals = [];
+        if (parent?.type === 'VariableDeclarator' && parent.init === node) {
+          if (parent.id.type === 'Identifier') {
+            binding = parent.id.name;
+            locals = [binding];
+          } else if (parent.id.type === 'ObjectPattern') {
+            names = parent.id.properties
+              .filter((p) => p.type === 'Property')
+              .map((p) => propKey(p.key, p.computed))
+              .filter(Boolean);
+            locals = patternNames(parent.id);
+          }
+        } else if (parent?.type === 'MemberExpression' && parent.object === node) {
+          const key = propName(parent);
+          if (key) names = [key];
+          const grand = anc[anc.length - 2];
+          if (grand?.type === 'VariableDeclarator' && grand.init === parent && grand.id.type === 'Identifier') {
+            locals = [grand.id.name];
+          }
+        }
+        register(makeImport(stringArg(node.arguments[0]), 'require', node.loc.start.line, { binding, names }), locals);
+      }
+    },
+  });
+
+  return { imports, bindings };
+}
+
+// ---------------------------------------------------------------------------
+// Naming helpers
+// ---------------------------------------------------------------------------
+
+/** `module.exports` / `exports.x` / any other assignment target as { name, exported }. */
+function assignTarget(left) {
+  const path = memberPath(left);
+  if (!path) return null;
+  if (path === 'module.exports') return { name: 'module.exports', exported: true };
+  const m = /^(?:module\.)?exports\.([^.]+)$/.exec(path);
+  if (m) return { name: m[1], exported: true };
+  return { name: path, exported: false };
+}
+
+/** The name a function/class expression is bound to by its parent, if any. */
+function bindingName(node, anc) {
+  const parent = anc[anc.length - 1];
+  if (!parent) return null;
+  switch (parent.type) {
+    case 'VariableDeclarator':
+      return parent.init === node && parent.id.type === 'Identifier' ? { name: parent.id.name } : null;
+    case 'AssignmentExpression':
+      return parent.right === node && parent.operator === '=' ? assignTarget(parent.left) : null;
+    case 'ExportDefaultDeclaration':
+      return { name: 'default' };
+    case 'Property': {
+      if (parent.value !== node) return null;
+      const key = propKey(parent.key, parent.computed);
+      if (!key) return null;
+      const object = anc[anc.length - 2];
+      const owner = anc[anc.length - 3];
+      if (object?.type === 'ObjectExpression') {
+        if (owner?.type === 'VariableDeclarator' && owner.init === object && owner.id.type === 'Identifier') {
+          return { name: `${owner.id.name}.${key}` };
+        }
+        if (owner?.type === 'AssignmentExpression' && owner.right === object) {
+          const target = assignTarget(owner.left);
+          if (target?.name === 'module.exports') return { name: key, exported: true };
+          if (target) return { name: `${target.name}.${key}` };
+        }
+      }
+      return { name: key };
+    }
+    default:
+      return null;
+  }
+}
+
+function methodKey(code, key, computed) {
+  return propKey(key, computed) ?? `[${snippet(code, key, 40)}]`;
+}
+
+function describeFunction(code, node, anc, classStack, routeNames) {
+  const parent = anc[anc.length - 1];
+  const cls = classStack[classStack.length - 1];
+  const className = cls?.name ?? '<anonymous>';
+
+  if (parent?.type === 'MethodDefinition' && parent.value === node) {
+    const kind =
+      parent.kind === 'constructor' ? 'constructor' : parent.kind === 'get' ? 'getter' : parent.kind === 'set' ? 'setter' : 'method';
+    const key = methodKey(code, parent.key, parent.computed);
+    return { name: `${className}.${key}`, kind, isStatic: parent.static, classMethod: { cls, key } };
+  }
+  if (parent?.type === 'PropertyDefinition' && parent.value === node) {
+    const key = methodKey(code, parent.key, parent.computed);
+    return { name: `${className}.${key}`, kind: 'method', isStatic: parent.static, classMethod: { cls, key } };
+  }
+
+  const routeName = routeNames.get(node);
+  if (routeName) return { name: routeName, kind: 'route-handler' };
+
+  const kind = node.type === 'ArrowFunctionExpression' ? 'arrow' : 'function';
+  if (node.type === 'FunctionDeclaration') return { name: node.id?.name ?? 'default', kind };
+
+  const bound = bindingName(node, anc);
+  if (bound) return { name: bound.name, kind, exported: bound.exported };
+  if (node.id) return { name: node.id.name, kind };
+  return null;
+}
+
+/** JSDoc summary attached to the statement that contains `node`, if any. */
+function findDoc(node, anc, docsByEndLine, usedDocs) {
+  const lines = [node.loc.start.line];
+  for (let i = anc.length - 1; i >= 0; i--) {
+    if (DOC_BOUNDARY.has(anc[i].type)) break;
+    lines.push(anc[i].loc.start.line);
+  }
+  for (const line of lines) {
+    for (const endLine of [line - 1, line]) {
+      const doc = docsByEndLine.get(endLine);
+      if (doc && !usedDocs.has(doc)) {
+        usedDocs.add(doc);
+        return jsdocSummary(doc.value);
+      }
+    }
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Routes
+// ---------------------------------------------------------------------------
+
+function handlerLabel(arg, routeLabel) {
+  switch (arg.type) {
+    case 'Identifier':
+      return arg.name;
+    case 'MemberExpression':
+      return memberPath(arg) ?? '<expression>';
+    case 'CallExpression': {
+      const name = calleeName(arg.callee);
+      return name ? `${name}()` : '<expression>';
+    }
+    case 'FunctionExpression':
+    case 'ArrowFunctionExpression':
+      return routeLabel;
+    default:
+      return '<expression>';
+  }
+}
+
+/**
+ * Recognise `app.get('/x', ...handlers)` and `router.route('/x').get(...handlers)`.
+ * This is a heuristic: HTTP-client calls such as `axios.get('/x')` are excluded.
+ */
+function detectRoute(node) {
+  const callee = node.callee;
+  if (callee.type !== 'MemberExpression') return null;
+  const method = propName(callee);
+  if (!method || !HTTP_METHODS.has(method)) return null;
+
+  let path = null;
+  let handlerArgs = node.arguments;
+  let viaRoute = false;
+
+  let object = callee.object;
+  while (object?.type === 'CallExpression' && object.callee.type === 'MemberExpression') {
+    if (propName(object.callee) === 'route') {
+      path = stringArg(object.arguments[0]);
+      viaRoute = true;
+      break;
+    }
+    object = object.callee.object;
+  }
+
+  if (!viaRoute) {
+    path = stringArg(node.arguments[0]);
+    handlerArgs = node.arguments.slice(1);
+  }
+  if (path === null || !path.startsWith('/')) return null;
+
+  const handlers = handlerArgs.filter((a) => a.type !== 'ObjectExpression' && a.type !== 'Literal' && a.type !== 'SpreadElement');
+  if (handlers.length === 0) return null;
+
+  if (!viaRoute) {
+    const objectPath = memberPath(callee.object);
+    const root = objectPath?.split('.')[0];
+    const leaf = objectPath?.split('.').pop();
+    if ((root && HTTP_CLIENTS.has(root)) || (leaf && HTTP_CLIENTS.has(leaf))) return null;
+    const hasInlineFunction = handlers.some((a) => a.type === 'FunctionExpression' || a.type === 'ArrowFunctionExpression');
+    const looksLikeRouter = Boolean((root && ROUTER_LIKE.test(root)) || (leaf && ROUTER_LIKE.test(leaf)));
+    if (!hasInlineFunction && !looksLikeRouter) return null;
+  }
+
+  return { method: method.toUpperCase(), path, handlers };
+}
+
+// ---------------------------------------------------------------------------
+// Side effects
+// ---------------------------------------------------------------------------
+
+function rootModule(callee, bindings) {
+  let n = callee;
+  while (n?.type === 'MemberExpression') n = n.object;
+  if (n?.type === 'ChainExpression') n = n.expression;
+  let specifier;
+  if (n?.type === 'Identifier') specifier = bindings.get(n.name);
+  else if (isRequireCall(n)) specifier = stringArg(n.arguments[0]);
+  return specifier?.replace(/^node:/, '');
+}
+
+function detectCallSideEffect(code, node, bindings) {
+  const name = calleeName(node.callee);
+  if (!name) return null;
+  const last = name.slice(name.lastIndexOf('.') + 1);
+  const mod = rootModule(node.callee, bindings);
+  const firstArg = node.arguments[0] ? snippet(code, node.arguments[0], 50) : undefined;
+
+  if (name === 'process.exit') return { type: 'process-exit', detail: name };
+  if (name === 'process.on' || name === 'process.once') return { type: 'process-handler', detail: firstArg ?? name };
+  if (/^(?:global\.|globalThis\.)?(?:setTimeout|setInterval|setImmediate)$/.test(name)) return { type: 'timer', detail: name };
+  if (last === 'listen') return { type: 'server-listen', detail: firstArg ?? name };
+  if (last === 'createServer' || last === 'createSecureServer') return { type: 'server-create', detail: name };
+  if (mod === 'dotenv' && (last === 'config' || last === 'configDotenv')) return { type: 'env-load', detail: `dotenv.${last}` };
+  if (mod === 'child_process' && CHILD_PROCESS_FNS.has(last)) return { type: 'child-process', detail: name };
+  if ((mod === 'fs' || mod === 'fs/promises') && FS_OPERATION.test(last)) return { type: 'filesystem', detail: name };
+  if (/^(?:connect|createConnection|createPool|createClient)$/.test(last)) return { type: 'connection', detail: name };
+  if (name.startsWith('console.')) return { type: 'console-output', detail: name };
+  return null;
+}
+
+function detectNewSideEffect(node) {
+  const name = calleeName(node.callee);
+  if (!name) return null;
+  const last = name.slice(name.lastIndexOf('.') + 1);
+  if (CONNECTION_CLASSES.has(last)) return { type: 'connection', detail: `new ${name}` };
+  if (SERVER_CLASSES.has(last)) return { type: 'server-create', detail: `new ${name}` };
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Environment variables
+// ---------------------------------------------------------------------------
+
+function isProcessEnv(node) {
+  return (
+    node?.type === 'MemberExpression' &&
+    !node.computed &&
+    node.object.type === 'Identifier' &&
+    node.object.name === 'process' &&
+    node.property.type === 'Identifier' &&
+    node.property.name === 'env'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+function joinList(parts) {
+  if (parts.length <= 1) return parts.join('');
+  return `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;
+}
+
+function buildSummary({ moduleType, lines, dependencies, functions, classes, exportList, routes, sideEffects, env }) {
+  const out = [`${moduleType === 'esm' ? 'ES module' : 'CommonJS module'}, ${plural(lines, 'line')}.`];
+
+  const deps = [];
+  if (dependencies.packages.length) deps.push(plural(dependencies.packages.length, 'npm package'));
+  if (dependencies.builtin.length) deps.push(plural(dependencies.builtin.length, 'Node built-in'));
+  if (dependencies.local.length) deps.push(plural(dependencies.local.length, 'local module'));
+  if (deps.length) out.push(`Depends on ${joinList(deps)}.`);
+
+  const defs = [];
+  if (functions.length) defs.push(plural(functions.length, 'function'));
+  if (classes.length) defs.push(plural(classes.length, 'class').replace('classs', 'classes'));
+  if (defs.length) out.push(`Defines ${joinList(defs)}.`);
+
+  if (exportList.length) out.push(`Exports ${plural(exportList.length, 'name')}.`);
+  if (routes.length) out.push(`Declares ${plural(routes.length, 'HTTP route')}.`);
+
+  const phrases = [...new Set(sideEffects.map((s) => SIDE_EFFECT_PHRASES[s.type]).filter(Boolean))];
+  if (phrases.length) out.push(`When loaded it ${joinList(phrases)}.`);
+  if (env.length) out.push(`Reads ${plural(env.length, 'environment variable')}.`);
+
+  return out.join(' ');
+}
+
+// ---------------------------------------------------------------------------
+// analyze
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyze JavaScript source and return a plain, JSON-serializable summary.
+ *
+ * @param {string} code
+ * @param {{ filename?: string, sourceType?: 'auto' | 'module' | 'script' }} [options]
+ */
+export function analyze(code, options = {}) {
+  if (typeof code !== 'string') throw new TypeError('analyze(code): code must be a string');
+  const { filename = null, sourceType = 'auto' } = options;
+  const text = code.charCodeAt(0) === 0xfeff ? code.slice(1) : code;
+
+  const { ast, comments } = parseSource(text, sourceType);
+  const { imports, bindings } = collectImports(ast);
+
+  const docsByEndLine = new Map();
+  for (const c of comments) {
+    if (c.type === 'Block' && c.value.startsWith('*') && c.loc) docsByEndLine.set(c.loc.end.line, c);
+  }
+  const usedDocs = new Set();
+
+  const functions = [];
+  const classes = [];
+  const exportList = [];
+  const routes = [];
+  const sideEffects = [];
+  const envMap = new Map();
+
+  const frames = new Map(); // function node -> frame
+  const allFrames = [];
+  const recStack = []; // frames of recorded (named) functions
+  const classStack = [];
+  const routeNames = new WeakMap();
+  const iifeNodes = new WeakSet();
+  const skippedNesting = new WeakSet();
+  let fnDepth = 0; // functions entered, not counting IIFEs: "is this code run when the file loads?"
+  let allFnDepth = 0; // every function entered
+  let hasEsmSyntax = false;
+
+  const addSideEffect = (type, detail, node) => {
+    const entry = { type };
+    if (detail) entry.detail = detail;
+    entry.line = node.loc.start.line;
+    sideEffects.push(entry);
+  };
+
+  const noteEnv = (name, node, hasDefault) => {
+    const existing = envMap.get(name);
+    if (existing) existing.hasDefault ||= hasDefault;
+    else envMap.set(name, { name, line: node.loc.start.line, hasDefault });
+  };
+
+  const kindOfValue = (value) => {
+    if (!value) return 'value';
+    if (value.type === 'FunctionExpression' || value.type === 'ArrowFunctionExpression') return 'function';
+    if (value.type === 'ClassExpression') return 'class';
+    if (value.type === 'Identifier') return 'unknown';
+    return 'value';
+  };
+
+  const addExport = (name, value, style, node, extra = {}) => {
+    const entry = { name, kind: extra.kind ?? kindOfValue(value), style };
+    if (extra.from) entry.from = extra.from;
+    const local = 'local' in extra ? extra.local : value?.type === 'Identifier' ? value.name : undefined;
+    if (local && local !== name) entry.local = local;
+    entry.line = node.loc.start.line;
+    exportList.push(entry);
+  };
+
+  walk(ast, {
+    enter(node, anc) {
+      const parent = anc[anc.length - 1];
+      const t = node.type;
+      const top = recStack[recStack.length - 1];
+
+      // ---- ES module syntax -------------------------------------------------
+      if (t === 'ImportDeclaration' || t === 'MetaProperty') hasEsmSyntax = true;
+
+      if (t === 'ExportNamedDeclaration') {
+        hasEsmSyntax = true;
+        const decl = node.declaration;
+        if (decl) {
+          if (decl.type === 'FunctionDeclaration') addExport(decl.id.name, null, 'esm', node, { kind: 'function' });
+          else if (decl.type === 'ClassDeclaration') addExport(decl.id.name, null, 'esm', node, { kind: 'class' });
+          else if (decl.type === 'VariableDeclaration') {
+            for (const d of decl.declarations) {
+              if (d.id.type === 'Identifier') addExport(d.id.name, d.init, 'esm', node, { local: null });
+              else for (const n of patternNames(d.id)) addExport(n, null, 'esm', node, { kind: 'value' });
+            }
+          }
+        }
+        for (const spec of node.specifiers) {
+          const exported = spec.exported.name ?? String(spec.exported.value);
+          const local = spec.local.name ?? String(spec.local.value);
+          if (node.source) {
+            addExport(exported, null, 'esm', node, { kind: 're-export', from: node.source.value, local });
+          } else {
+            addExport(exported, null, 'esm', node, { kind: 'unknown', local });
+          }
+        }
+      } else if (t === 'ExportDefaultDeclaration') {
+        hasEsmSyntax = true;
+        const decl = node.declaration;
+        if (decl.type === 'FunctionDeclaration') {
+          addExport('default', null, 'esm', node, { kind: 'function', local: decl.id?.name });
+        } else if (decl.type === 'ClassDeclaration') {
+          addExport('default', null, 'esm', node, { kind: 'class', local: decl.id?.name });
+        } else {
+          addExport('default', decl, 'esm', node);
+        }
+      } else if (t === 'ExportAllDeclaration') {
+        hasEsmSyntax = true;
+        const exported = node.exported ? (node.exported.name ?? String(node.exported.value)) : '*';
+        addExport(exported, null, 'esm', node, { kind: 're-export', from: node.source.value, local: null });
+      }
+
+      // ---- CommonJS exports & global mutation ------------------------------
+      if (t === 'AssignmentExpression' && node.operator === '=') {
+        const target = assignTarget(node.left);
+        if (target?.exported) {
+          if (target.name !== 'module.exports') {
+            addExport(target.name, node.right, 'commonjs', node);
+          } else if (node.right.type === 'ObjectExpression') {
+            for (const prop of node.right.properties) {
+              if (prop.type !== 'Property') continue;
+              const key = propKey(prop.key, prop.computed);
+              if (key) addExport(key, prop.value, 'commonjs', prop);
+            }
+          } else {
+            addExport('default', node.right, 'commonjs', node);
+          }
+        }
+        if (fnDepth === 0) {
+          const root = memberPath(node.left)?.split('.')[0];
+          if (node.left.type === 'MemberExpression' && (root === 'global' || root === 'globalThis')) {
+            addSideEffect('global-mutation', memberPath(node.left), node);
+          }
+        }
+      }
+
+      // ---- Classes -----------------------------------------------------------
+      if (CLASS_TYPES.has(t)) {
+        const bound = bindingName(node, anc);
+        const cls = {
+          name: node.id?.name ?? bound?.name ?? '<anonymous>',
+          extends: node.superClass ? snippet(text, node.superClass, 60) : null,
+          line: node.loc.start.line,
+          endLine: node.loc.end.line,
+          methods: [],
+          exported: Boolean(bound?.exported),
+        };
+        classes.push(cls);
+        classStack.push(cls);
+      }
+
+      // ---- Functions ---------------------------------------------------------
+      if (FUNCTION_TYPES.has(t)) {
+        allFnDepth++;
+        const isIife = parent?.type === 'CallExpression' && parent.callee === node;
+        if (isIife) iifeNodes.add(node);
+        else fnDepth++;
+
+        const d = describeFunction(text, node, anc, classStack, routeNames);
+        if (d) {
+          const doc = findDoc(node, anc, docsByEndLine, usedDocs);
+          const entry = {
+            name: d.name,
+            kind: d.kind,
+            async: node.async,
+            generator: node.generator,
+            ...(d.isStatic && { static: true }),
+            params: node.params.map((p) => snippet(text, p, 50)),
+            line: node.loc.start.line,
+            endLine: node.loc.end.line,
+            lines: node.loc.end.line - node.loc.start.line + 1,
+            exported: Boolean(d.exported),
+            ...(doc && { doc }),
+            complexity: 1,
+            maxNesting: 0,
+            calls: [],
+            localCalls: [],
+          };
+          functions.push(entry);
+          const frame = { entry, owner: classStack[classStack.length - 1]?.name ?? null, calls: new Set(), depth: 0 };
+          frames.set(node, frame);
+          allFrames.push(frame);
+          recStack.push(frame);
+          if (d.classMethod?.cls) {
+            d.classMethod.cls.methods.push({
+              name: d.classMethod.key,
+              kind: d.kind,
+              static: Boolean(d.isStatic),
+              async: node.async,
+            });
+          }
+        }
+      }
+
+      // ---- Calls, routes, side effects --------------------------------------
+      if (t === 'CallExpression') {
+        const name = calleeName(node.callee);
+        if (top && name && name !== 'require' && !name.startsWith('require()') && !name.startsWith('console.')) {
+          top.calls.add(name);
+        }
+
+        const route = detectRoute(node);
+        if (route) {
+          const label = `${route.method} ${route.path}`;
+          const last = route.handlers[route.handlers.length - 1];
+          if (last.type === 'FunctionExpression' || last.type === 'ArrowFunctionExpression') routeNames.set(last, label);
+          const entry = { method: route.method, path: route.path, handler: handlerLabel(last, label) };
+          const middleware = route.handlers.slice(0, -1).map((h) => handlerLabel(h, 'inline'));
+          if (middleware.length) entry.middleware = middleware;
+          entry.line = node.loc.start.line;
+          routes.push(entry);
+        }
+
+        if (fnDepth === 0) {
+          const effect = detectCallSideEffect(text, node, bindings);
+          if (effect) addSideEffect(effect.type, effect.detail, node);
+        }
+      } else if (t === 'NewExpression' && fnDepth === 0) {
+        const effect = detectNewSideEffect(node);
+        if (effect) addSideEffect(effect.type, effect.detail, node);
+      } else if ((t === 'AwaitExpression' || (t === 'ForOfStatement' && node.await)) && allFnDepth === 0) {
+        hasEsmSyntax = true;
+        addSideEffect('top-level-await', t === 'AwaitExpression' ? snippet(text, node.argument, 50) : 'for await', node);
+      }
+
+      // ---- Environment variables --------------------------------------------
+      if (t === 'MemberExpression' && isProcessEnv(node.object)) {
+        const isWrite = parent?.type === 'AssignmentExpression' && parent.left === node;
+        if (!isWrite) {
+          const hasDefault =
+            parent?.type === 'LogicalExpression' && (parent.operator === '||' || parent.operator === '??') && parent.left === node;
+          noteEnv(propName(node) ?? '<dynamic>', node, hasDefault);
+        }
+      } else if (t === 'VariableDeclarator' && isProcessEnv(node.init) && node.id.type === 'ObjectPattern') {
+        for (const prop of node.id.properties) {
+          if (prop.type !== 'Property') continue;
+          const key = propKey(prop.key, prop.computed);
+          if (key) noteEnv(key, prop, prop.value.type === 'AssignmentPattern');
+        }
+      }
+
+      // ---- Complexity & nesting (attributed to the nearest named function) --
+      if (top) {
+        if (COMPLEXITY_TYPES.has(t) || t === 'LogicalExpression' || (t === 'SwitchCase' && node.test)) {
+          top.entry.complexity++;
+        }
+        if (NESTING_TYPES.has(t)) {
+          if (t === 'IfStatement' && parent?.type === 'IfStatement' && parent.alternate === node) {
+            skippedNesting.add(node); // `else if` stays on the same level
+          } else {
+            top.depth++;
+            top.entry.maxNesting = Math.max(top.entry.maxNesting, top.depth);
+          }
+        }
+      }
+    },
+
+    leave(node) {
+      const t = node.type;
+      if (FUNCTION_TYPES.has(t)) {
+        allFnDepth--;
+        if (!iifeNodes.has(node)) fnDepth--;
+        if (frames.has(node)) recStack.pop();
+      } else if (CLASS_TYPES.has(t)) {
+        classStack.pop();
+      } else if (NESTING_TYPES.has(t) && !skippedNesting.has(node)) {
+        const top = recStack[recStack.length - 1];
+        if (top) top.depth--;
+      }
+    },
+  });
+
+  // `import 'dotenv/config'` loads a .env file just by being imported.
+  for (const imp of imports) {
+    if (imp.source === 'dotenv/config') {
+      sideEffects.push({ type: 'env-load', detail: 'import dotenv/config', line: imp.line });
+    }
+  }
+  sideEffects.sort((a, b) => a.line - b.line);
+
+  // ---- Resolve call graph ----------------------------------------------------
+  const functionNames = new Set(functions.map((f) => f.name));
+  for (const frame of allFrames) {
+    frame.entry.calls = [...frame.calls];
+    const local = new Set();
+    for (const call of frame.calls) {
+      if (functionNames.has(call)) {
+        local.add(call);
+      } else if (call.startsWith('this.') && frame.owner) {
+        const candidate = `${frame.owner}.${call.slice(5)}`;
+        if (functionNames.has(candidate)) local.add(candidate);
+      }
+    }
+    frame.entry.localCalls = [...local];
+  }
+
+  // ---- Resolve export kinds and "exported" flags ---------------------------
+  const classNames = new Set(classes.map((c) => c.name));
+  for (const e of exportList) {
+    if (e.kind !== 'unknown') continue;
+    const target = e.local ?? e.name;
+    e.kind = functionNames.has(target) ? 'function' : classNames.has(target) ? 'class' : 'value';
+  }
+  const exportedNames = new Set(exportList.filter((e) => e.kind !== 're-export').map((e) => e.local ?? e.name));
+  for (const f of functions) if (exportedNames.has(f.name)) f.exported = true;
+  for (const c of classes) if (exportedNames.has(c.name)) c.exported = true;
+
+  // ---- Dependencies ------------------------------------------------------------
+  const dependencies = { builtin: [], packages: [], local: [] };
+  const pushUnique = (list, value) => {
+    if (!list.includes(value)) list.push(value);
+  };
+  for (const imp of imports) {
+    if (imp.source === null) continue;
+    const c = classifySpecifier(imp.source);
+    if (c.kind === 'builtin') pushUnique(dependencies.builtin, c.name);
+    else if (c.kind === 'package') pushUnique(dependencies.packages, c.name);
+    else pushUnique(dependencies.local, c.name);
+  }
+
+  const moduleType = hasEsmSyntax ? 'esm' : 'commonjs';
+  // A final newline ends the last line; it does not start another one.
+  const lines = text === '' ? 0 : text.split(/\r\n|\r|\n/).length - (/(\r\n|\r|\n)$/.test(text) ? 1 : 0);
+  const env = [...envMap.values()];
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    file: filename,
+    moduleType,
+    stats: {
+      lines,
+      imports: imports.length,
+      exports: exportList.length,
+      functions: functions.length,
+      classes: classes.length,
+      routes: routes.length,
+    },
+    summary: buildSummary({ moduleType, lines, dependencies, functions, classes, exportList, routes, sideEffects, env }),
+    dependencies,
+    imports,
+    exports: exportList,
+    functions,
+    classes,
+    routes,
+    sideEffects,
+    env,
+  };
+}
+
+/** Read a file from disk and analyze it. `file` in the result is the path as given. */
+export async function analyzeFile(path, options = {}) {
+  const code = await readFile(path, 'utf8');
+  return analyze(code, { ...options, filename: String(path) });
+}