agentmap 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# mappamundi
+
+A compact, YAML-based inventory of your codebase, intended to be prepended to a coding agent's context at session start.
+
+## Purpose
+
+- Give the agent a fast, structured overview of files and responsibilities
+- Provide jump targets via top-level `defs` (functions/classes with line numbers)
+
+## Installation
+
+```bash
+npm install mappamundi
+```
+
+## CLI Usage
+
+```bash
+# Map current directory
+npx mappamundi
+
+# Map specific directory
+npx mappamundi ./src
+
+# Write to file
+npx mappamundi -o map.yaml
+
+# Ignore patterns
+npx mappamundi --ignore "dist/**" --ignore "**/test/**"
+```
+
+### Options
+
+```
+-o, --output <file>     Write output to file (default: stdout)
+-i, --ignore <pattern>  Ignore pattern (can be repeated)
+-h, --help              Show help
+-v, --version           Show version
+```
+
+## Library Usage
+
+```typescript
+import { generateMap, generateMapYaml } from 'mappamundi'
+
+// Get as object
+const map = await generateMap({ dir: './src' })
+
+// Get as YAML string
+const yaml = await generateMapYaml({ dir: './src' })
+
+// With ignore patterns
+const yaml = await generateMapYaml({
+  dir: './src',
+  ignore: ['**/test/**', '**/*.spec.ts']
+})
+```
+
+## Marking Files
+
+Only files with the `@mappamundi` marker comment are included. Add it to the top of files you want in the map:
+
+```typescript
+// @mappamundi
+// CLI entrypoint.
+// Parses args, wires deps, calls into lib/.
+
+export function main() { ... }
+```
+
+```python
+# @mappamundi
+# Parsing + normalization utilities.
+
+def parse_input(): ...
+```
+
+Block comments also work:
+
+```typescript
+/**
+ * @mappamundi
+ * Core data structures.
+ */
+```
+
+## Output Format
+
+```yaml
+my-project:
+  src:
+    main.py:
+      desc: |
+        CLI entrypoint.
+        Parses args, wires deps, calls into lib/.
+      defs:
+        main: 12
+        parse_args: 34
+        App: 58
+  lib:
+    parse.py:
+      desc: |
+        Parsing + normalization utilities.
+      defs:
+        parse_input: 10
+        ASTNode: 41
+```
+
+### Format Rules
+
+- Directories are YAML mappings
+- Files have optional `desc` (description) and `defs` (definitions)
+- `desc` uses YAML literal block scalar (`|`) for multi-line text
+- `defs` maps symbol names to 1-based line numbers
+- Only top-level `function` and `class` definitions are included
+
+## Supported Languages
+
+| Language   | Extensions                |
+|------------|---------------------------|
+| TypeScript | .ts .tsx .mts .cts        |
+| JavaScript | .js .jsx .mjs .cjs        |
+| Python     | .py .pyi                  |
+| Rust       | .rs                       |
+| Go         | .go                       |
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// @mappamundi
+// CLI entrypoint for generating codebase maps.
+import { writeFile } from 'fs/promises';
+import { resolve } from 'path';
+import { cac } from 'cac';
+import { generateMapYaml } from './index.js';
+const cli = cac('agentmap');
+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)', { type: [] })
+    .action(async (dir, options) => {
+    const targetDir = resolve(dir ?? '.');
+    try {
+        const yaml = await generateMapYaml({
+            dir: targetDir,
+            ignore: options.ignore,
+        });
+        if (options.output) {
+            await writeFile(options.output, yaml, 'utf8');
+            console.error(`Wrote map to ${options.output}`);
+        }
+        else {
+            console.log(yaml);
+        }
+    }
+    catch (err) {
+        console.error('Error:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+cli.help();
+cli.version('0.1.0');
+cli.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,cAAc;AACd,+CAA+C;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAC9B,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,CAAC,CAAA;AAE3B,GAAG;KACA,OAAO,CAAC,OAAO,EAAE,qCAAqC,CAAC;KACvD,MAAM,CAAC,qBAAqB,EAAE,wCAAwC,CAAC;KACvE,MAAM,CAAC,wBAAwB,EAAE,kCAAkC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;KAClF,MAAM,CAAC,KAAK,EAAE,GAAuB,EAAE,OAA+C,EAAE,EAAE;IACzF,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAA;IAErC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC;YACjC,GAAG,EAAE,SAAS;YACd,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAA;QAEF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;YAC7C,OAAO,CAAC,KAAK,CAAC,gBAAgB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QACjD,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACnB,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;AACH,CAAC,CAAC,CAAA;AAEJ,GAAG,CAAC,IAAI,EAAE,CAAA;AACV,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;AAEpB,GAAG,CAAC,KAAK,EAAE,CAAA"}

package/dist/extract/definitions.d.ts

@@ -0,0 +1,6 @@
+import type { Definition, Language, SyntaxNode } from '../types.js';
+/**
+ * Extract top-level definitions from a syntax tree
+ */
+export declare function extractDefinitions(rootNode: SyntaxNode, language: Language): Definition[];
+//# sourceMappingURL=definitions.d.ts.map

package/dist/extract/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/extract/definitions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAwBnE;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,QAAQ,GACjB,UAAU,EAAE,CAmDd"}

package/dist/extract/definitions.js

@@ -0,0 +1,207 @@
+// @mappamundi
+// Extract top-level function and class definitions using tree-sitter.
+/**
+ * Node types that represent functions per language
+ */
+const FUNCTION_TYPES = {
+    typescript: ['function_declaration', 'method_definition'],
+    javascript: ['function_declaration', 'method_definition'],
+    python: ['function_definition'],
+    rust: ['function_item'],
+    go: ['function_declaration', 'method_declaration'],
+};
+/**
+ * Node types that represent classes per language
+ */
+const CLASS_TYPES = {
+    typescript: ['class_declaration', 'abstract_class_declaration'],
+    javascript: ['class_declaration'],
+    python: ['class_definition'],
+    rust: ['struct_item', 'enum_item', 'impl_item', 'trait_item'],
+    go: ['type_declaration'],
+};
+/**
+ * Extract top-level definitions from a syntax tree
+ */
+export function extractDefinitions(rootNode, language) {
+    const definitions = [];
+    const functionTypes = FUNCTION_TYPES[language];
+    const classTypes = CLASS_TYPES[language];
+    // Walk immediate children of root (top-level only)
+    for (let i = 0; i < rootNode.childCount; i++) {
+        const node = rootNode.child(i);
+        if (!node)
+            continue;
+        // Handle export statements (unwrap to get actual declaration)
+        const actualNode = unwrapExport(node);
+        // Check for function
+        if (functionTypes.includes(actualNode.type)) {
+            const name = extractName(actualNode, language);
+            if (name) {
+                definitions.push({
+                    name,
+                    line: actualNode.startPosition.row + 1, // 1-based
+                    type: 'function',
+                });
+            }
+        }
+        // Check for class
+        if (classTypes.includes(actualNode.type)) {
+            const name = extractName(actualNode, language);
+            if (name) {
+                definitions.push({
+                    name,
+                    line: actualNode.startPosition.row + 1, // 1-based
+                    type: 'class',
+                });
+            }
+        }
+        // Handle variable declarations with arrow functions (TS/JS)
+        if (language === 'typescript' || language === 'javascript') {
+            const arrowFn = extractArrowFunction(actualNode);
+            if (arrowFn) {
+                definitions.push({
+                    name: arrowFn.name,
+                    line: arrowFn.line,
+                    type: 'function',
+                });
+            }
+        }
+    }
+    return definitions;
+}
+/**
+ * Unwrap export statement to get the actual declaration
+ */
+function unwrapExport(node) {
+    if (node.type === 'export_statement') {
+        // Find the declaration child
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (!child)
+                continue;
+            // Skip 'export' keyword and other tokens
+            if (child.type !== 'export' && !child.type.includes('comment')) {
+                return child;
+            }
+        }
+    }
+    return node;
+}
+/**
+ * Extract the name from a definition node
+ */
+function extractName(node, language) {
+    // Try to find 'name' field first
+    const nameNode = node.childForFieldName('name');
+    if (nameNode) {
+        return nameNode.text;
+    }
+    // Language-specific fallbacks
+    switch (language) {
+        case 'typescript':
+        case 'javascript':
+            return extractJSName(node);
+        case 'python':
+            return extractPythonName(node);
+        case 'rust':
+            return extractRustName(node);
+        case 'go':
+            return extractGoName(node);
+    }
+    return null;
+}
+function extractJSName(node) {
+    // Look for identifier or type_identifier child
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child)
+            continue;
+        if (child.type === 'identifier' || child.type === 'type_identifier') {
+            return child.text;
+        }
+        if (child.type === 'property_identifier') {
+            return child.text;
+        }
+    }
+    return null;
+}
+function extractPythonName(node) {
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child?.type === 'identifier') {
+            return child.text;
+        }
+    }
+    return null;
+}
+function extractRustName(node) {
+    // For impl blocks, try to get the type name
+    if (node.type === 'impl_item') {
+        const typeNode = node.childForFieldName('type');
+        if (typeNode) {
+            // Get the type identifier
+            const ident = typeNode.type === 'type_identifier'
+                ? typeNode
+                : findChild(typeNode, 'type_identifier');
+            return ident?.text ?? null;
+        }
+    }
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child?.type === 'identifier' || child?.type === 'type_identifier') {
+            return child.text;
+        }
+    }
+    return null;
+}
+function extractGoName(node) {
+    // For type declarations, look in type_spec
+    if (node.type === 'type_declaration') {
+        const spec = findChild(node, 'type_spec');
+        if (spec) {
+            const nameNode = spec.childForFieldName('name');
+            return nameNode?.text ?? null;
+        }
+    }
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child?.type === 'identifier' || child?.type === 'field_identifier') {
+            return child.text;
+        }
+    }
+    return null;
+}
+/**
+ * Extract arrow function assigned to const/let
+ */
+function extractArrowFunction(node) {
+    if (node.type !== 'lexical_declaration')
+        return null;
+    for (let i = 0; i < node.childCount; i++) {
+        const declarator = node.child(i);
+        if (declarator?.type !== 'variable_declarator')
+            continue;
+        const nameNode = declarator.childForFieldName('name');
+        const valueNode = declarator.childForFieldName('value');
+        if (nameNode && valueNode?.type === 'arrow_function') {
+            return {
+                name: nameNode.text,
+                line: node.startPosition.row + 1,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Find a child node by type
+ */
+function findChild(node, type) {
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child?.type === type)
+            return child;
+    }
+    return null;
+}
+//# sourceMappingURL=definitions.js.map

package/dist/extract/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/extract/definitions.ts"],"names":[],"mappings":"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"}

package/dist/extract/marker.d.ts

@@ -0,0 +1,7 @@
+import type { MarkerResult } from '../types.js';
+/**
+ * Check if file has @mappamundi marker and extract description.
+ * Only reads first ~30KB of file for performance.
+ */
+export declare function extractMarker(filepath: string): Promise<MarkerResult>;
+//# sourceMappingURL=marker.d.ts.map

package/dist/extract/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/extract/marker.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAmB/C;;;GAGG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgC3E"}

package/dist/extract/marker.js

@@ -0,0 +1,144 @@
+// @mappamundi
+// Extract @mappamundi marker and description from file header.
+import { open } from 'fs/promises';
+const MARKER = '@mappamundi';
+const MAX_BYTES = 30_000; // ~300 lines worth
+/**
+ * Read the first N bytes of a file
+ */
+async function readHead(filepath, maxBytes) {
+    const handle = await open(filepath, 'r');
+    try {
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+        return buffer.toString('utf8', 0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Check if file has @mappamundi marker and extract description.
+ * Only reads first ~30KB of file for performance.
+ */
+export async function extractMarker(filepath) {
+    const head = await readHead(filepath, MAX_BYTES);
+    const lines = head.split('\n');
+    // Find the marker line
+    let markerLineIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        // Skip empty lines at start
+        if (line === '')
+            continue;
+        // Check if this line contains the marker
+        if (line.includes(MARKER)) {
+            markerLineIndex = i;
+            break;
+        }
+        // If we hit a non-comment, non-empty line before finding marker, stop
+        if (!isCommentLine(line)) {
+            return { found: false };
+        }
+    }
+    if (markerLineIndex === -1) {
+        return { found: false };
+    }
+    // Extract description from lines after marker
+    const description = extractDescription(lines, markerLineIndex);
+    return {
+        found: true,
+        description: description || undefined,
+    };
+}
+/**
+ * Check if a line is a comment
+ */
+function isCommentLine(line) {
+    const trimmed = line.trim();
+    return (trimmed.startsWith('//') ||
+        trimmed.startsWith('#') ||
+        trimmed.startsWith('/*') ||
+        trimmed.startsWith('*') ||
+        trimmed.startsWith('"""') ||
+        trimmed.startsWith("'''") ||
+        trimmed.endsWith('*/') ||
+        trimmed.endsWith('"""') ||
+        trimmed.endsWith("'''"));
+}
+/**
+ * Extract description text from comment lines after marker
+ */
+function extractDescription(lines, markerLineIndex) {
+    const descLines = [];
+    // Check if marker is on its own line or has text after it
+    const markerLine = lines[markerLineIndex];
+    const markerText = extractTextAfterMarker(markerLine);
+    if (markerText) {
+        descLines.push(markerText);
+    }
+    // Continue reading comment lines after marker
+    for (let i = markerLineIndex + 1; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Empty line in comments is ok, include it
+        if (trimmed === '') {
+            // But stop if we've already collected some description
+            if (descLines.length > 0) {
+                // Check if next non-empty line is still a comment
+                let nextNonEmpty = i + 1;
+                while (nextNonEmpty < lines.length && lines[nextNonEmpty].trim() === '') {
+                    nextNonEmpty++;
+                }
+                if (nextNonEmpty < lines.length && !isCommentLine(lines[nextNonEmpty].trim())) {
+                    break;
+                }
+            }
+            continue;
+        }
+        // Stop at non-comment line
+        if (!isCommentLine(trimmed)) {
+            break;
+        }
+        // Stop at end of block comment
+        if (trimmed === '*/' || trimmed === '"""' || trimmed === "'''") {
+            break;
+        }
+        // Extract text from comment line
+        const text = stripCommentPrefix(trimmed);
+        if (text !== null) {
+            descLines.push(text);
+        }
+    }
+    return descLines.join('\n').trim();
+}
+/**
+ * Extract text after @mappamundi marker on the same line
+ */
+function extractTextAfterMarker(line) {
+    const idx = line.indexOf(MARKER);
+    if (idx === -1)
+        return '';
+    const after = line.slice(idx + MARKER.length).trim();
+    return after;
+}
+/**
+ * Strip comment prefix from a line
+ */
+function stripCommentPrefix(line) {
+    // Handle various comment styles
+    if (line.startsWith('///'))
+        return line.slice(3).trim();
+    if (line.startsWith('//'))
+        return line.slice(2).trim();
+    if (line.startsWith('##'))
+        return line.slice(2).trim();
+    if (line.startsWith('#'))
+        return line.slice(1).trim();
+    if (line.startsWith('*'))
+        return line.slice(1).trim();
+    if (line.startsWith('/*'))
+        return line.slice(2).trim();
+    return line;
+}
+//# sourceMappingURL=marker.js.map

package/dist/extract/marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.js","sourceRoot":"","sources":["../../src/extract/marker.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { GenerateOptions, MapNode } from './types.js';
+export type { DefEntry, Definition, FileEntry, FileResult, GenerateOptions, Language, MapNode, MarkerResult, } from './types.js';
+/**
+ * Generate a map object from a directory
+ */
+export declare function generateMap(options?: GenerateOptions): Promise<MapNode>;
+/**
+ * Generate a YAML string map from a directory
+ */
+export declare function generateMapYaml(options?: GenerateOptions): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAE1D,YAAY,EACV,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,eAAe,EACf,QAAQ,EACR,OAAO,EACP,YAAY,GACb,MAAM,YAAY,CAAA;AAEnB;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAKjF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpF"}

package/dist/index.js

@@ -0,0 +1,23 @@
+// @mappamundi
+// Library exports for programmatic usage.
+import { resolve } from 'path';
+import { scanDirectory } from './scanner.js';
+import { buildMap, getRootName } from './map/builder.js';
+import { toYaml } from './map/yaml.js';
+/**
+ * Generate a map object from a directory
+ */
+export async function generateMap(options = {}) {
+    const dir = resolve(options.dir ?? '.');
+    const results = await scanDirectory({ ...options, dir });
+    const rootName = getRootName(dir);
+    return buildMap(results, rootName);
+}
+/**
+ * Generate a YAML string map from a directory
+ */
+export async function generateMapYaml(options = {}) {
+    const map = await generateMap(options);
+    return toYaml(map);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,0CAA0C;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AActC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,UAA2B,EAAE;IAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,CAAC,CAAA;IACxD,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IACjC,OAAO,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAA2B,EAAE;IACjE,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAA;IACtC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAA;AACpB,CAAC"}

package/dist/map/builder.d.ts

@@ -0,0 +1,10 @@
+import type { FileResult, MapNode } from '../types.js';
+/**
+ * Build a nested map object from file results
+ */
+export declare function buildMap(results: FileResult[], rootName: string): MapNode;
+/**
+ * Get the root name from a directory path
+ */
+export declare function getRootName(dir: string): string;
+//# sourceMappingURL=builder.d.ts.map

package/dist/map/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/map/builder.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEjE;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CASzE;AAoCD;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C"}

package/dist/map/builder.js

@@ -0,0 +1,53 @@
+// @mappamundi
+// Build the nested map object from file results.
+import { basename } from 'path';
+/**
+ * Build a nested map object from file results
+ */
+export function buildMap(results, rootName) {
+    const root = {};
+    for (const result of results) {
+        insertFile(root, result);
+    }
+    // Wrap in root name
+    return { [rootName]: root };
+}
+/**
+ * Insert a file result into the map at its path location
+ */
+function insertFile(root, result) {
+    const parts = result.relativePath.split('/');
+    let current = root;
+    // Navigate/create directory structure
+    for (let i = 0; i < parts.length - 1; i++) {
+        const dir = parts[i];
+        if (!current[dir]) {
+            current[dir] = {};
+        }
+        current = current[dir];
+    }
+    // Create file entry
+    const filename = parts[parts.length - 1];
+    const entry = {};
+    if (result.description) {
+        entry.desc = result.description;
+    }
+    if (result.definitions.length > 0) {
+        entry.defs = {};
+        for (const def of result.definitions) {
+            entry.defs[def.name] = def.line;
+        }
+    }
+    current[filename] = entry;
+}
+/**
+ * Get the root name from a directory path
+ */
+export function getRootName(dir) {
+    // Handle trailing slashes
+    const cleaned = dir.replace(/\/+$/, '');
+    // Get basename, or use 'root' for current directory
+    const name = basename(cleaned);
+    return name === '.' || name === '' ? 'root' : name;
+}
+//# sourceMappingURL=builder.js.map

package/dist/map/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/map/builder.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,iDAAiD;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAA;AAG/B;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAqB,EAAE,QAAgB;IAC9D,MAAM,IAAI,GAAY,EAAE,CAAA;IAExB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC1B,CAAC;IAED,oBAAoB;IACpB,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAA;AAC7B,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,IAAa,EAAE,MAAkB;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC5C,IAAI,OAAO,GAAG,IAAI,CAAA;IAElB,sCAAsC;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAA;QACnB,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,GAAG,CAAY,CAAA;IACnC,CAAC;IAED,oBAAoB;IACpB,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACxC,MAAM,KAAK,GAAc,EAAE,CAAA;IAE3B,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,WAAW,CAAA;IACjC,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,GAAG,EAAE,CAAA;QACf,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,CAAA;QACjC,CAAC;IACH,CAAC;IAED,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAA;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,0BAA0B;IAC1B,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACvC,oDAAoD;IACpD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC9B,OAAO,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAA;AACpD,CAAC"}

package/dist/map/yaml.d.ts

@@ -0,0 +1,6 @@
+import type { MapNode } from '../types.js';
+/**
+ * Convert map object to YAML string
+ */
+export declare function toYaml(map: MapNode): string;
+//# sourceMappingURL=yaml.d.ts.map

package/dist/map/yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../../src/map/yaml.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE1C;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAS3C"}

package/dist/map/yaml.js

@@ -0,0 +1,17 @@
+// @mappamundi
+// Format map object to YAML string.
+import yaml from 'js-yaml';
+/**
+ * Convert map object to YAML string
+ */
+export function toYaml(map) {
+    return yaml.dump(map, {
+        indent: 2,
+        lineWidth: -1, // Don't wrap lines
+        noRefs: true, // Don't use YAML references
+        sortKeys: true, // Consistent ordering
+        quotingType: '"',
+        forceQuotes: false,
+    });
+}
+//# sourceMappingURL=yaml.js.map

package/dist/map/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../../src/map/yaml.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,oCAAoC;AAEpC,OAAO,IAAI,MAAM,SAAS,CAAA;AAG1B;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;QACpB,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,CAAC,CAAC,EAAG,mBAAmB;QACnC,MAAM,EAAE,IAAI,EAAI,4BAA4B;QAC5C,QAAQ,EAAE,IAAI,EAAE,sBAAsB;QACtC,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,KAAK;KACnB,CAAC,CAAA;AACJ,CAAC"}

package/dist/parser/index.d.ts

@@ -0,0 +1,15 @@
+import type { Language, SyntaxTree } from '../types.js';
+/**
+ * Initialize the tree-sitter parser
+ */
+export declare function initParser(): Promise<void>;
+/**
+ * Parse source code and return the syntax tree
+ */
+export declare function parseCode(code: string, language: Language): Promise<SyntaxTree>;
+/**
+ * Reset the parser (for testing)
+ */
+export declare function resetParser(): void;
+export { detectLanguage, loadGrammar, LANGUAGE_EXTENSIONS } from './languages.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/parser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/parser/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAMvD;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAIhD;AAYD;;GAEG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,UAAU,CAAC,CAKrB;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAMlC;AAED,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/parser/index.js

@@ -0,0 +1,46 @@
+// @mappamundi
+// Tree-sitter parser initialization and code parsing.
+import Parser from 'web-tree-sitter';
+import { loadGrammar } from './languages.js';
+let initialized = false;
+let sharedParser = null;
+/**
+ * Initialize the tree-sitter parser
+ */
+export async function initParser() {
+    if (initialized)
+        return;
+    await Parser.init();
+    initialized = true;
+}
+/**
+ * Get the shared parser instance
+ */
+async function getParser() {
+    if (sharedParser)
+        return sharedParser;
+    await initParser();
+    sharedParser = new Parser();
+    return sharedParser;
+}
+/**
+ * Parse source code and return the syntax tree
+ */
+export async function parseCode(code, language) {
+    const parser = await getParser();
+    const grammar = await loadGrammar(language);
+    parser.setLanguage(grammar);
+    return parser.parse(code);
+}
+/**
+ * Reset the parser (for testing)
+ */
+export function resetParser() {
+    if (sharedParser) {
+        sharedParser.delete();
+        sharedParser = null;
+    }
+    initialized = false;
+}
+export { detectLanguage, loadGrammar, LANGUAGE_EXTENSIONS } from './languages.js';
+//# sourceMappingURL=index.js.map

package/dist/parser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/parser/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,sDAAsD;AAEtD,OAAO,MAAM,MAAM,iBAAiB,CAAA;AAEpC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,IAAI,WAAW,GAAG,KAAK,CAAA;AACvB,IAAI,YAAY,GAAkB,IAAI,CAAA;AAEtC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,WAAW;QAAE,OAAM;IACvB,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;IACnB,WAAW,GAAG,IAAI,CAAA;AACpB,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,SAAS;IACtB,IAAI,YAAY;QAAE,OAAO,YAAY,CAAA;IACrC,MAAM,UAAU,EAAE,CAAA;IAClB,YAAY,GAAG,IAAI,MAAM,EAAE,CAAA;IAC3B,OAAO,YAAY,CAAA;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,QAAkB;IAElB,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAA;IAChC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAA;IAC3C,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;IAC3B,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,YAAY,EAAE,CAAC;QACjB,YAAY,CAAC,MAAM,EAAE,CAAA;QACrB,YAAY,GAAG,IAAI,CAAA;IACrB,CAAC;IACD,WAAW,GAAG,KAAK,CAAA;AACrB,CAAC;AAED,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/parser/languages.d.ts

@@ -0,0 +1,19 @@
+import Parser from 'web-tree-sitter';
+import type { Language } from '../types.js';
+/**
+ * File extension to language mapping
+ */
+export declare const LANGUAGE_EXTENSIONS: Record<string, Language>;
+/**
+ * Detect language from file path extension
+ */
+export declare function detectLanguage(filepath: string): Language | null;
+/**
+ * Load a tree-sitter grammar for the given language
+ */
+export declare function loadGrammar(language: Language): Promise<Parser.Language>;
+/**
+ * Clear grammar cache (for testing)
+ */
+export declare function clearGrammarCache(): void;
+//# sourceMappingURL=languages.d.ts.map

package/dist/parser/languages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"languages.d.ts","sourceRoot":"","sources":["../../src/parser/languages.ts"],"names":[],"mappings":"AAGA,OAAO,MAAM,MAAM,iBAAiB,CAAA;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAK3C;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAaxD,CAAA;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGhE;AAoCD;;GAEG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAU9E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/parser/languages.js

@@ -0,0 +1,80 @@
+// @mappamundi
+// Language detection and grammar loading for tree-sitter.
+import Parser from 'web-tree-sitter';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+/**
+ * File extension to language mapping
+ */
+export const LANGUAGE_EXTENSIONS = {
+    '.ts': 'typescript',
+    '.tsx': 'typescript',
+    '.mts': 'typescript',
+    '.cts': 'typescript',
+    '.js': 'javascript',
+    '.jsx': 'javascript',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+    '.py': 'python',
+    '.pyi': 'python',
+    '.rs': 'rust',
+    '.go': 'go',
+};
+/**
+ * Detect language from file path extension
+ */
+export function detectLanguage(filepath) {
+    const ext = filepath.slice(filepath.lastIndexOf('.'));
+    return LANGUAGE_EXTENSIONS[ext] ?? null;
+}
+/**
+ * Get the WASM grammar path for a language
+ */
+function getGrammarPath(language) {
+    switch (language) {
+        case 'typescript':
+            return require.resolve('tree-sitter-typescript/tree-sitter-tsx.wasm');
+        case 'javascript':
+            return require.resolve('tree-sitter-javascript/tree-sitter-javascript.wasm');
+        case 'python':
+            return require.resolve('tree-sitter-python/tree-sitter-python.wasm');
+        case 'rust':
+            return require.resolve('tree-sitter-rust/tree-sitter-rust.wasm');
+        case 'go':
+            return require.resolve('tree-sitter-go/tree-sitter-go.wasm');
+    }
+}
+/**
+ * Cache for loaded grammars
+ */
+const grammarCache = new Map();
+/**
+ * Ensure Parser is initialized before loading grammars
+ */
+let parserInitialized = false;
+async function ensureParserInit() {
+    if (!parserInitialized) {
+        await Parser.init();
+        parserInitialized = true;
+    }
+}
+/**
+ * Load a tree-sitter grammar for the given language
+ */
+export async function loadGrammar(language) {
+    await ensureParserInit();
+    const cached = grammarCache.get(language);
+    if (cached)
+        return cached;
+    const path = getGrammarPath(language);
+    const grammar = await Parser.Language.load(path);
+    grammarCache.set(language, grammar);
+    return grammar;
+}
+/**
+ * Clear grammar cache (for testing)
+ */
+export function clearGrammarCache() {
+    grammarCache.clear();
+}
+//# sourceMappingURL=languages.js.map

package/dist/parser/languages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"languages.js","sourceRoot":"","sources":["../../src/parser/languages.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,0DAA0D;AAE1D,OAAO,MAAM,MAAM,iBAAiB,CAAA;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEtC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA6B;IAC3D,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,IAAI;CACZ,CAAA;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IACrD,OAAO,mBAAmB,CAAC,GAAG,CAAC,IAAI,IAAI,CAAA;AACzC,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,QAAkB;IACxC,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,YAAY;YACf,OAAO,OAAO,CAAC,OAAO,CAAC,6CAA6C,CAAC,CAAA;QACvE,KAAK,YAAY;YACf,OAAO,OAAO,CAAC,OAAO,CAAC,oDAAoD,CAAC,CAAA;QAC9E,KAAK,QAAQ;YACX,OAAO,OAAO,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAA;QACtE,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,OAAO,CAAC,wCAAwC,CAAC,CAAA;QAClE,KAAK,IAAI;YACP,OAAO,OAAO,CAAC,OAAO,CAAC,oCAAoC,CAAC,CAAA;IAChE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAA6B,CAAA;AAEzD;;GAEG;AACH,IAAI,iBAAiB,GAAG,KAAK,CAAA;AAC7B,KAAK,UAAU,gBAAgB;IAC7B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QACnB,iBAAiB,GAAG,IAAI,CAAA;IAC1B,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAkB;IAClD,MAAM,gBAAgB,EAAE,CAAA;IAExB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IACzC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAA;IAEzB,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;IACrC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChD,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACnC,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,YAAY,CAAC,KAAK,EAAE,CAAA;AACtB,CAAC"}

package/dist/scanner.d.ts

@@ -0,0 +1,6 @@
+import type { FileResult, GenerateOptions } from './types.js';
+/**
+ * Scan directory and process files with @mappamundi marker
+ */
+export declare function scanDirectory(options?: GenerateOptions): Promise<FileResult[]>;
+//# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAyE7D;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAuCxF"}

package/dist/scanner.js

@@ -0,0 +1,139 @@
+// @mappamundi
+// Scan directory for files with @mappamundi marker.
+import { execSync } from 'child_process';
+import fg from 'fast-glob';
+import picomatch from 'picomatch';
+import { readFile } from 'fs/promises';
+import { join, normalize } from 'path';
+import { extractMarker } from './extract/marker.js';
+import { extractDefinitions } from './extract/definitions.js';
+import { parseCode, detectLanguage, LANGUAGE_EXTENSIONS } from './parser/index.js';
+/**
+ * Supported file extensions (from LANGUAGE_EXTENSIONS)
+ */
+const SUPPORTED_EXTENSIONS = new Set(Object.keys(LANGUAGE_EXTENSIONS));
+/**
+ * Check if a file has a supported extension
+ */
+function isSupportedFile(filepath) {
+    const ext = filepath.slice(filepath.lastIndexOf('.'));
+    return SUPPORTED_EXTENSIONS.has(ext);
+}
+/**
+ * Check if running inside a git repository
+ */
+function isGitRepo(dir) {
+    try {
+        execSync('git rev-parse --git-dir', { cwd: dir, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get files using git ls-files
+ * Uses --cached --others to get tracked + untracked files
+ * Uses --exclude-standard to respect .gitignore
+ */
+function getGitFiles(dir) {
+    const maxBuffer = 1024 * 10000000;
+    try {
+        // Get tracked and untracked files (respecting .gitignore)
+        const stdout = execSync('git ls-files --cached --others --exclude-standard', {
+            cwd: dir,
+            maxBuffer,
+            encoding: 'utf8',
+        });
+        // Get deleted files to exclude
+        const deleted = execSync('git ls-files --deleted', {
+            cwd: dir,
+            maxBuffer,
+            encoding: 'utf8',
+        });
+        const paths = stdout.split(/\r?\n/).map(x => x.trim()).filter(Boolean);
+        const deletedPaths = new Set(deleted.split(/\r?\n/).map(x => x.trim()).filter(Boolean));
+        return paths
+            .filter(p => !deletedPaths.has(p))
+            .map(normalize);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get files using fast-glob (fallback when not in git repo)
+ */
+async function getGlobFiles(dir) {
+    const patterns = Object.keys(LANGUAGE_EXTENSIONS).map(ext => `**/*${ext}`);
+    return fg(patterns, {
+        cwd: dir,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'],
+        absolute: false,
+        dot: false,
+    });
+}
+/**
+ * Scan directory and process files with @mappamundi marker
+ */
+export async function scanDirectory(options = {}) {
+    const dir = options.dir ?? process.cwd();
+    const ignorePatterns = options.ignore ?? [];
+    // Get file list - prefer git, fallback to glob
+    let files;
+    if (isGitRepo(dir)) {
+        files = getGitFiles(dir);
+    }
+    else {
+        files = await getGlobFiles(dir);
+    }
+    // Filter by supported extensions
+    files = files.filter(isSupportedFile);
+    // Filter by ignore patterns
+    if (ignorePatterns.length > 0) {
+        const isIgnored = picomatch(ignorePatterns);
+        files = files.filter(f => !isIgnored(f));
+    }
+    // Process each file
+    const results = [];
+    for (const relativePath of files) {
+        const fullPath = join(dir, relativePath);
+        try {
+            const result = await processFile(fullPath, relativePath);
+            if (result) {
+                results.push(result);
+            }
+        }
+        catch (err) {
+            // Skip files that fail to process
+            console.error(`Warning: Failed to process ${relativePath}:`, err);
+        }
+    }
+    return results;
+}
+/**
+ * Process a single file - check for marker and extract definitions
+ */
+async function processFile(fullPath, relativePath) {
+    // Check for marker first (only reads first 30KB)
+    const marker = await extractMarker(fullPath);
+    if (!marker.found) {
+        return null;
+    }
+    // Detect language
+    const language = detectLanguage(relativePath);
+    if (!language) {
+        return null;
+    }
+    // Read full file for parsing
+    const code = await readFile(fullPath, 'utf8');
+    // Parse and extract definitions
+    const tree = await parseCode(code, language);
+    const definitions = extractDefinitions(tree.rootNode, language);
+    return {
+        relativePath,
+        description: marker.description,
+        definitions,
+    };
+}
+//# sourceMappingURL=scanner.js.map

package/dist/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,oDAAoD;AAEpD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,MAAM,WAAW,CAAA;AAC1B,OAAO,SAAS,MAAM,WAAW,CAAA;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,MAAM,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAGlF;;GAEG;AACH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAA;AAEtE;;GAEG;AACH,SAAS,eAAe,CAAC,QAAgB;IACvC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IACrD,OAAO,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,QAAQ,CAAC,yBAAyB,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;QAClE,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAA;IACjC,IAAI,CAAC;QACH,0DAA0D;QAC1D,MAAM,MAAM,GAAG,QAAQ,CAAC,mDAAmD,EAAE;YAC3E,GAAG,EAAE,GAAG;YACR,SAAS;YACT,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAA;QAEF,+BAA+B;QAC/B,MAAM,OAAO,GAAG,QAAQ,CAAC,wBAAwB,EAAE;YACjD,GAAG,EAAE,GAAG;YACR,SAAS;YACT,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAA;QAEF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QACtE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;QAEvF,OAAO,KAAK;aACT,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;aACjC,GAAG,CAAC,SAAS,CAAC,CAAA;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,YAAY,CAAC,GAAW;IACrC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,EAAE,CAAC,CAAA;IAC1E,OAAO,EAAE,CAAC,QAAQ,EAAE;QAClB,GAAG,EAAE,GAAG;QACR,MAAM,EAAE,CAAC,oBAAoB,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,CAAC;QACzE,QAAQ,EAAE,KAAK;QACf,GAAG,EAAE,KAAK;KACX,CAAC,CAAA;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAA2B,EAAE;IAC/D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;IACxC,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAA;IAE3C,+CAA+C;IAC/C,IAAI,KAAe,CAAA;IACnB,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAA;IACjC,CAAC;IAED,iCAAiC;IACjC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;IAErC,4BAA4B;IAC5B,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,SAAS,CAAC,cAAc,CAAC,CAAA;QAC3C,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1C,CAAC;IAED,oBAAoB;IACpB,MAAM,OAAO,GAAiB,EAAE,CAAA;IAEhC,KAAK,MAAM,YAAY,IAAI,KAAK,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;QAExC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;YACxD,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YACtB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,kCAAkC;YAClC,OAAO,CAAC,KAAK,CAAC,8BAA8B,YAAY,GAAG,EAAE,GAAG,CAAC,CAAA;QACnE,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,WAAW,CACxB,QAAgB,EAChB,YAAoB;IAEpB,iDAAiD;IACjD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAA;IAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,kBAAkB;IAClB,MAAM,QAAQ,GAAG,cAAc,CAAC,YAAY,CAAC,CAAA;IAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAA;IACb,CAAC;IAED,6BAA6B;IAC7B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAE7C,gCAAgC;IAChC,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IAC5C,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAE/D,OAAO;QACL,YAAY;QACZ,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW;KACZ,CAAA;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+import type Parser from 'web-tree-sitter';
+/**
+ * Supported programming languages
+ */
+export type Language = 'typescript' | 'javascript' | 'python' | 'rust' | 'go';
+/**
+ * Symbol definitions mapping: name -> 1-based line number
+ */
+export interface DefEntry {
+    [symbolName: string]: number;
+}
+/**
+ * A file entry in the map
+ */
+export interface FileEntry {
+    desc?: string;
+    defs?: DefEntry;
+}
+/**
+ * Recursive map node - either a directory (with children) or a file entry
+ */
+export interface MapNode {
+    [name: string]: MapNode | FileEntry;
+}
+/**
+ * Result of extracting marker and description from a file
+ */
+export interface MarkerResult {
+    found: boolean;
+    description?: string;
+}
+/**
+ * A definition extracted from source code
+ */
+export interface Definition {
+    name: string;
+    line: number;
+    type: 'function' | 'class';
+}
+/**
+ * Result of processing a single file
+ */
+export interface FileResult {
+    relativePath: string;
+    description?: string;
+    definitions: Definition[];
+}
+/**
+ * Options for generating the map
+ */
+export interface GenerateOptions {
+    /** Directory to scan (default: cwd) */
+    dir?: string;
+    /** Glob patterns to ignore */
+    ignore?: string[];
+}
+/**
+ * Re-export parser types
+ */
+export type SyntaxNode = Parser.SyntaxNode;
+export type SyntaxTree = Parser.Tree;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC;;GAEG;AACH,MAAM,MAAM,QAAQ,GAChB,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,MAAM,GACN,IAAI,CAAA;AAER;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,UAAU,GAAG,OAAO,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAA;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAA"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// @mappamundi
+// Core type definitions for the codebase map.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,8CAA8C"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "agentmap",
+  "version": "0.1.0",
+  "description": "Generate a YAML map of your codebase for AI agent context",
+  "type": "module",
+  "bin": {
+    "agentmap": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "cli": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "cac": "^6.7.14",
+    "fast-glob": "^3.3.2",
+    "js-yaml": "^4.1.0",
+    "picomatch": "^4.0.2",
+    "tree-sitter-go": "^0.23.4",
+    "tree-sitter-javascript": "^0.23.1",
+    "tree-sitter-python": "^0.23.6",
+    "tree-sitter-rust": "^0.23.2",
+    "tree-sitter-typescript": "^0.23.2",
+    "web-tree-sitter": "^0.24.4"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.2",
+    "@types/picomatch": "^3.0.1",
+    "typescript": "^5.7.2"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "codebase",
+    "map",
+    "yaml",
+    "treesitter",
+    "ast"
+  ],
+  "license": "MIT"
+}