knowcode 0.1.0__py3-none-any.whl

structural_engine/parser/resolvers/calls.py

@@ -0,0 +1,105 @@
+"""Call resolver.
+
+Transforms RawCalls into CALLS relationships.
+Implements the conservative two-pass resolution strategy.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from structural_engine.parser.models import Entity, EntityType, RawCall, Relationship, RelationshipType
+
+
+def resolve_calls(
+    entities: list[Entity],
+    relationships: list[Relationship],
+    raw_calls: list[RawCall],
+) -> list[Relationship]:
+    """Resolve raw calls into structural CALLS relationships.
+
+    Uses a conservative strategy. If a call target cannot be uniquely
+    resolved, it is dropped. Missing edges are allowed; incorrect edges
+    are forbidden.
+
+    Parameters
+    ----------
+    entities : list[Entity]
+        All extracted entities.
+    relationships : list[Relationship]
+        Existing extracted relationships (like IMPORTS, CONTAINS).
+    raw_calls : list[RawCall]
+        Unresolved call extractions.
+
+    Returns
+    -------
+    list[Relationship]
+        A list of new Relationship objects of type CALLS.
+    """
+    resolved_calls: list[Relationship] = []
+
+    # Build a global map of function/method names to their full entity IDs.
+    name_to_ids: dict[str, list[str]] = defaultdict(list)
+    for entity in entities:
+        if entity.type in (EntityType.FUNCTION, EntityType.METHOD):
+            name_to_ids[entity.name].append(entity.id)
+
+    # Build an import map: source_file_id -> set of target_modules
+    # For Pass 1 (Import Guided) we'd use this.
+    imports: dict[str, set[str]] = defaultdict(set)
+    for rel in relationships:
+        if rel.type == RelationshipType.IMPORTS:
+            imports[rel.source_id].add(rel.target_id)
+
+    for call in raw_calls:
+        candidates = name_to_ids.get(call.target_name, [])
+
+        # Pass 2: Global Unique Match
+        # If there is exactly one function/method in the entire repository
+        # with this name, we resolve it.
+        if len(candidates) == 1:
+            resolved_calls.append(
+                Relationship(
+                    source_id=call.caller_id,
+                    target_id=candidates[0],
+                    type=RelationshipType.CALLS,
+                )
+            )
+            continue
+
+        # Pass 1: Import Guided (simplified for V1)
+        # If there are multiple candidates, we could check if the caller's file
+        # imports the module containing the candidate.
+        # This requires tracking the file containing each candidate.
+        if len(candidates) > 1:
+            caller_file_id = call.source_file
+            caller_imports = imports.get(caller_file_id, set())
+            
+            valid_candidates = []
+            for candidate_id in candidates:
+                # candidate_id format: src/auth.py::verify_token
+                candidate_file_id = candidate_id.split("::")[0]
+                # If it's in the same file, it's a strong candidate
+                if candidate_file_id == caller_file_id:
+                    valid_candidates.append(candidate_id)
+                else:
+                    # Check if caller imports the candidate's module
+                    # For simplicity, we check if the candidate_file_id is a substring
+                    # of any import target.
+                    candidate_module_base = candidate_file_id.replace(".py", "").replace(".ts", "").replace(".js", "")
+                    # e.g. src/auth -> auth
+                    candidate_module_name = candidate_module_base.split("/")[-1]
+                    
+                    if candidate_module_name in caller_imports:
+                        valid_candidates.append(candidate_id)
+
+            if len(valid_candidates) == 1:
+                resolved_calls.append(
+                    Relationship(
+                        source_id=call.caller_id,
+                        target_id=valid_candidates[0],
+                        type=RelationshipType.CALLS,
+                    )
+                )
+
+    return resolved_calls

structural_engine/parser/tree_sitter/registry.py

@@ -0,0 +1,61 @@
+"""Tree-sitter grammar registry.
+
+Loads and caches tree-sitter language grammars.
+"""
+
+from __future__ import annotations
+
+import tree_sitter
+import tree_sitter_python
+import tree_sitter_javascript
+import tree_sitter_typescript
+
+from structural_engine.parser.models import Language
+
+_REGISTRY: dict[Language, tree_sitter.Language] = {}
+
+def get_language(lang: Language) -> tree_sitter.Language:
+    """Get the tree-sitter Language object for a given supported language.
+
+    Parameters
+    ----------
+    lang : Language
+        The language to load.
+
+    Returns
+    -------
+    tree_sitter.Language
+        The compiled tree-sitter language.
+    """
+    if lang in _REGISTRY:
+        return _REGISTRY[lang]
+
+    ts_lang = None
+    if lang == Language.PYTHON:
+        ts_lang = tree_sitter.Language(tree_sitter_python.language())
+    elif lang == Language.JAVASCRIPT:
+        ts_lang = tree_sitter.Language(tree_sitter_javascript.language())
+    elif lang == Language.TYPESCRIPT:
+        ts_lang = tree_sitter.Language(tree_sitter_typescript.language_typescript())
+    else:
+        raise ValueError(f"Unsupported language: {lang}")
+
+    _REGISTRY[lang] = ts_lang
+    return ts_lang
+
+def get_parser(lang: Language) -> tree_sitter.Parser:
+    """Create a new tree-sitter parser for the given language.
+
+    Parameters
+    ----------
+    lang : Language
+        The language to parse.
+
+    Returns
+    -------
+    tree_sitter.Parser
+        A configured parser instance.
+    """
+    ts_lang = get_language(lang)
+    parser = tree_sitter.Parser(ts_lang)
+    return parser

structural_engine/reports/__init__.py

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

structural_engine/reports/generator.py

@@ -0,0 +1,77 @@
+"""Report generator.
+
+Creates human-readable Markdown summaries of structural diffs.
+"""
+
+from __future__ import annotations
+
+from runtime.repository.models import RepositoryPaths
+from structural_engine.diff.models import StructuralDiff
+
+
+def generate(diff: StructuralDiff, revision_id: str, paths: RepositoryPaths) -> str:
+    """Generate and write a human-readable report of the diff.
+
+    Parameters
+    ----------
+    diff : StructuralDiff
+        The computed structural changes.
+    revision_id : str
+        The ID of the new structural revision (e.g. ``S-014``).
+    paths : RepositoryPaths
+        Canonical paths; writes to ``paths.reports_dir``.
+
+    Returns
+    -------
+    str
+        The filename of the created report (e.g. ``R-014.md``), or
+        ``none`` if no report was generated (e.g., no changes).
+    """
+    if not diff.has_changes:
+        return "none"
+
+    report_filename = f"R-{revision_id[2:]}.md"
+    report_path = paths.reports_dir / report_filename
+
+    lines = [
+        f"# Structural Sync Report: {revision_id}",
+        "",
+        "## Affected Components",
+    ]
+
+    for comp in sorted(diff.affected_components):
+        lines.append(f"- `{comp}/`")
+    lines.append("")
+
+    if diff.entities_added:
+        lines.append("## Entities Added")
+        for e in sorted(diff.entities_added, key=lambda x: x.id):
+            lines.append(f"- **{e.type.name}**: `{e.id}`")
+        lines.append("")
+
+    if diff.entities_removed:
+        lines.append("## Entities Removed")
+        for e in sorted(diff.entities_removed, key=lambda x: x.id):
+            lines.append(f"- **{e.type.name}**: `{e.id}`")
+        lines.append("")
+
+    if diff.entities_modified:
+        lines.append("## Entities Modified (Line Shifts / Signature Changes)")
+        for e in sorted(diff.entities_modified, key=lambda x: x.id):
+            lines.append(f"- **{e.type.name}**: `{e.id}` (Lines {e.start_line}-{e.end_line})")
+        lines.append("")
+
+    if diff.relationships_added:
+        lines.append("## Relationships Added")
+        for r in sorted(diff.relationships_added, key=lambda x: (x.source_id, x.target_id)):
+            lines.append(f"- `{r.source_id}` **{r.type.name}** `{r.target_id}`")
+        lines.append("")
+
+    if diff.relationships_removed:
+        lines.append("## Relationships Removed")
+        for r in sorted(diff.relationships_removed, key=lambda x: (x.source_id, x.target_id)):
+            lines.append(f"- `{r.source_id}` **{r.type.name}** `{r.target_id}`")
+        lines.append("")
+
+    report_path.write_text("\n".join(lines), encoding="utf-8")
+    return report_filename

structural_engine/results.py

@@ -0,0 +1,54 @@
+"""Structural Engine result contracts.
+
+These models form the strict return boundary between the Engine and the Runtime.
+The Runtime only imports these results and the ``StructuralEngine`` facade.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class InitializationResult:
+    """Result of a successful KnowCode initialization."""
+
+    success: bool
+    structural_revision: str
+    snapshot_file: str
+    message: str
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    """Result of a sync operation.
+
+    If ``changes_detected`` is False, the other fields reflect the existing
+    unchanged state.
+    """
+
+    success: bool
+    changes_detected: bool
+    structural_revision: str
+    snapshot_file: str
+    report_file: str
+    message: str
+    affected_components: frozenset[str] = field(default_factory=frozenset)
+
+
+@dataclass(frozen=True)
+class StructuralStatusResult:
+    """Current status of the structural state.
+
+    Provides a comprehensive view of the engine's internal state
+    plus unowned passthrough fields (like semantic_revision).
+    """
+
+    initialized: bool
+    structural_revision: str
+    semantic_revision: str
+    current_snapshot: str
+    latest_report: str
+    last_sync: datetime | None
+    repository_root: str

structural_engine/revisions/__init__.py

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

structural_engine/revisions/tracker.py

@@ -0,0 +1,32 @@
+"""Revision tracking logic.
+
+Calculates the next structural revision ID based on the current ID.
+"""
+
+from __future__ import annotations
+
+
+def get_next_revision(current_id: str) -> str:
+    """Calculate the next sequential revision ID.
+
+    Parameters
+    ----------
+    current_id : str
+        The current structural revision ID (e.g. ``S-014``).
+
+    Returns
+    -------
+    str
+        The next sequential ID (e.g. ``S-015``).
+        If the current_id format is invalid, returns ``S-001``.
+    """
+    if not current_id.startswith("S-") or len(current_id) != 5:
+        # Fallback for corrupted state or unparseable initial state
+        return "S-001"
+
+    try:
+        current_num = int(current_id[2:])
+        next_num = current_num + 1
+        return f"S-{next_num:03d}"
+    except ValueError:
+        return "S-001"

structural_engine/snapshot/__init__.py

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

structural_engine/snapshot/generator.py

@@ -0,0 +1,58 @@
+"""Snapshot generator and persister.
+
+Serializes structural snapshots to JSON for deterministic persistence.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+from runtime.repository.models import RepositoryPaths
+from structural_engine.parser.models import StructuralSnapshot
+
+
+def persist(snapshot: StructuralSnapshot, revision_id: str, paths: RepositoryPaths) -> str:
+    """Serialize and write a StructuralSnapshot to disk.
+
+    Parameters
+    ----------
+    snapshot : StructuralSnapshot
+        The structural truth to persist.
+    revision_id : str
+        The ID to use for the snapshot file (e.g. ``S-014``).
+    paths : RepositoryPaths
+        Canonical paths; writes to ``paths.snapshots_dir``.
+
+    Returns
+    -------
+    str
+        The filename of the created snapshot (e.g. ``S-014.json``).
+    """
+    snapshot_filename = f"{revision_id}.json"
+    snapshot_path = paths.snapshots_dir / snapshot_filename
+
+    # We manually handle the enum serialization by transforming the output of asdict.
+    # A cleaner approach in a real app would be a custom JSONEncoder, but this is explicit.
+    
+    entities = []
+    for entity in snapshot.entities:
+        d = asdict(entity)
+        d["type"] = d["type"].name  # Enum to string
+        entities.append(d)
+
+    relationships = []
+    for rel in snapshot.relationships:
+        d = asdict(rel)
+        d["type"] = d["type"].name  # Enum to string
+        relationships.append(d)
+
+    data = {
+        "entities": entities,
+        "relationships": relationships,
+    }
+
+    with open(snapshot_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+    return snapshot_filename

structural_engine/snapshot/loader.py

@@ -0,0 +1,59 @@
+"""Snapshot loader.
+
+Deserializes JSON snapshots back into frozen model tuples.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from runtime.repository.models import RepositoryPaths
+from structural_engine.parser.models import (
+    Entity,
+    EntityType,
+    Relationship,
+    RelationshipType,
+    StructuralSnapshot,
+)
+
+
+def load(snapshot_id: str, paths: RepositoryPaths) -> StructuralSnapshot | None:
+    """Load a StructuralSnapshot from disk.
+
+    Parameters
+    ----------
+    snapshot_id : str
+        The filename or ID of the snapshot (e.g. ``S-014`` or ``S-014.json``).
+    paths : RepositoryPaths
+        Canonical paths; reads from ``paths.snapshots_dir``.
+
+    Returns
+    -------
+    StructuralSnapshot | None
+        The hydrated snapshot tuple, or None if the file doesn't exist.
+    """
+    if not snapshot_id.endswith(".json"):
+        snapshot_id = f"{snapshot_id}.json"
+
+    snapshot_path = paths.snapshots_dir / snapshot_id
+    if not snapshot_path.is_file():
+        return None
+
+    with open(snapshot_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    entities = []
+    for ed in data.get("entities", []):
+        ed["type"] = EntityType[ed["type"]]
+        entities.append(Entity(**ed))
+
+    relationships = []
+    for rd in data.get("relationships", []):
+        rd["type"] = RelationshipType[rd["type"]]
+        relationships.append(Relationship(**rd))
+
+    return StructuralSnapshot(
+        entities=tuple(entities),
+        relationships=tuple(relationships),
+    )

structural_engine/state/__init__.py

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

structural_engine/state/manager.py

@@ -0,0 +1,169 @@
+"""State Manager.
+
+Manages the persistent ``state.yaml`` file, maintaining strict stewardship
+boundaries. Uses a round-trip YAML parser to preserve human comments
+and unowned fields (like ``semantic_revision``).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ruamel.yaml import YAML
+import structlog
+
+from runtime.repository.models import RepositoryPaths
+from structural_engine.state.models import StructuralState
+
+logger = structlog.get_logger(__name__)
+
+
+class StateManager:
+    """Manages read/write operations for state.yaml."""
+
+    def __init__(self) -> None:
+        """Initialize the state manager."""
+        self.yaml = YAML()
+        self.yaml.preserve_quotes = True
+        self.yaml.indent(mapping=2, sequence=4, offset=2)
+
+    def initialize(self, paths: RepositoryPaths) -> None:
+        """Create the initial state.yaml file.
+
+        Writes the default structural fields plus the baseline
+        ``semantic_revision``.
+
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            The canonical path contract.
+        """
+        initial_state = {
+            "structural_revision": "S-001",
+            "current_snapshot": "S-001",
+            "latest_report": "none",
+            "last_sync": datetime.now(timezone.utc).isoformat(),
+            "semantic_revision": "none",
+        }
+
+        with open(paths.state_file, "w", encoding="utf-8") as f:
+            self.yaml.dump(initial_state, f)
+
+        logger.info(
+            "state_manager.initialized",
+            file=str(paths.state_file),
+            structural_revision="S-001",
+        )
+
+    def load(self, paths: RepositoryPaths) -> StructuralState:
+        """Load the structural state from disk.
+
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            The canonical path contract.
+
+        Returns
+        -------
+        StructuralState
+            The strictly typed state subset owned by the Engine.
+        """
+        with open(paths.state_file, "r", encoding="utf-8") as f:
+            data = self.yaml.load(f)
+
+        state = StructuralState(
+            structural_revision=data["structural_revision"],
+            current_snapshot=data["current_snapshot"],
+            latest_report=data["latest_report"],
+            last_sync=datetime.fromisoformat(data["last_sync"]),
+        )
+
+        logger.debug(
+            "state_manager.loaded",
+            revision=state.structural_revision,
+        )
+        return state
+
+    def update(
+        self,
+        paths: RepositoryPaths,
+        snapshot_id: str,
+        revision_id: str,
+        report_id: str,
+    ) -> None:
+        """Update the structural state fields while preserving everything else.
+
+        Performs a safe read-modify-write cycle. The ``semantic_revision``
+        field and any human comments are explicitly preserved.
+
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            The canonical path contract.
+        snapshot_id : str
+            The filename of the new snapshot.
+        revision_id : str
+            The new structural revision ID.
+        report_id : str
+            The filename of the new sync report.
+        """
+        # 1. Read existing
+        with open(paths.state_file, "r", encoding="utf-8") as f:
+            data = self.yaml.load(f)
+
+        # 2. Modify only our fields
+        data["structural_revision"] = revision_id
+        data["current_snapshot"] = snapshot_id
+        data["latest_report"] = report_id
+        data["last_sync"] = datetime.now(timezone.utc).isoformat()
+
+        # 3. Write back
+        with open(paths.state_file, "w", encoding="utf-8") as f:
+            self.yaml.dump(data, f)
+
+        logger.info(
+            "state_manager.updated",
+            file=str(paths.state_file),
+            revision=revision_id,
+        )
+
+    def increment_semantic_revision(self, paths: RepositoryPaths) -> str:
+        """Safely increment the semantic_revision field.
+        
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            The canonical path contract.
+            
+        Returns
+        -------
+        str
+            The new semantic revision ID.
+        """
+        with open(paths.state_file, "r", encoding="utf-8") as f:
+            data = self.yaml.load(f)
+            
+        current = data.get("semantic_revision", "none")
+        if current == "none":
+            new_rev = "M-001"
+        else:
+            try:
+                # e.g. "M-016" -> "M-017"
+                prefix, num_str = current.split("-")
+                new_num = int(num_str) + 1
+                new_rev = f"{prefix}-{new_num:03d}"
+            except ValueError:
+                # Fallback if corrupted
+                new_rev = "M-001"
+                
+        data["semantic_revision"] = new_rev
+        
+        with open(paths.state_file, "w", encoding="utf-8") as f:
+            self.yaml.dump(data, f)
+            
+        logger.info(
+            "state_manager.semantic_bumped",
+            file=str(paths.state_file),
+            semantic_revision=new_rev,
+        )
+        return new_rev

structural_engine/state/models.py

@@ -0,0 +1,34 @@
+"""State domain models.
+
+Defines the Structural Engine's partial view of ``state.yaml``.
+The Engine only cares about the fields it manages.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class StructuralState(BaseModel):
+    """The Structural Engine's typed view of state.yaml.
+
+    This model represents the strict, 4-field stewardship boundary.
+    It does not contain ``semantic_revision``, which is owned by
+    humans/AI agents.
+    """
+
+    structural_revision: str
+    """The latest structural revision ID (e.g. ``S-015``)."""
+
+    current_snapshot: str
+    """The filename of the current snapshot (e.g. ``S-015`` or ``S-015.json``)."""
+
+    latest_report: str
+    """The filename of the latest sync report (e.g. ``R-015.md``) or ``none``."""
+
+    last_sync: datetime = Field(default_factory=datetime.utcnow)
+    """Timestamp of the last structural synchronization."""
+
+    model_config = ConfigDict(frozen=True)