archbyte 0.1.0

package/dist/agents/static/index.js

@@ -0,0 +1,307 @@
+// Static Analysis — Orchestrator
+// Runs all scanners in dependency order and returns a complete StaticAnalysisResult
+import { StaticToolkit } from "./utils.js";
+import { scanStructure } from "./structure-scanner.js";
+import { parseDocs } from "./doc-parser.js";
+import { detectComponents } from "./component-detector.js";
+import { analyzeInfra } from "./infra-analyzer.js";
+import { detectEvents } from "./event-detector.js";
+import { detectEnvironments } from "./env-detector.js";
+import { mapConnections } from "./connection-mapper.js";
+import { validateAnalysis } from "./validator.js";
+import { collectFileTree } from "./file-tree-collector.js";
+import { collectCodeSamples } from "./code-sampler.js";
+export { validateAnalysis } from "./validator.js";
+/**
+ * Run all static analysis scanners.
+ *
+ * Pipeline:
+ *   1. Parallel: structure, docs, infra, events, envs
+ *   2. Sequential: components (needs structure), connections (needs components+infra+events)
+ *   3. Validation + auto-repair
+ *   4. Gap detection — identify what the LLM should resolve
+ */
+export async function runStaticAnalysis(projectRoot, onProgress) {
+    const tk = new StaticToolkit(projectRoot);
+    // Phase 1: parallel scanners (no dependencies)
+    onProgress?.("Running parallel scanners...");
+    const [structure, docs, infra, events, envs] = await Promise.all([
+        scanStructure(tk),
+        parseDocs(tk),
+        analyzeInfra(tk),
+        detectEvents(tk),
+        detectEnvironments(tk),
+    ]);
+    onProgress?.(`Detected: ${structure.language}, ${structure.framework ?? "no framework"}, monorepo=${structure.isMonorepo}`);
+    // Phase 2: component detection (needs structure for monorepo info)
+    onProgress?.("Detecting components...");
+    const components = await detectComponents(tk, structure);
+    onProgress?.(`Found ${components.components.length} component(s)`);
+    // Phase 3: connection mapping (needs components + infra + events)
+    onProgress?.("Mapping connections...");
+    const connections = await mapConnections(tk, components.components, infra, events);
+    onProgress?.(`Found ${connections.connections.length} connection(s)`);
+    // Assemble result
+    const analysis = {
+        structure,
+        docs,
+        components,
+        infra,
+        events,
+        envs,
+        connections,
+        validation: { valid: true, repairs: [], errors: [] },
+        gaps: [],
+    };
+    // Phase 4: validate + auto-repair
+    onProgress?.("Validating...");
+    analysis.validation = validateAnalysis(analysis);
+    if (analysis.validation.repairs.length > 0) {
+        onProgress?.(`Applied ${analysis.validation.repairs.length} auto-repair(s)`);
+    }
+    // Phase 5: identify gaps for LLM resolution
+    analysis.gaps = await collectGaps(analysis, tk);
+    if (analysis.gaps.length > 0) {
+        onProgress?.(`Identified ${analysis.gaps.length} gap(s) for LLM resolution`);
+    }
+    return analysis;
+}
+/**
+ * Analyze the static results and identify gaps the LLM should resolve.
+ * Fully generic — works for any project structure.
+ */
+async function collectGaps(analysis, tk) {
+    const gaps = [];
+    const componentIds = new Set(analysis.components.components.map((c) => c.id));
+    const connectedIds = new Set();
+    for (const c of analysis.connections.connections) {
+        connectedIds.add(c.from);
+        connectedIds.add(c.to);
+    }
+    // 1. Unknown primary language
+    if (analysis.structure.language === "unknown") {
+        gaps.push({
+            category: "unknown_primary_language",
+            description: "Could not determine the primary programming language from config files. Please infer from the component technologies and file structure.",
+            context: {
+                languages: analysis.structure.languages,
+                componentTechs: analysis.components.components.map((c) => ({
+                    id: c.id,
+                    technologies: c.technologies,
+                })),
+            },
+        });
+    }
+    // 2. Unresolved docker services — services that couldn't map to any component
+    if (analysis.infra.docker.composeFile) {
+        for (const svc of analysis.infra.docker.services) {
+            // Check if this service name or its build context maps to any component
+            const isConnected = analysis.connections.connections.some((c) => c.description.includes(svc.name));
+            const matchesComponent = analysis.components.components.some((c) => c.id === svc.name || c.path === svc.name ||
+                c.name.toLowerCase() === svc.name.toLowerCase());
+            if (!isConnected && !matchesComponent) {
+                gaps.push({
+                    category: "unresolved_docker_service",
+                    description: `Docker service "${svc.name}" could not be mapped to any detected component. What component does it belong to, or is it an external service (database, cache, queue)?`,
+                    context: {
+                        serviceName: svc.name,
+                        image: svc.image,
+                        buildContext: svc.buildContext,
+                        ports: svc.ports,
+                        dependsOn: svc.dependsOn,
+                        environment: svc.environment,
+                    },
+                });
+            }
+        }
+    }
+    // 3. Isolated components — no connections at all
+    for (const comp of analysis.components.components) {
+        if (!connectedIds.has(comp.id)) {
+            gaps.push({
+                category: "isolated_component",
+                description: `Component "${comp.name}" (${comp.id}) has no connections to other components. How does it communicate with the rest of the system?`,
+                relatedComponentIds: [comp.id],
+                context: {
+                    type: comp.type,
+                    path: comp.path,
+                    technologies: comp.technologies,
+                },
+            });
+        }
+    }
+    // 4. Weak or missing descriptions
+    for (const comp of analysis.components.components) {
+        if (!comp.description || comp.description.length < 20) {
+            gaps.push({
+                category: "weak_description",
+                description: `Component "${comp.name}" has a weak or missing description. Please provide a 1-2 sentence description of its purpose and role in the system.`,
+                relatedComponentIds: [comp.id],
+                context: {
+                    currentDescription: comp.description,
+                    type: comp.type,
+                    path: comp.path,
+                    technologies: comp.technologies,
+                },
+            });
+        }
+    }
+    // 5. Missing database — DB env vars found in components but no database component exists
+    const hasDbComponent = analysis.components.components.some((c) => c.type === "database" || c.layer === "data");
+    if (!hasDbComponent) {
+        // Check if any docker service looks like a database
+        const dbDockerServices = analysis.infra.docker.services.filter((s) => {
+            const img = (s.image ?? "").toLowerCase();
+            return img.includes("postgres") || img.includes("mysql") || img.includes("mongo") ||
+                img.includes("mariadb") || img.includes("redis") || img.includes("sqlite");
+        });
+        // Check if docs mention databases
+        const dbMentionsInDocs = analysis.docs.externalDependencies.filter((d) => /postgres|mysql|mongo|redis|sqlite|database|supabase|firebase/i.test(d));
+        // Check if any component has DB env vars (this was detected by connection-mapper)
+        const dbConnections = analysis.connections.connections.filter((c) => c.type === "database");
+        if (dbDockerServices.length > 0 || dbMentionsInDocs.length > 0 || dbConnections.length > 0) {
+            gaps.push({
+                category: "missing_database",
+                description: "Database references were found (Docker services, env vars, or docs) but no database component was detected. What databases does this project use?",
+                context: {
+                    dockerDbServices: dbDockerServices.map((s) => ({ name: s.name, image: s.image })),
+                    docMentions: dbMentionsInDocs,
+                    dbConnectionCount: dbConnections.length,
+                },
+            });
+        }
+    }
+    // 6. External services mentioned in docs but not modeled
+    if (analysis.docs.externalDependencies.length > 0) {
+        const modeledExternals = new Set(analysis.components.components
+            .filter((c) => c.layer === "external")
+            .flatMap((c) => c.technologies.map((t) => t.toLowerCase())));
+        const unmodeledServices = analysis.docs.externalDependencies.filter((dep) => !modeledExternals.has(dep.toLowerCase()));
+        if (unmodeledServices.length > 0) {
+            gaps.push({
+                category: "unmodeled_external_service",
+                description: `External services mentioned in documentation but not modeled as components: ${unmodeledServices.join(", ")}. Which components use these services, and how?`,
+                context: { services: unmodeledServices },
+            });
+        }
+    }
+    // 7. API endpoints found but not tied to connections
+    if (analysis.docs.apiEndpoints.length > 0 && analysis.connections.connections.length === 0) {
+        gaps.push({
+            category: "unmapped_api_endpoints",
+            description: `${analysis.docs.apiEndpoints.length} API endpoint(s) found in docs but no connections were detected. Which components expose and consume these APIs?`,
+            context: {
+                endpoints: analysis.docs.apiEndpoints.slice(0, 10),
+            },
+        });
+    }
+    // 8. Event-driven patterns detected but no event connections
+    if (analysis.events.hasEDA) {
+        const hasEventConnections = analysis.connections.connections.some((c) => c.type === "event" || c.type === "queue");
+        if (!hasEventConnections) {
+            gaps.push({
+                category: "event_pattern_no_connection",
+                description: `Event-driven patterns detected (${analysis.events.patterns.map((p) => p.technology).join(", ")}) but no event/queue connections were mapped. Which components publish and subscribe to events?`,
+                relatedComponentIds: analysis.components.components.map((c) => c.id),
+                context: {
+                    patterns: analysis.events.patterns,
+                    events: analysis.events.events.slice(0, 10),
+                },
+            });
+        }
+    }
+    // 9. Ambiguous component types — heuristic: Flutter/React Native should be "frontend" not "service"
+    for (const comp of analysis.components.components) {
+        const techs = comp.technologies.map((t) => t.toLowerCase());
+        const isFrontendTech = techs.some((t) => ["flutter", "react native", "react", "vue", "angular", "svelte", "next.js", "nuxt"].includes(t));
+        if (isFrontendTech && comp.type !== "frontend") {
+            gaps.push({
+                category: "ambiguous_component_type",
+                description: `Component "${comp.name}" uses ${comp.technologies.join(", ")} (frontend technologies) but is typed as "${comp.type}". Should it be "frontend"?`,
+                relatedComponentIds: [comp.id],
+                context: {
+                    currentType: comp.type,
+                    technologies: comp.technologies,
+                },
+            });
+        }
+    }
+    // 10. Large components that may contain multiple logical modules
+    const skipForSubdirScan = new Set(["node_modules", "dist", "build", ".git", "coverage", "venv", "__pycache__", "target"]);
+    for (const comp of analysis.components.components) {
+        if (comp.path === ".")
+            continue;
+        try {
+            const entries = await tk.listDir(comp.path);
+            const subdirs = entries
+                .filter((e) => e.type === "directory" && !skipForSubdirScan.has(e.name) && !e.name.startsWith("."))
+                .map((e) => e.name);
+            if (subdirs.length >= 8) {
+                gaps.push({
+                    category: "isolated_component",
+                    description: `Component "${comp.name}" at ${comp.path}/ has ${subdirs.length} subdirectories that may be separate logical modules. Should any of these be their own component? List: ${subdirs.join(", ")}`,
+                    relatedComponentIds: [comp.id],
+                    context: {
+                        subdirectories: subdirs,
+                        count: subdirs.length,
+                    },
+                });
+            }
+        }
+        catch {
+            // Can't list dir, skip
+        }
+    }
+    // 11. Top-level directories with many subdirectories not detected as components
+    // (e.g. skills/, apps/ with 50+ items that aren't workspace members)
+    const componentPaths = new Set(analysis.components.components.map((c) => c.path));
+    const topDirs = Object.keys(analysis.structure.directories);
+    for (const dir of topDirs) {
+        if (componentPaths.has(dir))
+            continue;
+        if (skipForSubdirScan.has(dir) || dir.startsWith("."))
+            continue;
+        try {
+            const entries = await tk.listDir(dir);
+            const subdirs = entries
+                .filter((e) => e.type === "directory" && !e.name.startsWith("."))
+                .map((e) => e.name);
+            if (subdirs.length >= 5) {
+                gaps.push({
+                    category: "isolated_component",
+                    description: `Directory "${dir}/" has ${subdirs.length} subdirectories but was not detected as a component. These may be plugins, extensions, skills, or other modules: ${subdirs.slice(0, 20).join(", ")}${subdirs.length > 20 ? ` (+${subdirs.length - 20} more)` : ""}`,
+                    context: {
+                        directory: dir,
+                        subdirectories: subdirs.slice(0, 30),
+                        count: subdirs.length,
+                    },
+                });
+            }
+        }
+        catch {
+            // Skip
+        }
+    }
+    return gaps;
+}
+/**
+ * Collect raw static context from all 7 scanners.
+ * This runs ONLY fact-collectors (no component-detector, connection-mapper, or validator).
+ * Output is consumed by the pipeline LLM agents.
+ */
+export async function runStaticContextCollection(projectRoot, onProgress) {
+    const tk = new StaticToolkit(projectRoot);
+    onProgress?.("Collecting static context (7 scanners in parallel)...");
+    const [structure, docs, infra, events, envs, fileTree, codeSamples] = await Promise.all([
+        scanStructure(tk),
+        parseDocs(tk),
+        analyzeInfra(tk),
+        detectEvents(tk),
+        detectEnvironments(tk),
+        collectFileTree(tk),
+        collectCodeSamples(tk),
+    ]);
+    onProgress?.(`Context: ${fileTree.totalFiles} files, ${fileTree.totalDirs} dirs, ${codeSamples.configFiles.length} configs, ${codeSamples.samples.length} samples`);
+    onProgress?.(`Detected: ${structure.language}, ${structure.framework ?? "no framework"}, monorepo=${structure.isMonorepo}`);
+    return { structure, docs, infra, events, envs, fileTree, codeSamples };
+}

package/dist/agents/static/infra-analyzer.d.ts

@@ -0,0 +1,3 @@
+import type { InfraResult } from "./types.js";
+import type { StaticToolkit } from "./utils.js";
+export declare function analyzeInfra(tk: StaticToolkit): Promise<InfraResult>;

package/dist/agents/static/infra-analyzer.js

@@ -0,0 +1,208 @@
+// Static Analysis — Infrastructure Analyzer
+// Parses Docker, Kubernetes, CI/CD, and cloud infrastructure via js-yaml
+export async function analyzeInfra(tk) {
+    const result = {
+        docker: { services: [], composeFile: false },
+        kubernetes: { resources: [] },
+        cloud: { provider: null, services: [], iac: null },
+        ci: { platform: null, pipelines: [] },
+    };
+    await Promise.all([
+        parseDockerCompose(tk, result),
+        parseKubernetes(tk, result),
+        detectCI(tk, result),
+        detectCloud(tk, result),
+    ]);
+    return result;
+}
+async function parseDockerCompose(tk, result) {
+    // Try common compose file names at root and in subdirectories
+    const composeNames = ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"];
+    let composeData = null;
+    let composeDir = "";
+    // Check root first
+    for (const name of composeNames) {
+        composeData = await tk.readYAML(name);
+        if (composeData) {
+            composeDir = "";
+            break;
+        }
+    }
+    // If not at root, search subdirectories
+    if (!composeData) {
+        const rootEntries = await tk.listDir(".");
+        const dirs = rootEntries.filter((e) => e.type === "directory").map((e) => e.name);
+        for (const dir of dirs) {
+            if (dir.startsWith(".") || dir === "node_modules" || dir === "dist")
+                continue;
+            for (const name of composeNames) {
+                composeData = await tk.readYAML(`${dir}/${name}`);
+                if (composeData) {
+                    composeDir = dir;
+                    break;
+                }
+            }
+            if (composeData)
+                break;
+        }
+    }
+    if (!composeData || typeof composeData !== "object")
+        return;
+    result.docker.composeFile = true;
+    result.docker.composeFilePath = composeDir || undefined;
+    const compose = composeData;
+    const services = compose.services;
+    if (!services)
+        return;
+    for (const [name, svc] of Object.entries(services)) {
+        const ports = svc.ports?.map(String) ?? [];
+        const dependsOn = Array.isArray(svc.depends_on)
+            ? svc.depends_on
+            : svc.depends_on && typeof svc.depends_on === "object"
+                ? Object.keys(svc.depends_on)
+                : [];
+        const envObj = svc.environment;
+        const environment = {};
+        if (Array.isArray(envObj)) {
+            for (const e of envObj) {
+                const [k, v] = e.split("=");
+                if (k)
+                    environment[k] = v ?? "";
+            }
+        }
+        else if (envObj && typeof envObj === "object") {
+            Object.assign(environment, envObj);
+        }
+        // Extract build context
+        let buildContext;
+        if (svc.build) {
+            if (typeof svc.build === "string") {
+                buildContext = svc.build;
+            }
+            else if (typeof svc.build === "object") {
+                const buildObj = svc.build;
+                buildContext = buildObj.context;
+            }
+        }
+        result.docker.services.push({
+            name,
+            image: svc.image,
+            buildContext,
+            ports,
+            dependsOn,
+            environment,
+        });
+    }
+}
+async function parseKubernetes(tk, result) {
+    const k8sFiles = await tk.globFiles("k8s/**/*.{yml,yaml}");
+    const k8sRoot = await tk.globFiles("*.{yml,yaml}");
+    // Also check common k8s dirs
+    const moreDirs = await Promise.all([
+        tk.globFiles("kubernetes/**/*.{yml,yaml}"),
+        tk.globFiles("deploy/**/*.{yml,yaml}"),
+        tk.globFiles("manifests/**/*.{yml,yaml}"),
+    ]);
+    const allFiles = [...k8sFiles, ...moreDirs.flat()];
+    // Filter out docker-compose and CI files
+    const k8sManifests = allFiles.filter((f) => !f.includes("docker-compose") && !f.includes("compose.y"));
+    for (const file of k8sManifests.slice(0, 20)) {
+        const docs = await tk.readYAMLAll(file);
+        for (const doc of docs) {
+            if (!doc || typeof doc !== "object")
+                continue;
+            const resource = doc;
+            if (resource.kind && resource.metadata) {
+                const meta = resource.metadata;
+                result.kubernetes.resources.push({
+                    kind: resource.kind,
+                    name: meta.name ?? "unknown",
+                    namespace: meta.namespace,
+                });
+            }
+        }
+    }
+}
+async function detectCI(tk, result) {
+    // Check for CI configs in parallel
+    const [ghWorkflows, gitlabCI, circleci, jenkinsfile] = await Promise.all([
+        tk.globFiles(".github/workflows/*.{yml,yaml}"),
+        tk.readFileSafe(".gitlab-ci.yml"),
+        tk.readFileSafe(".circleci/config.yml"),
+        tk.readFileSafe("Jenkinsfile"),
+    ]);
+    if (ghWorkflows.length > 0) {
+        result.ci.platform = "GitHub Actions";
+        result.ci.pipelines = ghWorkflows.map((f) => f.replace(".github/workflows/", "").replace(/\.ya?ml$/, ""));
+    }
+    else if (gitlabCI) {
+        result.ci.platform = "GitLab CI";
+        result.ci.pipelines = ["gitlab-ci"];
+    }
+    else if (circleci) {
+        result.ci.platform = "CircleCI";
+        result.ci.pipelines = ["circleci"];
+    }
+    else if (jenkinsfile) {
+        result.ci.platform = "Jenkins";
+        result.ci.pipelines = ["Jenkinsfile"];
+    }
+}
+async function detectCloud(tk, result) {
+    // Check for IaC and cloud config in parallel
+    const [terraformFiles, wranglerToml, vercelJson, netlifyToml, awsCdk, samTemplate, serverlessYml,] = await Promise.all([
+        tk.globFiles("**/*.tf"),
+        tk.readFileSafe("wrangler.toml"),
+        tk.readJSON("vercel.json"),
+        tk.readFileSafe("netlify.toml"),
+        tk.readJSON("cdk.json"),
+        tk.readYAML("template.yaml"), // AWS SAM
+        tk.readYAML("serverless.yml"),
+    ]);
+    if (terraformFiles.length > 0) {
+        result.cloud.iac = "Terraform";
+        // Try to detect provider from tf files
+        for (const tf of terraformFiles.slice(0, 5)) {
+            const content = await tk.readFileSafe(tf);
+            if (content?.includes("aws_")) {
+                result.cloud.provider = "AWS";
+                break;
+            }
+            if (content?.includes("google_")) {
+                result.cloud.provider = "GCP";
+                break;
+            }
+            if (content?.includes("azurerm_")) {
+                result.cloud.provider = "Azure";
+                break;
+            }
+            if (content?.includes("digitalocean_")) {
+                result.cloud.provider = "DigitalOcean";
+                break;
+            }
+        }
+    }
+    if (wranglerToml) {
+        result.cloud.provider = result.cloud.provider ?? "Cloudflare";
+        result.cloud.services.push("Cloudflare Workers");
+    }
+    if (vercelJson) {
+        result.cloud.provider = result.cloud.provider ?? "Vercel";
+        result.cloud.services.push("Vercel");
+    }
+    if (netlifyToml) {
+        result.cloud.provider = result.cloud.provider ?? "Netlify";
+        result.cloud.services.push("Netlify");
+    }
+    if (awsCdk) {
+        result.cloud.iac = "AWS CDK";
+        result.cloud.provider = result.cloud.provider ?? "AWS";
+    }
+    if (samTemplate) {
+        result.cloud.iac = "AWS SAM";
+        result.cloud.provider = result.cloud.provider ?? "AWS";
+    }
+    if (serverlessYml) {
+        result.cloud.iac = "Serverless Framework";
+    }
+}

package/dist/agents/static/structure-scanner.d.ts

@@ -0,0 +1,3 @@
+import type { StructureResult } from "./types.js";
+import type { StaticToolkit } from "./utils.js";
+export declare function scanStructure(tk: StaticToolkit): Promise<StructureResult>;