@gurulu/cli 0.4.7 → 1.0.1

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

@@ -1,345 +0,0 @@
-// 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.extractedProperties || e.autoProperties),
-  );
-  const injected = ast.injectTrackBeforeLastReturn(target.fn, target.body, trackStmts);
-  if (!injected) {
-    return { ok: false, reason: 'inject-failed' };
-  }
-  // Sprint D / D4 — pick `@/lib/gurulu` only when tsconfig is wired,
-  // otherwise fall back to a relative import from the route file.
-  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 (legacy Phase 18.7 pathway) — unchanged behaviour, kept in
-// scope for graceful degradation.
-// ---------------------------------------------------------------------------
-
-function regexEnsureImport(source, opts = {}) {
-  // Sprint D / D4 — same `@/lib/gurulu` vs relative-path detection as the
-  // AST path. Falls back to the alias form for older test fixtures that
-  // don't pass a repoRoot.
-  const specifier =
-    opts.repoRoot
-      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
-      : '@/lib/gurulu';
-  const importLine = `import { gurulu } from '${specifier}';`;
-  if (source.includes(importLine)) return { source, added: false };
-  // Don't double-import: if the legacy alias line exists, leave it alone.
-  if (specifier !== '@/lib/gurulu' && 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) + importLine + '\n' + source.slice(end), added: true };
-  }
-  return { source: importLine + '\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, extractedProperties) {
-  const safeName = JSON.stringify(eventName);
-  let propsStr = '{}';
-  if (Array.isArray(extractedProperties) && extractedProperties.length > 0) {
-    const entries = extractedProperties
-      .filter((p) => p && p.name && p.source)
-      .map((p) => `${p.name}: ${p.source}`);
-    if (entries.length > 0) {
-      propsStr = `{ ${entries.join(', ')} }`;
-    }
-  }
-  return (
-    `${indent}${MARKER} ${eventName}\n` +
-    `${indent}gurulu.track(${safeName}, ${propsStr});\n`
-  );
-}
-
-function regexInstrumentFile(before, method, events, opts = {}) {
-  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, e.extractedProperties)).join('');
-  let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
-  after = regexEnsureImport(after, opts).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 = [];
-  // Sprint D / D4 — thread repoRoot + relPath through to the import
-  // resolver so `@/*` and relative-path setups pick the right specifier.
-  const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath };
-  let res;
-  try {
-    res = astInstrumentFile(before, method, events, { ...(ctx || {}), ...fileOpts });
-  } 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, fileOpts);
-  }
-  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,
-  },
-};

package/scripts/patches/auto-instrument/nextjs-pages.cjs

@@ -1,361 +0,0 @@
-// scripts/patches/auto-instrument/nextjs-pages.cjs — Phase 20 W1 A1.
-//
-// AST-based auto-instrumentation for Next.js Pages Router handlers. The
-// default export is the handler. We parse with Babel, find the exported
-// handler (default export function or arrow), locate a method branch if the
-// handler switches on `req.method`, and inject `gurulu.track(...)` before
-// the final `return` inside that branch (or the handler body when no branch
-// exists).
-//
-// Regex fallback is preserved for malformed sources.
-
-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-pages';
-const SUPPORTED = ['nextjs-pages'];
-const MARKER = '// @gurulu-instrumented';
-const IMPORT_LINE = "import { gurulu } from '@/lib/gurulu';";
-
-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(/^\//, '').replace(/\/+$/, '');
-  const exts = ['ts', 'tsx', 'js', 'jsx'];
-  const prefixes = ['pages', 'src/pages'];
-  const candidates = [];
-  for (const p of prefixes) {
-    for (const ext of exts) {
-      candidates.push(path.posix.join(p, `${urlPath}.${ext}`));
-      candidates.push(path.posix.join(p, urlPath, `index.${ext}`));
-    }
-  }
-  return { method, candidates };
-}
-
-// ---------------------------------------------------------------------------
-// AST path
-// ---------------------------------------------------------------------------
-
-/**
- * Given a handler body and a method string, return the BlockStatement of
- * `if (req.method === 'POST') { ... }` or null if no method branch is found.
- */
-function findMethodBranchBody(handlerBody, method) {
-  if (!handlerBody || !Array.isArray(handlerBody.body)) return null;
-  const t = ast.t;
-  for (const stmt of handlerBody.body) {
-    if (!t.isIfStatement(stmt)) continue;
-    if (!matchesMethodTest(stmt.test, method)) continue;
-    if (t.isBlockStatement(stmt.consequent)) return stmt.consequent;
-  }
-  // Recurse into else-if chains.
-  for (const stmt of handlerBody.body) {
-    if (!t.isIfStatement(stmt)) continue;
-    let cursor = stmt.alternate;
-    while (cursor) {
-      if (t.isIfStatement(cursor)) {
-        if (matchesMethodTest(cursor.test, method) && t.isBlockStatement(cursor.consequent)) {
-          return cursor.consequent;
-        }
-        cursor = cursor.alternate;
-      } else {
-        break;
-      }
-    }
-  }
-  return null;
-}
-
-function matchesMethodTest(node, method) {
-  const t = ast.t;
-  if (!node) return false;
-  if (t.isBinaryExpression(node) && (node.operator === '===' || node.operator === '==')) {
-    const isMethod = (n) =>
-      t.isMemberExpression(n) &&
-      t.isIdentifier(n.object) &&
-      n.object.name === 'req' &&
-      t.isIdentifier(n.property) &&
-      n.property.name === 'method';
-    const isMethodLiteral = (n) => t.isStringLiteral(n) && n.value.toUpperCase() === method;
-    if (isMethod(node.left) && isMethodLiteral(node.right)) return true;
-    if (isMethod(node.right) && isMethodLiteral(node.left)) return true;
-  }
-  return false;
-}
-
-function astInstrumentFile(source, method, events, opts = {}) {
-  const tree = ast.parseSource(source);
-  const fns = ast.findExportedFunction(tree, 'default', { defaultExport: true });
-  if (fns.length === 0) {
-    return { ok: false, reason: 'handler-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 branch = findMethodBranchBody(target.body, method);
-  const injectBody = branch || target.body;
-  const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
-  ast.injectTrackBeforeLastReturn(target.fn, injectBody, 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 regexEnsureImport(source, opts = {}) {
-  // 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;
-  if (specifier !== '@/lib/gurulu' && source.includes(IMPORT_LINE)) {
-    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 regexFindHandlerBody(source) {
-  const patterns = [
-    /export\s+default\s+async\s+function\s+\w+\s*\([^)]*\)\s*\{/,
-    /export\s+default\s+function\s+\w+\s*\([^)]*\)\s*\{/,
-    /export\s+default\s+async\s*\([^)]*\)\s*=>\s*\{/,
-    /export\s+default\s*\([^)]*\)\s*=>\s*\{/,
-  ];
-  for (const re of patterns) {
-    const m = re.exec(source);
-    if (m) {
-      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 regexFindLastResponseCall(source, start, end) {
-  const snippet = source.slice(start, end);
-  const patterns = [
-    /res\.status\s*\([^)]*\)\s*\.json\s*\(/g,
-    /res\.status\s*\([^)]*\)\s*\.send\s*\(/g,
-    /res\.json\s*\(/g,
-    /res\.send\s*\(/g,
-    /res\.sendStatus\s*\(/g,
-    /res\.end\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 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 regexBuildTrackCall(eventName, indent) {
-  const safeName = JSON.stringify(eventName);
-  return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
-}
-
-function regexInstrumentFile(before, method, events, opts = {}) {
-  const body = regexFindHandlerBody(before);
-  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 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 = [];
-  // Sprint D / D4 — thread repoRoot + relPath through to the import resolver.
-  const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath };
-  let res;
-  try {
-    res = astInstrumentFile(before, method, events, fileOpts);
-  } 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, fileOpts);
-  }
-  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;
-    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-pages');
-  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-pages');
-}
-
-module.exports = {
-  name: NAME,
-  supportedFrameworks: SUPPORTED,
-  ensureSingletonHelper,
-  instrumentEvents,
-  _internals: {
-    resolveRouteFileCandidates,
-    astInstrumentFile,
-    regexInstrumentFile,
-    groupEventsByRoute,
-    instrumentRouteFile,
-  },
-};