knowcode 0.1.0__py3-none-any.whl

structural_engine/engine.py

@@ -0,0 +1,192 @@
+"""Structural Engine Facade.
+
+The single public entry point for all structural operations.
+Orchestrates parsers, state, diffs, and generators safely behind
+a strict facade.
+"""
+
+from __future__ import annotations
+
+import structlog
+from ruamel.yaml import YAML
+
+from runtime.exceptions.errors import StructuralEngineFailure
+from runtime.repository.models import RepositoryPaths
+from structural_engine.diff.generator import generate as generate_diff
+from structural_engine.logs.generator import append as append_log
+from structural_engine.parser.parser import parse
+from structural_engine.reports.generator import generate as generate_report
+from structural_engine.results import InitializationResult, StructuralStatusResult, SyncResult
+from structural_engine.revisions.tracker import get_next_revision
+from structural_engine.snapshot.generator import persist as persist_snapshot
+from structural_engine.snapshot.loader import load as load_snapshot
+from structural_engine.state.manager import StateManager
+
+logger = structlog.get_logger(__name__)
+
+
+class StructuralEngine:
+    """Facade for the Structural Engine."""
+
+    def __init__(self) -> None:
+        self.state_manager = StateManager()
+
+    def initialize(self, paths: RepositoryPaths) -> InitializationResult:
+        """Initialize the structural state of the repository.
+
+        Must only be called after the Runtime has scaffolded the
+        .knowcode directory via ArtifactBuilder.
+
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            Canonical paths.
+
+        Returns
+        -------
+        InitializationResult
+            Success and initial S-001 markers.
+        """
+        try:
+            logger.info("engine.initialize.started")
+            
+            # 1. Parse current state
+            snapshot = parse(paths)
+            
+            # 2. Persist initial snapshot
+            revision_id = "S-001"
+            snapshot_file = persist_snapshot(snapshot, revision_id, paths)
+            
+            # 3. Initialize state.yaml
+            self.state_manager.initialize(paths)
+            
+            logger.info("engine.initialize.complete", revision=revision_id)
+            return InitializationResult(
+                success=True,
+                structural_revision=revision_id,
+                snapshot_file=snapshot_file,
+                message="Structural Engine initialized successfully.",
+            )
+        except Exception as e:
+            logger.exception("engine.initialize.failed")
+            raise StructuralEngineFailure(f"Failed to initialize Engine: {e}") from e
+
+    def status(self, paths: RepositoryPaths) -> StructuralStatusResult:
+        """Get the current status of the engine.
+
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            Canonical paths.
+
+        Returns
+        -------
+        StructuralStatusResult
+            Combined structural state and unowned passthrough fields.
+        """
+        try:
+            state = self.state_manager.load(paths)
+            
+            # Read semantic_revision manually for the passthrough
+            yaml = YAML()
+            with open(paths.state_file, "r", encoding="utf-8") as f:
+                raw_data = yaml.load(f)
+            semantic_rev = raw_data.get("semantic_revision", "none")
+            
+            return StructuralStatusResult(
+                initialized=True,
+                structural_revision=state.structural_revision,
+                semantic_revision=semantic_rev,
+                current_snapshot=state.current_snapshot,
+                latest_report=state.latest_report,
+                last_sync=state.last_sync,
+                repository_root=str(paths.repo_root),
+            )
+        except Exception as e:
+            logger.exception("engine.status.failed")
+            raise StructuralEngineFailure(f"Failed to read engine status: {e}") from e
+
+    def sync(self, paths: RepositoryPaths) -> SyncResult:
+        """Synchronize the engine with the current repository filesystem.
+
+        Follows strict persistence ordering:
+        Parse -> Diff -> Persist Snapshot -> Persist Report -> Persist Log -> Update State.
+
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            Canonical paths.
+
+        Returns
+        -------
+        SyncResult
+            Outcome of the sync operation.
+        """
+        try:
+            logger.info("engine.sync.started")
+            
+            # 1. Load previous state
+            state = self.state_manager.load(paths)
+            prev_snapshot = load_snapshot(state.current_snapshot, paths)
+            if prev_snapshot is None:
+                raise StructuralEngineFailure(f"Missing snapshot: {state.current_snapshot}")
+                
+            # 2. Parse current state
+            curr_snapshot = parse(paths)
+            
+            # 3. Compute Diff
+            diff = generate_diff(prev_snapshot, curr_snapshot)
+            
+            # 4. No-Change Shortcut
+            if not diff.has_changes:
+                logger.info("engine.sync.no_changes")
+                return SyncResult(
+                    success=True,
+                    changes_detected=False,
+                    structural_revision=state.structural_revision,
+                    snapshot_file=state.current_snapshot,
+                    report_file=state.latest_report,
+                    affected_components=frozenset(),
+                    message="No structural changes detected.",
+                )
+                
+            # 5. Changes detected — execute strict persistence order
+            next_rev = get_next_revision(state.structural_revision)
+            
+            # 5a. Persist Snapshot
+            snapshot_file = persist_snapshot(curr_snapshot, next_rev, paths)
+            
+            # 5b. Persist Report
+            report_file = generate_report(diff, next_rev, paths)
+            
+            # 5c. Persist Log
+            append_log(next_rev, report_file, "SUCCESS", paths)
+            
+            # 5d. Update State (MUST BE LAST)
+            self.state_manager.update(
+                paths=paths,
+                snapshot_id=snapshot_file,
+                revision_id=next_rev,
+                report_id=report_file,
+            )
+            
+            logger.info("engine.sync.complete", next_revision=next_rev)
+            return SyncResult(
+                success=True,
+                changes_detected=True,
+                structural_revision=next_rev,
+                snapshot_file=snapshot_file,
+                report_file=report_file,
+                affected_components=diff.affected_components,
+                message=f"Sync complete: {next_rev}",
+            )
+            
+        except Exception as e:
+            logger.exception("engine.sync.failed")
+            # Attempt to log failure if possible, but safely
+            try:
+                state = self.state_manager.load(paths)
+                append_log(state.structural_revision, "none", f"FAILED: {e}", paths)
+            except Exception:
+                pass
+            raise StructuralEngineFailure(f"Sync failed: {e}") from e

structural_engine/logs/__init__.py

@@ -0,0 +1 @@
+# Logs subsystem.

structural_engine/logs/generator.py

@@ -0,0 +1,33 @@
+"""Log generator.
+
+Appends structured timestamps and operations to the sync log.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from runtime.repository.models import RepositoryPaths
+
+
+def append(revision_id: str, report_id: str, status: str, paths: RepositoryPaths) -> None:
+    """Append a sync operation entry to the persistent log.
+
+    Parameters
+    ----------
+    revision_id : str
+        The ID of the generated structural revision.
+    report_id : str
+        The filename of the generated report, or ``none``.
+    status : str
+        The outcome of the sync (e.g. ``SUCCESS``, ``NO_CHANGES``).
+    paths : RepositoryPaths
+        Canonical paths; appends to ``paths.logs_dir / sync.md``.
+    """
+    log_file = paths.logs_dir / "sync.md"
+    timestamp = datetime.now(timezone.utc).isoformat()
+
+    entry = f"- **{timestamp}** | Revision: `{revision_id}` | Report: `{report_id}` | Status: `{status}`\n"
+
+    with open(log_file, "a", encoding="utf-8") as f:
+        f.write(entry)

structural_engine/parser/__init__.py

@@ -0,0 +1,7 @@
+# Parser subsystem — internal to the Structural Engine.
+# Observes current repository structure and produces a StructuralSnapshot.
+# Stateless, side-effect free, deterministic.
+
+from structural_engine.parser.parser import parse
+
+__all__ = ["parse"]

structural_engine/parser/discovery.py

@@ -0,0 +1,165 @@
+"""File discovery and language detection.
+
+Recursively walks the repository starting from ``repo_root``, discovers
+source files in supported languages, and filters out ignored directories.
+
+This module is stateless and side-effect free.  It performs no writes,
+no persistence, and no Brain-awareness.
+
+Ignored Directories
+-------------------
+::
+
+    .git, .knowcode, node_modules, dist, build, target, venv,
+    .venv, __pycache__, .mypy_cache, .pytest_cache, .tox,
+    .eggs, .idea, .vscode, .vs
+
+Supported Extensions
+--------------------
+::
+
+    .py   → PYTHON
+    .ts   → TYPESCRIPT
+    .tsx  → TYPESCRIPT
+    .js   → JAVASCRIPT
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from structural_engine.parser.models import (
+    EXTENSION_LANGUAGE_MAP,
+    FileInfo,
+    Language,
+)
+
+# Directories to skip during recursive walk.
+# This set is intentionally broad to avoid traversing large vendored
+# or generated trees that have no structural relevance.
+IGNORED_DIRECTORIES: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".knowcode",
+        ".agent",
+        "node_modules",
+        "dist",
+        "build",
+        "target",
+        "venv",
+        ".venv",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".tox",
+        ".eggs",
+        ".idea",
+        ".vscode",
+        ".vs",
+    }
+)
+
+
+def discover_files(repo_root: Path) -> list[FileInfo]:
+    """Walk the repository and discover all supported source files.
+
+    Parameters
+    ----------
+    repo_root : Path
+        Absolute path to the repository root.
+
+    Returns
+    -------
+    list[FileInfo]
+        Discovered files sorted by ``relative_path`` for determinism.
+        Files in ignored directories are excluded.
+        Files with unsupported extensions are excluded.
+    """
+    discovered: list[FileInfo] = []
+
+    for item in _walk_filtered(repo_root):
+        if not item.is_file():
+            continue
+
+        language = detect_language(item)
+        if language is None:
+            continue
+
+        # Relative path always uses forward slashes for cross-platform
+        # determinism (entity IDs depend on this).
+        relative = item.relative_to(repo_root).as_posix()
+
+        discovered.append(
+            FileInfo(
+                absolute_path=item,
+                relative_path=relative,
+                language=language,
+            )
+        )
+
+    # Sort for deterministic output — entity ID generation depends on
+    # a stable file ordering.
+    discovered.sort(key=lambda f: f.relative_path)
+    return discovered
+
+
+def detect_language(file_path: Path) -> Language | None:
+    """Detect the programming language of a file by extension.
+
+    Parameters
+    ----------
+    file_path : Path
+        Path to the source file.
+
+    Returns
+    -------
+    Language | None
+        The detected language, or *None* if the extension is not
+        supported.
+    """
+    return EXTENSION_LANGUAGE_MAP.get(file_path.suffix.lower())
+
+
+def _walk_filtered(root: Path) -> list[Path]:
+    """Recursively collect all file paths, skipping ignored directories.
+
+    Uses ``Path.iterdir()`` + manual recursion instead of ``os.walk()``
+    to have fine-grained control over directory filtering before descent.
+
+    Parameters
+    ----------
+    root : Path
+        Directory to walk.
+
+    Returns
+    -------
+    list[Path]
+        All non-ignored file paths under *root*.
+    """
+    results: list[Path] = []
+    _walk_recursive(root, results)
+    return results
+
+
+def _walk_recursive(directory: Path, accumulator: list[Path]) -> None:
+    """Internal recursive walker.
+
+    Parameters
+    ----------
+    directory : Path
+        Current directory being walked.
+    accumulator : list[Path]
+        Mutable list collecting discovered file paths.
+    """
+    try:
+        entries = sorted(directory.iterdir(), key=lambda p: p.name)
+    except PermissionError:
+        # Skip directories we can't read.
+        return
+
+    for entry in entries:
+        if entry.is_dir():
+            if entry.name not in IGNORED_DIRECTORIES:
+                _walk_recursive(entry, accumulator)
+        elif entry.is_file():
+            accumulator.append(entry)

structural_engine/parser/extractors/base.py

@@ -0,0 +1,44 @@
+"""Base extraction architecture.
+
+Defines the interface for language-specific adapters that extract
+entities, relationships, and raw calls from tree-sitter ASTs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import tree_sitter
+
+from structural_engine.parser.models import Entity, FileInfo, RawCall, Relationship
+
+@dataclass
+class ExtractionResult:
+    """Accumulates structural information extracted from a single file."""
+
+    entities: list[Entity] = field(default_factory=list)
+    relationships: list[Relationship] = field(default_factory=list)
+    raw_calls: list[RawCall] = field(default_factory=list)
+
+class LanguageAdapter(Protocol):
+    """Protocol for language-specific tree-sitter AST extractors."""
+
+    def extract(self, file_info: FileInfo, tree: tree_sitter.Tree, source_bytes: bytes) -> ExtractionResult:
+        """Extract structural facts from a parsed AST.
+
+        Parameters
+        ----------
+        file_info : FileInfo
+            Information about the source file being parsed.
+        tree : tree_sitter.Tree
+            The tree-sitter syntax tree.
+        source_bytes : bytes
+            The raw bytes of the source file.
+
+        Returns
+        -------
+        ExtractionResult
+            The extracted entities, relationships, and unresolved calls.
+        """
+        ...

structural_engine/parser/languages/javascript/adapter.py

@@ -0,0 +1,149 @@
+"""JavaScript structural extractor.
+
+Walks a JavaScript tree-sitter AST to extract entities, relationships,
+and raw calls.
+"""
+
+from __future__ import annotations
+
+import tree_sitter
+
+from structural_engine.parser.extractors.base import ExtractionResult, LanguageAdapter
+from structural_engine.parser.models import (
+    Entity,
+    EntityType,
+    FileInfo,
+    RawCall,
+    Relationship,
+    RelationshipType,
+)
+
+
+class JavaScriptAdapter(LanguageAdapter):
+    """AST extractor for JavaScript."""
+
+    def extract(
+        self, file_info: FileInfo, tree: tree_sitter.Tree, source_bytes: bytes
+    ) -> ExtractionResult:
+        result = ExtractionResult()
+
+        file_id = file_info.relative_path
+        parent_dir = file_info.relative_path.rsplit("/", 1)[0] if "/" in file_info.relative_path else "repo"
+        file_entity = Entity(
+            id=file_id,
+            type=EntityType.FILE,
+            name=file_info.absolute_path.name,
+            path=file_info.relative_path,
+            parent_id=parent_dir,
+            start_line=1,
+            end_line=source_bytes.count(b"\n") + 1,
+        )
+        result.entities.append(file_entity)
+
+        def walk(node: tree_sitter.Node, current_parent_id: str, is_in_class: bool = False):
+            # Extract Imports
+            if node.type == "import_statement":
+                source_node = node.child_by_field_name("source")
+                if source_node:
+                    imported_module = source_node.text.decode("utf-8").strip("'\"")
+                    result.relationships.append(
+                        Relationship(
+                            source_id=file_id,
+                            target_id=imported_module,
+                            type=RelationshipType.IMPORTS,
+                        )
+                    )
+
+            # Extract Classes
+            elif node.type == "class_declaration":
+                name_node = node.child_by_field_name("name")
+                if name_node:
+                    name = name_node.text.decode("utf-8")
+                    class_id = f"{current_parent_id}::{name}"
+                    
+                    result.entities.append(
+                        Entity(
+                            id=class_id,
+                            type=EntityType.CLASS,
+                            name=name,
+                            path=file_info.relative_path,
+                            parent_id=current_parent_id,
+                            start_line=node.start_point[0] + 1,
+                            end_line=node.end_point[0] + 1,
+                        )
+                    )
+                    result.relationships.append(
+                        Relationship(
+                            source_id=current_parent_id,
+                            target_id=class_id,
+                            type=RelationshipType.CONTAINS,
+                        )
+                    )
+
+                    heritage = node.child_by_field_name("heritage")
+                    if heritage and heritage.type == "class_heritage":
+                        for child in heritage.children:
+                            if child.type == "identifier":
+                                result.relationships.append(
+                                    Relationship(
+                                        source_id=class_id,
+                                        target_id=child.text.decode("utf-8"),
+                                        type=RelationshipType.INHERITS,
+                                    )
+                                )
+
+                    for child in node.children:
+                        walk(child, class_id, is_in_class=True)
+                return
+
+            # Extract Functions
+            elif node.type in ("function_declaration", "method_definition"):
+                name_node = node.child_by_field_name("name")
+                if name_node:
+                    name = name_node.text.decode("utf-8")
+                    func_id = f"{current_parent_id}::{name}"
+                    func_type = EntityType.METHOD if is_in_class or node.type == "method_definition" else EntityType.FUNCTION
+                    
+                    result.entities.append(
+                        Entity(
+                            id=func_id,
+                            type=func_type,
+                            name=name,
+                            path=file_info.relative_path,
+                            parent_id=current_parent_id,
+                            start_line=node.start_point[0] + 1,
+                            end_line=node.end_point[0] + 1,
+                        )
+                    )
+                    result.relationships.append(
+                        Relationship(
+                            source_id=current_parent_id,
+                            target_id=func_id,
+                            type=RelationshipType.CONTAINS,
+                        )
+                    )
+                    for child in node.children:
+                        walk(child, func_id, is_in_class=False)
+                return
+
+            # Extract Calls
+            elif node.type == "call_expression":
+                func_node = node.child_by_field_name("function")
+                if func_node:
+                    target_name = func_node.text.decode("utf-8")
+                    if "." in target_name:
+                        target_name = target_name.split(".")[-1]
+                    result.raw_calls.append(
+                        RawCall(
+                            caller_id=current_parent_id,
+                            target_name=target_name,
+                            source_file=file_info.relative_path,
+                            line=node.start_point[0] + 1,
+                        )
+                    )
+            
+            for child in node.children:
+                walk(child, current_parent_id, is_in_class)
+
+        walk(tree.root_node, file_id)
+        return result