@gurulu/cli 0.1.1 → 0.1.3

package/scripts/patches/auto-instrument/ast-helper.cjs

@@ -0,0 +1,332 @@
+// scripts/patches/auto-instrument/ast-helper.cjs — Phase 20 W1 A1.
+//
+// Shared Babel AST helpers used by every auto-instrument module. The goal of
+// this file is twofold:
+//
+//   1. Provide a single place where we resolve `@babel/parser`,
+//      `@babel/traverse`, `@babel/generator`, `@babel/types` so the patcher
+//      modules stay tiny and framework-focused.
+//   2. Encode the shared instrumentation operations (parse, find function
+//      node, insert a `gurulu.track(...)` call before the last return, ensure
+//      the `gurulu` import, check idempotency marker, serialize back to
+//      source) in one place — consistent behaviour across NestJS, Remix,
+//      SvelteKit, Astro, Fastify, Vue patchers.
+//
+// None of these helpers mutate source strings directly; they parse an AST,
+// apply transforms, then run `@babel/generator` to serialize the result.
+// Parse errors are NOT swallowed — callers catch and fall back to regex.
+
+const parser = require('@babel/parser');
+// `@babel/traverse` exposes its default export under `.default` in CJS.
+const traverseMod = require('@babel/traverse');
+const traverse = traverseMod.default || traverseMod;
+const generatorMod = require('@babel/generator');
+const generate = generatorMod.default || generatorMod;
+const t = require('@babel/types');
+
+const IMPORT_LINE = "import { gurulu } from '@/lib/gurulu';";
+const MARKER = '@gurulu-instrumented';
+const MARKER_COMMENT = `// @gurulu-instrumented`;
+
+const DEFAULT_PARSE_PLUGINS = [
+  'typescript',
+  'jsx',
+  'decorators-legacy',
+  'classProperties',
+  'classPrivateProperties',
+  'classPrivateMethods',
+  'topLevelAwait',
+  'importAssertions',
+  'importAttributes',
+  'explicitResourceManagement',
+];
+
+/**
+ * Parse `content` into a Babel AST. Throws on parse error so callers can
+ * fall back to their legacy regex path.
+ */
+function parseSource(content) {
+  return parser.parse(content, {
+    sourceType: 'module',
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+    allowImportExportEverywhere: true,
+    errorRecovery: false,
+    plugins: DEFAULT_PARSE_PLUGINS,
+  });
+}
+
+/**
+ * Serialize an AST back to source. We preserve the original source for
+ * fidelity when possible; otherwise Babel re-prints using its default.
+ */
+function generateSource(ast, originalSource) {
+  const out = generate(
+    ast,
+    {
+      retainLines: false,
+      compact: false,
+      comments: true,
+      jsescOption: { minimal: true, quotes: 'single' },
+    },
+    originalSource,
+  );
+  return out.code;
+}
+
+/**
+ * Return true if `node` (function declaration / expression / arrow) carries
+ * a leading `@gurulu-instrumented` block/line comment. We look at
+ * `leadingComments` on the node AND on its parent export declaration (set by
+ * the caller when relevant).
+ */
+function hasInstrumentedMarker(node) {
+  const comments = (node && (node.leadingComments || [])) || [];
+  for (const c of comments) {
+    if (c && typeof c.value === 'string' && c.value.includes(MARKER)) return true;
+  }
+  return false;
+}
+
+/**
+ * Attach the `@gurulu-instrumented` marker to a function node so future
+ * runs are idempotent.
+ */
+function tagInstrumented(node) {
+  t.addComment(node, 'leading', ` @gurulu-instrumented`, true);
+}
+
+/**
+ * Build the `gurulu.track('eventName', { ...properties })` statement. Empty
+ * object when no auto-properties; otherwise an ObjectExpression with the
+ * property AST nodes inlined.
+ */
+function buildTrackStatement(eventName, autoProperties) {
+  const args = [t.stringLiteral(eventName)];
+  if (Array.isArray(autoProperties) && autoProperties.length > 0) {
+    const props = [];
+    for (const p of autoProperties) {
+      if (!p || !p.name) continue;
+      // Allow `source` to be a JS expression like `req.body.orderId`.
+      let valueNode;
+      if (p.source && typeof p.source === 'string') {
+        try {
+          const parsedExpr = parser.parseExpression(p.source, {
+            plugins: DEFAULT_PARSE_PLUGINS,
+          });
+          valueNode = parsedExpr;
+        } catch (_) {
+          valueNode = t.stringLiteral(String(p.source));
+        }
+      } else {
+        valueNode = t.identifier('undefined');
+      }
+      props.push(
+        t.objectProperty(
+          t.identifier(toSafeIdentifier(p.name)),
+          valueNode,
+          false,
+          toSafeIdentifier(p.name) === p.name,
+        ),
+      );
+    }
+    args.push(t.objectExpression(props));
+  } else {
+    args.push(t.objectExpression([]));
+  }
+
+  const call = t.expressionStatement(
+    t.callExpression(
+      t.memberExpression(t.identifier('gurulu'), t.identifier('track')),
+      args,
+    ),
+  );
+  // Leading marker so humans can spot the insertion and so idempotency
+  // fallbacks (string-based) still see it.
+  t.addComment(
+    call,
+    'leading',
+    ` @gurulu-instrumented ${eventName}`,
+    true,
+  );
+  return call;
+}
+
+function toSafeIdentifier(name) {
+  return String(name).replace(/[^A-Za-z0-9_$]/g, '_');
+}
+
+/**
+ * Given a function body (BlockStatement), inject `gurulu.track(...)`
+ * statements right before the LAST top-level `return` statement. If the
+ * function has no top-level return, append at the end of the body.
+ *
+ * The function tags the containing function node with the
+ * `@gurulu-instrumented` comment (via the `fn` param passed by the caller).
+ *
+ * Returns `true` if any statements were injected.
+ */
+function injectTrackBeforeLastReturn(fn, body, trackStatements) {
+  if (!body || !Array.isArray(body.body)) return false;
+  if (trackStatements.length === 0) return false;
+
+  // Find last top-level return.
+  let lastIdx = -1;
+  for (let i = body.body.length - 1; i >= 0; i--) {
+    if (t.isReturnStatement(body.body[i])) {
+      lastIdx = i;
+      break;
+    }
+  }
+
+  if (lastIdx === -1) {
+    // No top-level return — insert BEFORE the last statement of the body
+    // so trailing `res.json(...)` / `reply.send(...)` calls still come after
+    // our track call (matching operator intuition + Phase 18.7 tests).
+    const insertAt = Math.max(0, body.body.length - 1);
+    body.body.splice(insertAt, 0, ...trackStatements);
+  } else {
+    body.body.splice(lastIdx, 0, ...trackStatements);
+  }
+  tagInstrumented(fn);
+  return true;
+}
+
+/**
+ * Ensure `import { gurulu } from '@/lib/gurulu'` is present. No-op when the
+ * import already exists.
+ */
+function ensureGuruluImport(ast) {
+  let present = false;
+  let lastImportIdx = -1;
+  const body = ast.program.body;
+  for (let i = 0; i < body.length; i++) {
+    const node = body[i];
+    if (t.isImportDeclaration(node)) {
+      lastImportIdx = i;
+      if (node.source && node.source.value === '@/lib/gurulu') {
+        const hasNamed = (node.specifiers || []).some(
+          (s) => t.isImportSpecifier(s) && t.isIdentifier(s.imported) && s.imported.name === 'gurulu',
+        );
+        if (hasNamed) present = true;
+      }
+    }
+  }
+  if (present) return;
+  const imp = t.importDeclaration(
+    [t.importSpecifier(t.identifier('gurulu'), t.identifier('gurulu'))],
+    t.stringLiteral('@/lib/gurulu'),
+  );
+  body.splice(lastImportIdx + 1, 0, imp);
+}
+
+/**
+ * Walk the AST and locate the underlying function node for a named export
+ * (handles `export async function NAME(){}`, `export const NAME = () => {}`,
+ * `export { NAME }` re-exports where NAME binds to a locally-defined function,
+ * and `export default` when `defaultName === true`).
+ *
+ * Returns an array of `{ fn, body }` entries (multiple when the name matches
+ * several export shapes in the same file, which is rare but tolerated).
+ */
+function findExportedFunction(ast, exportName, opts = {}) {
+  const results = [];
+  const wantDefault = !!opts.defaultExport;
+
+  // Resolve local bindings for later lookup of re-exports + const-init arrows.
+  const localBindings = new Map();
+
+  traverse(ast, {
+    FunctionDeclaration(pathNode) {
+      if (pathNode.node.id && pathNode.node.id.name) {
+        localBindings.set(pathNode.node.id.name, pathNode.node);
+      }
+    },
+    VariableDeclaration(pathNode) {
+      for (const decl of pathNode.node.declarations) {
+        if (!t.isIdentifier(decl.id)) continue;
+        if (!decl.init) continue;
+        if (
+          t.isArrowFunctionExpression(decl.init) ||
+          t.isFunctionExpression(decl.init)
+        ) {
+          localBindings.set(decl.id.name, decl.init);
+        }
+      }
+    },
+  });
+
+  traverse(ast, {
+    ExportNamedDeclaration(pathNode) {
+      const decl = pathNode.node.declaration;
+      if (decl) {
+        if (t.isFunctionDeclaration(decl) && decl.id && decl.id.name === exportName) {
+          results.push({ fn: decl, body: decl.body });
+          return;
+        }
+        if (t.isVariableDeclaration(decl)) {
+          for (const d of decl.declarations) {
+            if (!t.isIdentifier(d.id) || d.id.name !== exportName) continue;
+            if (t.isArrowFunctionExpression(d.init) || t.isFunctionExpression(d.init)) {
+              // Arrow functions need a block body for injection.
+              if (t.isBlockStatement(d.init.body)) {
+                results.push({ fn: d.init, body: d.init.body });
+              }
+            }
+          }
+        }
+      }
+      // `export { foo }` re-export referencing local binding.
+      for (const spec of pathNode.node.specifiers || []) {
+        if (!t.isExportSpecifier(spec)) continue;
+        const exported = t.isIdentifier(spec.exported) ? spec.exported.name : null;
+        if (exported !== exportName) continue;
+        const localName = t.isIdentifier(spec.local) ? spec.local.name : null;
+        if (!localName) continue;
+        const bound = localBindings.get(localName);
+        if (!bound) continue;
+        if (t.isBlockStatement(bound.body)) {
+          results.push({ fn: bound, body: bound.body });
+        }
+      }
+    },
+    ExportDefaultDeclaration(pathNode) {
+      if (!wantDefault) return;
+      const decl = pathNode.node.declaration;
+      if (t.isFunctionDeclaration(decl) || t.isFunctionExpression(decl)) {
+        if (t.isBlockStatement(decl.body)) {
+          results.push({ fn: decl, body: decl.body });
+        }
+      } else if (t.isArrowFunctionExpression(decl)) {
+        if (t.isBlockStatement(decl.body)) {
+          results.push({ fn: decl, body: decl.body });
+        }
+      } else if (t.isIdentifier(decl)) {
+        const bound = localBindings.get(decl.name);
+        if (bound && t.isBlockStatement(bound.body)) {
+          results.push({ fn: bound, body: bound.body });
+        }
+      }
+    },
+  });
+
+  return results;
+}
+
+module.exports = {
+  parser,
+  traverse,
+  generate,
+  t,
+  parseSource,
+  generateSource,
+  hasInstrumentedMarker,
+  tagInstrumented,
+  buildTrackStatement,
+  injectTrackBeforeLastReturn,
+  ensureGuruluImport,
+  findExportedFunction,
+  IMPORT_LINE,
+  MARKER,
+  MARKER_COMMENT,
+};

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

@@ -0,0 +1,267 @@
+// scripts/patches/auto-instrument/astro.cjs — Phase 20 W1 A3.
+//
+// Astro API endpoints live at `src/pages/api/**.{ts,js}` and export HTTP
+// verb functions (`GET`, `POST`, ...). `.astro` components with a server
+// frontmatter block (between `---` fences) are also supported: the patcher
+// extracts the frontmatter JS/TS, detects server-side fetch/data-loading
+// patterns, and injects `gurulu.track()` calls.
+
+const fs = require('fs');
+const path = require('path');
+
+const ast = require('./ast-helper.cjs');
+const singleton = require('./singleton-helper.cjs');
+
+const NAME = 'auto-instrument-astro';
+const SUPPORTED = ['astro'];
+
+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 routeToCandidates(urlPath) {
+  const cleaned = urlPath.replace(/^\//, '').replace(/\/+$/, '');
+  const segments = cleaned.split('/').filter(Boolean);
+  const exts = ['ts', 'js', 'mjs'];
+  const out = [];
+  for (const ext of exts) {
+    out.push(path.posix.join('src', 'pages', ...segments) + `.${ext}`);
+    out.push(path.posix.join('src', 'pages', ...segments, `index.${ext}`));
+  }
+  // .astro component files (page routes, not API endpoints)
+  out.push(path.posix.join('src', 'pages', ...segments) + '.astro');
+  out.push(path.posix.join('src', 'pages', ...segments, 'index.astro'));
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// .astro frontmatter support
+// ---------------------------------------------------------------------------
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/**
+ * Server-side data-loading patterns we look for inside .astro frontmatter.
+ * If any match, we consider the frontmatter instrumentable.
+ */
+const DATA_LOADING_PATTERNS = [
+  /\bfetch\s*\(/,
+  /\bawait\b/,
+  /\bgetCollection\s*\(/,
+  /\bgetEntryBySlug\s*\(/,
+  /\bAstro\s*\.\s*glob\s*\(/,
+  /\bimport\s*\(/, // dynamic import
+  /\.findMany\s*\(/,
+  /\.find\s*\(/,
+  /\.query\s*\(/,
+  /\.select\s*\(/,
+];
+
+function hasDataLoadingPattern(frontmatterSource) {
+  return DATA_LOADING_PATTERNS.some((re) => re.test(frontmatterSource));
+}
+
+/**
+ * Instrument an .astro file's frontmatter block. Parses the JS/TS inside the
+ * `---` fences via the shared AST helper, injects gurulu.track() calls, and
+ * reconstructs the full .astro file.
+ */
+function astInstrumentFrontmatter(source, events) {
+  const fmMatch = source.match(FRONTMATTER_RE);
+  if (!fmMatch) return { ok: false, reason: 'no-frontmatter' };
+
+  const frontmatter = fmMatch[1];
+  if (!hasDataLoadingPattern(frontmatter)) {
+    return { ok: false, reason: 'no-data-loading-pattern' };
+  }
+
+  // Check idempotency — if the frontmatter already has the marker, skip.
+  if (frontmatter.includes(ast.MARKER)) {
+    return {
+      ok: true,
+      after: source,
+      instrumented: [],
+      skipped: events.map((e) => ({ event: e.name, reason: 'already-instrumented' })),
+      changed: false,
+    };
+  }
+
+  // Parse the frontmatter as a standalone JS/TS module.
+  const tree = ast.parseSource(frontmatter);
+
+  // Build track statements for all events.
+  const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
+
+  // Inject before last return or at end of program body.
+  const body = tree.program;
+  let lastReturnIdx = -1;
+  for (let i = body.body.length - 1; i >= 0; i--) {
+    if (ast.t.isReturnStatement(body.body[i])) {
+      lastReturnIdx = i;
+      break;
+    }
+  }
+
+  // Add marker comment to first track statement
+  if (stmts.length > 0) {
+    // Tag the program itself with a comment (will appear in generated source)
+    const markerComment = ast.t.addComment(
+      body.body[0] || stmts[0],
+      'leading',
+      ` @gurulu-instrumented`,
+      true,
+    );
+  }
+
+  if (lastReturnIdx >= 0) {
+    body.body.splice(lastReturnIdx, 0, ...stmts);
+  } else {
+    // Append at end of frontmatter
+    body.body.push(...stmts);
+  }
+
+  ast.ensureGuruluImport(tree);
+  const newFrontmatter = ast.generateSource(tree, frontmatter);
+
+  // Reconstruct the full .astro file
+  const beforeFm = source.substring(0, fmMatch.index);
+  const afterFm = source.substring(fmMatch.index + fmMatch[0].length);
+  const after = `${beforeFm}---\n${newFrontmatter}\n---${afterFm}`;
+
+  return {
+    ok: true,
+    after,
+    instrumented: events.map((e) => e.name),
+    skipped: [],
+    changed: true,
+  };
+}
+
+function astInstrumentFile(source, method, events) {
+  const tree = ast.parseSource(source);
+  const fns = ast.findExportedFunction(tree, method);
+  if (fns.length === 0) return { ok: false, reason: `${method}-not-found` };
+  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 stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
+  ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
+  ast.ensureGuruluImport(tree);
+  const after = ast.generateSource(tree, source);
+  return {
+    ok: true,
+    after,
+    instrumented: events.map((e) => e.name),
+    skipped: [],
+    changed: true,
+  };
+}
+
+function instrumentEvents(ctx, events) {
+  const helper = singleton.ensureSingletonHelper(ctx, 'astro');
+  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 candidates = routeToCandidates(parsed.urlPath);
+    const found = candidates.find((rel) => fs.existsSync(path.join(ctx.repoRoot, rel)));
+    if (!found) {
+      notes.push(`skip:${e.name}:route-file-not-found`);
+      eventsSkipped++;
+      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);
+  }
+
+  for (const group of groups.values()) {
+    const abs = path.join(ctx.repoRoot, group.relPath);
+    const before = fs.readFileSync(abs, 'utf8');
+    let res;
+    try {
+      const isAstroComponent = group.relPath.endsWith('.astro');
+      res = isAstroComponent
+        ? astInstrumentFrontmatter(before, group.events)
+        : astInstrumentFile(before, group.method, group.events);
+    } 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) {
+      changes.push({
+        relPath: group.relPath,
+        before,
+        after: res.after,
+        reason: `auto-instrument-astro`,
+        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, 'astro');
+}
+
+module.exports = {
+  name: NAME,
+  supportedFrameworks: SUPPORTED,
+  ensureSingletonHelper,
+  instrumentEvents,
+  _internals: {
+    parseEventRoute,
+    routeToCandidates,
+    astInstrumentFile,
+    astInstrumentFrontmatter,
+    hasDataLoadingPattern,
+  },
+};