From 424be699681fa445fc5a73a24916fcb544e11711 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Thu, 12 Mar 2026 23:51:47 -0600 Subject: [PATCH 1/2] refactor: curate public API surface (ROADMAP 3.6, 3.7) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mark 3.6 (CLI Command Objects) complete — already shipped in #427. Implement 3.7: reduce index.js from ~190 named exports to 48 curated exports. Keep only *Data() query functions, graph building, export formats, and essential constants. Remove CLI formatters, DB internals, parser internals, infrastructure helpers, and implementation-detail constants from the public surface. All removed exports remain importable via direct paths. Add ./cli entry point to package.json exports field. --- docs/roadmap/ROADMAP.md | 34 +++--- package.json | 3 + src/index.js | 244 +++++----------------------------------- 3 files changed, 48 insertions(+), 233 deletions(-) diff --git a/docs/roadmap/ROADMAP.md b/docs/roadmap/ROADMAP.md index 5a8b424c..19231fb9 100644 --- a/docs/roadmap/ROADMAP.md +++ b/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` diff --git a/package.json b/package.json index e50b6426..2e68434a 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,9 @@ ".": { "import": "./src/index.js" }, + "./cli": { + "import": "./src/cli.js" + }, "./package.json": "./package.json" }, "bin": { diff --git a/src/index.js b/src/index.js index b798d38a..d15f0f07 100644 --- a/src/index.js +++ b/src/index.js @@ -1,243 +1,55 @@ /** * 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) +// ── Query Data Functions ──────────────────────────────────────────────── +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'; +// ── Graph Building & Search ───────────────────────────────────────────── +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 +// ── Constants ─────────────────────────────────────────────────────────── +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 Formats ────────────────────────────────────────────────────── +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'; From c15e059633b08cc56b37f08d62b9bfd5af32733f Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 13 Mar 2026 00:13:10 -0600 Subject: [PATCH 2/2] refactor: remove misleading section headers from public API --- src/index.js | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/index.js b/src/index.js index d15f0f07..15a018fb 100644 --- a/src/index.js +++ b/src/index.js @@ -9,12 +9,10 @@ * import { buildGraph, queryNameData, findCycles, exportDOT } from '@optave/codegraph'; */ -// ── Query Data Functions ──────────────────────────────────────────────── export { astQueryData } from './ast.js'; export { auditData } from './audit.js'; export { batchData } from './batch.js'; export { branchCompareData } from './branch-compare.js'; -// ── Graph Building & Search ───────────────────────────────────────────── export { buildGraph } from './builder.js'; export { cfgData } from './cfg.js'; export { checkData } from './check.js'; @@ -22,12 +20,10 @@ export { coChangeData } from './cochange.js'; export { communitiesData } from './communities.js'; export { complexityData } from './complexity.js'; export { loadConfig } from './config.js'; -// ── Constants ─────────────────────────────────────────────────────────── 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 Formats ────────────────────────────────────────────────────── export { exportDOT, exportJSON, exportMermaid } from './export.js'; export { flowData, listEntryPointsData } from './flow.js'; export { EVERY_EDGE_KIND, EVERY_SYMBOL_KIND } from './kinds.js';