@gurulu/cli 0.1.1 → 0.1.2

package/scripts/patches/auto-instrument/nestjs.cjs

@@ -0,0 +1,282 @@
+// scripts/patches/auto-instrument/nestjs.cjs — Phase 20 W1 A3.
+//
+// AST-based auto-instrumentation for NestJS controllers. We parse every
+// controller file under `src/**` and look for class methods decorated with
+// `@Get`, `@Post`, etc. whose enclosing class carries a `@Controller('...')`
+// decorator. Matching methods get a `gurulu.track(...)` call inserted
+// before the last top-level return.
+//
+// Route matching: given a ProposedEvent with `source.route = 'POST /users'`
+// we match against `<controllerBase>/<methodPath>` where `controllerBase`
+// comes from the `@Controller('path')` argument and `methodPath` comes from
+// the method decorator argument (optional, defaults to '/').
+
+const fs = require('fs');
+const path = require('path');
+
+const ast = require('./ast-helper.cjs');
+const singleton = require('./singleton-helper.cjs');
+
+const NAME = 'auto-instrument-nestjs';
+const SUPPORTED = ['nestjs'];
+
+const HTTP_DECORATORS = new Set([
+  'Get', 'Post', 'Put', 'Patch', 'Delete', 'Options', 'Head', 'All',
+]);
+
+function parseEventRoute(routeStr) {
+  if (!routeStr || typeof routeStr !== 'string') return null;
+  const m = routeStr.trim().match(/^([A-Z]+)\s+(\/.*)$/);
+  if (!m) return null;
+  return { method: m[1].toUpperCase(), urlPath: m[2].replace(/\/+$/, '') || '/' };
+}
+
+function walkSourceFiles(repoRoot) {
+  const results = [];
+  const stack = ['src'];
+  while (stack.length > 0) {
+    const rel = stack.pop();
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) continue;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const childRel = path.posix.join(rel, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(childRel);
+      } else if (/\.(ts|js)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+        results.push(childRel);
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Normalize a base + method route into the "/base/method" form (no trailing
+ * slash, no duplicate slashes). Leading slash enforced.
+ */
+function joinRoute(base, method) {
+  const a = String(base || '').replace(/^\//, '').replace(/\/+$/, '');
+  const b = String(method || '').replace(/^\//, '').replace(/\/+$/, '');
+  let joined = [a, b].filter(Boolean).join('/');
+  joined = '/' + joined;
+  return joined.replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+}
+
+/**
+ * Scan an AST for controller class methods and collect
+ * `{ classNode, methodNode, method, urlPath }` entries.
+ */
+function collectControllerMethods(tree) {
+  const t = ast.t;
+  const results = [];
+  ast.traverse(tree, {
+    ClassDeclaration(p) {
+      const decorators = p.node.decorators || [];
+      let controllerBase = '';
+      let isController = false;
+      for (const d of decorators) {
+        if (!t.isDecorator(d)) continue;
+        const expr = d.expression;
+        if (t.isCallExpression(expr) && t.isIdentifier(expr.callee) && expr.callee.name === 'Controller') {
+          isController = true;
+          const arg0 = expr.arguments[0];
+          if (t.isStringLiteral(arg0)) controllerBase = arg0.value;
+        }
+      }
+      if (!isController) return;
+      for (const member of p.node.body.body) {
+        if (!t.isClassMethod(member) && !t.isClassProperty(member)) continue;
+        const mDecorators = member.decorators || [];
+        for (const dec of mDecorators) {
+          if (!t.isDecorator(dec)) continue;
+          const expr = dec.expression;
+          if (!t.isCallExpression(expr)) continue;
+          if (!t.isIdentifier(expr.callee)) continue;
+          if (!HTTP_DECORATORS.has(expr.callee.name)) continue;
+          const httpMethod = expr.callee.name.toUpperCase();
+          const arg0 = expr.arguments[0];
+          const methodPath = t.isStringLiteral(arg0) ? arg0.value : '';
+          const fullPath = joinRoute(controllerBase, methodPath);
+          // Only support class methods with block bodies.
+          if (!t.isClassMethod(member) || !t.isBlockStatement(member.body)) continue;
+          results.push({
+            methodNode: member,
+            body: member.body,
+            httpMethod,
+            urlPath: fullPath,
+          });
+        }
+      }
+    },
+  });
+  return results;
+}
+
+function astInstrumentFile(source, targets) {
+  // targets: [{ httpMethod, urlPath, events: [] }]
+  const tree = ast.parseSource(source);
+  const methods = collectControllerMethods(tree);
+  if (methods.length === 0) return { ok: false, reason: 'no-controllers' };
+  let changed = false;
+  const instrumentedNames = [];
+  const skipped = [];
+  for (const target of targets) {
+    const match = methods.find(
+      (m) => m.httpMethod === target.httpMethod && m.urlPath === target.urlPath,
+    );
+    if (!match) {
+      for (const e of target.events) {
+        skipped.push({ event: e.name, reason: 'controller-method-not-found' });
+      }
+      continue;
+    }
+    if (ast.hasInstrumentedMarker(match.methodNode)) {
+      for (const e of target.events) skipped.push({ event: e.name, reason: 'already-instrumented' });
+      continue;
+    }
+    const stmts = target.events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
+    ast.injectTrackBeforeLastReturn(match.methodNode, match.body, stmts);
+    changed = true;
+    for (const e of target.events) instrumentedNames.push(e.name);
+  }
+  if (!changed) {
+    return { ok: true, after: source, instrumented: [], skipped, changed: false };
+  }
+  ast.ensureGuruluImport(tree);
+  const after = ast.generateSource(tree, source);
+  return { ok: true, after, instrumented: instrumentedNames, skipped, changed: true };
+}
+
+function resolveControllerFileForEvent(ctx, httpMethod, urlPath) {
+  const files = walkSourceFiles(ctx.repoRoot);
+  for (const rel of files) {
+    if (!/\.controller\.(ts|js)$/.test(rel) && !rel.includes('controller')) continue;
+    const abs = path.join(ctx.repoRoot, rel);
+    let src;
+    try {
+      src = fs.readFileSync(abs, 'utf8');
+    } catch (_) {
+      continue;
+    }
+    if (!src.includes('@Controller')) continue;
+    try {
+      const tree = ast.parseSource(src);
+      const methods = collectControllerMethods(tree);
+      if (methods.some((m) => m.httpMethod === httpMethod && m.urlPath === urlPath)) {
+        return rel;
+      }
+    } catch (_) {
+      // Skip malformed files.
+    }
+  }
+  return null;
+}
+
+function instrumentEvents(ctx, events) {
+  const helper = singleton.ensureSingletonHelper(ctx, 'nestjs');
+  const changes = [...helper.changes];
+  const notes = [...helper.notes];
+  let eventsInstrumented = 0;
+  let eventsSkipped = 0;
+
+  if (helper.collision) {
+    return {
+      changes: [],
+      notes,
+      filesModified: 0,
+      eventsInstrumented: 0,
+      eventsSkipped: events ? events.length : 0,
+      collision: true,
+    };
+  }
+
+  // Group events by (file, httpMethod, urlPath).
+  const fileGroups = new Map();
+  for (const e of events || []) {
+    const parsed = parseEventRoute(e && e.source && e.source.route);
+    if (!parsed) {
+      notes.push(`skip:${e && e.name}:no-source-route`);
+      eventsSkipped++;
+      continue;
+    }
+    const rel = resolveControllerFileForEvent(ctx, parsed.method, parsed.urlPath);
+    if (!rel) {
+      notes.push(`skip:${e.name}:controller-not-found`);
+      eventsSkipped++;
+      continue;
+    }
+    if (!fileGroups.has(rel)) fileGroups.set(rel, new Map());
+    const perFile = fileGroups.get(rel);
+    const key = `${parsed.method}::${parsed.urlPath}`;
+    if (!perFile.has(key)) perFile.set(key, { httpMethod: parsed.method, urlPath: parsed.urlPath, events: [] });
+    perFile.get(key).events.push(e);
+  }
+
+  for (const [rel, perFile] of fileGroups.entries()) {
+    const abs = path.join(ctx.repoRoot, rel);
+    const before = fs.readFileSync(abs, 'utf8');
+    const targets = Array.from(perFile.values());
+    let res;
+    try {
+      res = astInstrumentFile(before, targets);
+    } catch (err) {
+      const msg = (err && err.message) || String(err);
+      // eslint-disable-next-line no-console
+      console.warn(`[auto-instrument] patch.fallback ${rel}: ${msg}`);
+      notes.push(`patch.fallback:${rel}:${msg}`);
+      continue;
+    }
+    if (!res.ok) {
+      for (const t of targets) {
+        for (const e of t.events) {
+          notes.push(`skip:${e.name}:${res.reason}`);
+          eventsSkipped++;
+        }
+      }
+      continue;
+    }
+    for (const s of res.skipped || []) {
+      notes.push(`skip:${s.event}:${s.reason}`);
+      eventsSkipped++;
+    }
+    if (res.changed) {
+      changes.push({
+        relPath: rel,
+        before,
+        after: res.after,
+        reason: `auto-instrument-nestjs`,
+        type: 'auto-instrument',
+      });
+      eventsInstrumented += (res.instrumented || []).length;
+    }
+  }
+
+  const filesModified = changes.filter((c) => c.type === 'auto-instrument').length;
+  return { changes, notes, filesModified, eventsInstrumented, eventsSkipped, collision: false };
+}
+
+function ensureSingletonHelper(ctx) {
+  return singleton.ensureSingletonHelper(ctx, 'nestjs');
+}
+
+module.exports = {
+  name: NAME,
+  supportedFrameworks: SUPPORTED,
+  ensureSingletonHelper,
+  instrumentEvents,
+  _internals: {
+    parseEventRoute,
+    walkSourceFiles,
+    collectControllerMethods,
+    astInstrumentFile,
+    resolveControllerFileForEvent,
+    joinRoute,
+  },
+};

package/scripts/patches/auto-instrument/nextjs-app-router.cjs

@@ -0,0 +1,318 @@
+// scripts/patches/auto-instrument/nextjs-app-router.cjs — Phase 20 W1 A1.
+//
+// AST-based auto-instrumentation for Next.js App Router route files. Each
+// `ProposedEvent` whose `source.route` looks like "POST /api/foo" is mapped
+// to its `app/api/foo/route.ts` file, parsed with Babel, and the matching
+// HTTP method export gets a `gurulu.track('eventName', {})` call injected
+// before its last top-level `return`.
+//
+// Idempotency is enforced by tagging each instrumented function with a
+// leading `@gurulu-instrumented` comment. Running the patcher twice is a
+// no-op.
+//
+// If Babel fails to parse the file (exotic TS syntax not yet supported, or
+// a malformed source), we fall back to the original regex-based pathway and
+// emit a `patch.fallback` note so operators can investigate. The regex
+// implementation is kept inline at the bottom of this file for that reason.
+
+const fs = require('fs');
+const path = require('path');
+
+const ast = require('./ast-helper.cjs');
+const singleton = require('./singleton-helper.cjs');
+
+const NAME = 'auto-instrument-nextjs-app-router';
+const SUPPORTED = ['nextjs-app-router', 'nextjs-app', 'nextjs'];
+const MARKER = '// @gurulu-instrumented';
+const IMPORT_LINE = "import { gurulu } from '@/lib/gurulu';";
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+
+function resolveRouteFileCandidates(routeStr) {
+  if (!routeStr || typeof routeStr !== 'string') return null;
+  const m = routeStr.trim().match(/^([A-Z]+)\s+(\/.*)$/);
+  if (!m) return null;
+  const method = m[1].toUpperCase();
+  const urlPath = m[2].replace(/\/+$/, '').split('?')[0];
+  const segments = urlPath.split('/').filter(Boolean);
+  const relA = path.posix.join('src', 'app', ...segments, 'route.ts');
+  const relB = path.posix.join('app', ...segments, 'route.ts');
+  const relAx = path.posix.join('src', 'app', ...segments, 'route.tsx');
+  const relBx = path.posix.join('app', ...segments, 'route.tsx');
+  return { method, candidates: [relA, relB, relAx, relBx] };
+}
+
+// ---------------------------------------------------------------------------
+// AST path
+// ---------------------------------------------------------------------------
+
+/**
+ * Instrument a single file with a set of events. `events` is expected to all
+ * target the same HTTP method export. Returns a unified result with the
+ * serialized `after` source and the list of event names that were actually
+ * instrumented (vs. already-instrumented skipped).
+ */
+function astInstrumentFile(source, method, events, opts = {}) {
+  const tree = ast.parseSource(source);
+  const fns = ast.findExportedFunction(tree, method);
+  if (fns.length === 0) {
+    return { ok: false, reason: `method-${method}-not-found` };
+  }
+  // Use the first matching function — multiple same-name exports are a
+  // user error, not something we try to be clever about.
+  const target = fns[0];
+  if (ast.hasInstrumentedMarker(target.fn)) {
+    return {
+      ok: true,
+      after: source,
+      instrumented: [],
+      skipped: events.map((e) => ({ event: e.name, reason: 'already-instrumented' })),
+      changed: false,
+    };
+  }
+  const trackStmts = events.map((e) =>
+    ast.buildTrackStatement(e.name, e.autoProperties || opts.autoProperties && e.extractedProperties),
+  );
+  const injected = ast.injectTrackBeforeLastReturn(target.fn, target.body, trackStmts);
+  if (!injected) {
+    return { ok: false, reason: 'inject-failed' };
+  }
+  ast.ensureGuruluImport(tree);
+  const after = ast.generateSource(tree, source);
+  return {
+    ok: true,
+    after,
+    instrumented: events.map((e) => e.name),
+    skipped: [],
+    changed: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Regex fallback (legacy Phase 18.7 pathway) — unchanged behaviour, kept in
+// scope for graceful degradation.
+// ---------------------------------------------------------------------------
+
+function regexEnsureImport(source) {
+  if (source.includes(IMPORT_LINE)) return { source, added: false };
+  const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
+  const m = source.match(importRegex);
+  if (m) {
+    const end = m.index + m[0].length;
+    return { source: source.slice(0, end) + IMPORT_LINE + '\n' + source.slice(end), added: true };
+  }
+  return { source: IMPORT_LINE + '\n' + source, added: true };
+}
+
+function regexFindMethodBody(source, method) {
+  const re = new RegExp(
+    `export\\s+async\\s+function\\s+${method}\\s*\\([^)]*\\)\\s*(?::\\s*[^\\{]+)?\\{`,
+    'm',
+  );
+  const m = re.exec(source);
+  if (!m) return null;
+  const openIdx = m.index + m[0].length - 1;
+  let depth = 0;
+  for (let i = openIdx; i < source.length; i++) {
+    const c = source[i];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return { start: openIdx, end: i };
+    }
+  }
+  return null;
+}
+
+function regexFindLastReturnInBody(source, start, end) {
+  const snippet = source.slice(start, end);
+  const patterns = [
+    /return\s+NextResponse\.json\s*\(/g,
+    /return\s+Response\.json\s*\(/g,
+    /return\s+new\s+Response\s*\(/g,
+    /return\s+NextResponse\s*\./g,
+  ];
+  let lastIdx = -1;
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(snippet)) !== null) {
+      if (m.index > lastIdx) lastIdx = m.index;
+    }
+  }
+  if (lastIdx === -1) return null;
+  const absoluteReturnIdx = start + lastIdx;
+  let lineStart = absoluteReturnIdx;
+  while (lineStart > 0 && source[lineStart - 1] !== '\n') lineStart--;
+  const indentMatch = source.slice(lineStart, absoluteReturnIdx).match(/^(\s*)/);
+  const indent = (indentMatch && indentMatch[1]) || '  ';
+  return { insertAt: lineStart, indent };
+}
+
+function regexBuildTrackCall(eventName, indent) {
+  const safeName = JSON.stringify(eventName);
+  return (
+    `${indent}${MARKER} ${eventName}\n` +
+    `${indent}gurulu.track(${safeName}, {});\n`
+  );
+}
+
+function regexInstrumentFile(before, method, events) {
+  const body = regexFindMethodBody(before, method);
+  if (!body) {
+    return { ok: false, reason: `method-${method}-not-found` };
+  }
+  const bodySnippet = before.slice(body.start, body.end);
+  const needed = [];
+  const skipped = [];
+  for (const e of events) {
+    if (bodySnippet.includes(`${MARKER} ${e.name}`)) {
+      skipped.push({ event: e.name, reason: 'already-instrumented' });
+    } else {
+      needed.push(e);
+    }
+  }
+  if (needed.length === 0) return { ok: true, after: before, instrumented: [], skipped, changed: false };
+  const ret = regexFindLastReturnInBody(before, body.start, body.end);
+  if (!ret) return { ok: false, reason: 'no-return-found' };
+  const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent)).join('');
+  let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
+  after = regexEnsureImport(after).source;
+  return {
+    ok: true,
+    after,
+    instrumented: needed.map((e) => e.name),
+    skipped,
+    changed: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher plumbing
+// ---------------------------------------------------------------------------
+
+function instrumentRouteFile(ctx, relPath, method, events) {
+  const abs = path.join(ctx.repoRoot, relPath);
+  if (!fs.existsSync(abs)) {
+    return { change: null, skipped: events.map((e) => ({ event: e.name, reason: 'route-file-missing' })), notes: [] };
+  }
+  const before = fs.readFileSync(abs, 'utf8');
+  const notes = [];
+  let res;
+  try {
+    res = astInstrumentFile(before, method, events, ctx || {});
+  } catch (err) {
+    const msg = (err && err.message) || String(err);
+    // eslint-disable-next-line no-console
+    console.warn(`[auto-instrument] patch.fallback ${relPath}: ${msg}`);
+    notes.push(`patch.fallback:${relPath}:${msg}`);
+    res = regexInstrumentFile(before, method, events);
+  }
+  if (!res.ok) {
+    return {
+      change: null,
+      skipped: events.map((e) => ({ event: e.name, reason: res.reason || 'instrument-failed' })),
+      notes,
+    };
+  }
+  if (!res.changed) {
+    return { change: null, skipped: res.skipped, notes };
+  }
+  return {
+    change: {
+      relPath,
+      before,
+      after: res.after,
+      reason: `auto-instrument-${method}`,
+      type: 'auto-instrument',
+    },
+    skipped: res.skipped,
+    instrumented: res.instrumented,
+    notes,
+  };
+}
+
+function groupEventsByRoute(ctx, events) {
+  const groups = new Map();
+  const unresolved = [];
+  for (const e of events || []) {
+    const routeStr = (e && e.source && e.source.route) || null;
+    if (!routeStr) {
+      unresolved.push({ event: e && e.name, reason: 'no-source-route' });
+      continue;
+    }
+    const parsed = resolveRouteFileCandidates(routeStr);
+    if (!parsed) {
+      unresolved.push({ event: e.name, reason: `unparseable-route:${routeStr}` });
+      continue;
+    }
+    const found = parsed.candidates.find((rel) =>
+      fs.existsSync(path.join(ctx.repoRoot, rel)),
+    );
+    if (!found) {
+      unresolved.push({ event: e.name, reason: 'route-file-not-found' });
+      continue;
+    }
+    const key = `${found}::${parsed.method}`;
+    if (!groups.has(key)) groups.set(key, { relPath: found, method: parsed.method, events: [] });
+    groups.get(key).events.push(e);
+  }
+  return { groups: Array.from(groups.values()), unresolved };
+}
+
+function instrumentEvents(ctx, events) {
+  const helper = singleton.ensureSingletonHelper(ctx, 'nextjs-app-router');
+  const changes = [...helper.changes];
+  const notes = [...helper.notes];
+  let eventsInstrumented = 0;
+  let eventsSkipped = 0;
+
+  if (helper.collision) {
+    return {
+      changes: [],
+      notes,
+      filesModified: 0,
+      eventsInstrumented: 0,
+      eventsSkipped: events ? events.length : 0,
+      collision: true,
+    };
+  }
+
+  const { groups, unresolved } = groupEventsByRoute(ctx, events || []);
+  for (const u of unresolved) {
+    notes.push(`skip:${u.event || '(unknown)'}:${u.reason}`);
+    eventsSkipped++;
+  }
+  for (const group of groups) {
+    const res = instrumentRouteFile(ctx, group.relPath, group.method, group.events);
+    if (res.notes && res.notes.length) notes.push(...res.notes);
+    if (res.change) {
+      changes.push(res.change);
+      eventsInstrumented += (res.instrumented || []).length;
+    }
+    for (const s of res.skipped || []) {
+      notes.push(`skip:${s.event}:${s.reason}`);
+      eventsSkipped++;
+    }
+  }
+
+  const filesModified = changes.filter((c) => c.type === 'auto-instrument').length;
+  return { changes, notes, filesModified, eventsInstrumented, eventsSkipped, collision: false };
+}
+
+function ensureSingletonHelper(ctx) {
+  return singleton.ensureSingletonHelper(ctx, 'nextjs-app-router');
+}
+
+module.exports = {
+  name: NAME,
+  supportedFrameworks: SUPPORTED,
+  ensureSingletonHelper,
+  instrumentEvents,
+  _internals: {
+    resolveRouteFileCandidates,
+    astInstrumentFile,
+    regexInstrumentFile,
+    groupEventsByRoute,
+    instrumentRouteFile,
+    METHODS,
+  },
+};