agentmap 0.8.0 → 0.9.0

package/dist/test-helpers/git-test-helpers.js

@@ -0,0 +1,48 @@
+// Helpers for creating temporary git repositories in tests.
+import { execSync } from 'child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+function run(command, cwd) {
+    return execSync(command, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+}
+export function createTempDir(prefix) {
+    return mkdtempSync(join(tmpdir(), prefix));
+}
+export function initRepo(dir) {
+    run('git init', dir);
+    run('git config user.name "agentmap tests"', dir);
+    run('git config user.email "agentmap@example.com"', dir);
+    return { dir };
+}
+export function createRepo(prefix) {
+    const dir = createTempDir(prefix);
+    mkdirSync(dir, { recursive: true });
+    return initRepo(dir);
+}
+export function writeTrackedFile(repo, relativePath, content) {
+    const filePath = join(repo.dir, relativePath);
+    mkdirSync(join(filePath, '..'), { recursive: true });
+    writeFileSync(filePath, content, 'utf8');
+}
+export function commitAll(repo, message) {
+    run('git add .', repo.dir);
+    run(`git commit -m ${JSON.stringify(message)}`, repo.dir);
+}
+export function shortHead(repo) {
+    return run('git rev-parse --short HEAD', repo.dir).trim();
+}
+export function addSubmodule(repo, sourceDir, targetPath) {
+    run(`git -c protocol.file.allow=always submodule add ${JSON.stringify(sourceDir)} ${JSON.stringify(targetPath)}`, repo.dir);
+}
+export function updateSubmodulesRecursive(repo) {
+    run('git -c protocol.file.allow=always submodule update --init --recursive', repo.dir);
+}
+export function deinitSubmodule(repo, targetPath) {
+    run(`git submodule deinit -f ${JSON.stringify(targetPath)}`, repo.dir);
+}
+//# sourceMappingURL=git-test-helpers.js.map

package/dist/test-helpers/git-test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-test-helpers.js","sourceRoot":"","sources":["../../src/test-helpers/git-test-helpers.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,IAAI,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAA;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAM3B,SAAS,GAAG,CAAC,OAAe,EAAE,GAAW;IACvC,OAAO,QAAQ,CAAC,OAAO,EAAE;QACvB,GAAG;QACH,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,CAAA;IACpB,GAAG,CAAC,uCAAuC,EAAE,GAAG,CAAC,CAAA;IACjD,GAAG,CAAC,8CAA8C,EAAE,GAAG,CAAC,CAAA;IACxD,OAAO,EAAE,GAAG,EAAE,CAAA;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;IACjC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACnC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAA;AACtB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAc,EAAE,YAAoB,EAAE,OAAe;IACpF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;IAC7C,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACpD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,OAAe;IACvD,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IAC1B,GAAG,CAAC,iBAAiB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;AAC3D,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,OAAO,GAAG,CAAC,4BAA4B,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;AAC3D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,SAAiB,EAAE,UAAkB;IAChF,GAAG,CAAC,mDAAmD,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7H,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,IAAc;IACtD,GAAG,CAAC,uEAAuE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;AACxF,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAc,EAAE,UAAkB;IAChE,GAAG,CAAC,2BAA2B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;AACxE,CAAC"}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type Parser from 'web-tree-sitter';
+import type { Logger } from './logger.js';
 /**
  * Supported programming languages
  */
@@ -32,6 +33,13 @@ export interface SubmoduleEntry {
     submodule: string;
     dirty?: string;
 }
+/**
+ * A submodule node in the map.
+ * Carries submodule metadata and can also contain nested files/directories.
+ */
+export interface SubmoduleNode extends SubmoduleEntry {
+    [name: string]: MapNode | FileEntry | SubmoduleNode | string | undefined;
+}
 /**
  * Info about a git submodule discovered in the repo
  */
@@ -53,7 +61,7 @@ export interface SubmoduleInfo {
  * Recursive map node - either a directory (with children), a file entry, or a submodule entry
  */
 export interface MapNode {
-    [name: string]: MapNode | FileEntry | SubmoduleEntry;
+    [name: string]: MapNode | FileEntry | SubmoduleNode;
 }
 /**
  * Result of extracting marker and description from a file
@@ -98,6 +106,8 @@ export interface FileResult {
     description?: string;
     definitions: Definition[];
     diff?: FileDiffStats;
+    /** If set, this file is an exact duplicate of another file (by git blob SHA) */
+    duplicateOf?: string;
 }
 /**
  * Options for generating the map
@@ -115,8 +125,12 @@ export interface GenerateOptions {
     diffBase?: string;
     /** Max definitions per file before truncation (default: 25) */
     maxDefs?: number;
+    /** Max characters for file descriptions before truncation (default: 300). Rounds up to full line. */
+    maxDescChars?: number;
     /** Include submodule info in the map (default: true) */
     submodules?: boolean;
+    /** Logger implementation (default: console logger) */
+    logger?: Logger;
 }
 /**
  * A hunk from git diff output

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC;;GAEG;AACH,MAAM,MAAM,QAAQ,GAChB,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,MAAM,GACN,IAAI,GACJ,KAAK,GACL,KAAK,CAAA;AAET;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,OAAO,CAAC,EAAE,QAAQ,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,CAAA;CACzE;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,2CAA2C;IAC3C,WAAW,EAAE,OAAO,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,CAAA;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,WAAW,GACX,OAAO,GACP,MAAM,CAAA;AAEV;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,gBAAgB,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,cAAc,CAAA;IACpB,QAAQ,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,cAAc,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qGAAqG;IACrG,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wDAAwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,QAAQ,EAAE,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAA;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentmap",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Generate a YAML map of your codebase for AI agent context",
   "type": "module",
   "repository": {
@@ -18,13 +18,25 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./src": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./src/*": {
+      "types": "./dist/*.d.ts",
+      "default": "./src/*.ts"
     }
   },
   "files": [
-    "dist"
+    "src",
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -35,7 +47,7 @@
   },
   "dependencies": {
     "@tree-sitter-grammars/tree-sitter-zig": "^1.1.2",
-    "cac": "^6.7.14",
+    "goke": "^6.2.0",
     "js-yaml": "^4.1.0",
     "marked": "^17.0.1",
     "p-limit": "^7.2.0",

package/src/cli.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// CLI entrypoint for generating codebase maps.
+
+import { writeFile } from 'fs/promises'
+import { resolve } from 'path'
+import { goke } from 'goke'
+import { generateMap, toYaml } from './index.js'
+import { createConsoleLogger } from './logger.js'
+
+const cli = goke('agentmap')
+const logger = createConsoleLogger()
+
+function normalizePatterns(value: unknown): string[] | undefined {
+  if (typeof value === 'string') {
+    const normalized = value.trim()
+    return normalized ? [normalized] : undefined
+  }
+
+  if (!Array.isArray(value)) {
+    return undefined
+  }
+
+  const normalized = value
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map(entry => entry.trim())
+    .filter(Boolean)
+
+  return normalized.length > 0 ? normalized : undefined
+}
+
+const NO_FILES_MESSAGE = `No files found with header comments.
+
+To include a file in the map, add a comment at the top:
+
+  // Description of this file.
+  // What it does and why.
+
+  export function main() { ... }
+
+The description will appear in the 'desc' field of the output.
+`
+
+cli
+  .command('[dir]', 'Generate a YAML map of the codebase')
+  .option('-o, --output <file>', 'Write output to file (default: stdout)')
+  .option('-i, --ignore <pattern>', 'Ignore pattern (can be repeated)')
+  .option('-f, --filter <pattern>', 'Filter pattern - only include matching files (can be repeated)')
+  .option('--no-submodules', 'Exclude submodule info from the map')
+  .option('--max-desc-chars <chars>', 'Max characters for descriptions (default: 300, rounds up to full line)')
+  .action(async (dir, options) => {
+    const targetDir = resolve(dir ?? '.')
+
+    try {
+      const map = await generateMap({
+        dir: targetDir,
+        ignore: normalizePatterns(options.ignore),
+        filter: normalizePatterns(options.filter),
+        diff: true,
+        submodules: options.noSubmodules ? false : undefined,
+        maxDescChars: options.maxDescChars != null && Number.isFinite(Number(options.maxDescChars)) && Number(options.maxDescChars) > 0
+          ? Number(options.maxDescChars)
+          : undefined,
+        logger,
+      })
+
+      // Check if map is empty (only has root key with empty object)
+      const rootKey = Object.keys(map)[0]
+      const rootValue = map[rootKey]
+      if (!rootValue || Object.keys(rootValue).length === 0) {
+        logger.warn(NO_FILES_MESSAGE.trimEnd())
+        process.exit(0)
+      }
+
+      const yaml = toYaml(map)
+
+      if (options.output) {
+        await writeFile(options.output, yaml, 'utf8')
+        logger.info(`Wrote map to ${options.output}`)
+      } else {
+        process.stdout.write(yaml.endsWith('\n') ? yaml : `${yaml}\n`)
+      }
+    } catch (err) {
+      logger.error('Error:', err instanceof Error ? err.message : err)
+      process.exit(1)
+    }
+  })
+
+const PROMPT_TEXT = `Analyze the repository structure first. Look for clear separation of concerns:
+- Monorepo workspaces (package.json workspaces, pnpm-workspace.yaml, etc.)
+- Separate packages or modules
+- Different languages or technology stacks
+- Independent services or apps
+
+If you find well-separated packages, use the Task tool to process them concurrently - assign each package/workspace to a separate task agent for speed.
+
+For each package/area, identify the most important files - entry points, core modules, main utilities, and key abstractions.
+
+For each important file, add a descriptive comment at the top (before any imports or code). The comment should:
+- Be 2-4 lines describing what the file does and why it exists
+- Use the appropriate comment style for the language (// for JS/TS, # for Python, //! for Rust modules, etc.)
+- If the file is an entry point (CLI, main, server start, etc.), mark it as such in the description
+- If the file already has a top comment, review and update it to be accurate and descriptive - don't skip it
+- If the file has a shebang (#!/...), keep it as the first line and add the description comment immediately after
+- Ensure the description comment appears above any import statements in the file
+
+Examples:
+
+TypeScript/JavaScript:
+// CLI entrypoint for the application.
+// Parses command-line arguments and orchestrates the main workflow.
+import { run } from "./runner"
+
+Python:
+# Database connection manager.
+# Handles connection pooling and provides transaction helpers.
+import asyncio
+
+Rust:
+//! HTTP server module.
+//! Entry point for the web API, configures routes and middleware.
+use crate::server::start
+
+With shebang (shell scripts, node CLI, etc.):
+#!/usr/bin/env node
+// CLI entrypoint for the build tool.
+// Handles argument parsing and runs the build pipeline.
+import { build } from "./build"
+
+After adding comments to all important files, run \`npx -y agentmap\` to verify the files appear in the generated map.
+
+You can run this prompt again anytime to keep file descriptions up to date as the codebase evolves.
+
+Finally, add these instructions to the project's AGENTS.md or CLAUDE.md file (create it if it doesn't exist):
+
+\`\`\`markdown
+## Codebase Map
+
+Run \`npx -y agentmap\` to see the repo structure with file descriptions, definitions, and git diff status.
+
+When editing files with top-level description comments, keep them accurate and up-to-date with your changes.
+\`\`\`
+
+For OpenCode users, also set up the agentmap plugin so future sessions automatically get the codebase map:
+1. Add "@agentmap/opencode" to the plugin array in ~/.config/opencode/config.json
+   - Create the file if it doesn't exist
+   - If a plugin array already exists, append to it
+   - Example: { "plugin": ["@agentmap/opencode"] }
+2. Tell the user to restart OpenCode to activate the plugin.`
+
+cli
+  .command('prompt', 'Generate a prompt to help AI agents add file descriptions')
+  .action(() => {
+    process.stdout.write(`${PROMPT_TEXT}\n`)
+  })
+
+cli.help()
+cli.version('0.8.0')
+
+if (process.argv.slice(2).some(arg => arg === '-v' || arg === '--version')) {
+  cli.outputVersion()
+  process.exit(0)
+}
+
+cli.parse()