Skip to content

api-reference.md

Latest commit

 

History

History
345 lines (265 loc) · 7.16 KB

api-reference.md

File metadata and controls

345 lines (265 loc) · 7.16 KB
Raw

API Reference

This document provides technical reference for DoCode's internal APIs and data formats.

Core Package API

Analyzer Class

The main analysis engine exposed by @docode/core.

Location: docode/packages/core/src/analyzer.ts

Methods

analyze(options: AnalyzeOptions): Promise<AnalysisResult>

Performs code analysis on the specified input.

Parameters:

interface AnalyzeOptions {
  source: {
    type: 'github' | 'folder' | 'zip';
    url?: string;        // for GitHub
    path?: string;       // for folder/zip
  };
  outputDir: string;     // where to write .DoCode/
  includeDomain?: boolean; // generate domain graph
  ai?: {
    enabled: boolean;
    semanticSearch?: boolean;
    explain?: boolean;
  };
}

Returns:

interface AnalysisResult {
  knowledgeGraph: GraphData;
  domainGraph?: GraphData;
  meta: MetaData;
}

Example:

import { Analyzer } from '@docode/core';

const analyzer = new Analyzer();
const result = await analyzer.analyze({
  source: {
    type: 'folder',
    path: '/home/ashil/my-project'
  },
  outputDir: '/home/ashil/my-project/.DoCode',
  includeDomain: false
});
loadGraph(graphDir: string): GraphData

Load an existing knowledge graph from disk.

Parameters:

  • graphDir: string - Path to .DoCode/ or .understand-anything/ directory

Returns: GraphData object

Example:

const graph = await analyzer.loadGraph('/path/to/project/.DoCode');
console.log(`Loaded ${graph.nodes.length} nodes`);

Data Formats

GraphData Structure

interface GraphData {
  nodes: GraphNode[];
  edges: GraphEdge[];
}

GraphNode

interface GraphNode {
  id: string;              // Unique identifier (e.g., "file:src/index.ts")
  type: NodeType;           // 'file' | 'function' | 'class' | 'module' | 'variable'
  label: string;            // Display name
  path?: string;            // File path (for file nodes)
  line?: number;            // Line number (for functions/classes)
  language?: string;        // Programming language
  file?: string;            // Source file (for functions/classes)
  metadata?: Record<string, any>; // Additional properties
}

GraphEdge

interface GraphEdge {
  source: string;           // Source node ID
  target: string;           // Target node ID
  type: EdgeType;           // 'defines' | 'calls' | 'imports' | 'extends' | 'references'
  metadata?: Record<string, any>;
}

MetaData

interface MetaData {
  lastAnalyzedAt: string;    // ISO 8601 timestamp
  gitCommitHash?: string;    // Current git commit (if available)
  version: string;           // Analyzer version
  analyzedFiles: number;     // Number of files analyzed
  analysisMode: string;      // 'codebase' | 'domain'
  sourceType: 'folder' | 'github' | 'zip';
  runtime: {
    startedAt: string;
    completedAt: string;
    durationMs: number;
    cacheKey: string;
    cacheHit: boolean;
  };
  ai?: {
    enabled: boolean;
    semanticSearch: boolean;
    explain: boolean;
  };
}

CLI Commands

Analyze Command

node dist/index.js analyze [options]

Options:
  --github <url>         Analyze a GitHub repository
  --folder <path>         Analyze a local folder
  --zip <path>           Analyze a ZIP archive
  --output <dir>         Output directory (default: ./.DoCode)
  --include-domain       Generate domain graph
  --ai-enabled           Enable AI features

Examples:

# GitHub repo
node dist/index.js analyze --github https://github.com/4shil/agent-sandbox

# Local folder
node dist/index.js analyze --folder /home/ashil/my-project

# ZIP archive
node dist/index.js analyze --zip /tmp/project.zip --output /tmp/output

Dashboard API

Environment Variables

Variable Required Description
GRAPH_DIR Yes Path to .DoCode/ directory containing knowledge-graph.json

Dashboard Endpoints (if applicable)

If the dashboard exposes API endpoints:

GET /api/graph
  Returns: GraphData

GET /api/node/:id
  Returns: GraphNode

GET /api/search?q=<query>
  Returns: GraphNode[]

Internal APIs

Parser Modules

Location: docode/packages/core/src/parsers/

parseJavaScript(filePath: string): ParseResult

Parses JavaScript/TypeScript files.

parsePython(filePath: string): ParseResult

Parses Python files.

parseGeneric(filePath: string): ParseResult

Fallback parser for unknown file types.

Graph Builder

Location: docode/packages/core/src/graph-builder.ts

Builds the knowledge graph from parsed ASTs.

Methods:

  • addNode(node: GraphNode): void
  • addEdge(edge: GraphEdge): void
  • build(): GraphData

Events (If Supported)

The core analyzer may emit events during analysis:

analyzer.on('file:start', (filePath) => {
  console.log(`Analyzing ${filePath}...`);
});

analyzer.on('file:complete', (filePath, result) => {
  console.log(`Completed ${filePath}: ${result.nodes.length} nodes`);
});

analyzer.on('analysis:complete', (result) => {
  console.log(`Total: ${result.nodes.length} nodes, ${result.edges.length} edges`);
});

Legacy Understand-Anything Compatibility

DoCode reads from both directories:

  • .DoCode/ (new)
  • .understand-anything/ (legacy)

Mapping:

New Path Legacy Path
.DoCode/knowledge-graph.json .understand-anything/knowledge-graph.json
.DoCode/domain-graph.json .understand-anything/domain-graph.json
.DoCode/meta.json .understand-anything/meta.json

Error Handling

Common Errors

ENOENT: no such file or directory

  • Cause: Invalid input path
  • Fix: Verify the path exists and is accessible

Invalid JSON in knowledge-graph.json

  • Cause: Corrupted graph file
  • Fix: Re-run analysis

Unsupported source type

  • Cause: Unknown file extension
  • Fix: Use generic parser or skip file

Error Types

class AnalysisError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly filePath?: string
  ) {
    super(message);
  }
}

// Error codes
'ANALYSIS_FAILED'
'FILE_NOT_FOUND'
'INVALID_JSON'
'UNSUPPORTED_TYPE'

TypeScript Definitions

All types are exported from @docode/core:

import type { 
  GraphData, 
  GraphNode, 
  GraphEdge, 
  AnalyzeOptions,
  AnalysisResult 
} from '@docode/core';

Performance Metrics

Access analysis performance data from meta.json:

{
  "runtime": {
    "durationMs": 1006,
    "analyzedFiles": 485,
    "filesPerSecond": 482.1
  }
}

Future API (Planned)

AI-Enhanced Analysis

const result = await analyzer.analyze({
  source: { type: 'folder', path: '/path' },
  ai: {
    enabled: true,
    semanticSearch: true,
    explain: true,
    insights: true
  }
});

Export API

await analyzer.export({
  format: 'documentation',  // or 'json', 'markdown'
  outputPath: './docs'
});

Watch Mode

// Re-analyze on file changes
analyzer.watch({
  folder: '/path/to/project',
  onChange: (changedFiles) => {
    console.log('Files changed:', changedFiles);
  }
});