coding-os 0.3.2__py3-none-any.whl

graph_os/tree_sitter_overlay.py

@@ -0,0 +1,235 @@
+"""Tree-sitter overlay.
+
+DEPENDS:  tree-sitter >= 0.22, tree-sitter-python, tree-sitter-typescript,
+          tree-sitter-bash, tree-sitter-yaml (graph_os extra).
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger("graph_os.tree_sitter_overlay")
+
+
+@dataclass(frozen=True)
+class OverlayParse:
+    """Wrapper around a tree-sitter parse result."""
+
+    language_id: str
+    tree: Any
+    root: Any
+
+
+def is_available() -> bool:
+    """Return True iff the tree-sitter core package is importable."""
+    try:
+        import tree_sitter  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+@functools.lru_cache(maxsize=32)
+def _load_language(language_id: str) -> Any | None:
+    """Return a `tree_sitter.Language` for `language_id`, or None on miss.
+
+    Language ids match the tree-sitter ecosystem (`python`, `typescript`,
+    `tsx`, `bash`, `yaml`). Unknown ids return None so callers degrade.
+    """
+    if not is_available():
+        return None
+    try:
+        from tree_sitter import Language
+    except ImportError as exc:
+        logger.debug("tree-sitter core missing: %s", exc)
+        return None
+    loader: Callable[[], Any] | None = _LOADERS.get(language_id)
+    if loader is None:
+        return None
+    try:
+        raw = loader()
+    except ImportError as exc:
+        logger.debug("grammar %s not installed: %s", language_id, exc)
+        return None
+    except Exception as exc:
+        logger.debug("grammar %s failed to load: %s", language_id, exc)
+        return None
+    try:
+        return Language(raw)
+    except Exception as exc:
+        logger.debug("Language wrap failed for %s: %s", language_id, exc)
+        return None
+
+
+def _load_python() -> Any:
+    import tree_sitter_python as m
+
+    return m.language()
+
+
+def _load_typescript() -> Any:
+    import tree_sitter_typescript as m
+
+    return m.language_typescript()
+
+
+def _load_tsx() -> Any:
+    import tree_sitter_typescript as m
+
+    return m.language_tsx()
+
+
+def _load_bash() -> Any:
+    import tree_sitter_bash as m
+
+    return m.language()
+
+
+def _load_yaml() -> Any:
+    import tree_sitter_yaml as m
+
+    return m.language()
+
+
+def _load_go() -> Any:
+    import tree_sitter_go as m
+
+    return m.language()
+
+
+# Polyglot baseline grammars (code_generic). Each is optional: a missing
+# package makes _load_language return None and the generic extractor degrades
+# to a file-node-only result with a dep_missing parse error.
+def _load_rust() -> Any:
+    import tree_sitter_rust as m
+
+    return m.language()
+
+
+def _load_ruby() -> Any:
+    import tree_sitter_ruby as m
+
+    return m.language()
+
+
+def _load_java() -> Any:
+    import tree_sitter_java as m
+
+    return m.language()
+
+
+def _load_c() -> Any:
+    import tree_sitter_c as m
+
+    return m.language()
+
+
+def _load_cpp() -> Any:
+    import tree_sitter_cpp as m
+
+    return m.language()
+
+
+def _load_c_sharp() -> Any:
+    import tree_sitter_c_sharp as m
+
+    return m.language()
+
+
+def _load_scala() -> Any:
+    import tree_sitter_scala as m
+
+    return m.language()
+
+
+def _load_kotlin() -> Any:
+    import tree_sitter_kotlin as m
+
+    return m.language()
+
+
+def _load_lua() -> Any:
+    import tree_sitter_lua as m
+
+    return m.language()
+
+
+_LOADERS: dict[str, Callable[[], Any]] = {
+    "python": _load_python,
+    "typescript": _load_typescript,
+    "tsx": _load_tsx,
+    "bash": _load_bash,
+    "yaml": _load_yaml,
+    "go": _load_go,
+    "rust": _load_rust,
+    "ruby": _load_ruby,
+    "java": _load_java,
+    "c": _load_c,
+    "cpp": _load_cpp,
+    "c_sharp": _load_c_sharp,
+    "scala": _load_scala,
+    "kotlin": _load_kotlin,
+    "lua": _load_lua,
+}
+
+
+def parse(language_id: str, content: str) -> OverlayParse | None:
+    """Parse `content` under `language_id`. Returns None when unavailable."""
+    language = _load_language(language_id)
+    if language is None:
+        return None
+    try:
+        from tree_sitter import Parser
+    except ImportError:
+        return None
+    try:
+        parser = Parser(language)
+    except TypeError:
+        # Older tree-sitter (<0.22) used `Parser().set_language(...)`.
+        try:
+            parser = Parser()
+            parser.set_language(language)
+        except Exception as exc:
+            logger.debug("parser init failed for %s: %s", language_id, exc)
+            return None
+    try:
+        tree = parser.parse(content.encode("utf-8"))
+    except Exception as exc:
+        logger.debug("parse failed for %s: %s", language_id, exc)
+        return None
+    return OverlayParse(language_id=language_id, tree=tree, root=tree.root_node)
+
+
+def iter_nodes(root: Any, kinds: set[str]):
+    """Pre-order iterator yielding nodes whose `type` is in `kinds`."""
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        if node.type in kinds:
+            yield node
+        # Reverse so traversal order matches source order after pop.
+        stack.extend(reversed(list(node.children)))
+
+
+def node_text(node: Any, content: bytes) -> str:
+    """Return the source text covered by `node`."""
+    try:
+        start = node.start_byte
+        end = node.end_byte
+        return content[start:end].decode("utf-8", errors="replace")
+    except Exception:
+        return ""
+
+
+__all__ = [
+    "OverlayParse",
+    "is_available",
+    "iter_nodes",
+    "node_text",
+    "parse",
+]

graph_os/types.py

@@ -0,0 +1,252 @@
+"""graph_os — typed records exchanged between extractors and backends.
+
+DEPENDS:  stdlib only.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from types import MappingProxyType
+from typing import Any
+
+
+class NodeKind(str, Enum):
+    """Canonical node kinds for the graph_os tree / spine (S3).
+
+    DEPENDS:  stdlib Enum.
+    """
+
+    FOLDER = "folder"
+    FILE = "file"
+    MODULE = "module"
+    CLASS = "class"
+    METHOD = "method"
+    FUNCTION = "function"
+    VARIABLE = "variable"
+    INTERFACE = "interface"
+    IMPORT_ = "import_"
+    ROUTE = "route"
+    TOOL = "tool"
+    MCP_TOOL = "mcp_tool"
+    EVENT = "event"
+    TASK = "task"
+    DOC_FILE = "doc_file"
+    DOC_HEADING = "doc_heading"
+    DOC_FRONTMATTER = "doc_frontmatter"
+    DOC_EXTERNAL = "doc_external"
+    RULE = "rule"
+    SKILL = "skill"
+    CONTRACT = "contract"
+    COMMUNITY = "community"
+    HOOK = "hook"
+    IDENTIFIER = "identifier"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_any(cls, value: object) -> NodeKind:
+        """Coerce a legacy / new string to a canonical ``NodeKind``.
+
+        Raises ``ValueError`` for empty / unrecognised inputs. Accepts
+        both legacy colon-prefixed strings (``"code:function"``,
+        ``"doc:heading"``, ``"task:file"``, ``"cos:mcp_tool"``, …) and
+        post-S3 short forms (``"function"``, ``"doc_heading"``).
+        """
+        return normalize_kind(value)
+
+
+# Legacy colon-prefixed strings → canonical short form. Every value in
+# the RHS is a valid NodeKind member. Extractors produce legacy forms
+# today; migration v16 rewrites stored rows; ``normalize_kind`` bridges
+# the read path.
+_LEGACY_KIND_MAP: dict[str, str] = {
+    # code:*
+    "code:file": "file",
+    "code:module": "module",
+    "code:class": "class",
+    "code:method": "method",
+    "code:function": "function",
+    "code:variable": "variable",
+    "code:interface": "interface",
+    "code:import": "import_",
+    # Go package-grouping node (one per `package <name>`) — a module-tier
+    # namespace, mapped to `module` so it gets a legend slot and
+    # `normalize_kind` never raises on the stored row (TASK-409).
+    "code:package": "module",
+    # `code:external:*` UIDs are unresolved cross-module references —
+    # builtin types, dynamic attribute accesses, third-party imports
+    # the extractor couldn't pin to a real definition. They're not
+    # "unknown" (which the canvas treats as a true mystery), they're
+    # bonafide identifiers without resolution. Mapping to `identifier`
+    # gets them their own legend slot + colour and lets the noise
+    # filter on the export side hide them when needed.
+    "code:external": "identifier",
+    # doc:*
+    "doc:file": "doc_file",
+    "doc:heading": "doc_heading",
+    "doc:frontmatter_key": "doc_frontmatter",
+    "doc:external": "doc_external",
+    # task:*
+    "task:file": "task",
+    # cos:*
+    "cos:route": "route",
+    "cos:mcp_tool": "mcp_tool",
+    "cos:tool": "tool",
+    "cos:event": "event",
+    "cos:hook": "hook",
+    "cos:skill": "skill",
+    "cos:rule": "rule",
+    "cos:contract": "contract",
+    "cos:identifier": "identifier",
+    "cos:community": "community",
+}
+
+
+def normalize_kind(value: object) -> NodeKind:
+    """Map a stored/extracted kind string to a canonical ``NodeKind``."""
+    if value is None:
+        raise ValueError("kind cannot be None")
+    raw = str(value).strip()
+    if not raw:
+        raise ValueError("kind cannot be empty")
+    lowered = raw.lower()
+    # Direct enum value match (post-S3 emission).
+    try:
+        return NodeKind(lowered)
+    except ValueError:
+        pass
+    # Legacy colon-prefixed forms.
+    if lowered in _LEGACY_KIND_MAP:
+        return NodeKind(_LEGACY_KIND_MAP[lowered])
+    # Common legacy sub-prefix fallbacks — any ``code:foo``/``doc:foo``/
+    # ``cos:foo`` string we don't explicitly map surfaces as UNKNOWN
+    # rather than raising, so a single stray kind doesn't poison a bulk
+    # reindex. Strict callers can still catch and inspect.
+    if ":" in lowered:
+        raise ValueError(f"unknown kind: {raw!r}")
+    raise ValueError(f"unknown kind: {raw!r}")
+
+
+@dataclass(frozen=True)
+class GraphNode:
+    """A single node in the knowledge graph."""
+
+    uid: str
+    kind: str
+    label: str
+    file_path: str | None = None
+    start_line: int | None = None
+    end_line: int | None = None
+    signature: str | None = None
+    lang: str | None = None
+    doc_blob: str | None = None
+    ast_hash: str | None = None
+    content_hash: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # B11: wrap metadata in a read-only view so ``frozen=True`` isn't
+        # silently undermined by callers mutating the backing dict. The
+        # mapping view is read-only; equality/containment still work
+        # exactly like a dict. Accept pre-wrapped values idempotently.
+        md = self.metadata
+        if isinstance(md, MappingProxyType):
+            return
+        backing: dict[str, Any] = dict(md) if md else {}
+        object.__setattr__(self, "metadata", MappingProxyType(backing))
+
+
+@dataclass(frozen=True)
+class EvidenceSignal:
+    """One signal that contributed to an edge's confidence.
+
+    DEPENDS:  GraphEdge references these via EvidenceSignal rows keyed
+              by edge_id (normalized, Section 5.3 of the plan).
+    """
+
+    signal_name: str
+    weight: float
+    note: str | None = None
+
+
+@dataclass(frozen=True)
+class GraphEdge:
+    """A directed relation between two nodes.
+
+    DEPENDS:  GraphNode (via uid references), EvidenceSignal.
+    """
+
+    source_uid: str
+    target_uid: str
+    edge_type: str
+    extractor: str
+    confidence: float = 1.0
+    source_span: str | None = None
+    evidence: tuple[EvidenceSignal, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError(f"edge confidence must lie in [0,1], got {self.confidence!r}")
+
+
+# ---------------------------------------------------------------------------
+# Provenance
+# ---------------------------------------------------------------------------
+#
+# `provenance` is a single-string label for "what kind of parser produced
+# this edge".  It's not stored on disk — it's derived from the existing
+# `extractor` field at read time, so the migration is purely additive
+# and existing rows light up with the correct value the moment a caller
+# asks for it.
+
+
+PROVENANCE_VALUES: tuple[str, ...] = (
+    "tree-sitter",
+    "ast",
+    "regex",
+    "lsp",
+    "text-search",
+    "parser",
+    "unknown",
+)
+
+
+_EXTRACTOR_PROVENANCE: dict[str, str] = {
+    "code_python@v1": "ast",
+    "code_python_ts@v1": "tree-sitter",
+    "code_ts@v1": "regex",
+    "code_ts_ts@v1": "tree-sitter",
+    "code_go@v1": "regex",
+    "code_go@v2": "tree-sitter",
+    "code_go_ts@v1": "tree-sitter",
+    "code_php@v1": "tree-sitter",
+    "code_shell@v1": "regex",
+    "code_shell@v2": "tree-sitter",
+    "code_yaml@v1": "parser",
+    "code_json@v1": "parser",
+    "code_toml@v1": "parser",
+    "code_generic@v1": "tree-sitter",
+    "contracts@v1": "regex",
+    "md_links@v1": "parser",
+    "task_deps@v1": "parser",
+    "groups.cross_repo@v1": "text-search",
+}
+
+
+def provenance_for(extractor: str | None) -> str:
+    """Return the provenance label for an extractor ID."""
+    if not extractor:
+        return "unknown"
+    return _EXTRACTOR_PROVENANCE.get(extractor, "unknown")
+
+
+__all__ = [
+    "PROVENANCE_VALUES",
+    "EvidenceSignal",
+    "GraphEdge",
+    "GraphNode",
+    "NodeKind",
+    "normalize_kind",
+    "provenance_for",
+]