pi-compass 0.2.0

package/src/analyzers/directory-tree.ts

@@ -0,0 +1,65 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { DirectoryEntry } from "../types.js";
+
+const IGNORED_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".nuxt",
+  "__pycache__", ".tox", ".mypy_cache", ".pytest_cache",
+  "target", ".gradle", ".idea", ".vscode",
+  "vendor", "coverage", ".turbo", ".cache",
+]);
+
+export function buildDirectoryTree(cwd: string, depth = 2): readonly DirectoryEntry[] {
+  return scanDir(cwd, cwd, depth);
+}
+
+function scanDir(dir: string, root: string, remaining: number): DirectoryEntry[] {
+  if (remaining <= 0) return [];
+
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  const result: DirectoryEntry[] = [];
+
+  for (const name of entries.sort()) {
+    if (name.startsWith(".") && name !== ".github") continue;
+    if (IGNORED_DIRS.has(name)) continue;
+
+    const fullPath = join(dir, name);
+    let stat;
+    try {
+      stat = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) {
+      const children = remaining > 1 ? scanDir(fullPath, root, remaining - 1) : undefined;
+      result.push({ name, type: "dir", ...(children ? { children } : {}) });
+    } else if (stat.isFile()) {
+      result.push({ name, type: "file" });
+    }
+  }
+
+  return result;
+}
+
+export function formatDirectoryTree(entries: readonly DirectoryEntry[], indent = ""): string {
+  const lines: string[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!;
+    const isLast = i === entries.length - 1;
+    const prefix = isLast ? "└── " : "├── ";
+    const childIndent = indent + (isLast ? "    " : "│   ");
+
+    lines.push(`${indent}${prefix}${entry.name}${entry.type === "dir" ? "/" : ""}`);
+    if (entry.children && entry.children.length > 0) {
+      lines.push(formatDirectoryTree(entry.children, childIndent));
+    }
+  }
+  return lines.join("\n");
+}

package/src/analyzers/entry-point-detector.ts

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PackageInfo, EntryPoint } from "../types.js";
+
+const COMMON_ENTRY_POINTS: readonly { path: string; kind: EntryPoint["kind"] }[] = [
+  { path: "src/index.ts", kind: "index" },
+  { path: "src/index.tsx", kind: "index" },
+  { path: "src/index.js", kind: "index" },
+  { path: "src/main.ts", kind: "main" },
+  { path: "src/main.tsx", kind: "main" },
+  { path: "src/main.js", kind: "main" },
+  { path: "src/app.ts", kind: "main" },
+  { path: "src/app.tsx", kind: "main" },
+  { path: "src/app.js", kind: "main" },
+  { path: "index.ts", kind: "index" },
+  { path: "index.js", kind: "index" },
+  { path: "main.go", kind: "main" },
+  { path: "cmd/main.go", kind: "main" },
+  { path: "src/main.rs", kind: "main" },
+  { path: "src/lib.rs", kind: "main" },
+  { path: "manage.py", kind: "main" },
+  { path: "app.py", kind: "main" },
+  { path: "main.py", kind: "main" },
+];
+
+const ROUTE_DIRS: readonly string[] = [
+  "src/routes",
+  "src/pages",
+  "src/api",
+  "app/routes",
+  "app/api",
+  "pages",
+  "routes",
+  "api",
+];
+
+const CONFIG_FILES: readonly string[] = [
+  "next.config.js",
+  "next.config.ts",
+  "next.config.mjs",
+  "vite.config.ts",
+  "vite.config.js",
+  "webpack.config.js",
+  "webpack.config.ts",
+  "nuxt.config.ts",
+  "astro.config.mjs",
+];
+
+export function detectEntryPoints(
+  cwd: string,
+  packages: readonly PackageInfo[],
+): readonly EntryPoint[] {
+  const results: EntryPoint[] = [];
+  const seen = new Set<string>();
+
+  for (const pkg of packages) {
+    if (pkg.manager === "npm") {
+      const mainField = extractMainField(cwd);
+      if (mainField && !seen.has(mainField)) {
+        seen.add(mainField);
+        results.push({ path: mainField, kind: "main" });
+      }
+    }
+  }
+
+  for (const { path, kind } of COMMON_ENTRY_POINTS) {
+    if (!seen.has(path) && existsSync(join(cwd, path))) {
+      seen.add(path);
+      results.push({ path, kind });
+    }
+  }
+
+  for (const dir of ROUTE_DIRS) {
+    if (existsSync(join(cwd, dir))) {
+      results.push({ path: dir, kind: "route" });
+    }
+  }
+
+  for (const config of CONFIG_FILES) {
+    if (!seen.has(config) && existsSync(join(cwd, config))) {
+      seen.add(config);
+      results.push({ path: config, kind: "config" });
+    }
+  }
+
+  return results;
+}
+
+function extractMainField(cwd: string): string | null {
+  try {
+    const raw = readFileSync(join(cwd, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw) as Record<string, unknown>;
+    if (typeof pkg["main"] === "string") return pkg["main"];
+  } catch {
+    // absent
+  }
+  return null;
+}

package/src/analyzers/framework-detector.ts

@@ -0,0 +1,76 @@
+import type { PackageInfo, FrameworkDetection } from "../types.js";
+
+interface FrameworkRule {
+  readonly dep: string;
+  readonly name: string;
+  readonly confidence: "definite" | "likely";
+}
+
+const FRAMEWORK_RULES: readonly FrameworkRule[] = [
+  { dep: "next", name: "Next.js", confidence: "definite" },
+  { dep: "react", name: "React", confidence: "definite" },
+  { dep: "vue", name: "Vue", confidence: "definite" },
+  { dep: "@angular/core", name: "Angular", confidence: "definite" },
+  { dep: "svelte", name: "Svelte", confidence: "definite" },
+  { dep: "express", name: "Express", confidence: "definite" },
+  { dep: "fastify", name: "Fastify", confidence: "definite" },
+  { dep: "hono", name: "Hono", confidence: "definite" },
+  { dep: "koa", name: "Koa", confidence: "definite" },
+  { dep: "nestjs", name: "NestJS", confidence: "likely" },
+  { dep: "@nestjs/core", name: "NestJS", confidence: "definite" },
+  { dep: "nuxt", name: "Nuxt", confidence: "definite" },
+  { dep: "remix", name: "Remix", confidence: "likely" },
+  { dep: "@remix-run/react", name: "Remix", confidence: "definite" },
+  { dep: "astro", name: "Astro", confidence: "definite" },
+  { dep: "gatsby", name: "Gatsby", confidence: "definite" },
+  { dep: "tailwindcss", name: "Tailwind CSS", confidence: "definite" },
+  { dep: "prisma", name: "Prisma", confidence: "definite" },
+  { dep: "@prisma/client", name: "Prisma", confidence: "definite" },
+  { dep: "drizzle-orm", name: "Drizzle", confidence: "definite" },
+  { dep: "django", name: "Django", confidence: "definite" },
+  { dep: "flask", name: "Flask", confidence: "definite" },
+  { dep: "fastapi", name: "FastAPI", confidence: "definite" },
+  { dep: "spring-boot", name: "Spring Boot", confidence: "likely" },
+  { dep: "actix-web", name: "Actix Web", confidence: "definite" },
+  { dep: "rocket", name: "Rocket", confidence: "definite" },
+  { dep: "axum", name: "Axum", confidence: "definite" },
+  { dep: "tokio", name: "Tokio", confidence: "definite" },
+  { dep: "gin-gonic/gin", name: "Gin", confidence: "definite" },
+  { dep: "labstack/echo", name: "Echo", confidence: "definite" },
+  { dep: "gofiber/fiber", name: "Fiber", confidence: "definite" },
+  { dep: "laravel/framework", name: "Laravel", confidence: "definite" },
+  { dep: "symfony/framework-bundle", name: "Symfony", confidence: "definite" },
+  { dep: "vitest", name: "Vitest", confidence: "definite" },
+  { dep: "jest", name: "Jest", confidence: "definite" },
+  { dep: "playwright", name: "Playwright", confidence: "definite" },
+  { dep: "@playwright/test", name: "Playwright", confidence: "definite" },
+  { dep: "cypress", name: "Cypress", confidence: "definite" },
+  { dep: "pytest", name: "pytest", confidence: "definite" },
+];
+
+export function detectFrameworks(
+  packages: readonly PackageInfo[],
+): readonly FrameworkDetection[] {
+  const allDeps = new Set<string>();
+  for (const pkg of packages) {
+    for (const dep of pkg.dependencies) {
+      allDeps.add(dep);
+    }
+  }
+
+  const seen = new Set<string>();
+  const results: FrameworkDetection[] = [];
+
+  for (const rule of FRAMEWORK_RULES) {
+    if (allDeps.has(rule.dep) && !seen.has(rule.name)) {
+      seen.add(rule.name);
+      results.push({
+        name: rule.name,
+        confidence: rule.confidence,
+        source: rule.dep,
+      });
+    }
+  }
+
+  return results;
+}

package/src/analyzers/index.ts

@@ -0,0 +1,7 @@
+export { buildDirectoryTree, formatDirectoryTree } from "./directory-tree.js";
+export { detectPackages } from "./package-detector.js";
+export { detectFrameworks } from "./framework-detector.js";
+export { detectEntryPoints } from "./entry-point-detector.js";
+export { detectBuildScripts } from "./build-script-detector.js";
+export { detectConventions } from "./convention-detector.js";
+export { detectKeyFiles } from "./key-file-detector.js";

package/src/analyzers/key-file-detector.ts

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { KeyFile } from "../types.js";
+
+const KEY_FILES: readonly { path: string; description: string }[] = [
+  { path: "README.md", description: "Project documentation" },
+  { path: "LICENSE", description: "License file" },
+  { path: "LICENSE.md", description: "License file" },
+  { path: "CHANGELOG.md", description: "Release history" },
+  { path: "CONTRIBUTING.md", description: "Contribution guidelines" },
+  { path: "SECURITY.md", description: "Security policy" },
+  { path: "ARCHITECTURE.md", description: "Architecture documentation" },
+  { path: "AGENTS.md", description: "AI agent conventions" },
+  { path: "CLAUDE.md", description: "Claude Code instructions" },
+  { path: ".env.example", description: "Environment variable template" },
+  { path: ".env.sample", description: "Environment variable template" },
+  { path: "Dockerfile", description: "Container build definition" },
+  { path: "docker-compose.yml", description: "Container orchestration" },
+  { path: "docker-compose.yaml", description: "Container orchestration" },
+  { path: "Makefile", description: "Build automation" },
+  { path: ".github/workflows", description: "GitHub Actions CI/CD" },
+  { path: ".gitlab-ci.yml", description: "GitLab CI/CD" },
+  { path: "Jenkinsfile", description: "Jenkins pipeline" },
+];
+
+export function detectKeyFiles(cwd: string): readonly KeyFile[] {
+  const results: KeyFile[] = [];
+
+  for (const { path, description } of KEY_FILES) {
+    if (existsSync(join(cwd, path))) {
+      results.push({ path, description });
+    }
+  }
+
+  return results;
+}

package/src/analyzers/package-detector.ts

@@ -0,0 +1,87 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { PackageInfo } from "../types.js";
+import { readTextFile, readJsonFile } from "../fs-utils.js";
+
+export function detectPackages(cwd: string): readonly PackageInfo[] {
+  const results: PackageInfo[] = [];
+
+  const npmPkg = readJsonFile(join(cwd, "package.json"));
+  if (npmPkg) {
+    const deps = Object.keys(npmPkg.dependencies ?? {});
+    const devDeps = Object.keys(npmPkg.devDependencies ?? {});
+    const name = typeof npmPkg.name === "string" ? npmPkg.name : "";
+    const version = typeof npmPkg.version === "string" ? npmPkg.version : null;
+    results.push({
+      manager: "npm",
+      name,
+      ...(version ? { version } : {}),
+      dependencies: [...deps, ...devDeps],
+    });
+  }
+
+  const goMod = readTextFile(join(cwd, "go.mod"));
+  if (goMod) {
+    const moduleMatch = goMod.match(/^module\s+(\S+)/m);
+    const deps = [...goMod.matchAll(/^\t(\S+)\s/gm)].map((m) => m[1]!);
+    results.push({
+      manager: "go",
+      name: moduleMatch?.[1] ?? "",
+      dependencies: deps,
+    });
+  }
+
+  const cargo = readTextFile(join(cwd, "Cargo.toml"));
+  if (cargo) {
+    const nameMatch = cargo.match(/^name\s*=\s*"([^"]+)"/m);
+    const versionMatch = cargo.match(/^version\s*=\s*"([^"]+)"/m);
+    const deps = [...cargo.matchAll(/^\[(?:dev-)?dependencies\.([^\]]+)\]/gm)].map((m) => m[1]!);
+    const inlineDeps = [...cargo.matchAll(/^(\w[\w-]*)\s*=\s*(?:"|{)/gm)]
+      .map((m) => m[1]!)
+      .filter((d) => d !== "name" && d !== "version" && d !== "edition" && d !== "authors");
+    const cargoVersion = versionMatch?.[1];
+    results.push({
+      manager: "cargo",
+      name: nameMatch?.[1] ?? "",
+      ...(cargoVersion ? { version: cargoVersion } : {}),
+      dependencies: [...new Set([...deps, ...inlineDeps])],
+    });
+  }
+
+  const pyproject = readTextFile(join(cwd, "pyproject.toml"));
+  if (pyproject) {
+    const nameMatch = pyproject.match(/^name\s*=\s*"([^"]+)"/m);
+    const versionMatch = pyproject.match(/^version\s*=\s*"([^"]+)"/m);
+    const depsSection = pyproject.match(/^dependencies\s*=\s*\[([\s\S]*?)\]/m);
+    const deps = depsSection
+      ? [...depsSection[1]!.matchAll(/"([^">=<\s]+)/g)].map((m) => m[1]!)
+      : [];
+    const hasPoetry = pyproject.includes("[tool.poetry]");
+    const pyVersion = versionMatch?.[1];
+    results.push({
+      manager: hasPoetry ? "poetry" : "pip",
+      name: nameMatch?.[1] ?? "",
+      ...(pyVersion ? { version: pyVersion } : {}),
+      dependencies: deps,
+    });
+  }
+
+  const composer = readJsonFile(join(cwd, "composer.json"));
+  if (composer) {
+    results.push({
+      manager: "composer",
+      name: typeof composer.name === "string" ? composer.name : "",
+      dependencies: Object.keys(composer.require ?? {}),
+    });
+  }
+
+  if (existsSync(join(cwd, "build.gradle")) || existsSync(join(cwd, "build.gradle.kts"))) {
+    results.push({ manager: "gradle", name: "", dependencies: [] });
+  }
+
+  if (existsSync(join(cwd, "pom.xml"))) {
+    results.push({ manager: "maven", name: "", dependencies: [] });
+  }
+
+  return results;
+}

package/src/codemap-formatter.ts

@@ -0,0 +1,90 @@
+import type { CodeMap } from "./types.js";
+import { formatDirectoryTree } from "./analyzers/directory-tree.js";
+
+export function formatCodemapMarkdown(codemap: CodeMap): string {
+  const sections: string[] = [
+    `## Codebase Map: ${codemap.projectName}`,
+    `Generated: ${codemap.generatedAt} | Hash: ${codemap.contentHash}`,
+  ];
+
+  if (codemap.directoryTree.length > 0) {
+    sections.push(
+      "",
+      "### Directory Structure",
+      "```",
+      formatDirectoryTree(codemap.directoryTree),
+      "```",
+    );
+  }
+
+  if (codemap.packages.length > 0) {
+    sections.push("", "### Packages");
+    for (const pkg of codemap.packages) {
+      const version = pkg.version ? ` v${pkg.version}` : "";
+      sections.push(`- **${pkg.name || "(unnamed)"}**${version} (${pkg.manager})`);
+      if (pkg.dependencies.length > 0) {
+        const depList = pkg.dependencies.slice(0, 20).join(", ");
+        const more = pkg.dependencies.length > 20 ? ` (+${pkg.dependencies.length - 20} more)` : "";
+        sections.push(`  Dependencies: ${depList}${more}`);
+      }
+    }
+  }
+
+  if (codemap.frameworks.length > 0) {
+    sections.push("", "### Frameworks");
+    for (const fw of codemap.frameworks) {
+      const version = fw.version ? ` v${fw.version}` : "";
+      const confidence = fw.confidence === "likely" ? " (likely)" : "";
+      sections.push(`- ${fw.name}${version}${confidence}`);
+    }
+  }
+
+  if (codemap.entryPoints.length > 0) {
+    sections.push("", "### Entry Points");
+    for (const ep of codemap.entryPoints) {
+      sections.push(`- \`${ep.path}\` (${ep.kind})`);
+    }
+  }
+
+  if (codemap.buildScripts.length > 0) {
+    sections.push("", "### Build / Test / Deploy");
+    for (const script of codemap.buildScripts) {
+      sections.push(`- **${script.name}**: \`${script.command}\` (${script.source})`);
+    }
+  }
+
+  if (codemap.conventions.length > 0) {
+    sections.push("", "### Conventions");
+    for (const conv of codemap.conventions) {
+      sections.push(``, `#### ${conv.source}`, conv.content);
+    }
+  }
+
+  if (codemap.keyFiles.length > 0) {
+    sections.push("", "### Key Files");
+    for (const kf of codemap.keyFiles) {
+      sections.push(`- \`${kf.path}\` -- ${kf.description}`);
+    }
+  }
+
+  return sections.join("\n");
+}
+
+export function truncateCodemap(markdown: string, maxChars: number): string {
+  if (markdown.length <= maxChars) return markdown;
+
+  const lines = markdown.split("\n");
+  let length = 0;
+  const kept: string[] = [];
+
+  for (const line of lines) {
+    if (length + line.length + 1 > maxChars) {
+      kept.push("", "... (codemap truncated, run /onboard to see full output)");
+      break;
+    }
+    kept.push(line);
+    length += line.length + 1;
+  }
+
+  return kept.join("\n");
+}

package/src/codemap-generator.ts

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { CodeMap, CacheEntry } from "./types.js";
+import {
+  buildDirectoryTree,
+  detectPackages,
+  detectFrameworks,
+  detectEntryPoints,
+  detectBuildScripts,
+  detectConventions,
+  detectKeyFiles,
+} from "./analyzers/index.js";
+import { loadCachedCodemap, saveCachedCodemap } from "./storage.js";
+
+const HASH_FILES = [
+  "package.json",
+  "package-lock.json",
+  "tsconfig.json",
+  "go.mod",
+  "go.sum",
+  "Cargo.toml",
+  "Cargo.lock",
+  "pyproject.toml",
+  "composer.json",
+  "composer.lock",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+];
+
+export function computeContentHash(cwd: string): string {
+  const hash = createHash("sha256");
+
+  for (const file of HASH_FILES) {
+    try {
+      hash.update(readFileSync(join(cwd, file), "utf-8"));
+    } catch {
+      // absent
+    }
+  }
+
+  try {
+    const entries = readdirSync(cwd).sort();
+    hash.update(entries.join("\n"));
+  } catch {
+    // absent
+  }
+
+  return hash.digest("hex").substring(0, 16);
+}
+
+export function generateCodemap(
+  cwd: string,
+  projectId: string,
+  projectName: string,
+): CodeMap {
+  const directoryTree = buildDirectoryTree(cwd);
+  const packages = detectPackages(cwd);
+  const frameworks = detectFrameworks(packages);
+  const entryPoints = detectEntryPoints(cwd, packages);
+  const buildScripts = detectBuildScripts(cwd);
+  const conventions = detectConventions(cwd);
+  const keyFiles = detectKeyFiles(cwd);
+
+  return {
+    projectId,
+    projectName,
+    generatedAt: new Date().toISOString(),
+    contentHash: computeContentHash(cwd),
+    directoryTree,
+    packages,
+    frameworks,
+    entryPoints,
+    buildScripts,
+    conventions,
+    keyFiles,
+  };
+}
+
+export interface CodemapResult {
+  readonly codemap: CodeMap;
+  readonly fromCache: boolean;
+  readonly stale: boolean;
+}
+
+export function getOrGenerateCodemap(
+  cwd: string,
+  projectId: string,
+  projectName: string,
+  baseDir?: string,
+): CodemapResult {
+  const cached = loadCachedCodemap(projectId, baseDir);
+  if (cached) {
+    const currentHash = computeContentHash(cwd);
+    if (cached.contentHash === currentHash) {
+      return { codemap: cached.data, fromCache: true, stale: false };
+    }
+    return { codemap: cached.data, fromCache: true, stale: true };
+  }
+
+  const codemap = generateCodemap(cwd, projectId, projectName);
+  const entry: CacheEntry<CodeMap> = {
+    data: codemap,
+    contentHash: codemap.contentHash,
+    createdAt: codemap.generatedAt,
+  };
+  saveCachedCodemap(projectId, entry, baseDir);
+  return { codemap, fromCache: false, stale: false };
+}

package/src/codemap-injector.ts

@@ -0,0 +1,44 @@
+import type { CodeMap, CompassState } from "./types.js";
+import { formatCodemapMarkdown, truncateCodemap } from "./codemap-formatter.js";
+
+export interface BeforeAgentStartEvent {
+  type: "before_agent_start";
+  prompt: string;
+  systemPrompt: string;
+}
+
+export interface InjectionResult {
+  systemPrompt: string;
+}
+
+export function buildCodemapInjection(
+  codemap: CodeMap,
+  stale: boolean,
+  maxChars: number,
+): string {
+  const markdown = formatCodemapMarkdown(codemap);
+  const truncated = truncateCodemap(markdown, maxChars);
+  const staleNote = stale
+    ? "\n\n> This codemap may be outdated. Run `/onboard` to refresh."
+    : "";
+
+  return `\n\n${truncated}${staleNote}`;
+}
+
+export function handleBeforeAgentStart(
+  event: BeforeAgentStartEvent,
+  state: CompassState,
+  maxChars: number,
+): InjectionResult | undefined {
+  if (state.codemapInjected) return undefined;
+  if (!state.cachedCodemap) return undefined;
+
+  const block = buildCodemapInjection(
+    state.cachedCodemap.data,
+    state.stale,
+    maxChars,
+  );
+  if (!block) return undefined;
+
+  return { systemPrompt: event.systemPrompt + block };
+}

package/src/fs-utils.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+
+export function readTextFile(path: string): string | null {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function readJsonFile(path: string): Record<string, unknown> | null {
+  const text = readTextFile(path);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}