fix(blast,surface): dogfooding finds real bugs; add comment-strip, extends chain, src/ fallback

Discovered by meta-testing blast+surface against the charter monorepo itself.

blast:
- Resolve directory aliases via src/index.* FIRST (monorepo source layout)
- Fall back to package.json source/types/main for legacy packages
- Follow tsconfig extends chain when loading aliases (baseUrl resolution
  is per-file, not global). Charter uses tsconfig.base.json which my
  old code never read, so @stackbilt/types was unresolvable.
- Prefer source over types/dist so the dep graph edges point at .ts
  files, not compiled .d.ts declarations.
- Add --format, --config to VALUE_FLAGS so global CLI flags don't get
  swept into the positional seeds list.

surface:
- Strip block and line comments before scanning for routes. jsdoc
  examples in surface's own source were matching as real routes during
  meta-testing. Comment stripping preserves line numbers.
- Ignore __tests__, __mocks__, __fixtures__ directories and
  *.test.*, *.spec.* files. Test fixtures contain route-like strings
  that aren't real routes.

Real-world validation:
- `charter blast packages/types/src/index.ts` on charter now correctly
  reports 27 affected files (was 0 before fixes). types.ts shows up in
  hot files with 14 importers pointing at .ts source, not .d.ts.
- `charter surface` on charter correctly returns 0 routes (CLI project,
  not a Worker) instead of 15 false positives from test fixtures.
- All 341 existing tests still pass. 30 → 33 tests in blast+surface.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Kurt Overmier

packages/blast/src/__tests__/blast.test.ts

@@ -74,6 +74,30 @@ describe('buildGraph', () => {
     expect(graph.imports.get(consumerPath)?.has(libIndex)).toBe(true);
   });
 
+  it('resolves alias to package dir via src/index.ts fallback', () => {
+    // Simulates monorepo layout: @stackbilt/types → packages/types
+    write('packages/types/src/index.ts', `export type X = number;`);
+    write('packages/cli/src/index.ts', `import type { X } from '@stackbilt/types';`);
+
+    const graph = buildGraph(tmpRoot, { aliases: { '@stackbilt/types': 'packages/types' } });
+    const consumerPath = path.join(tmpRoot, 'packages', 'cli', 'src', 'index.ts');
+    const libPath = path.join(tmpRoot, 'packages', 'types', 'src', 'index.ts');
+
+    expect(graph.imports.get(consumerPath)?.has(libPath)).toBe(true);
+  });
+
+  it('resolves alias to package dir via package.json main', () => {
+    write('packages/lib/package.json', `{"main":"./lib/entry.ts"}`);
+    write('packages/lib/lib/entry.ts', `export const x = 1;`);
+    write('consumer.ts', `import { x } from '@scope/lib';`);
+
+    const graph = buildGraph(tmpRoot, { aliases: { '@scope/lib': 'packages/lib' } });
+    const consumerPath = path.join(tmpRoot, 'consumer.ts');
+    const entryPath = path.join(tmpRoot, 'packages', 'lib', 'lib', 'entry.ts');
+
+    expect(graph.imports.get(consumerPath)?.has(entryPath)).toBe(true);
+  });
+
   it('resolves path aliases', () => {
     write('src/consumer.ts', `import { x } from '@/lib';`);
     write('src/lib.ts', `export const x = 1;`);

packages/blast/src/index.ts

@@ -208,13 +208,39 @@ function resolveWithExtensions(base: string, extensions: string[]): string | nul
     const candidate = base + ext;
     if (fs.existsSync(candidate)) return candidate;
   }
-  // Index file in directory
+  // Directory resolution. Source-first, then package.json as fallback.
+  // Rationale: in monorepos with TS workspaces, we want dep-graph edges
+  // pointing at .ts source files, not compiled .d.ts declarations.
   try {
     if (fs.statSync(base).isDirectory()) {
+      // 1. src/index.* — standard monorepo source layout
+      for (const ext of extensions) {
+        const srcIndex = path.join(base, 'src', 'index' + ext);
+        if (fs.existsSync(srcIndex)) return srcIndex;
+      }
+      // 2. bare index.*
       for (const ext of extensions) {
         const candidate = path.join(base, 'index' + ext);
         if (fs.existsSync(candidate)) return candidate;
       }
+      // 3. package.json source/types/main (for packages without src/)
+      const pkgPath = path.join(base, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as {
+            main?: string;
+            types?: string;
+            source?: string;
+          };
+          const candidates = [pkg.source, pkg.types, pkg.main].filter(Boolean) as string[];
+          for (const c of candidates) {
+            const resolved = resolveWithExtensions(path.join(base, c), extensions);
+            if (resolved) return resolved;
+          }
+        } catch {
+          /* malformed package.json */
+        }
+      }
     }
   } catch {
     /* not a directory */

packages/cli/src/commands/blast.ts

@@ -15,8 +15,9 @@ import { CLIError, EXIT_CODE } from '../index';
 import { getFlag } from '../flags';
 import { buildGraph, blastRadius } from '@stackbilt/blast';
 
-// Flags that consume a value (so the next positional should not be treated as a seed file)
-const VALUE_FLAGS = new Set(['--root', '--depth']);
+// Flags that consume a value (so the next positional should not be treated as a seed file).
+// Includes local flags (--root, --depth) and global CLI flags (--format, --config).
+const VALUE_FLAGS = new Set(['--root', '--depth', '--format', '--config']);
 
 export async function blastCommand(options: CLIOptions, args: string[]): Promise<number> {
   const seedArgs: string[] = [];
@@ -121,29 +122,88 @@ export async function blastCommand(options: CLIOptions, args: string[]): Promise
 // tsconfig path alias detection
 // ============================================================================
 
-function detectTsconfigAliases(root: string): Record<string, string> {
-  const tsconfigPath = path.join(root, 'tsconfig.json');
-  if (!fs.existsSync(tsconfigPath)) return {};
+interface MinimalTsconfig {
+  extends?: string | string[];
+  compilerOptions?: { baseUrl?: string; paths?: Record<string, string[]> };
+}
+
+function readTsconfig(tsconfigPath: string): MinimalTsconfig | null {
+  if (!fs.existsSync(tsconfigPath)) return null;
   try {
     const raw = fs.readFileSync(tsconfigPath, 'utf8');
     // Strip JSON comments (tsconfig allows them)
     const cleaned = raw.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
-    const parsed = JSON.parse(cleaned) as {
-      compilerOptions?: { baseUrl?: string; paths?: Record<string, string[]> };
-    };
-    const paths = parsed.compilerOptions?.paths;
-    const baseUrl = parsed.compilerOptions?.baseUrl ?? '.';
-    if (!paths) return {};
-    const aliases: Record<string, string> = {};
-    for (const [key, targets] of Object.entries(paths)) {
-      if (!targets || targets.length === 0) continue;
-      // Normalize "@/*" -> "@/", "src/*" -> "src/"
-      const aliasKey = key.replace(/\*$/, '');
-      const targetPath = targets[0].replace(/\*$/, '');
-      aliases[aliasKey] = path.join(baseUrl, targetPath);
-    }
-    return aliases;
+    return JSON.parse(cleaned) as MinimalTsconfig;
   } catch {
-    return {};
+    return null;
+  }
+}
+
+/**
+ * Walk the tsconfig `extends` chain and merge compilerOptions.paths from
+ * parents into the child. Shallower (closer to the child) wins on conflicts.
+ */
+function loadTsconfigChain(tsconfigPath: string, seen = new Set<string>()): MinimalTsconfig {
+  const abs = path.resolve(tsconfigPath);
+  if (seen.has(abs)) return {};
+  seen.add(abs);
+
+  const parsed = readTsconfig(abs);
+  if (!parsed) return {};
+
+  const merged: MinimalTsconfig = { compilerOptions: { baseUrl: '.', paths: {} } };
+
+  // Resolve extends first, then overlay current file's options on top
+  const extendsRaw = parsed.extends;
+  const extendsList = Array.isArray(extendsRaw) ? extendsRaw : extendsRaw ? [extendsRaw] : [];
+  for (const ext of extendsList) {
+    let extPath = ext;
+    if (!extPath.endsWith('.json')) extPath += '.json';
+    if (!path.isAbsolute(extPath)) extPath = path.resolve(path.dirname(abs), extPath);
+    const parent = loadTsconfigChain(extPath, seen);
+    if (parent.compilerOptions?.paths) {
+      Object.assign(merged.compilerOptions!.paths!, parent.compilerOptions.paths);
+    }
+    if (parent.compilerOptions?.baseUrl) {
+      // baseUrl is relative to the tsconfig that declared it
+      merged.compilerOptions!.baseUrl = path.resolve(
+        path.dirname(extPath),
+        parent.compilerOptions.baseUrl
+      );
+    }
+  }
+
+  if (parsed.compilerOptions?.paths) {
+    Object.assign(merged.compilerOptions!.paths!, parsed.compilerOptions.paths);
+  }
+  if (parsed.compilerOptions?.baseUrl) {
+    merged.compilerOptions!.baseUrl = path.resolve(
+      path.dirname(abs),
+      parsed.compilerOptions.baseUrl
+    );
+  }
+
+  return merged;
+}
+
+function detectTsconfigAliases(root: string): Record<string, string> {
+  const tsconfigPath = path.join(root, 'tsconfig.json');
+  const merged = loadTsconfigChain(tsconfigPath);
+  const paths = merged.compilerOptions?.paths;
+  const baseUrl = merged.compilerOptions?.baseUrl ?? root;
+  if (!paths || Object.keys(paths).length === 0) return {};
+  const aliases: Record<string, string> = {};
+  for (const [key, targets] of Object.entries(paths)) {
+    if (!targets || targets.length === 0) continue;
+    // Normalize "@/*" -> "@/", "src/*" -> "src/"
+    const aliasKey = key.replace(/\*$/, '');
+    const targetPath = targets[0].replace(/\*$/, '');
+    // baseUrl is already absolute after loadTsconfigChain; produce an absolute alias target
+    const absoluteTarget = path.isAbsolute(targetPath)
+      ? targetPath
+      : path.resolve(baseUrl, targetPath);
+    // Express target as relative to root so buildGraph's resolveSpecifier can join it
+    aliases[aliasKey] = path.relative(root, absoluteTarget) || '.';
   }
+  return aliases;
 }

packages/surface/src/__tests__/surface.test.ts

@@ -60,6 +60,22 @@ app.get('/users', h);
     expect(routes[0].prefix).toBe('/api/v1');
   });
 
+  it('ignores route patterns inside comments', () => {
+    const src = `
+import { Hono } from 'hono';
+const app = new Hono();
+// Example usage: app.get('/fake-from-comment', handler)
+/* Another example:
+ *   app.post('/also-fake', h);
+ *   router.delete('/nope', h);
+ */
+app.get('/real', handler);
+`;
+    const routes = extractRoutes(src, 'app.ts');
+    expect(routes).toHaveLength(1);
+    expect(routes[0].path).toBe('/real');
+  });
+
   it('handles router. prefix', () => {
     const src = `
 const router = new Hono();
@@ -158,6 +174,17 @@ app.post('/api/users', createUser);
     expect(surface.schemas[0].name).toBe('users');
   });
 
+  it('ignores test/spec files and __tests__ dirs', () => {
+    write('src/app.ts', `import { Hono } from 'hono';\napp.get('/real', h);`);
+    write('src/app.test.ts', `app.get('/fake-from-test', h);`);
+    write('src/__tests__/fixtures.ts', `app.get('/fake-from-tests-dir', h);`);
+    write('src/handler.spec.ts', `app.post('/fake-from-spec', h);`);
+
+    const surface = extractSurface({ root: tmpRoot });
+    expect(surface.summary.routeCount).toBe(1);
+    expect(surface.routes[0].path).toBe('/real');
+  });
+
   it('ignores node_modules and dist', () => {
     write('src/app.ts', `app.get('/a', h);`);
     write('node_modules/bad/src/x.ts', `app.get('/evil', h);`);

packages/surface/src/index.ts

@@ -82,6 +82,9 @@ const DEFAULT_IGNORE_DIRS = new Set([
   '.turbo',
   '.wrangler',
   'coverage',
+  '__tests__',
+  '__mocks__',
+  '__fixtures__',
 ]);
 
 const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'all'];
@@ -130,14 +133,18 @@ function walkFiles(
  */
 export function extractRoutes(source: string, filePath: string): Route[] {
   const routes: Route[] = [];
-  const lines = source.split('\n');
+  // Strip block comments and line comments before scanning.
+  // Preserves line numbers by replacing comment bodies with spaces.
+  const stripped = stripComments(source);
+  const lines = stripped.split('\n');
 
   // Detect basePath (applies to this router within the file)
   let basePath: string | undefined;
-  const basePathMatch = source.match(/\.basePath\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/);
+  const basePathMatch = stripped.match(/\.basePath\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/);
   if (basePathMatch) basePath = basePathMatch[1];
 
-  // Framework detection from import statements
+  // Framework detection from import statements (use original source —
+  // detectFramework only looks at import lines which aren't commented out)
   const framework = detectFramework(source);
 
   // Pattern: <identifier>.METHOD('/path', ...)
@@ -169,6 +176,63 @@ export function extractRoutes(source: string, filePath: string): Route[] {
   return routes;
 }
 
+/**
+ * Strip block and line comments from source, preserving line numbers
+ * by replacing stripped content with equivalent whitespace.
+ */
+function stripComments(source: string): string {
+  let result = '';
+  let i = 0;
+  const n = source.length;
+  while (i < n) {
+    const ch = source[i];
+    const next = source[i + 1];
+    // Block comment
+    if (ch === '/' && next === '*') {
+      result += '  ';
+      i += 2;
+      while (i < n - 1 && !(source[i] === '*' && source[i + 1] === '/')) {
+        result += source[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      result += '  ';
+      i += 2;
+      continue;
+    }
+    // Line comment
+    if (ch === '/' && next === '/') {
+      while (i < n && source[i] !== '\n') {
+        result += ' ';
+        i++;
+      }
+      continue;
+    }
+    // String literal — preserve contents (contains real route paths)
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const quote = ch;
+      result += ch;
+      i++;
+      while (i < n && source[i] !== quote) {
+        if (source[i] === '\\' && i + 1 < n) {
+          result += source[i] + source[i + 1];
+          i += 2;
+          continue;
+        }
+        result += source[i];
+        i++;
+      }
+      if (i < n) {
+        result += source[i];
+        i++;
+      }
+      continue;
+    }
+    result += ch;
+    i++;
+  }
+  return result;
+}
+
 function detectFramework(source: string): Route['framework'] {
   if (/from\s+['"`]hono['"`]/.test(source) || /require\s*\(\s*['"`]hono['"`]/.test(source)) {
     return 'hono';
@@ -320,6 +384,10 @@ export function extractSurface(options: ExtractOptions = {}): Surface {
   const sourceFiles = walkFiles(root, extensions, ignoreDirs);
   const routes: Route[] = [];
   for (const file of sourceFiles) {
+    // Skip test/spec files — their route strings are fixtures, not real routes
+    const base = path.basename(file);
+    if (/\.(test|spec)\.[mc]?[tj]sx?$/i.test(base)) continue;
+
     let content: string;
     try {
       content = fs.readFileSync(file, 'utf8');