@dotdotgod/cli 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/cli/usage.mjs

@@ -36,6 +36,11 @@ Create dotdotgod.config.json from a bundled or user template. Without --template
   dotdotgod query <root> <query> [--limit n] [--json]
 
 Search shared project documentation with the resolved local or remote embedding provider.`;
+    case 'map':
+      return `Usage:
+  dotdotgod map <root> [--depth <positive-integer>] [--json]
+
+Render the configured shared Markdown documentation map without modifying the project.`;
     case 'resolve':
       return `Usage:
   dotdotgod resolve <root> <ref> [--max-results n] [--include-archive] [--json]`;
@@ -73,6 +78,7 @@ Commands:
   init                  Initialize project memory files.
   config                Inspect or initialize project configuration.
   query                 Search project documentation.
+  map                   Render the project documentation map.
   resolve               Resolve a project reference.
   expand                Expand references in a prompt.
   validate              Validate project memory and documentation.

package/src/commands/map.mjs

@@ -0,0 +1,41 @@
+import { resolve } from 'node:path';
+import { buildDocumentationMap } from '../memory/documentation-map.mjs';
+
+function fail(json, code, message) {
+  if (json) console.log(JSON.stringify({ ok: false, error: { code, message } }, null, 2));
+  else console.error(message);
+  process.exit(2);
+}
+
+function parseMapOptions(argv) {
+  const options = { root: '.', depth: 5, json: false };
+  let rootSet = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') options.json = true;
+  }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') continue;
+    if (arg === '--depth') {
+      const value = argv[index + 1];
+      if (!value || !/^\d+$/.test(value) || Number(value) < 1) fail(options.json, 'INVALID_DEPTH', '--depth requires a positive integer.');
+      options.depth = Number(value);
+      index += 1;
+    } else if (!arg.startsWith('-') && !rootSet) {
+      options.root = arg;
+      rootSet = true;
+    } else if (!arg.startsWith('-')) fail(options.json, 'UNEXPECTED_ARGUMENT', `Unexpected argument: ${arg}`);
+    else fail(options.json, 'UNKNOWN_OPTION', `Unknown option: ${arg}`);
+  }
+  options.root = resolve(options.root);
+  return options;
+}
+
+export function runMap(argv) {
+  const options = parseMapOptions(argv);
+  const result = buildDocumentationMap(options.root, { depth: options.depth });
+  if (!result.ok) fail(options.json, result.error.code, result.error.message);
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(result.tree);
+}

package/src/core.mjs

@@ -4,6 +4,7 @@ import { runValidate } from './validate/run.mjs';
 import { runIndex, runStatus } from './index/cache.mjs';
 import { runConfig } from './commands/config.mjs';
 import { runQuery } from './commands/query.mjs';
+import { runMap } from './commands/map.mjs';
 import { runResolve, runExpand } from './reference/resolve.mjs';
 import { runTraceability } from './commands/traceability.mjs';
 import { runGraph } from './commands/graph.mjs';
@@ -19,6 +20,7 @@ export { buildCommunities, relationWeight } from './graph/communities.mjs';
 export { addEdge, addNode, compactGraph, expandGraph, graphStats, jsonSize, shardFile, writeJson } from './graph/store.mjs';
 export { cacheFile, collectIndexFiles, fingerprint, shouldIndexPath } from './index/files.mjs';
 export { buildMemoryAreas, detectCommandGuidance, detectPackageManager } from './memory/summary.mjs';
+export { buildDocumentationMap, formatDocumentationTree } from './memory/documentation-map.mjs';
 export { isReadmeIndexPath, retrievalMetadataForPath } from './graph/metadata.mjs';
 export { buildGraph } from './graph/extract.mjs';
 export { addDeterministicSemanticEdges } from './graph/semantic.mjs';
@@ -29,6 +31,7 @@ export { buildChangedFileProfile, MAX_VECTOR_PROFILE_CHARS, MAX_VECTOR_PROFILE_F
 export { buildVectorImpactOverlay, VECTOR_RELATION_WEIGHT } from './impact/vector-overlay.mjs';
 export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from './impact/format.mjs';
 export { runConfig } from './commands/config.mjs';
+export { runMap } from './commands/map.mjs';
 export { buildVectorIndex, cosineScore, parseQueryOptions, queryDocumentation, rankVectorFiles, runQuery } from './commands/query.mjs';
 export { chunkMarkdown, collectDocumentationChunks, collectDocumentationMarkdown, textFingerprint } from './query/chunks.mjs';
 export { readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, VECTOR_SCHEMA_VERSION, profileFingerprint, vectorCachePaths, writeVectorCache } from './query/store.mjs';
@@ -51,6 +54,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   else if (command === 'config') runConfig(args);
   else if (command === 'status') runStatus(args);
   else if (command === 'query') await runQuery(args);
+  else if (command === 'map') runMap(args);
   else if (command === 'resolve') runResolve(args);
   else if (command === 'expand') runExpand(args);
   else if (command === 'traceability') runTraceability(args);

package/src/memory/documentation-map.mjs

@@ -0,0 +1,111 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isSecretLikePathPattern, matchPathPattern, readMemoryConfig } from './config.mjs';
+
+const SKIPPED_DIRECTORIES = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.dotdotgod']);
+
+function node() {
+  return { directories: new Map(), files: [] };
+}
+
+function buildTree(paths) {
+  const root = node();
+  for (const path of [...new Set(paths)].sort()) {
+    const parts = path.split('/');
+    let current = root;
+    for (const part of parts.slice(0, -1)) {
+      if (!current.directories.has(part)) current.directories.set(part, node());
+      current = current.directories.get(part);
+    }
+    current.files.push(parts.at(-1));
+  }
+  return root;
+}
+
+function descendantCounts(current) {
+  let directories = 0;
+  let files = current.files.length;
+  for (const child of current.directories.values()) {
+    directories += 1;
+    const nested = descendantCounts(child);
+    directories += nested.directories;
+    files += nested.files;
+  }
+  return { directories, files };
+}
+
+function plural(count, singular, pluralForm = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+export function formatDocumentationTree(paths, documentationRoot = 'docs', maxDepth = 5) {
+  const tree = buildTree(paths);
+  let docs = tree;
+  for (const part of documentationRoot.split('/')) {
+    docs = docs.directories.get(part);
+    if (!docs) return `- ${documentationRoot}/: missing`;
+  }
+  const lines = [`${documentationRoot}/`];
+  const render = (current, depth, indent) => {
+    for (const file of current.files.sort()) lines.push(`${indent}- ${file}`);
+    if (depth >= maxDepth && current.directories.size > 0) {
+      for (const [name, child] of [...current.directories.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const counts = descendantCounts(child);
+        lines.push(`${indent}- ${name}/`);
+        lines.push(`${indent}  - … ${plural(counts.directories, 'directory', 'directories')}, ${plural(counts.files, 'Markdown file')}`);
+      }
+      return;
+    }
+    for (const [name, child] of [...current.directories.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      lines.push(`${indent}- ${name}/`);
+      render(child, depth + 1, `${indent}  `);
+    }
+  };
+  render(docs, 1, '  ');
+  return lines.join('\n');
+}
+
+function discoverMarkdown(root, documentationRoot, exclude) {
+  const paths = [];
+  const walk = (relativeDirectory) => {
+    let entries;
+    try {
+      entries = readdirSync(join(root, relativeDirectory), { withFileTypes: true, encoding: 'utf8' });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const path = `${relativeDirectory}/${entry.name}`.replaceAll('\\', '/');
+      if (entry.name.startsWith('.') || isSecretLikePathPattern(path) || exclude.some(pattern => matchPathPattern(path, pattern))) continue;
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRECTORIES.has(entry.name)) walk(path);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) paths.push(path);
+    }
+  };
+  walk(documentationRoot);
+  return paths.sort();
+}
+
+export function buildDocumentationMap(projectRoot = '.', { depth = 5 } = {}) {
+  const root = resolve(projectRoot);
+  if (!existsSync(root)) return { ok: false, error: { code: 'ROOT_NOT_FOUND', message: `Project root not found: ${root}` } };
+  try {
+    if (!statSync(root).isDirectory()) return { ok: false, error: { code: 'ROOT_NOT_FOUND', message: `Project root not found: ${root}` } };
+  } catch {
+    return { ok: false, error: { code: 'ROOT_NOT_FOUND', message: `Project root not found: ${root}` } };
+  }
+  const config = readMemoryConfig(root);
+  const documentationRoot = config.documentation?.root ?? 'docs';
+  const exclude = [...(config.load?.documentationSummary?.exclude ?? [])].sort();
+  const paths = discoverMarkdown(root, documentationRoot, exclude);
+  return {
+    ok: true,
+    root,
+    documentationRoot,
+    depth,
+    exclude,
+    paths,
+    tree: formatDocumentationTree(paths, documentationRoot, depth),
+  };
+}