refactor: curate public API surface (ROADMAP 3.6, 3.7)

docs/roadmap/ROADMAP.md

@@ -739,37 +739,37 @@ Adding a new MCP tool = adding a file + one line in the barrel. No other files c
 
 **Affected files:** `src/mcp.js` -> split into `src/mcp/`
 
-### 3.6 -- CLI Command Objects
+### 3.6 -- CLI Command Objects ✅
 
-Move from 1,557 lines of inline Commander chains to self-contained command modules.
-
-> **Note:** Phase 2.7.11 consolidated 5 commands — the first CLI surface area reduction. This item continues that direction by making each of the 39 remaining commands independently testable.
+Monolithic 1,525-line `src/cli.js` split into `src/cli/` with auto-discovery of command modules. 40 independently testable command files in `src/cli/commands/`, each exporting `{ name, description, options, queryOpts, validate, execute }`. Shared utilities extracted to `src/cli/shared/` (query options, output formatting). `src/cli/index.js` provides `registerCommand()` + `discoverCommands()` — new commands are added by dropping a file into `commands/`. `src/cli.js` reduced to an 8-line thin wrapper ([#427](https://github.com/optave/codegraph/pull/427)).
 
 ```
 src/
+  cli.js                         # 8-line thin wrapper → cli/index.js
   cli/
-    index.js                   # Commander setup, auto-discover commands
+    index.js                     # Commander setup, registerCommand(), discoverCommands()
     shared/
-      output.js                # --json, --ndjson, table, plain text
-      options.js               # Shared options (--no-tests, --json, --db, etc.)
-    commands/                  # 39 files, one per command
-      build.js                 # { name, description, options, validate, execute }
+      output.js                  # --json, --ndjson, table, plain text
+      options.js                 # Shared options (--no-tests, --json, --db, etc.)
+    commands/                    # 40 files, one per command
+      build.js                   # { name, description, options, validate, execute }
       ...
 ```
 
-Each command is independently testable by calling `execute()` directly.
-
 **Affected files:** `src/cli.js` -> split into `src/cli/`
 
-### 3.7 -- Curated Public API Surface
+### 3.7 -- Curated Public API Surface ✅
 
-Reduce `index.js` from 140+ exports to ~35 curated exports. Use `package.json` `exports` field to enforce module boundaries.
+Reduced `index.js` from ~190 named exports (243 lines) to 48 curated exports (57 lines). CLI formatters, internal DB utilities, parser internals, infrastructure helpers, and implementation-detail constants removed from the public surface. `package.json` `exports` field updated to expose `./cli` entry point.
 
-```json
-{ "exports": { ".": "./src/index.js", "./cli": "./src/cli.js" } }
-```
+**What's exported:**
+- **31 `*Data()` query functions** — one per command (e.g. `queryNameData`, `contextData`, `auditData`, `cfgData`)
+- **4 graph building** — `buildGraph`, `loadConfig`, `findCycles`, `buildEmbeddings`
+- **3 export formats** — `exportDOT`, `exportJSON`, `exportMermaid`
+- **3 search** — `searchData`, `multiSearchData`, `hybridSearchData`
+- **4 constants** — `EVERY_SYMBOL_KIND`, `EVERY_EDGE_KIND`, `EXTENSIONS`, `IGNORE_DIRS`
 
-Export only `*Data()` functions (the command execute functions). Never export CLI formatters. Group by domain.
+**What's removed:** CLI display wrappers (`commands/*.js`, `queries-cli.js`), internal DB functions (`fanInJoinSQL`, `NodeQuery`, etc.), parser internals (`parseFileAuto`, `disposeParsers`), infrastructure (`outputResult`, `isTestFile`), registry management, snapshot internals, pagination helpers, implementation-detail constants (`COMPLEXITY_RULES`, `HALSTEAD_RULES`, etc.), and lower-level analysis functions. All remain importable via direct paths.
 
 **Affected files:** `src/index.js`, `package.json`
 

package.json

@@ -8,6 +8,9 @@
     ".": {
       "import": "./src/index.js"
     },
+    "./cli": {
+      "import": "./src/cli.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {

src/index.js

@@ -1,243 +1,51 @@
 /**
  * codegraph — Programmatic API
  *
+ * Curated public surface: *Data() query functions, graph building,
+ * export formats, and essential constants. CLI formatters and internal
+ * utilities are not exported — import them directly if needed.
+ *
  * Usage:
- *   import { buildGraph, queryNameData, findCycles, exportDOT } from 'codegraph';
+ *   import { buildGraph, queryNameData, findCycles, exportDOT } from '@optave/codegraph';
  */
 
-// AST node queries
-export { AST_NODE_KINDS, astQuery, astQueryData } from './ast.js';
-// Audit (composite report)
+export { astQueryData } from './ast.js';
 export { auditData } from './audit.js';
-// Batch querying
-export {
-  BATCH_COMMANDS,
-  batchData,
-  multiBatchData,
-  splitTargets,
-} from './batch.js';
-// Architecture boundary rules
-export { evaluateBoundaries, PRESETS, validateBoundaryConfig } from './boundaries.js';
-// Branch comparison
-export { branchCompareData, branchCompareMermaid } from './branch-compare.js';
-// Graph building
-export { buildGraph, collectFiles, loadPathAliases, resolveImportPath } from './builder.js';
-// Control flow graph (intraprocedural)
-export {
-  buildCFGData,
-  buildFunctionCFG,
-  CFG_RULES,
-  cfgData,
-  cfgToDOT,
-  cfgToMermaid,
-} from './cfg.js';
-// Check (CI validation predicates)
+export { batchData } from './batch.js';
+export { branchCompareData } from './branch-compare.js';
+export { buildGraph } from './builder.js';
+export { cfgData } from './cfg.js';
 export { checkData } from './check.js';
-// Co-change analysis
-export {
-  analyzeCoChanges,
-  coChangeData,
-  coChangeForFiles,
-  coChangeTopData,
-  computeCoChanges,
-  scanGitHistory,
-} from './cochange.js';
-export { audit } from './commands/audit.js';
-export { batch, batchQuery } from './commands/batch.js';
-export { cfg } from './commands/cfg.js';
-export { check } from './commands/check.js';
-export { communities } from './commands/communities.js';
-export { complexity } from './commands/complexity.js';
-export { dataflow } from './commands/dataflow.js';
-export { manifesto } from './commands/manifesto.js';
-export { owners } from './commands/owners.js';
-export { sequence } from './commands/sequence.js';
-export { formatHotspots, formatModuleBoundaries, formatStructure } from './commands/structure.js';
-export { triage } from './commands/triage.js';
-// Community detection
-export { communitiesData, communitySummaryForStats } from './communities.js';
-// Complexity metrics
-export {
-  COMPLEXITY_RULES,
-  complexityData,
-  computeFunctionComplexity,
-  computeHalsteadMetrics,
-  computeLOCMetrics,
-  computeMaintainabilityIndex,
-  findFunctionNode,
-  HALSTEAD_RULES,
-  iterComplexity,
-} from './complexity.js';
-// Configuration
+export { coChangeData } from './cochange.js';
+export { communitiesData } from './communities.js';
+export { complexityData } from './complexity.js';
 export { loadConfig } from './config.js';
-// Shared constants
-export { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
-// Circular dependency detection
-export { findCycles, formatCycles } from './cycles.js';
-// Dataflow analysis
-export {
-  buildDataflowEdges,
-  dataflowData,
-  dataflowImpactData,
-  dataflowPathData,
-  extractDataflow,
-} from './dataflow.js';
-// Database utilities
-export {
-  countEdges,
-  countFiles,
-  countNodes,
-  fanInJoinSQL,
-  fanOutJoinSQL,
-  findDbPath,
-  findNodesForTriage,
-  findNodesWithFanIn,
-  getBuildMeta,
-  initSchema,
-  iterateFunctionNodes,
-  kindInClause,
-  listFunctionNodes,
-  NodeQuery,
-  openDb,
-  openReadonlyOrFail,
-  setBuildMeta,
-  testFilterSQL,
-} from './db.js';
-// Embeddings
+export { EXTENSIONS, IGNORE_DIRS } from './constants.js';
+export { findCycles } from './cycles.js';
+export { dataflowData } from './dataflow.js';
+export { buildEmbeddings, hybridSearchData, multiSearchData, searchData } from './embedder.js';
+export { exportDOT, exportJSON, exportMermaid } from './export.js';
+export { flowData, listEntryPointsData } from './flow.js';
+export { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND } from './kinds.js';
+export { manifestoData } from './manifesto.js';
+export { ownersData } from './owners.js';
 export {
-  buildEmbeddings,
-  cosineSim,
-  DEFAULT_MODEL,
-  disposeModel,
-  EMBEDDING_STRATEGIES,
-  embed,
-  estimateTokens,
-  ftsSearchData,
-  hybridSearchData,
-  MODELS,
-  multiSearchData,
-  search,
-  searchData,
-} from './embedder.js';
-// Export (DOT/Mermaid/JSON/GraphML/GraphSON/Neo4j CSV)
-export {
-  exportDOT,
-  exportGraphML,
-  exportGraphSON,
-  exportJSON,
-  exportMermaid,
-  exportNeo4jCSV,
-} from './export.js';
-// Execution flow tracing
-export { entryPointType, flowData, listEntryPointsData } from './flow.js';
-// Result formatting
-export { outputResult } from './infrastructure/result-formatter.js';
-// Test file detection
-export { isTestFile, TEST_PATTERN } from './infrastructure/test-filter.js';
-// Logger
-export { setVerbose } from './logger.js';
-// Manifesto rule engine
-export { manifestoData, RULE_DEFS } from './manifesto.js';
-// Native engine
-export { isNativeAvailable } from './native.js';
-// Ownership (CODEOWNERS)
-export { matchOwners, ownersData, ownersForFiles, parseCodeowners } from './owners.js';
-// Pagination utilities
-export { MCP_DEFAULTS, MCP_MAX_LIMIT, paginate, paginateResult, printNdjson } from './paginate.js';
-// Unified parser API
-export {
-  disposeParsers,
-  getActiveEngine,
-  isWasmAvailable,
-  parseFileAuto,
-  parseFilesAuto,
-} from './parser.js';
-// Query functions (data-returning)
-export {
-  ALL_SYMBOL_KINDS,
-  CORE_EDGE_KINDS,
-  CORE_SYMBOL_KINDS,
   childrenData,
   contextData,
   diffImpactData,
-  diffImpactMermaid,
-  EVERY_EDGE_KIND,
-  EVERY_SYMBOL_KIND,
-  EXTENDED_SYMBOL_KINDS,
   explainData,
   exportsData,
-  FALSE_POSITIVE_CALLER_THRESHOLD,
-  FALSE_POSITIVE_NAMES,
   fileDepsData,
   fnDepsData,
   fnImpactData,
   impactAnalysisData,
-  iterListFunctions,
-  iterRoles,
-  iterWhere,
-  kindIcon,
   moduleMapData,
-  normalizeSymbol,
   pathData,
   queryNameData,
   rolesData,
-  STRUCTURAL_EDGE_KINDS,
   statsData,
-  VALID_ROLES,
   whereData,
 } from './queries.js';
-// Query CLI display wrappers
-export {
-  children,
-  context,
-  diffImpact,
-  explain,
-  fileDeps,
-  fileExports,
-  fnDeps,
-  fnImpact,
-  impactAnalysis,
-  moduleMap,
-  queryName,
-  roles,
-  stats,
-  symbolPath,
-  where,
-} from './queries-cli.js';
-// Registry (multi-repo)
-export {
-  listRepos,
-  loadRegistry,
-  pruneRegistry,
-  REGISTRY_PATH,
-  registerRepo,
-  resolveRepoDbPath,
-  saveRegistry,
-  unregisterRepo,
-} from './registry.js';
-// Sequence diagram generation
-export { sequenceData, sequenceToMermaid } from './sequence.js';
-// Snapshot management
-export {
-  snapshotDelete,
-  snapshotList,
-  snapshotRestore,
-  snapshotSave,
-  snapshotsDir,
-  validateSnapshotName,
-} from './snapshot.js';
-// Structure analysis
-export {
-  buildStructure,
-  classifyNodeRoles,
-  FRAMEWORK_ENTRY_PREFIXES,
-  hotspotsData,
-  moduleBoundariesData,
-  structureData,
-} from './structure.js';
-// Triage — composite risk audit
+export { sequenceData } from './sequence.js';
+export { hotspotsData, moduleBoundariesData, structureData } from './structure.js';
 export { triageData } from './triage.js';
-// Interactive HTML viewer
-export { generatePlotHTML, loadPlotConfig } from './viewer.js';
-// Watch mode
-export { watchProject } from './watcher.js';