@thoughtflow/codebase 0.2.0

package/src/tools/workspace/project-scanner.tool.ts

@@ -0,0 +1,1058 @@
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import { ToolBase, ToolContext, ToolExecutionResult, resolveSafePath } from "@thoughtflow/core";
+
+/* ═══════════════════════════════════════════════════════════════
+   RULE TYPES — stable interface for extensibility.
+   To support a new technology: add an entry to TECH_RULES.
+   To support a new monorepo tool: add an entry to MONOREPO_RULES.
+   ═══════════════════════════════════════════════════════════════ */
+
+export type TechCategory =
+  | "language"
+  | "framework"
+  | "database"
+  | "infra"
+  | "testing"
+  | "build";
+
+export interface TechRule {
+  id: string;
+  name: string;
+  category: TechCategory;
+  /** Files whose existence signals this tech (relative to scanned dir). */
+  fileMarkers: string[];
+  /** Directories whose existence signals this tech. */
+  dirMarkers: string[];
+  /** package.json / composer.json dependency names that signal this tech. */
+  packageDeps?: string[];
+  /** Directories to skip when this tech is detected. */
+  ignoreDirs: string[];
+  /** Important files worth reading (only shown when they exist). */
+  keyFiles: string[];
+  /** Glob patterns for find_files exploration. */
+  explorePatterns: string[];
+  /** Short actionable hints for the LLM. */
+  hints: string[];
+}
+
+export interface MonorepoRule {
+  id: string;
+  name: string;
+  /** Files in root that indicate this monorepo tool. */
+  fileMarkers: string[];
+  /** Conventional sub-dirs that contain sub-projects (e.g. apps, libs). */
+  workspaceDirs: string[];
+  ignoreDirs: string[];
+  hints: string[];
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   TECH RULES — sorted by category, then by specificity.
+   Framework rules should come AFTER language rules so the
+   output reads naturally (language first, then framework).
+   ═══════════════════════════════════════════════════════════════ */
+
+export const TECH_RULES: TechRule[] = [
+  // ——— Languages ———————————————————————————————————————
+  {
+    id: "typescript",
+    name: "TypeScript",
+    category: "language",
+    fileMarkers: ["tsconfig.json", "tsconfig.base.json"],
+    dirMarkers: [],
+    ignoreDirs: ["node_modules", "dist", "build", ".tsbuildinfo"],
+    keyFiles: ["tsconfig.json"],
+    explorePatterns: [],
+    hints: [],
+  },
+  {
+    id: "nodejs",
+    name: "Node.js",
+    category: "language",
+    fileMarkers: ["package.json"],
+    dirMarkers: [],
+    ignoreDirs: ["node_modules", "dist", "build", ".cache", ".parcel-cache"],
+    keyFiles: ["package.json"],
+    explorePatterns: [],
+    hints: ["Check 'scripts' in package.json for build/start/test commands"],
+  },
+  {
+    id: "python",
+    name: "Python",
+    category: "language",
+    fileMarkers: [
+      "pyproject.toml",
+      "setup.py",
+      "requirements.txt",
+      "Pipfile",
+      "setup.cfg",
+    ],
+    dirMarkers: [],
+    ignoreDirs: [
+      "__pycache__",
+      ".venv",
+      "venv",
+      "env",
+      ".eggs",
+      ".mypy_cache",
+      ".pytest_cache",
+      ".ruff_cache",
+    ],
+    keyFiles: ["pyproject.toml", "requirements.txt", "setup.py"],
+    explorePatterns: ["**/*.py"],
+    hints: ["Entry points in pyproject.toml [project.scripts] or setup.py"],
+  },
+  {
+    id: "rust",
+    name: "Rust",
+    category: "language",
+    fileMarkers: ["Cargo.toml"],
+    dirMarkers: [],
+    ignoreDirs: ["target"],
+    keyFiles: ["Cargo.toml", "src/main.rs", "src/lib.rs"],
+    explorePatterns: ["**/*.rs"],
+    hints: ["Binaries in src/bin/, library in src/lib.rs"],
+  },
+  {
+    id: "go",
+    name: "Go",
+    category: "language",
+    fileMarkers: ["go.mod"],
+    dirMarkers: [],
+    ignoreDirs: ["vendor"],
+    keyFiles: ["go.mod"],
+    explorePatterns: ["**/*.go"],
+    hints: ["Binaries in cmd/, private libs in internal/"],
+  },
+  {
+    id: "php",
+    name: "PHP",
+    category: "language",
+    fileMarkers: ["composer.json"],
+    dirMarkers: [],
+    ignoreDirs: ["vendor", "storage/framework"],
+    keyFiles: ["composer.json"],
+    explorePatterns: ["**/*.php"],
+    hints: ["PSR-4 autoloading in composer.json"],
+  },
+  {
+    id: "java",
+    name: "Java",
+    category: "language",
+    fileMarkers: ["pom.xml", "build.gradle", "build.gradle.kts"],
+    dirMarkers: [],
+    ignoreDirs: ["target", "build", ".gradle", "out"],
+    keyFiles: ["pom.xml", "build.gradle", "build.gradle.kts"],
+    explorePatterns: ["**/*.java", "**/*.kt"],
+    hints: ["Source in src/main/java, tests in src/test/java"],
+  },
+  {
+    id: "dotnet",
+    name: ".NET/C#",
+    category: "language",
+    fileMarkers: [], // detected via extension scan in detectTechs
+    dirMarkers: [],
+    ignoreDirs: ["bin", "obj", ".vs"],
+    keyFiles: [],
+    explorePatterns: ["**/*.cs", "**/*.csproj"],
+    hints: [".sln defines project structure, .csproj defines build"],
+  },
+  {
+    id: "ruby",
+    name: "Ruby",
+    category: "language",
+    fileMarkers: ["Gemfile"],
+    dirMarkers: [],
+    ignoreDirs: ["vendor/bundle", ".bundle"],
+    keyFiles: ["Gemfile"],
+    explorePatterns: ["**/*.rb"],
+    hints: ["Application code in lib/ or app/"],
+  },
+
+  // ——— Frameworks ——————————————————————————————————————
+  {
+    id: "nestjs",
+    name: "NestJS",
+    category: "framework",
+    fileMarkers: ["nest-cli.json"],
+    dirMarkers: [],
+    packageDeps: ["@nestjs/core"],
+    ignoreDirs: [],
+    keyFiles: ["nest-cli.json", "src/main.ts", "src/app.module.ts"],
+    explorePatterns: [
+      "**/*.controller.ts",
+      "**/*.module.ts",
+      "**/*.service.ts",
+      "**/*.guard.ts",
+      "**/*.gateway.ts",
+    ],
+    hints: [
+      "Controllers: @Get/@Post/@Put/@Delete define HTTP endpoints",
+      "Modules: imports[] shows feature dependencies",
+    ],
+  },
+  {
+    id: "angular",
+    name: "Angular",
+    category: "framework",
+    fileMarkers: ["angular.json"],
+    dirMarkers: [],
+    packageDeps: ["@angular/core"],
+    ignoreDirs: [".angular"],
+    keyFiles: [
+      "angular.json",
+      "src/app/app.routes.ts",
+      "src/app/app.module.ts",
+      "src/app/app.config.ts",
+    ],
+    explorePatterns: [
+      "**/*.component.ts",
+      "**/*routing*",
+      "**/*.module.ts",
+    ],
+    hints: [
+      "Routes: app.routes.ts (standalone) or *-routing.module.ts",
+      "Components: @Component decorator, templates inline or .html",
+    ],
+  },
+  {
+    id: "react",
+    name: "React",
+    category: "framework",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["react"],
+    ignoreDirs: [],
+    keyFiles: ["src/App.tsx", "src/App.jsx", "src/index.tsx"],
+    explorePatterns: ["**/*.tsx", "**/*.jsx"],
+    hints: ["Components in src/, routing often in App.tsx or routes/"],
+  },
+  {
+    id: "nextjs",
+    name: "Next.js",
+    category: "framework",
+    fileMarkers: ["next.config.js", "next.config.mjs", "next.config.ts"],
+    dirMarkers: [],
+    packageDeps: ["next"],
+    ignoreDirs: [".next"],
+    keyFiles: ["next.config.js", "next.config.mjs", "next.config.ts"],
+    explorePatterns: ["app/**/page.tsx", "app/**/route.ts", "pages/**/*.tsx"],
+    hints: [
+      "App Router: app/ dir, page.tsx=pages, route.ts=API",
+      "Pages Router: pages/ dir, file-based routing",
+    ],
+  },
+  {
+    id: "vue",
+    name: "Vue.js",
+    category: "framework",
+    fileMarkers: ["vue.config.js"],
+    dirMarkers: [],
+    packageDeps: ["vue"],
+    ignoreDirs: [],
+    keyFiles: ["src/App.vue", "src/main.ts", "src/router/index.ts"],
+    explorePatterns: ["**/*.vue"],
+    hints: ["Single-file components (.vue), routing in src/router/"],
+  },
+  {
+    id: "nuxt",
+    name: "Nuxt",
+    category: "framework",
+    fileMarkers: ["nuxt.config.ts", "nuxt.config.js"],
+    dirMarkers: [],
+    packageDeps: ["nuxt"],
+    ignoreDirs: [".nuxt", ".output"],
+    keyFiles: ["nuxt.config.ts"],
+    explorePatterns: ["pages/**/*.vue", "server/api/**/*.ts"],
+    hints: ["File-based routing in pages/, server API in server/api/"],
+  },
+  {
+    id: "express",
+    name: "Express.js",
+    category: "framework",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["express"],
+    ignoreDirs: [],
+    keyFiles: ["src/app.ts", "src/app.js", "src/server.ts"],
+    explorePatterns: ["**/*route*", "**/*controller*", "**/*middleware*"],
+    hints: ["Routes in routes/ or src/routes/"],
+  },
+  {
+    id: "fastify",
+    name: "Fastify",
+    category: "framework",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["fastify"],
+    ignoreDirs: [],
+    keyFiles: ["src/app.ts", "src/server.ts"],
+    explorePatterns: ["**/*route*", "**/*plugin*"],
+    hints: ["Routes as plugins, registered via app.register()"],
+  },
+  {
+    id: "hono",
+    name: "Hono",
+    category: "framework",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["hono"],
+    ignoreDirs: [],
+    keyFiles: ["src/index.ts"],
+    explorePatterns: ["**/*route*"],
+    hints: ["Lightweight HTTP framework, routes via app.get/post"],
+  },
+  {
+    id: "django",
+    name: "Django",
+    category: "framework",
+    fileMarkers: ["manage.py"],
+    dirMarkers: [],
+    ignoreDirs: ["staticfiles", "media"],
+    keyFiles: ["manage.py"],
+    explorePatterns: [
+      "**/views.py",
+      "**/models.py",
+      "**/urls.py",
+      "**/serializers.py",
+    ],
+    hints: [
+      "Apps in INSTALLED_APPS (settings.py)",
+      "URLs in urls.py, views define endpoints, models define DB",
+    ],
+  },
+  {
+    id: "fastapi",
+    name: "FastAPI",
+    category: "framework",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["fastapi"],
+    ignoreDirs: [],
+    keyFiles: ["main.py", "app/main.py"],
+    explorePatterns: ["**/*router*", "**/*route*"],
+    hints: ["Routes with @app.get/@app.post, routers in separate files"],
+  },
+  {
+    id: "flask",
+    name: "Flask",
+    category: "framework",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["flask"],
+    ignoreDirs: [],
+    keyFiles: ["app.py", "wsgi.py"],
+    explorePatterns: ["**/*route*", "**/*view*"],
+    hints: ["Routes via @app.route or blueprints"],
+  },
+  {
+    id: "laravel",
+    name: "Laravel",
+    category: "framework",
+    fileMarkers: ["artisan"],
+    dirMarkers: ["app/Http/Controllers"],
+    ignoreDirs: ["vendor", "storage/framework", "bootstrap/cache"],
+    keyFiles: [
+      "routes/web.php",
+      "routes/api.php",
+      "app/Http/Kernel.php",
+      ".env.example",
+    ],
+    explorePatterns: [
+      "app/Http/Controllers/**/*.php",
+      "app/Models/**/*.php",
+      "database/migrations/*.php",
+    ],
+    hints: [
+      "Routes: routes/web.php + routes/api.php",
+      "Controllers: app/Http/Controllers, Models: app/Models",
+    ],
+  },
+  {
+    id: "rails",
+    name: "Ruby on Rails",
+    category: "framework",
+    fileMarkers: ["config/routes.rb"],
+    dirMarkers: ["app/controllers", "app/models"],
+    ignoreDirs: ["vendor/bundle", "tmp", "log"],
+    keyFiles: ["config/routes.rb", "Gemfile", "config/database.yml"],
+    explorePatterns: [
+      "app/controllers/**/*.rb",
+      "app/models/**/*.rb",
+      "db/migrate/*.rb",
+    ],
+    hints: ["Routes in config/routes.rb, MVC in app/"],
+  },
+  {
+    id: "spring",
+    name: "Spring Boot",
+    category: "framework",
+    fileMarkers: [
+      "src/main/resources/application.properties",
+      "src/main/resources/application.yml",
+    ],
+    dirMarkers: [],
+    ignoreDirs: ["target", "build"],
+    keyFiles: [
+      "src/main/resources/application.yml",
+      "src/main/resources/application.properties",
+    ],
+    explorePatterns: [
+      "**/*Controller.java",
+      "**/*Service.java",
+      "**/*Repository.java",
+    ],
+    hints: ["@RestController, @Service, @Entity, JPA for data access"],
+  },
+
+  // ——— Database / ORM ——————————————————————————————————
+  {
+    id: "prisma",
+    name: "Prisma",
+    category: "database",
+    fileMarkers: ["prisma/schema.prisma"],
+    dirMarkers: [],
+    packageDeps: ["prisma", "@prisma/client"],
+    ignoreDirs: [],
+    keyFiles: ["prisma/schema.prisma"],
+    explorePatterns: ["prisma/migrations/**/migration.sql"],
+    hints: ["All models in schema.prisma, migrations in prisma/migrations/"],
+  },
+  {
+    id: "typeorm",
+    name: "TypeORM",
+    category: "database",
+    fileMarkers: ["ormconfig.json", "ormconfig.ts"],
+    dirMarkers: [],
+    packageDeps: ["typeorm"],
+    ignoreDirs: [],
+    keyFiles: ["ormconfig.json", "ormconfig.ts"],
+    explorePatterns: ["**/*.entity.ts", "**/migration/*.ts"],
+    hints: ["Entities with @Entity, migrations in migrations/"],
+  },
+  {
+    id: "drizzle",
+    name: "Drizzle ORM",
+    category: "database",
+    fileMarkers: ["drizzle.config.ts"],
+    dirMarkers: [],
+    packageDeps: ["drizzle-orm"],
+    ignoreDirs: [],
+    keyFiles: ["drizzle.config.ts"],
+    explorePatterns: ["**/*schema*", "**/drizzle/**"],
+    hints: ["Schema in schema files, migrations in drizzle/"],
+  },
+  {
+    id: "sequelize",
+    name: "Sequelize",
+    category: "database",
+    fileMarkers: [".sequelizerc"],
+    dirMarkers: [],
+    packageDeps: ["sequelize"],
+    ignoreDirs: [],
+    keyFiles: [".sequelizerc"],
+    explorePatterns: ["**/models/**", "**/migrations/**"],
+    hints: ["Models in models/, migrations in migrations/"],
+  },
+  {
+    id: "mongoose",
+    name: "Mongoose",
+    category: "database",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["mongoose"],
+    ignoreDirs: [],
+    keyFiles: [],
+    explorePatterns: ["**/*schema*", "**/*model*"],
+    hints: ["MongoDB schemas, usually in schemas/ or models/"],
+  },
+
+  // ——— Infrastructure ——————————————————————————————————
+  {
+    id: "docker",
+    name: "Docker",
+    category: "infra",
+    fileMarkers: [
+      "Dockerfile",
+      "docker-compose.yml",
+      "docker-compose.yaml",
+      "compose.yml",
+      "compose.yaml",
+    ],
+    dirMarkers: [],
+    ignoreDirs: [],
+    keyFiles: [
+      "Dockerfile",
+      "docker-compose.yml",
+      "docker-compose.yaml",
+      "compose.yml",
+      "compose.yaml",
+      ".dockerignore",
+    ],
+    explorePatterns: ["**/Dockerfile*"],
+    hints: ["docker-compose defines services, ports, volumes, networks"],
+  },
+  {
+    id: "kubernetes",
+    name: "Kubernetes",
+    category: "infra",
+    fileMarkers: ["kustomization.yaml", "skaffold.yaml"],
+    dirMarkers: ["k8s", "kubernetes", "manifests"],
+    ignoreDirs: [],
+    keyFiles: ["kustomization.yaml"],
+    explorePatterns: ["k8s/**/*.yaml", "kubernetes/**/*.yaml"],
+    hints: ["Manifests: deployments, services, configmaps, secrets"],
+  },
+  {
+    id: "terraform",
+    name: "Terraform",
+    category: "infra",
+    fileMarkers: ["main.tf"],
+    dirMarkers: [],
+    ignoreDirs: [".terraform"],
+    keyFiles: ["main.tf", "variables.tf", "outputs.tf"],
+    explorePatterns: ["**/*.tf"],
+    hints: ["main.tf=resources, variables.tf=inputs, outputs.tf=exports"],
+  },
+
+  // ——— Testing —————————————————————————————————————————
+  {
+    id: "jest",
+    name: "Jest",
+    category: "testing",
+    fileMarkers: ["jest.config.ts", "jest.config.js", "jest.config.mjs"],
+    dirMarkers: [],
+    packageDeps: ["jest"],
+    ignoreDirs: [],
+    keyFiles: ["jest.config.ts", "jest.config.js"],
+    explorePatterns: ["**/*.test.ts", "**/*.spec.ts"],
+    hints: ["Tests in *.test.ts / *.spec.ts"],
+  },
+  {
+    id: "vitest",
+    name: "Vitest",
+    category: "testing",
+    fileMarkers: ["vitest.config.ts", "vitest.config.js"],
+    dirMarkers: [],
+    packageDeps: ["vitest"],
+    ignoreDirs: [],
+    keyFiles: ["vitest.config.ts"],
+    explorePatterns: ["**/*.test.ts", "**/*.spec.ts"],
+    hints: ["Tests in *.test.ts / *.spec.ts"],
+  },
+  {
+    id: "pytest",
+    name: "pytest",
+    category: "testing",
+    fileMarkers: ["pytest.ini", "conftest.py"],
+    dirMarkers: [],
+    ignoreDirs: [".pytest_cache"],
+    keyFiles: ["pytest.ini", "conftest.py"],
+    explorePatterns: ["**/test_*.py", "**/*_test.py"],
+    hints: ["Tests in test_*.py, fixtures in conftest.py"],
+  },
+  {
+    id: "playwright",
+    name: "Playwright",
+    category: "testing",
+    fileMarkers: ["playwright.config.ts", "playwright.config.js"],
+    dirMarkers: [],
+    packageDeps: ["@playwright/test"],
+    ignoreDirs: ["test-results", "playwright-report"],
+    keyFiles: ["playwright.config.ts"],
+    explorePatterns: ["**/*.spec.ts"],
+    hints: ["E2E tests, config in playwright.config.ts"],
+  },
+
+  // ——— Build tools —————————————————————————————————————
+  {
+    id: "webpack",
+    name: "Webpack",
+    category: "build",
+    fileMarkers: ["webpack.config.js", "webpack.config.ts"],
+    dirMarkers: [],
+    packageDeps: ["webpack"],
+    ignoreDirs: [],
+    keyFiles: ["webpack.config.js", "webpack.config.ts"],
+    explorePatterns: [],
+    hints: [],
+  },
+  {
+    id: "vite",
+    name: "Vite",
+    category: "build",
+    fileMarkers: ["vite.config.ts", "vite.config.js"],
+    dirMarkers: [],
+    packageDeps: ["vite"],
+    ignoreDirs: [],
+    keyFiles: ["vite.config.ts", "vite.config.js"],
+    explorePatterns: [],
+    hints: [],
+  },
+  {
+    id: "esbuild",
+    name: "esbuild",
+    category: "build",
+    fileMarkers: [],
+    dirMarkers: [],
+    packageDeps: ["esbuild"],
+    ignoreDirs: [],
+    keyFiles: [],
+    explorePatterns: [],
+    hints: [],
+  },
+];
+
+/* ═══════════════════════════════════════════════════════════════
+   MONOREPO RULES
+   ═══════════════════════════════════════════════════════════════ */
+
+export const MONOREPO_RULES: MonorepoRule[] = [
+  {
+    id: "nx",
+    name: "NX",
+    fileMarkers: ["nx.json"],
+    workspaceDirs: ["apps", "libs", "packages"],
+    ignoreDirs: [".nx", "node_modules"],
+    hints: [
+      "project.json in each sub-project defines targets (build/serve/test)",
+      "nx graph shows dependency graph",
+    ],
+  },
+  {
+    id: "turborepo",
+    name: "Turborepo",
+    fileMarkers: ["turbo.json"],
+    workspaceDirs: ["apps", "packages"],
+    ignoreDirs: [".turbo", "node_modules"],
+    hints: ["Pipeline in turbo.json, packages in packages/ and apps/"],
+  },
+  {
+    id: "lerna",
+    name: "Lerna",
+    fileMarkers: ["lerna.json"],
+    workspaceDirs: ["packages"],
+    ignoreDirs: ["node_modules"],
+    hints: ["Packages in packages/, version mgmt via lerna.json"],
+  },
+  {
+    id: "pnpm-workspaces",
+    name: "pnpm workspaces",
+    fileMarkers: ["pnpm-workspace.yaml"],
+    workspaceDirs: ["packages", "apps", "libs"],
+    ignoreDirs: ["node_modules"],
+    hints: ["Workspace members defined in pnpm-workspace.yaml"],
+  },
+  {
+    id: "go-workspaces",
+    name: "Go workspaces",
+    fileMarkers: ["go.work"],
+    workspaceDirs: ["cmd", "internal", "pkg"],
+    ignoreDirs: ["vendor"],
+    hints: ["Workspace modules in go.work"],
+  },
+];
+
+/** Dirs always excluded regardless of detected tech. */
+const ALWAYS_IGNORE = new Set([".git", "coverage", ".idea", ".vscode"]);
+
+/* ═══════════════════════════════════════════════════════════════
+   INTERNAL TYPES
+   ═══════════════════════════════════════════════════════════════ */
+
+interface DetectedTech {
+  rule: TechRule;
+  evidence: string[];
+}
+
+interface SubProject {
+  relPath: string;
+  techs: DetectedTech[];
+}
+
+interface ScanResult {
+  monorepo: MonorepoRule | null;
+  yarnWorkspaceDirs: string[];
+  rootTechs: DetectedTech[];
+  subProjects: SubProject[];
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   TOOL
+   ═══════════════════════════════════════════════════════════════ */
+
+export class ProjectScannerTool extends ToolBase {
+  readonly name = "projectScanner";
+  override readonly readonly = true;
+  readonly description =
+    "Fast structural scan of a project or monorepo. " +
+    "Detects languages, frameworks, databases, infrastructure, testing, build tools, " +
+    "and monorepo layout including sub-projects. " +
+    "Returns compact guidance: dirs to ignore, key files to read, " +
+    "patterns for find_files, and technology-specific hints. " +
+    "Use FIRST before any deep file exploration.";
+
+  constructor(private readonly rootDir: string) {
+    super(
+      z.object({
+        path: z
+          .string()
+          .optional()
+          .describe(
+            "Path to scan, relative to project root. Defaults to root."
+          ),
+      })
+    );
+  }
+
+  async run(
+    input: Record<string, unknown>,
+    _ctx: ToolContext
+  ): Promise<ToolExecutionResult> {
+    const relPath = (input.path as string) || ".";
+    const scanDir = resolveSafePath(this.rootDir, relPath);
+    if (!scanDir) {
+      return { success: false, error: "Path traversal not allowed." };
+    }
+    if (!fs.existsSync(scanDir) || !fs.statSync(scanDir).isDirectory()) {
+      return { success: false, error: `Not a directory: ${relPath}` };
+    }
+
+    const result = this.scan(scanDir);
+    return { success: true, output: this.format(result, scanDir) };
+  }
+
+  /* ——— Scanning ——————————————————————————————————————— */
+
+  private scan(dir: string): ScanResult {
+    const rootDeps = this.readDeps(dir);
+    const rootTechs = this.detectTechs(dir, rootDeps);
+
+    // Monorepo detection
+    let monorepo: MonorepoRule | null = null;
+    for (const rule of MONOREPO_RULES) {
+      if (rule.fileMarkers.some((f) => fs.existsSync(path.join(dir, f)))) {
+        monorepo = rule;
+        break;
+      }
+    }
+
+    // Yarn/npm workspaces (package.json "workspaces" field)
+    const yarnWorkspaceDirs: string[] = [];
+    const pkg = this.readPackageJson(dir);
+    if (pkg?.workspaces) {
+      const patterns: string[] = Array.isArray(pkg.workspaces)
+        ? pkg.workspaces
+        : pkg.workspaces.packages || [];
+      for (const pattern of patterns) {
+        const prefix = pattern.split(/[*{]/)[0].replace(/\/$/, "");
+        if (prefix && !yarnWorkspaceDirs.includes(prefix)) {
+          yarnWorkspaceDirs.push(prefix);
+        }
+      }
+    }
+
+    // Collect workspace dirs to scan
+    const wsDirs = new Set<string>();
+    if (monorepo) {
+      for (const d of monorepo.workspaceDirs) wsDirs.add(d);
+    }
+    for (const d of yarnWorkspaceDirs) wsDirs.add(d);
+
+    // Detect sub-projects
+    const subProjects: SubProject[] = [];
+    for (const wsDir of wsDirs) {
+      this.scanWorkspaceDir(dir, wsDir, rootDeps, subProjects);
+    }
+
+    // No monorepo tool detected — check for plain multi-project layout
+    if (!monorepo && yarnWorkspaceDirs.length === 0 && subProjects.length === 0) {
+      this.detectPlainSubProjects(dir, subProjects);
+    }
+
+    return { monorepo, yarnWorkspaceDirs, rootTechs, subProjects };
+  }
+
+  private scanWorkspaceDir(
+    rootDir: string,
+    wsDir: string,
+    rootDeps: Set<string>,
+    out: SubProject[]
+  ): void {
+    const full = path.join(rootDir, wsDir);
+    if (!fs.existsSync(full) || !fs.statSync(full).isDirectory()) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(full, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const projDir = path.join(full, entry.name);
+      const projDeps = this.readDeps(projDir, rootDeps);
+      const techs = this.detectTechs(projDir, projDeps);
+      if (techs.length > 0) {
+        out.push({ relPath: path.relative(rootDir, projDir), techs });
+      }
+    }
+  }
+
+  /**
+   * Fallback: scan top-level dirs that have their own config file
+   * (looks like independent projects grouped in a directory).
+   */
+  private detectPlainSubProjects(
+    dir: string,
+    out: SubProject[]
+  ): void {
+    const PROJECT_CONFIGS = [
+      "package.json",
+      "Cargo.toml",
+      "go.mod",
+      "pyproject.toml",
+      "composer.json",
+      "Gemfile",
+      "pom.xml",
+      "build.gradle",
+    ];
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      if (ALWAYS_IGNORE.has(entry.name)) continue;
+
+      const subDir = path.join(dir, entry.name);
+      const hasOwnConfig = PROJECT_CONFIGS.some((f) =>
+        fs.existsSync(path.join(subDir, f))
+      );
+      if (!hasOwnConfig) continue;
+
+      const subDeps = this.readDeps(subDir);
+      const techs = this.detectTechs(subDir, subDeps);
+      if (techs.length > 0) {
+        out.push({ relPath: entry.name, techs });
+      }
+    }
+  }
+
+  /* ——— Tech detection ———————————————————————————————— */
+
+  private detectTechs(dir: string, deps: Set<string>): DetectedTech[] {
+    const detected: DetectedTech[] = [];
+
+    for (const rule of TECH_RULES) {
+      const evidence: string[] = [];
+
+      for (const f of rule.fileMarkers) {
+        if (fs.existsSync(path.join(dir, f))) evidence.push(f);
+      }
+      for (const d of rule.dirMarkers) {
+        const full = path.join(dir, d);
+        try {
+          if (fs.existsSync(full) && fs.statSync(full).isDirectory()) {
+            evidence.push(d + "/");
+          }
+        } catch {
+          /* permission error etc. */
+        }
+      }
+      if (rule.packageDeps) {
+        for (const dep of rule.packageDeps) {
+          if (deps.has(dep)) evidence.push(`dep:${dep}`);
+        }
+      }
+
+      if (evidence.length > 0) {
+        detected.push({ rule, evidence });
+      }
+    }
+
+    // Special: .NET detection via extensions (no fixed filenames)
+    this.detectByExtension(dir, detected);
+
+    return detected;
+  }
+
+  private detectByExtension(dir: string, detected: DetectedTech[]): void {
+    // Skip if .NET already detected
+    if (detected.some((d) => d.rule.id === "dotnet")) return;
+
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      return;
+    }
+    const hasSln = entries.some((e) => e.endsWith(".sln"));
+    const hasCsproj = entries.some((e) => e.endsWith(".csproj"));
+    if (hasSln || hasCsproj) {
+      const rule = TECH_RULES.find((r) => r.id === "dotnet")!;
+      const evidence = hasSln ? ["*.sln"] : ["*.csproj"];
+      detected.push({ rule, evidence });
+    }
+  }
+
+  /* ——— Dependency reading ————————————————————————————— */
+
+  private readPackageJson(dir: string): Record<string, any> | null {
+    const p = path.join(dir, "package.json");
+    try {
+      if (fs.existsSync(p)) {
+        return JSON.parse(fs.readFileSync(p, "utf-8"));
+      }
+    } catch {
+      /* malformed JSON */
+    }
+    return null;
+  }
+
+  private readDeps(dir: string, fallback?: Set<string>): Set<string> {
+    const deps = new Set<string>(fallback ?? []);
+
+    // package.json
+    const pkg = this.readPackageJson(dir);
+    if (pkg) {
+      for (const section of [
+        "dependencies",
+        "devDependencies",
+        "peerDependencies",
+      ]) {
+        if (pkg[section]) {
+          for (const name of Object.keys(pkg[section])) deps.add(name);
+        }
+      }
+    }
+
+    // Python: read requirements.txt package names
+    const reqTxt = path.join(dir, "requirements.txt");
+    try {
+      if (fs.existsSync(reqTxt)) {
+        const lines = fs.readFileSync(reqTxt, "utf-8").split("\n");
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("-")) continue;
+          const name = trimmed.split(/[>=<!~\[;]/)[0].trim().toLowerCase();
+          if (name) deps.add(name);
+        }
+      }
+    } catch {
+      /* read error */
+    }
+
+    return deps;
+  }
+
+  /* ——— Output formatting ————————————————————————————— */
+
+  private format(result: ScanResult, scanDir: string): string {
+    const lines: string[] = [];
+    const hasSubProjects = result.subProjects.length > 0;
+
+    // Structure
+    if (result.monorepo) {
+      lines.push(`Structure: monorepo (${result.monorepo.name})`);
+    } else if (result.yarnWorkspaceDirs.length > 0) {
+      lines.push(`Structure: monorepo (npm/yarn workspaces)`);
+    } else if (hasSubProjects) {
+      lines.push(`Structure: multi-project`);
+    } else {
+      lines.push(`Structure: single project`);
+    }
+
+    // Aggregate ignore dirs
+    const ignoreSet = new Set<string>(ALWAYS_IGNORE);
+    const allTechs = [...result.rootTechs];
+    for (const sp of result.subProjects) {
+      for (const t of sp.techs) allTechs.push(t);
+    }
+    if (result.monorepo) {
+      for (const d of result.monorepo.ignoreDirs) ignoreSet.add(d);
+    }
+    for (const t of allTechs) {
+      for (const d of t.rule.ignoreDirs) ignoreSet.add(d);
+    }
+    lines.push(`Ignore: ${[...ignoreSet].sort().join(", ")}`);
+    lines.push("");
+
+    // Root technologies
+    if (result.rootTechs.length > 0) {
+      const label = hasSubProjects ? "Root" : "Detected";
+      lines.push(this.formatSection(label, result.rootTechs, scanDir));
+    }
+
+    // Sub-projects
+    for (const sp of result.subProjects) {
+      const spDir = path.join(scanDir, sp.relPath);
+      lines.push(this.formatSection(sp.relPath, sp.techs, spDir));
+    }
+
+    // Monorepo-specific hints
+    if (result.monorepo && result.monorepo.hints.length > 0) {
+      lines.push("Monorepo:");
+      for (const h of result.monorepo.hints) lines.push(`  ${h}`);
+    }
+
+    return lines.join("\n").trimEnd();
+  }
+
+  private formatSection(
+    label: string,
+    techs: DetectedTech[],
+    dir: string
+  ): string {
+    const lines: string[] = [];
+
+    // Tech names
+    const names = techs.map((t) => t.rule.name).join(", ");
+    lines.push(`${label}: ${names}`);
+
+    // Key files (only those that actually exist on disk)
+    const keyFiles: string[] = [];
+    for (const t of techs) {
+      for (const f of t.rule.keyFiles) {
+        if (!keyFiles.includes(f) && fs.existsSync(path.join(dir, f))) {
+          keyFiles.push(f);
+        }
+      }
+    }
+    if (keyFiles.length > 0) {
+      lines.push(`  read: ${keyFiles.join(", ")}`);
+    }
+
+    // Explore patterns (deduplicated)
+    const patterns: string[] = [];
+    for (const t of techs) {
+      for (const p of t.rule.explorePatterns) {
+        if (!patterns.includes(p)) patterns.push(p);
+      }
+    }
+    if (patterns.length > 0) {
+      lines.push(`  find: ${patterns.join(", ")}`);
+    }
+
+    // Hints — only from framework, database, and infra categories (skip generic language/build hints)
+    const hints: string[] = [];
+    for (const t of techs) {
+      if (["framework", "database", "infra"].includes(t.rule.category)) {
+        for (const h of t.rule.hints) hints.push(h);
+      }
+    }
+    if (hints.length > 0) {
+      lines.push(`  hints: ${hints.join(" · ")}`);
+    }
+
+    lines.push("");
+    return lines.join("\n");
+  }
+}