@gurulu/cli 0.4.7 → 1.0.1

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

@@ -1,262 +0,0 @@
-// scripts/patches/auto-instrument/fastify.cjs — Phase 20 W1 A3.
-//
-// Fastify supports two idiomatic route registration shapes:
-//
-//   fastify.get('/users', async (req, reply) => { ... });
-//   fastify.route({ method: 'GET', url: '/users', handler: async (req, reply) => { ... } });
-//
-// We search the usual server entry files plus `routes/**` for a matching
-// registration, parse the AST, and inject `gurulu.track(...)` into the
-// handler body before the last return.
-
-const fs = require('fs');
-const path = require('path');
-
-const ast = require('./ast-helper.cjs');
-const singleton = require('./singleton-helper.cjs');
-
-const NAME = 'auto-instrument-fastify';
-const SUPPORTED = ['fastify'];
-
-const CANDIDATE_ENTRIES = [
-  'app.js',
-  'server.js',
-  'index.js',
-  'src/app.js',
-  'src/server.js',
-  'src/index.js',
-  'src/app.ts',
-  'src/server.ts',
-  'src/index.ts',
-];
-
-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 walkRoutes(repoRoot) {
-  const results = [];
-  const dirs = ['routes', 'src/routes', 'plugins', 'src/plugins'];
-  for (const d of dirs) {
-    const abs = path.join(repoRoot, d);
-    if (!fs.existsSync(abs)) continue;
-    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
-      if (entry.isFile() && /\.(js|ts|mjs|cjs)$/.test(entry.name)) {
-        results.push(path.posix.join(d, entry.name));
-      }
-    }
-  }
-  return results;
-}
-
-function findFastifyHandlers(tree, method, urlPath) {
-  const t = ast.t;
-  const results = [];
-  const lowerMethod = method.toLowerCase();
-
-  ast.traverse(tree, {
-    CallExpression(p) {
-      const callee = p.node.callee;
-      // Shape 1: fastify.get('/users', handler) / app.get(...) — identifier may
-      // be any local name bound to the fastify instance.
-      if (t.isMemberExpression(callee) && t.isIdentifier(callee.property)) {
-        if (callee.property.name === lowerMethod) {
-          const args = p.node.arguments;
-          if (args.length >= 2 && t.isStringLiteral(args[0]) && args[0].value === urlPath) {
-            const handler = args[args.length - 1];
-            if (
-              (t.isArrowFunctionExpression(handler) || t.isFunctionExpression(handler)) &&
-              t.isBlockStatement(handler.body)
-            ) {
-              results.push({ fn: handler, body: handler.body });
-            }
-          }
-        }
-        // Shape 2: fastify.route({ method, url, handler })
-        if (callee.property.name === 'route') {
-          const arg0 = p.node.arguments[0];
-          if (t.isObjectExpression(arg0)) {
-            let m, u, handlerNode;
-            for (const prop of arg0.properties) {
-              if (!t.isObjectProperty(prop)) continue;
-              const key = t.isIdentifier(prop.key) ? prop.key.name : (t.isStringLiteral(prop.key) ? prop.key.value : null);
-              if (!key) continue;
-              if (key === 'method' && t.isStringLiteral(prop.value)) m = prop.value.value.toUpperCase();
-              else if (key === 'url' && t.isStringLiteral(prop.value)) u = prop.value.value;
-              else if (key === 'handler') handlerNode = prop.value;
-            }
-            if (m === method && u === urlPath && handlerNode) {
-              if (
-                (t.isArrowFunctionExpression(handlerNode) || t.isFunctionExpression(handlerNode)) &&
-                t.isBlockStatement(handlerNode.body)
-              ) {
-                results.push({ fn: handlerNode, body: handlerNode.body });
-              }
-            }
-          }
-        }
-      }
-    },
-  });
-  return results;
-}
-
-function astInstrumentFile(source, method, urlPath, events, opts = {}) {
-  const tree = ast.parseSource(source);
-  const handlers = findFastifyHandlers(tree, method, urlPath);
-  if (handlers.length === 0) return { ok: false, reason: 'handler-not-found' };
-  const target = handlers[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 stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
-  ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
-  // Sprint D / D4 — alias-aware import.
-  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
-  ast.ensureGuruluImport(tree, specifier);
-  const after = ast.generateSource(tree, source);
-  return {
-    ok: true,
-    after,
-    instrumented: events.map((e) => e.name),
-    skipped: [],
-    changed: true,
-  };
-}
-
-function resolveRouteFile(ctx, method, urlPath) {
-  const seen = new Set();
-  const candidates = [
-    ...CANDIDATE_ENTRIES,
-    ...walkRoutes(ctx.repoRoot),
-  ].filter((rel) => {
-    if (seen.has(rel)) return false;
-    seen.add(rel);
-    return fs.existsSync(path.join(ctx.repoRoot, rel));
-  });
-  for (const rel of candidates) {
-    const src = fs.readFileSync(path.join(ctx.repoRoot, rel), 'utf8');
-    if (!src.includes(urlPath)) continue;
-    try {
-      const tree = ast.parseSource(src);
-      const h = findFastifyHandlers(tree, method, urlPath);
-      if (h.length > 0) return rel;
-    } catch (_) {
-      // ignore
-    }
-  }
-  return null;
-}
-
-function instrumentEvents(ctx, events) {
-  const helper = singleton.ensureSingletonHelper(ctx, 'fastify');
-  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 = 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 = resolveRouteFile(ctx, parsed.method, parsed.urlPath);
-    if (!rel) {
-      notes.push(`skip:${e.name}:route-not-found`);
-      eventsSkipped++;
-      continue;
-    }
-    const key = `${rel}::${parsed.method}::${parsed.urlPath}`;
-    if (!groups.has(key)) {
-      groups.set(key, { relPath: rel, method: parsed.method, urlPath: parsed.urlPath, events: [] });
-    }
-    groups.get(key).events.push(e);
-  }
-
-  for (const group of groups.values()) {
-    const abs = path.join(ctx.repoRoot, group.relPath);
-    const before = fs.readFileSync(abs, 'utf8');
-    // Sprint D / D4 — pass repoRoot + relPath to the import resolver.
-    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
-    let res;
-    try {
-      res = astInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
-    } catch (err) {
-      const msg = (err && err.message) || String(err);
-      // eslint-disable-next-line no-console
-      console.warn(`[auto-instrument] patch.fallback ${group.relPath}: ${msg}`);
-      notes.push(`patch.fallback:${group.relPath}:${msg}`);
-      continue;
-    }
-    if (!res.ok) {
-      for (const e of group.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) {
-      const existing = changes.find((c) => c.relPath === group.relPath && c.type === 'auto-instrument');
-      if (existing) {
-        existing.after = res.after;
-      } else {
-        changes.push({
-          relPath: group.relPath,
-          before,
-          after: res.after,
-          reason: `auto-instrument-fastify`,
-          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, 'fastify');
-}
-
-module.exports = {
-  name: NAME,
-  supportedFrameworks: SUPPORTED,
-  ensureSingletonHelper,
-  instrumentEvents,
-  _internals: {
-    parseEventRoute,
-    walkRoutes,
-    findFastifyHandlers,
-    astInstrumentFile,
-    resolveRouteFile,
-  },
-};

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

@@ -1,392 +0,0 @@
-// scripts/patches/auto-instrument/hono.cjs — Phase 20 W1 A4.
-//
-// Hono supports several idiomatic route registration shapes:
-//
-//   app.get('/users', (c) => { ... });
-//   app.post('/orders', async (c) => { ... });
-//   const api = new Hono(); api.get('/users', handler);
-//   app.get('/health', (c) => c.json({ ok: true })).post('/data', async (c) => { ... });
-//
-// We search the usual server entry files plus `routes/**` for a matching
-// registration, parse the AST, and inject `gurulu.track(...)` into the
-// handler body before the last return.
-
-const fs = require('fs');
-const path = require('path');
-
-const ast = require('./ast-helper.cjs');
-const singleton = require('./singleton-helper.cjs');
-
-const NAME = 'auto-instrument-hono';
-const SUPPORTED = ['hono'];
-const MARKER = '// @gurulu-instrumented';
-const IMPORT_LINE_ESM = "import { gurulu } from '@/lib/gurulu';";
-
-const CANDIDATE_ENTRIES = [
-  'app.js',
-  'server.js',
-  'index.js',
-  'src/app.js',
-  'src/server.js',
-  'src/index.js',
-  'src/app.ts',
-  'src/server.ts',
-  'src/index.ts',
-  'src/main.ts',
-  'src/main.js',
-];
-
-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 walkRoutes(repoRoot) {
-  const results = [];
-  const dirs = ['routes', 'src/routes', 'src/api', 'app', 'src/app'];
-  for (const d of dirs) {
-    const abs = path.join(repoRoot, d);
-    if (!fs.existsSync(abs)) continue;
-    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
-      if (entry.isFile() && /\.(js|ts|mjs|cjs)$/.test(entry.name)) {
-        results.push(path.posix.join(d, entry.name));
-      }
-    }
-  }
-  return results;
-}
-
-// ---------------------------------------------------------------------------
-// AST path
-// ---------------------------------------------------------------------------
-
-/**
- * Find all `app.<method>('path', ..., handler)` or `api.<method>(...)`
- * or `router.<method>(...)` call expressions matching the given method +
- * urlPath. Hono apps are typically named `app`, `api`, `router`, or
- * `server`. Returns an array of `{ fn, body }` entries.
- */
-function findHonoHandlers(tree, method, urlPath) {
-  const t = ast.t;
-  const results = [];
-  const lowerMethod = method.toLowerCase();
-  const HONO_IDENTIFIERS = new Set(['app', 'api', 'router', 'server']);
-
-  ast.traverse(tree, {
-    CallExpression(p) {
-      const callee = p.node.callee;
-      if (!t.isMemberExpression(callee)) return;
-      if (!t.isIdentifier(callee.property) || callee.property.name !== lowerMethod) return;
-
-      // The object can be a simple identifier (app.get) or a chained call
-      // expression (app.get('/a', h).post('/b', h) — the object of `.post`
-      // is the preceding CallExpression). We accept identifiers from the
-      // known set, and also any CallExpression (chained).
-      const obj = callee.object;
-      const isKnownIdent = t.isIdentifier(obj) && HONO_IDENTIFIERS.has(obj.name);
-      const isChained = t.isCallExpression(obj);
-      if (!isKnownIdent && !isChained) return;
-
-      const args = p.node.arguments;
-      if (args.length < 2) return;
-      if (!t.isStringLiteral(args[0]) || args[0].value !== urlPath) return;
-
-      // The final argument should be the handler function.
-      const handler = args[args.length - 1];
-      if (
-        (t.isArrowFunctionExpression(handler) || t.isFunctionExpression(handler)) &&
-        t.isBlockStatement(handler.body)
-      ) {
-        results.push({ fn: handler, body: handler.body });
-      }
-    },
-  });
-  return results;
-}
-
-function astInstrumentFile(source, method, urlPath, events, opts = {}) {
-  const tree = ast.parseSource(source);
-  const handlers = findHonoHandlers(tree, method, urlPath);
-  if (handlers.length === 0) {
-    return { ok: false, reason: 'handler-not-found' };
-  }
-  const target = handlers[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 stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
-  ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
-  // Sprint D / D4 — alias-aware import.
-  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
-  ast.ensureGuruluImport(tree, specifier);
-  const after = ast.generateSource(tree, source);
-  return {
-    ok: true,
-    after,
-    instrumented: events.map((e) => e.name),
-    skipped: [],
-    changed: true,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Regex fallback
-// ---------------------------------------------------------------------------
-
-function regexFindHandlerStart(source, method, urlPath) {
-  const lower = method.toLowerCase();
-  const escapedPath = urlPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const re = new RegExp(
-    `(?:app|api|router|server)\\.${lower}\\s*\\(\\s*['"\`]${escapedPath}['"\`]\\s*,`,
-  );
-  const m = re.exec(source);
-  if (!m) return null;
-  let i = m.index + m[0].length;
-  const tail = source.slice(i);
-  const arrowIdx = tail.search(/=>\s*\{/);
-  const funcIdx = tail.search(/function\s*[^(]*\([^)]*\)\s*\{/);
-  let bodyOpen = -1;
-  if (arrowIdx !== -1 && (funcIdx === -1 || arrowIdx < funcIdx)) {
-    bodyOpen = i + tail.indexOf('{', arrowIdx);
-  } else if (funcIdx !== -1) {
-    bodyOpen = i + tail.indexOf('{', funcIdx);
-  }
-  if (bodyOpen === -1) return null;
-  let depth = 0;
-  for (let j = bodyOpen; j < source.length; j++) {
-    const c = source[j];
-    if (c === '{') depth++;
-    else if (c === '}') {
-      depth--;
-      if (depth === 0) return { start: bodyOpen, end: j };
-    }
-  }
-  return null;
-}
-
-function regexFindLastResponseCall(source, start, end) {
-  const snippet = source.slice(start, end);
-  // Hono response patterns: c.json(), c.text(), c.html(), c.body(),
-  // c.redirect(), c.notFound()
-  const patterns = [
-    /c\.json\s*\(/g,
-    /c\.text\s*\(/g,
-    /c\.html\s*\(/g,
-    /c\.body\s*\(/g,
-    /c\.redirect\s*\(/g,
-    /c\.notFound\s*\(/g,
-    /return\s+c\./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 absoluteIdx = start + lastIdx;
-  let lineStart = absoluteIdx;
-  while (lineStart > 0 && source[lineStart - 1] !== '\n') lineStart--;
-  const indentMatch = source.slice(lineStart, absoluteIdx).match(/^(\s*)/);
-  const indent = (indentMatch && indentMatch[1]) || '  ';
-  return { insertAt: lineStart, indent };
-}
-
-function regexEnsureImport(source, opts = {}) {
-  if (source.includes(IMPORT_LINE_ESM)) return source;
-  // Sprint D / D4 — alias-aware specifier.
-  const specifier =
-    opts.repoRoot
-      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
-      : '@/lib/gurulu';
-  const importLine = `import { gurulu } from '${specifier}';`;
-  if (source.includes(importLine)) return source;
-  const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
-  const m = source.match(importRegex);
-  if (m) {
-    const end = m.index + m[0].length;
-    return source.slice(0, end) + importLine + '\n' + source.slice(end);
-  }
-  return importLine + '\n' + source;
-}
-
-function regexBuildTrackCall(eventName, indent) {
-  const safeName = JSON.stringify(eventName);
-  return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
-}
-
-function regexInstrumentFile(before, method, urlPath, events, opts = {}) {
-  const body = regexFindHandlerStart(before, method, urlPath);
-  if (!body) return { ok: false, reason: 'handler-not-found' };
-  const snippet = before.slice(body.start, body.end);
-  const needed = [];
-  const skipped = [];
-  for (const e of events) {
-    if (snippet.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 = regexFindLastResponseCall(before, body.start, body.end);
-  if (!ret) return { ok: false, reason: 'no-response-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, opts);
-  return {
-    ok: true,
-    after,
-    instrumented: needed.map((e) => e.name),
-    skipped,
-    changed: true,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Glue
-// ---------------------------------------------------------------------------
-
-function resolveRouteFile(ctx, method, urlPath) {
-  const seen = new Set();
-  const candidates = [
-    ...CANDIDATE_ENTRIES,
-    ...walkRoutes(ctx.repoRoot),
-  ].filter((rel) => {
-    if (seen.has(rel)) return false;
-    seen.add(rel);
-    return fs.existsSync(path.join(ctx.repoRoot, rel));
-  });
-  for (const rel of candidates) {
-    const src = fs.readFileSync(path.join(ctx.repoRoot, rel), 'utf8');
-    // Cheap pre-filter: must contain `.${method.toLowerCase()}(`.
-    if (!src.includes(`.${method.toLowerCase()}(`)) continue;
-    try {
-      const tree = ast.parseSource(src);
-      const handlers = findHonoHandlers(tree, method, urlPath);
-      if (handlers.length > 0) return { relPath: rel };
-    } catch (_) {
-      // Regex check as last-ditch.
-      if (regexFindHandlerStart(src, method, urlPath)) return { relPath: rel };
-    }
-  }
-  return null;
-}
-
-function instrumentEvents(ctx, events) {
-  const helper = singleton.ensureSingletonHelper(ctx, 'hono');
-  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 = 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 resolved = resolveRouteFile(ctx, parsed.method, parsed.urlPath);
-    if (!resolved) {
-      notes.push(`skip:${e.name}:route-not-found`);
-      eventsSkipped++;
-      continue;
-    }
-    const key = `${resolved.relPath}::${parsed.method}::${parsed.urlPath}`;
-    if (!groups.has(key)) {
-      groups.set(key, {
-        relPath: resolved.relPath,
-        method: parsed.method,
-        urlPath: parsed.urlPath,
-        events: [],
-      });
-    }
-    groups.get(key).events.push(e);
-  }
-
-  for (const group of groups.values()) {
-    const abs = path.join(ctx.repoRoot, group.relPath);
-    const before = fs.readFileSync(abs, 'utf8');
-    // Sprint D / D4 — thread repoRoot + relPath into the import resolver.
-    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
-    let res;
-    try {
-      res = astInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
-    } catch (err) {
-      const msg = (err && err.message) || String(err);
-      // eslint-disable-next-line no-console
-      console.warn(`[auto-instrument] patch.fallback ${group.relPath}: ${msg}`);
-      notes.push(`patch.fallback:${group.relPath}:${msg}`);
-      res = regexInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
-    }
-    if (!res.ok) {
-      for (const e of group.events) {
-        notes.push(`skip:${e.name}:${res.reason || 'instrument-failed'}`);
-        eventsSkipped++;
-      }
-      continue;
-    }
-    for (const s of res.skipped || []) {
-      notes.push(`skip:${s.event}:${s.reason}`);
-      eventsSkipped++;
-    }
-    if (!res.changed) continue;
-    const existing = changes.find((c) => c.relPath === group.relPath && c.type === 'auto-instrument');
-    if (existing) {
-      existing.after = res.after;
-    } else {
-      changes.push({
-        relPath: group.relPath,
-        before,
-        after: res.after,
-        reason: `auto-instrument-${group.method}`,
-        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, 'hono');
-}
-
-module.exports = {
-  name: NAME,
-  supportedFrameworks: SUPPORTED,
-  ensureSingletonHelper,
-  instrumentEvents,
-  _internals: {
-    parseEventRoute,
-    resolveRouteFile,
-    astInstrumentFile,
-    regexInstrumentFile,
-    walkRoutes,
-    findHonoHandlers,
-  },
-};