archbyte 0.5.0 → 0.5.2

package/bin/archbyte.js

@@ -22,6 +22,11 @@ import { handleVersion, handleUpdate } from '../dist/cli/version.js';
 import { requireLicense } from '../dist/cli/license-gate.js';
 import { DEFAULT_PORT } from '../dist/cli/constants.js';
 
+// When spawned by `archbyte serve` (internal), skip interactive license checks.
+// The user already authenticated when they started the server.
+const isInternal = process.env.ARCHBYTE_INTERNAL === '1';
+const gate = isInternal ? async () => {} : requireLicense;
+
 const require = createRequire(import.meta.url);
 const { version: PKG_VERSION } = require('../package.json');
 
@@ -111,7 +116,7 @@ program
   .option('--force', 'Force full re-scan (skip incremental detection)')
   .option('--dry-run', 'Preview without running')
   .action(async (options) => {
-    await requireLicense('analyze');
+    await gate('analyze');
     await handleAnalyze(options);
   });
 
@@ -122,7 +127,7 @@ program
   .option('-o, --output <path>', 'Output diagram (default: .archbyte/architecture.json)')
   .option('-v, --verbose', 'Show detailed output')
   .action(async (options) => {
-    await requireLicense('generate');
+    await gate('generate');
     await handleGenerate(options);
   });
 

package/dist/agents/pipeline/agents/service-describer.js

@@ -33,13 +33,13 @@ export const serviceDescriber = {
         parts.push(`Detected language: ${ctx.structure.language}`);
         parts.push(`Languages: ${ctx.structure.languages.join(", ") || "none"}`);
         parts.push(`Framework: ${ctx.structure.framework ?? "none"}`);
-        // Docs
+        // Docs — only project description, NOT externalDependencies.
+        // Doc-extracted dependency mentions prime the LLM to hallucinate phantom services
+        // (e.g., docs mention "MCP" → LLM creates "MCP Server" component).
+        // The LLM should discover services from actual code evidence only.
         if (ctx.docs.projectDescription) {
             parts.push(`\nFrom docs: ${ctx.docs.projectDescription}`);
         }
-        if (ctx.docs.externalDependencies.length > 0) {
-            parts.push(`\nExternal dependencies mentioned: ${ctx.docs.externalDependencies.join(", ")}`);
-        }
         // Docker services — only include if infra/config files changed (or full scan)
         if (ctx.infra.docker.composeFile && (hasInfraChanges || hasConfigChanges)) {
             const svcInfo = ctx.infra.docker.services.map((s) => {

package/dist/agents/pipeline/merger.js

@@ -1,5 +1,6 @@
 // Pipeline — Merger
 // Assembles all agent outputs into a StaticAnalysisResult
+import { categorizeDep } from "../static/taxonomy.js";
 function sanitize(s) {
     if (!s)
         return s;
@@ -9,21 +10,24 @@ function sanitize(s) {
  * Build a set of "evidence tokens" from the static context — things that concretely
  * exist in the codebase (dependencies, env vars, docker images/services).
  * Used to gate LLM-generated databases/external services against hallucination.
+ *
+ * Uses the package taxonomy to resolve package names to their display names
+ * (e.g., "pg" → also adds "postgresql", "stripe" → also adds "stripe").
+ * This lets the LLM use human-readable names while still requiring code evidence.
  */
 function buildEvidenceTokens(ctx) {
     const tokens = new Set();
+    /** Add a dependency name + its taxonomy display name as tokens. */
+    function addDep(dep) {
+        tokens.add(dep.toLowerCase());
+        const cat = categorizeDep(dep);
+        if (cat)
+            tokens.add(cat.displayName.toLowerCase());
+    }
     // Package dependencies from import map (codeSamples.importMap: file → imported modules)
     for (const imports of Object.values(ctx.codeSamples.importMap)) {
-        for (const imp of imports) {
-            tokens.add(imp.toLowerCase());
-            // Also add short name for scoped packages: @aws-sdk/client-s3 → client-s3, aws-sdk
-            if (imp.startsWith("@")) {
-                const parts = imp.split("/");
-                if (parts[1])
-                    tokens.add(parts[1].toLowerCase());
-                tokens.add(parts[0].slice(1).toLowerCase());
-            }
-        }
+        for (const imp of imports)
+            addDep(imp);
     }
     // Config files may contain dependency info (package.json deps etc.)
     for (const cfg of ctx.codeSamples.configFiles) {
@@ -31,13 +35,7 @@ function buildEvidenceTokens(ctx) {
             try {
                 const pkg = JSON.parse(cfg.content);
                 for (const dep of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })) {
-                    tokens.add(dep.toLowerCase());
-                    if (dep.startsWith("@")) {
-                        const parts = dep.split("/");
-                        if (parts[1])
-                            tokens.add(parts[1].toLowerCase());
-                        tokens.add(parts[0].slice(1).toLowerCase());
-                    }
+                    addDep(dep);
                 }
             }
             catch { /* ignore parse errors */ }
@@ -59,35 +57,29 @@ function buildEvidenceTokens(ctx) {
     for (const s of ctx.infra.cloud.services) {
         tokens.add(s.toLowerCase());
     }
-    // External dependencies mentioned in docs
-    for (const dep of ctx.docs.externalDependencies) {
-        tokens.add(dep.toLowerCase());
-    }
+    // NOTE: ctx.docs.externalDependencies intentionally excluded.
+    // Doc mentions (from markdown/README) are not concrete code evidence and cause
+    // hallucination — the LLM sees "MCP" in docs and creates phantom components.
+    // Only code-level signals (imports, deps, env vars, Docker, cloud) count.
     return tokens;
 }
 /**
- * Check if a service/database ID and type have concrete evidence in the static context.
- * Uses fuzzy matching: checks if any evidence token contains or is contained by the service keywords.
+ * Check if a service/database has concrete evidence in the static context.
+ * Strict exact-match only — no substring/regex fuzzy matching.
+ * The taxonomy enriches evidence tokens with display names (pg → PostgreSQL)
+ * so the LLM can use human-readable names and still match.
  */
 function hasEvidence(id, name, type, evidenceTokens) {
-    // Build candidate keywords from the service
     const candidates = [
         id.toLowerCase(),
         name.toLowerCase(),
         type.toLowerCase(),
-        // Split hyphenated IDs: "aws-sqs" → ["aws", "sqs"]
+        // Split hyphenated IDs: "aws-sqs" → also check "aws", "sqs"
         ...id.toLowerCase().split("-"),
     ].filter(Boolean);
     for (const candidate of candidates) {
-        for (const token of evidenceTokens) {
-            // Direct match or substring match (in both directions)
-            if (token === candidate)
-                return true;
-            if (token.includes(candidate) && candidate.length >= 3)
-                return true;
-            if (candidate.includes(token) && token.length >= 3)
-                return true;
-        }
+        if (evidenceTokens.has(candidate))
+            return true;
     }
     return false;
 }

package/dist/agents/static/component-detector.js

@@ -1,75 +1,22 @@
 // Static Analysis — Component Detector
 // Detects project components via workspaces, conventional directories, build configs, or single-app fallback
 import { slugify, assignLayer } from "./utils.js";
-// Map well-known deps to architecturally significant tech names
-const TECH_MAP = {
-    react: "React", "react-dom": "React", "next": "Next.js", "vue": "Vue", "nuxt": "Nuxt",
-    svelte: "Svelte", angular: "Angular", "@angular/core": "Angular",
-    express: "Express", fastify: "Fastify", "@nestjs/core": "NestJS", hono: "Hono", koa: "Koa",
-    prisma: "Prisma", "@prisma/client": "Prisma", typeorm: "TypeORM", drizzle: "Drizzle",
-    sequelize: "Sequelize", mongoose: "Mongoose", pg: "PostgreSQL", mysql2: "MySQL",
-    redis: "Redis", ioredis: "Redis",
-    graphql: "GraphQL", "@apollo/server": "Apollo GraphQL",
-    "socket.io": "Socket.IO", ws: "WebSocket",
-    tailwindcss: "Tailwind CSS", "@xyflow/react": "React Flow",
-    commander: "Commander.js", yargs: "Yargs",
-    vite: "Vite", webpack: "Webpack", esbuild: "esbuild",
-    typescript: "TypeScript",
-    kafkajs: "Kafka", amqplib: "RabbitMQ", bullmq: "BullMQ", bull: "Bull",
-    stripe: "Stripe", "@stripe/stripe-js": "Stripe",
-    playwright: "Playwright", "@playwright/test": "Playwright",
-    jest: "Jest", vitest: "Vitest", mocha: "Mocha",
-    flutter: "Flutter",
-};
-// Conventional directory → type mapping (hint-based, not exclusive)
-const DIR_TYPE_HINTS = {
-    ui: { type: "frontend", label: "UI" },
-    web: { type: "frontend", label: "Web App" },
-    frontend: { type: "frontend", label: "Frontend" },
-    client: { type: "frontend", label: "Client" },
-    app: { type: "frontend", label: "App" },
-    server: { type: "api", label: "Server" },
-    api: { type: "api", label: "API" },
-    backend: { type: "api", label: "Backend" },
-    gateway: { type: "api", label: "Gateway" },
-    cli: { type: "service", label: "CLI" },
-    agents: { type: "library", label: "Agents" },
-    lib: { type: "library", label: "Library" },
-    packages: { type: "library", label: "Packages" },
-    shared: { type: "library", label: "Shared" },
-    common: { type: "library", label: "Common" },
-    cloud: { type: "service", label: "Cloud" },
-    infra: { type: "service", label: "Infrastructure" },
-    deploy: { type: "service", label: "Deployment" },
-    deployment: { type: "service", label: "Deployment" },
-    workers: { type: "worker", label: "Workers" },
-    jobs: { type: "worker", label: "Jobs" },
-    scripts: { type: "service", label: "Scripts" },
-    e2e: { type: "service", label: "E2E Tests" },
-    tests: { type: "service", label: "Tests" },
-    tools: { type: "service", label: "Tools" },
-    homepage: { type: "frontend", label: "Homepage" },
-    docs: { type: "service", label: "Docs" },
-};
-// Build config files that indicate a directory is a standalone component
-const BUILD_CONFIG_FILES = [
-    "package.json",
-    "Cargo.toml",
-    "go.mod",
-    "pyproject.toml",
-    "requirements.txt",
-    "setup.py",
-    "pubspec.yaml",
-    "build.gradle",
-    "pom.xml",
-    "Gemfile",
-    "Makefile",
-    "Dockerfile",
-    "wrangler.toml",
-    "tsconfig.json",
-];
+import { categorizeDep, categorizeAllDeps, ROLE_TO_TYPE, MANIFEST_FILES } from "./taxonomy.js";
 // Skip these dirs — not components
 import { EXCLUDED_DIRS as SKIP_DIRS } from "./excluded-dirs.js";
+// Structural inference patterns — framework-agnostic grep queries
+const STRUCTURAL_PROBES = [
+    // Frontend: renders UI to DOM / uses JSX components
+    { grep: "createRoot|ReactDOM|hydrateRoot|createApp.*mount|new Vue|bootstrapApplication", type: "frontend", label: "UI renderer" },
+    // API: defines HTTP route handlers
+    { grep: "app\\.(get|post|put|delete|use)\\(|router\\.|@(Get|Post|Put|Delete|Controller)|handle.*Request|Hono\\(", type: "api", label: "HTTP routes" },
+    // Worker: consumes from queue / processes jobs
+    { grep: "\\.process\\(|\\.consume\\(|new Worker\\(|@Processor|celery\\.task", type: "worker", label: "Job processor" },
+    // CLI: parses command-line args
+    { grep: "\\.command\\(|\\.parse\\(process\\.argv|argparse|@Command\\(", type: "service", label: "CLI" },
+    // Server: creates a network listener
+    { grep: "createServer\\(|listen\\(\\d|serve\\(|app\\.listen", type: "api", label: "Server" },
+];
 export async function detectComponents(tk, structure) {
     // Strategy 1: Monorepo workspaces
     if (structure.isMonorepo) {
@@ -157,8 +104,8 @@ async function resolveWorkspacePatterns(tk) {
 }
 /**
  * Scan every top-level directory. If it has a build config, README, Dockerfile,
- * or code files, treat it as a component. Use dir name hints + config file analysis
- * to determine type.
+ * or code files, treat it as a component. Use taxonomy + grep-based structural
+ * inference to determine type.
  */
 async function detectAllComponents(tk, structure) {
     const components = [];
@@ -171,7 +118,7 @@ async function detectAllComponents(tk, structure) {
             continue;
         const fileNames = entries.map((e) => e.name);
         // Check for build config files
-        const hasBuildConfig = BUILD_CONFIG_FILES.some((f) => fileNames.includes(f));
+        const hasBuildConfig = MANIFEST_FILES.some((f) => fileNames.includes(f));
         const hasCode = entries.some((e) => e.type === "file" &&
             /\.(ts|js|tsx|jsx|py|go|rs|java|rb|dart|kt|swift|c|cpp|cs)$/.test(e.name));
         const hasSrcDir = entries.some((e) => e.type === "directory" && (e.name === "src" || e.name === "lib" || e.name === "app"));
@@ -181,10 +128,12 @@ async function detectAllComponents(tk, structure) {
             continue;
         // Detect language + type + tech stack from config files
         const detected = await detectFromBuildConfigs(tk, dir, fileNames);
-        const hint = DIR_TYPE_HINTS[dir.toLowerCase()];
-        const type = detected.type ?? hint?.type ?? "service";
-        const label = hint?.label ?? capitalize(dir);
-        const name = label;
+        // If no type from deps, try grep-based structural inference
+        if (!detected.type) {
+            detected.type = await inferTypeFromCode(tk, dir);
+        }
+        const type = detected.type ?? "service";
+        const name = capitalize(dir);
         // Read description from sub-README if available
         let description = detected.description;
         if (!description && hasReadme) {
@@ -205,6 +154,21 @@ async function detectAllComponents(tk, structure) {
     }
     return components;
 }
+/**
+ * Infer component type by grepping actual code in the directory.
+ * Runs all probes in parallel — first match with hits wins.
+ */
+async function inferTypeFromCode(tk, dir) {
+    const results = await Promise.all(STRUCTURAL_PROBES.map(async (probe) => ({
+        ...probe,
+        hits: await tk.grepFiles(probe.grep, dir),
+    })));
+    for (const r of results) {
+        if (r.hits.length > 0)
+            return r.type;
+    }
+    return null;
+}
 async function detectFromBuildConfigs(tk, dir, fileNames) {
     const info = {
         type: null,
@@ -335,57 +299,57 @@ async function detectFromBuildConfigs(tk, dir, fileNames) {
     info.technologies = [...new Set(info.technologies)].slice(0, 5);
     return info;
 }
-function buildSingleAppComponent(structure) {
-    return {
-        id: slugify(structure.projectName) ?? "app",
-        name: structure.projectName || "Application",
-        type: structure.framework
-            ? (["React", "Vue", "Svelte", "Angular", "Next.js", "Nuxt"].includes(structure.framework)
-                ? "frontend"
-                : "api")
-            : "service",
-        layer: "application",
-        path: ".",
-        description: "",
-        technologies: [structure.language, structure.framework].filter(Boolean),
-    };
-}
+/** Detect component type from package.json dependencies using taxonomy */
 function detectTypeFromDeps(pkg) {
     const deps = Object.keys({
         ...pkg.dependencies,
         ...pkg.devDependencies,
     });
-    // Frontend indicators
-    if (deps.some((d) => ["react", "react-dom", "vue", "svelte", "@angular/core", "next", "nuxt"].includes(d))) {
-        return "frontend";
-    }
-    // API indicators
-    if (deps.some((d) => ["express", "fastify", "@nestjs/core", "hono", "koa"].includes(d))) {
-        return "api";
-    }
-    // Worker indicators
-    if (deps.some((d) => ["bullmq", "bull", "bee-queue"].includes(d))) {
-        return "worker";
-    }
-    // Test indicators
-    if (deps.some((d) => ["@playwright/test", "playwright", "cypress"].includes(d))) {
-        return "service";
+    // Priority: meta-framework > ui-framework > http-framework > queue > test
+    const priorityCategories = [
+        "meta-framework", "ui-framework", "http-framework", "queue-client", "test-framework",
+    ];
+    for (const targetCat of priorityCategories) {
+        for (const dep of deps) {
+            const cat = categorizeDep(dep);
+            if (cat?.category === targetCat) {
+                return ROLE_TO_TYPE[cat.role] ?? "service";
+            }
+        }
     }
     return "service";
 }
+/** Extract display-worthy tech stack names from deps using taxonomy */
 function extractTechStack(pkg) {
     const deps = Object.keys({
         ...pkg.dependencies,
         ...pkg.devDependencies,
     });
+    const categorized = categorizeAllDeps(deps);
+    const seen = new Set();
     const techs = [];
-    for (const dep of deps) {
-        if (TECH_MAP[dep] && !techs.includes(TECH_MAP[dep])) {
-            techs.push(TECH_MAP[dep]);
+    for (const cat of categorized.values()) {
+        if (!seen.has(cat.displayName)) {
+            seen.add(cat.displayName);
+            techs.push(cat.displayName);
         }
     }
     return techs.slice(0, 5);
 }
+function buildSingleAppComponent(structure) {
+    const type = structure.framework
+        ? (categorizeDep(structure.framework.toLowerCase())?.role === "frontend" ? "frontend" : "api")
+        : "service";
+    return {
+        id: slugify(structure.projectName) ?? "app",
+        name: structure.projectName || "Application",
+        type,
+        layer: "application",
+        path: ".",
+        description: "",
+        technologies: [structure.language, structure.framework].filter(Boolean),
+    };
+}
 function capitalize(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }

package/dist/agents/static/connection-mapper.js

@@ -2,6 +2,7 @@
 // Maps connections between components via imports, Docker, K8s, env vars, known SDKs
 // Only deterministic matches — ambiguous mappings are left as gaps for the LLM
 import { slugify } from "./utils.js";
+import { categorizeDep } from "./taxonomy.js";
 export async function mapConnections(tk, components, infra, events, importMap) {
     const connections = [];
     const componentIds = new Set(components.map((c) => c.id));
@@ -194,34 +195,32 @@ async function detectServerServesUI(tk, components, connections) {
     }
 }
 async function detectKnownSDKConnections(components, connections) {
-    const externalTechs = {
-        Stripe: "stripe-api",
-        Firebase: "firebase",
-        Supabase: "supabase",
-        Redis: "redis",
-        Kafka: "kafka",
-        RabbitMQ: "rabbitmq",
-        "Socket.IO": "websocket",
-        PostgreSQL: "database",
-        MySQL: "database",
-        MongoDB: "database",
+    // Role → connection type mapping
+    const roleToConnType = {
+        data: "database",
+        messaging: "queue",
+        external: "http",
     };
     for (const comp of components) {
         for (const tech of comp.technologies) {
-            const externalId = externalTechs[tech];
-            if (externalId) {
-                const target = components.find((c) => c.id !== comp.id && (c.technologies.includes(tech) ||
-                    c.type === "database" && (externalId === "database")));
-                if (target) {
-                    connections.push({
-                        from: comp.id,
-                        to: target.id,
-                        type: externalId === "database" ? "database" : "http",
-                        description: `${comp.name} uses ${tech}`,
-                        confidence: 95,
-                        async: false,
-                    });
-                }
+            // Use taxonomy to determine the role/connection type of this tech
+            const cat = categorizeDep(tech.toLowerCase());
+            if (!cat)
+                continue;
+            const connType = roleToConnType[cat.role];
+            if (!connType)
+                continue;
+            const target = components.find((c) => c.id !== comp.id && (c.technologies.includes(tech) ||
+                (c.type === "database" && connType === "database")));
+            if (target) {
+                connections.push({
+                    from: comp.id,
+                    to: target.id,
+                    type: connType,
+                    description: `${comp.name} uses ${tech}`,
+                    confidence: 95,
+                    async: false,
+                });
             }
         }
     }

package/dist/agents/static/deep-drill.d.ts

@@ -0,0 +1,72 @@
+import type { TreeEntry } from "./types.js";
+export interface DeepDrillResult {
+    componentId: string;
+    componentName: string;
+    componentPath: string;
+    scannedAt: string;
+    durationMs: number;
+    fileTree: TreeEntry[];
+    metrics: {
+        fileCount: number;
+        codeFileCount: number;
+        totalLines: number;
+        languages: Array<{
+            language: string;
+            files: number;
+        }>;
+    };
+    structure: {
+        entryPoints: string[];
+        keyFiles: Array<{
+            path: string;
+            role: string;
+        }>;
+        publicExports: string[];
+        directories: string[];
+    };
+    dependencies: {
+        manifest: string | null;
+        production: Array<{
+            name: string;
+            category: string | null;
+            displayName: string;
+        }>;
+        development: Array<{
+            name: string;
+            category: string | null;
+            displayName: string;
+        }>;
+    };
+    imports: {
+        internalImports: Array<{
+            targetPath: string;
+            sourceFiles: string[];
+        }>;
+        externalPackages: string[];
+    };
+    patterns: Array<{
+        type: string;
+        label: string;
+        matches: Array<{
+            file: string;
+            line: string;
+            content: string;
+        }>;
+        count: number;
+    }>;
+    connections: {
+        outgoing: Array<{
+            targetId: string;
+            targetName: string;
+            type: string;
+            description: string;
+        }>;
+        incoming: Array<{
+            sourceId: string;
+            sourceName: string;
+            type: string;
+            description: string;
+        }>;
+    };
+}
+export declare function runDeepDrill(projectRoot: string, componentId: string, componentName: string, componentPath: string): Promise<DeepDrillResult>;