codegraph-py 1.0.0__py3-none-any.whl

codegraph/db/schema.sql

@@ -0,0 +1,151 @@
+-- CodeGraph SQLite Schema
+-- Version 1
+
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS schema_versions (
+    version INTEGER PRIMARY KEY,
+    applied_at INTEGER NOT NULL,
+    description TEXT
+);
+
+-- Core Tables
+
+-- Nodes: Code symbols (functions, classes, variables, etc.)
+CREATE TABLE IF NOT EXISTS nodes (
+    id TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    name TEXT NOT NULL,
+    qualified_name TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    language TEXT NOT NULL,
+    start_line INTEGER NOT NULL,
+    end_line INTEGER NOT NULL,
+    start_column INTEGER NOT NULL,
+    end_column INTEGER NOT NULL,
+    docstring TEXT,
+    signature TEXT,
+    visibility TEXT,
+    is_exported INTEGER DEFAULT 0,
+    is_async INTEGER DEFAULT 0,
+    is_static INTEGER DEFAULT 0,
+    is_abstract INTEGER DEFAULT 0,
+    decorators TEXT,
+    type_parameters TEXT,
+    return_type TEXT,
+    updated_at INTEGER NOT NULL
+);
+
+-- Edges: Relationships between nodes
+CREATE TABLE IF NOT EXISTS edges (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source TEXT NOT NULL,
+    target TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    metadata TEXT,
+    line INTEGER,
+    col INTEGER,
+    provenance TEXT DEFAULT NULL,
+    FOREIGN KEY (source) REFERENCES nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (target) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- Files: Tracked source files
+CREATE TABLE IF NOT EXISTS files (
+    path TEXT PRIMARY KEY,
+    content_hash TEXT NOT NULL,
+    language TEXT NOT NULL,
+    size INTEGER NOT NULL,
+    modified_at INTEGER NOT NULL,
+    indexed_at INTEGER NOT NULL,
+    node_count INTEGER DEFAULT 0,
+    errors TEXT
+);
+
+-- Unresolved References: References that need resolution after full indexing
+CREATE TABLE IF NOT EXISTS unresolved_refs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_node_id TEXT NOT NULL,
+    reference_name TEXT NOT NULL,
+    reference_kind TEXT NOT NULL,
+    line INTEGER NOT NULL,
+    col INTEGER NOT NULL,
+    candidates TEXT,
+    file_path TEXT NOT NULL DEFAULT '',
+    language TEXT NOT NULL DEFAULT 'unknown',
+    FOREIGN KEY (from_node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+-- =============================================================================
+-- Indexes for Query Performance
+-- =============================================================================
+
+-- Node indexes
+CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
+CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
+CREATE INDEX IF NOT EXISTS idx_nodes_qualified_name ON nodes(qualified_name);
+CREATE INDEX IF NOT EXISTS idx_nodes_file_path ON nodes(file_path);
+CREATE INDEX IF NOT EXISTS idx_nodes_language ON nodes(language);
+CREATE INDEX IF NOT EXISTS idx_nodes_file_line ON nodes(file_path, start_line);
+
+-- Full-text search index on node names, docstrings, and signatures
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+    id UNINDEXED,
+    name,
+    qualified_name,
+    docstring,
+    signature,
+    content='nodes',
+    content_rowid='rowid'
+);
+
+-- Triggers to keep FTS index in sync
+CREATE TRIGGER IF NOT EXISTS nodes_ai AFTER INSERT ON nodes BEGIN
+    INSERT INTO nodes_fts(rowid, id, name, qualified_name, docstring, signature)
+    VALUES (new.rowid, new.id, new.name, new.qualified_name, new.docstring, new.signature);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_ad AFTER DELETE ON nodes BEGIN
+    INSERT INTO nodes_fts(nodes_fts, rowid, id, name, qualified_name, docstring, signature)
+    VALUES ('delete', old.rowid, old.id, old.name, old.qualified_name, old.docstring, old.signature);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_au AFTER UPDATE ON nodes BEGIN
+    INSERT INTO nodes_fts(nodes_fts, rowid, id, name, qualified_name, docstring, signature)
+    VALUES ('delete', old.rowid, old.id, old.name, old.qualified_name, old.docstring, old.signature);
+    INSERT INTO nodes_fts(rowid, id, name, qualified_name, docstring, signature)
+    VALUES (new.rowid, new.id, new.name, new.qualified_name, new.docstring, new.signature);
+END;
+
+-- Name segment vocabulary for natural language matching
+CREATE TABLE IF NOT EXISTS name_segment_vocab (
+    segment TEXT NOT NULL,
+    name TEXT NOT NULL,
+    PRIMARY KEY (segment, name)
+) WITHOUT ROWID;
+
+-- Edge indexes
+CREATE INDEX IF NOT EXISTS idx_edges_kind ON edges(kind);
+CREATE INDEX IF NOT EXISTS idx_edges_source_kind ON edges(source, kind);
+CREATE INDEX IF NOT EXISTS idx_edges_target_kind ON edges(target, kind);
+
+-- Edge identity uniqueness
+CREATE UNIQUE INDEX IF NOT EXISTS idx_edges_identity
+  ON edges(source, target, kind, IFNULL(line, -1), IFNULL(col, -1));
+
+-- File indexes
+CREATE INDEX IF NOT EXISTS idx_files_language ON files(language);
+CREATE INDEX IF NOT EXISTS idx_files_modified_at ON files(modified_at);
+
+-- Unresolved refs indexes
+CREATE INDEX IF NOT EXISTS idx_unresolved_from_node ON unresolved_refs(from_node_id);
+CREATE INDEX IF NOT EXISTS idx_unresolved_name ON unresolved_refs(reference_name);
+CREATE INDEX IF NOT EXISTS idx_unresolved_file_path ON unresolved_refs(file_path);
+CREATE INDEX IF NOT EXISTS idx_unresolved_from_name ON unresolved_refs(from_node_id, reference_name);
+CREATE INDEX IF NOT EXISTS idx_edges_provenance ON edges(provenance);
+
+-- Project metadata for version/provenance tracking
+CREATE TABLE IF NOT EXISTS project_metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at INTEGER NOT NULL
+);

codegraph/directory.py

@@ -0,0 +1,160 @@
+"""
+CodeGraph Directory Management
+
+Manages the .codegraph/ directory structure.
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import shutil
+from pathlib import Path
+from typing import Optional, List, Tuple
+
+import codegraph.errors as err
+
+CODEGRAPH_DIR = '.codegraph'
+
+
+def get_codegraph_dir(project_root: str) -> str:
+    """Get the path to the .codegraph directory."""
+    return os.path.join(project_root, CODEGRAPH_DIR)
+
+
+def get_database_path(project_root: str) -> str:
+    """Get the path to the SQLite database."""
+    return os.path.join(get_codegraph_dir(project_root), 'codegraph.db')
+
+
+def is_initialized(project_root: str) -> bool:
+    """Check if a directory has been initialized as a CodeGraph project."""
+    cg_dir = get_codegraph_dir(project_root)
+    db_path = os.path.join(cg_dir, 'codegraph.db')
+    return os.path.isdir(cg_dir) and os.path.isfile(db_path)
+
+
+def create_directory(project_root: str) -> None:
+    """Create the .codegraph directory structure."""
+    cg_dir = get_codegraph_dir(project_root)
+    os.makedirs(cg_dir, exist_ok=True)
+
+
+def remove_directory(project_root: str) -> None:
+    """Remove the .codegraph directory structure."""
+    cg_dir = get_codegraph_dir(project_root)
+    if os.path.isdir(cg_dir):
+        shutil.rmtree(cg_dir)
+
+
+def validate_directory(project_root: str) -> Tuple[bool, List[str]]:
+    """Validate the .codegraph directory structure."""
+    errors_list = []
+    cg_dir = get_codegraph_dir(project_root)
+
+    if not os.path.isdir(cg_dir):
+        errors_list.append(f'{CODEGRAPH_DIR}/ directory not found')
+
+    db_path = os.path.join(cg_dir, 'codegraph.db')
+    if not os.path.isfile(db_path):
+        errors_list.append(f'{CODEGRAPH_DIR}/codegraph.db not found')
+
+    return (len(errors_list) == 0, errors_list)
+
+
+def find_nearest_codegraph_root(path: str) -> Optional[str]:
+    """Walk up from path to find the nearest .codegraph directory."""
+    path = os.path.normpath(os.path.abspath(path))
+    root = Path(path).anchor
+
+    while path and path != root:
+        if is_initialized(path):
+            return path
+        parent = os.path.dirname(path)
+        if parent == path:
+            break
+        path = parent
+
+    return None
+
+
+def is_codegraph_data_dir(name: str) -> bool:
+    """Check if a directory name is the CodeGraph data directory."""
+    return name == CODEGRAPH_DIR
+
+
+def unsafe_index_root_reason(path: str) -> Optional[str]:
+    """Check if a path is unsafe to index (home dir, root, etc)."""
+    home = os.path.expanduser('~')
+    path = os.path.normpath(os.path.abspath(path))
+
+    if path == home:
+        return 'your home directory'
+    if path == Path(path).anchor:
+        return 'a filesystem root'
+
+    # Check common dangerous paths
+    dangerous = [
+        '/etc', '/var', '/sys', '/proc', '/dev', '/bin', '/sbin',
+        '/usr/bin', '/usr/lib', '/usr/sbin',
+    ]
+    if os.name == 'posix':
+        for d in dangerous:
+            if path == d:
+                return 'a system directory'
+
+    return None
+
+
+def derive_project_name_tokens(project_root: str) -> List[str]:
+    """Derive project name tokens from project configuration files."""
+    tokens = []
+
+    # Try pyproject.toml
+    pyproject = os.path.join(project_root, 'pyproject.toml')
+    if os.path.isfile(pyproject):
+        try:
+            # Minimal TOML parsing for project name
+            with open(pyproject, 'r') as f:
+                for line in f:
+                    if line.strip().startswith('name'):
+                        import re
+                        m = re.search(r'name\s*=\s*["\'](.+?)["\']', line)
+                        if m:
+                            tokens.extend(m.group(1).replace('-', ' ').replace('_', ' ').split())
+                        break
+        except Exception:
+            pass
+
+    # Try package.json
+    pkg_json = os.path.join(project_root, 'package.json')
+    if os.path.isfile(pkg_json):
+        try:
+            with open(pkg_json, 'r') as f:
+                data = json.load(f)
+                if 'name' in data:
+                    tokens.extend(data['name'].replace('-', ' ').replace('_', ' ').split())
+        except Exception:
+            pass
+
+    # Try setup.cfg
+    setup_cfg = os.path.join(project_root, 'setup.cfg')
+    if os.path.isfile(setup_cfg):
+        try:
+            with open(setup_cfg, 'r') as f:
+                for line in f:
+                    if line.strip().startswith('name'):
+                        import re
+                        m = re.search(r'name\s*=\s*(.+?)$', line)
+                        if m:
+                            tokens.extend(m.group(1).strip().replace('-', ' ').replace('_', ' ').split())
+                        break
+        except Exception:
+            pass
+
+    # Fallback: use directory name
+    if not tokens:
+        dir_name = os.path.basename(project_root)
+        tokens = dir_name.replace('-', ' ').replace('_', ' ').split()
+
+    return [t.lower() for t in tokens if len(t) > 1]

codegraph/errors.py

@@ -0,0 +1,101 @@
+"""
+CodeGraph Error Types
+
+Custom exceptions and logging utilities.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Optional
+
+
+class CodeGraphError(Exception):
+    """Base error for all CodeGraph errors."""
+    def __init__(self, message: str, cause: Optional[Exception] = None):
+        self.message = message
+        self.cause = cause
+        super().__init__(message)
+
+
+class FileError(CodeGraphError):
+    """Error related to file operations."""
+    pass
+
+
+class ParseError(CodeGraphError):
+    """Error during code parsing."""
+    def __init__(self, message: str, file_path: Optional[str] = None,
+                 line: Optional[int] = None, column: Optional[int] = None):
+        self.file_path = file_path
+        self.line = line
+        self.column = column
+        super().__init__(message)
+
+
+class DatabaseError(CodeGraphError):
+    """Error related to database operations."""
+    pass
+
+
+class SearchError(CodeGraphError):
+    """Error during search operations."""
+    pass
+
+
+class ConfigError(CodeGraphError):
+    """Error related to configuration."""
+    pass
+
+
+# =============================================================================
+# Logger
+# =============================================================================
+
+_logger: Optional[logging.Logger] = None
+
+
+def get_logger() -> logging.Logger:
+    """Get the global CodeGraph logger."""
+    global _logger
+    if _logger is None:
+        _logger = logging.getLogger('codegraph')
+        if not _logger.handlers:
+            handler = logging.StreamHandler(sys.stderr)
+            handler.setFormatter(logging.Formatter(
+                '[%(levelname)s] %(message)s'
+            ))
+            _logger.addHandler(handler)
+            _logger.setLevel(logging.WARNING)
+    return _logger
+
+
+def set_logger(logger: logging.Logger) -> None:
+    """Set a custom logger."""
+    global _logger
+    _logger = logger
+
+
+def log_debug(message: str, **kwargs) -> None:
+    """Log a debug message."""
+    extra = f' {" ".join(f"{k}={v}" for k, v in kwargs.items())}' if kwargs else ''
+    get_logger().debug(f'{message}{extra}')
+
+
+def log_info(message: str, **kwargs) -> None:
+    """Log an info message."""
+    extra = f' {" ".join(f"{k}={v}" for k, v in kwargs.items())}' if kwargs else ''
+    get_logger().info(f'{message}{extra}')
+
+
+def log_warn(message: str, **kwargs) -> None:
+    """Log a warning message."""
+    extra = f' {" ".join(f"{k}={v}" for k, v in kwargs.items())}' if kwargs else ''
+    get_logger().warning(f'{message}{extra}')
+
+
+def log_error(message: str, **kwargs) -> None:
+    """Log an error message."""
+    extra = f' {" ".join(f"{k}={v}" for k, v in kwargs.items())}' if kwargs else ''
+    get_logger().error(f'{message}{extra}')