@gurulu/cli 0.4.7 → 1.0.1

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

@@ -1,480 +0,0 @@
-// 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 fs = require('fs');
-const path = require('path');
-
-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 HELPER_REL_PATH = 'src/lib/gurulu';
-const MARKER = '@gurulu-instrumented';
-const MARKER_COMMENT = `// @gurulu-instrumented`;
-
-// ---------------------------------------------------------------------------
-// Sprint D / D4 — tsconfig `@/*` path detection + relative-path fallback.
-//
-// Many auto-instrumented files want to write `import { gurulu } from
-// '@/lib/gurulu'`. That works for the typical Next.js scaffold, but breaks
-// in vanilla TS / Vite / Express setups whose `tsconfig.json` does not
-// configure `compilerOptions.paths['@/*']`. Without the alias the inserted
-// import resolves to a missing module and the patched file fails to
-// compile.
-//
-// `resolveGuruluImportSpecifier(repoRoot, relativeRouteFile)` returns the
-// import specifier the patcher should embed. When the alias is configured
-// it returns `'@/lib/gurulu'`; otherwise it computes the POSIX-style
-// relative path from the route file to `src/lib/gurulu` (e.g.
-// `'../../lib/gurulu'`).
-// ---------------------------------------------------------------------------
-
-function stripJsonComments(text) {
-  // Tolerate `// ...` and `/* ... */` comments as found in tsconfig files.
-  return text
-    .replace(/\/\*[\s\S]*?\*\//g, '')
-    .replace(/(^|[^:\\])\/\/.*$/gm, '$1');
-}
-
-function readTsconfigPaths(repoRoot) {
-  const candidates = ['tsconfig.json', 'tsconfig.base.json', 'jsconfig.json'];
-  for (const rel of candidates) {
-    const abs = path.join(repoRoot, rel);
-    if (!fs.existsSync(abs)) continue;
-    try {
-      const raw = fs.readFileSync(abs, 'utf8');
-      const parsed = JSON.parse(stripJsonComments(raw));
-      const co = parsed && parsed.compilerOptions;
-      if (co && co.paths && typeof co.paths === 'object') {
-        return { paths: co.paths, baseUrl: co.baseUrl || '.' };
-      }
-    } catch {
-      // Ignore malformed tsconfig — fall through to the next candidate.
-    }
-  }
-  return null;
-}
-
-/**
- * Returns true when tsconfig.json (or jsconfig.json) declares
- * `compilerOptions.paths['@/*']`. We accept any value — most projects map it
- * to `['./src/*']` but custom roots like `['./*']` also count as wired.
- */
-function hasAtAlias(repoRoot) {
-  const cfg = readTsconfigPaths(repoRoot);
-  if (!cfg) return false;
-  return Object.prototype.hasOwnProperty.call(cfg.paths, '@/*');
-}
-
-/**
- * Compute a POSIX-style relative import path from `fromFileRel` (a repo
- * relative path like `src/app/api/checkout/route.ts`) to the singleton
- * helper at `src/lib/gurulu`. The returned path is suitable for use as an
- * ES module import specifier: it always starts with `./` or `../` and never
- * carries a file extension.
- */
-function relativeHelperSpecifier(fromFileRel) {
-  const fromDir = path.posix.dirname(fromFileRel.split(path.sep).join('/'));
-  let rel = path.posix.relative(fromDir, HELPER_REL_PATH);
-  if (!rel) rel = '.';
-  if (!rel.startsWith('.')) rel = `./${rel}`;
-  return rel;
-}
-
-/**
- * Pick the right import specifier for `import { gurulu } from <here>`
- * given the repo root and the file the import will be written into.
- *
- * - When `@/*` is configured in tsconfig, prefer the alias for clean diffs
- *   that match the singleton helper documentation.
- * - Otherwise fall back to a relative import computed from the route file.
- */
-function resolveGuruluImportSpecifier(repoRoot, fromFileRel) {
-  if (repoRoot && hasAtAlias(repoRoot)) return '@/lib/gurulu';
-  if (fromFileRel) return relativeHelperSpecifier(fromFileRel);
-  return '@/lib/gurulu';
-}
-
-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);
-}
-
-// Sprint D / D1 — typed-helper selector. Lives in its own CJS module so the
-// auto-instrumenter can swap `gurulu.track('$purchase', {...})` for the
-// canonical `gurulu.purchase({...})` whenever the LLM-extracted properties
-// satisfy the helper's required fields. When `selectHelper` returns null we
-// fall through to the legacy generic-track shape — no behaviour change for
-// custom (non-canonical) events.
-const sdkHelperMap = require('./sdk-helper-map.cjs');
-
-function safeParseExpression(text) {
-  return parser.parseExpression(text, { plugins: DEFAULT_PARSE_PLUGINS });
-}
-
-function buildTypedHelperCall(eventName, autoProperties) {
-  const helper = sdkHelperMap.selectHelper(eventName, autoProperties);
-  if (!helper) return null;
-  const argNodes = [];
-  for (const expr of helper.argExpressions) {
-    try {
-      argNodes.push(safeParseExpression(expr));
-    } catch (_) {
-      // Defensive: if any arg expression is malformed, abort the typed
-      // upgrade and let the caller emit `gurulu.track(...)` instead.
-      return null;
-    }
-  }
-  return t.expressionStatement(
-    t.callExpression(
-      t.memberExpression(t.identifier('gurulu'), t.identifier(helper.method)),
-      argNodes,
-    ),
-  );
-}
-
-/**
- * Build the `gurulu.track('eventName', { ...properties })` statement. Empty
- * object when no auto-properties; otherwise an ObjectExpression with the
- * property AST nodes inlined.
- *
- * Sprint D / D1: when `eventName` is a canonical event ($purchase, $signup,
- * etc.) AND the extracted properties supply every required field, we emit
- * the typed helper instead — `gurulu.purchase({ value, currency })` rather
- * than `gurulu.track('$purchase', { ... })`. The marker comment is identical
- * in either form so idempotency checks still work.
- */
-function buildTrackStatement(eventName, autoProperties, opts = {}) {
-  // Try the typed helper first. Tests and patcher modules pass `opts.preferTyped =
-  // false` to opt out (e.g. when verifying the legacy shape). Default is true.
-  const preferTyped = opts.preferTyped !== false;
-  if (preferTyped) {
-    const typed = buildTypedHelperCall(eventName, autoProperties);
-    if (typed) {
-      t.addComment(typed, 'leading', ` @gurulu-instrumented ${eventName}`, true);
-      return typed;
-    }
-  }
-
-  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 {
-          valueNode = safeParseExpression(p.source);
-        } 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 <specifier>` is present. No-op when an
- * existing import already binds the `gurulu` named export from a path
- * pointing at our singleton helper (alias OR relative). Sprint D / D4: the
- * specifier is derived from tsconfig — callers may pass an explicit one.
- */
-function ensureGuruluImport(ast, specifierOpt) {
-  const specifier = specifierOpt || '@/lib/gurulu';
-  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;
-      const src = node.source && node.source.value;
-      if (
-        src === specifier ||
-        src === '@/lib/gurulu' ||
-        (typeof src === 'string' && /(^|\/)lib\/gurulu$/.test(src))
-      ) {
-        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(specifier),
-  );
-  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,
-  buildTypedHelperCall,
-  injectTrackBeforeLastReturn,
-  ensureGuruluImport,
-  findExportedFunction,
-  hasAtAlias,
-  relativeHelperSpecifier,
-  resolveGuruluImportSpecifier,
-  sdkHelperMap,
-  IMPORT_LINE,
-  HELPER_REL_PATH,
-  MARKER,
-  MARKER_COMMENT,
-};