domain-context-graph 0.4.0__py3-none-any.whl

dcg/__init__.py

@@ -0,0 +1,41 @@
+"""DCG — Domain Context Graph."""
+
+from dcg.core import (
+    entity_uid,
+    relation_uid,
+    Entity,
+    Relation,
+    SCHEMA_VERSION,
+    TYPE_REGISTRY,
+    PROPERTY_REGISTRY,
+    register_global_type,
+    register_property,
+    register_alias,
+    resolve_property,
+    GraphStore,
+    GraphStoreProtocol,
+    StackLoader,
+    DomainProject,
+    purge_retracted,
+    builders,
+)
+
+__all__ = [
+    "entity_uid",
+    "relation_uid",
+    "Entity",
+    "Relation",
+    "SCHEMA_VERSION",
+    "TYPE_REGISTRY",
+    "PROPERTY_REGISTRY",
+    "register_global_type",
+    "register_property",
+    "register_alias",
+    "resolve_property",
+    "GraphStore",
+    "GraphStoreProtocol",
+    "StackLoader",
+    "DomainProject",
+    "purge_retracted",
+    "builders",
+]

dcg/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""DCG adapters — pluggable backends for loading layers from external sources."""
+from .base import AdapterProxy, LayerAdapterProtocol
+from .graphify import GraphifyAdapter
+from .registry import register
+
+register("graphify", GraphifyAdapter)
+
+__all__ = ["AdapterProxy", "GraphifyAdapter", "LayerAdapterProtocol"]

dcg/adapters/base.py

@@ -0,0 +1,156 @@
+"""Layer adapter protocol and enrichment proxy."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from dcg.core.model import SCHEMA_VERSION
+from dcg.core.store import GraphStore
+
+
+@runtime_checkable
+class LayerAdapterProtocol(Protocol):
+    """Reads an external source and populates a GraphStore."""
+
+    def load(self, source: Path, store: GraphStore, config: dict) -> None: ...
+
+    def source_exists(self, source: Path) -> bool: ...
+
+
+def _hash(obj: dict) -> str:
+    return hashlib.md5(json.dumps(obj, sort_keys=True, default=str).encode()).hexdigest()
+
+
+def _get_source_anchor(entity: dict) -> str | None:
+    for attr in entity.get("attributes", []):
+        if attr.get("property") == "source_anchor":
+            return attr.get("string")
+    return None
+
+
+class AdapterProxy:
+    """Wraps a LayerAdapter with a DCG-native enrichment overlay.
+
+    Phase 1: adapter.load() populates store from external source.
+    Phase 2: overlay applies enrichments (patched entities, new relations).
+    On save: only the delta vs baseline is written to the overlay file.
+    """
+
+    OVERLAY_DIR = ".dcg"
+    OVERLAY_FILE = "overlay.json"
+
+    def __init__(self, adapter: LayerAdapterProtocol) -> None:
+        self._adapter = adapter
+        self._baseline_entities: dict[str, str] = {}
+        self._baseline_relations: dict[str, str] = {}
+        self._anchor_index: dict[str, str] = {}
+
+    def load(self, source: Path, store: GraphStore, config: dict) -> None:
+        self._adapter.load(source, store, config)
+
+        self._snapshot_baseline(store)
+
+        overlay_path = source / self.OVERLAY_DIR / self.OVERLAY_FILE
+        if overlay_path.exists():
+            self._apply_overlay(store, overlay_path)
+            self._snapshot_baseline(store)
+
+    def _snapshot_baseline(self, store: GraphStore) -> None:
+        self._baseline_entities = {
+            uid: _hash(ent) for uid, ent in store._entities.items()
+        }
+        self._baseline_relations = {
+            uid: _hash(rel) for uid, rel in store._relations.items()
+        }
+        self._anchor_index = {}
+        for uid, ent in store._entities.items():
+            anchor = _get_source_anchor(ent)
+            if anchor:
+                self._anchor_index[anchor] = uid
+
+    def save_enrichments(self, source: Path, store: GraphStore) -> Path:
+        """Write only the delta (enrichments) to the overlay file."""
+        overlay_path = source / self.OVERLAY_DIR / self.OVERLAY_FILE
+
+        enriched_entities: dict[str, dict] = {}
+        for uid, ent in store._entities.items():
+            if uid not in self._baseline_entities:
+                enriched_entities[uid] = ent
+            elif _hash(ent) != self._baseline_entities[uid]:
+                enriched_entities[uid] = ent
+
+        enriched_relations: dict[str, dict] = {}
+        for uid, rel in store._relations.items():
+            if uid not in self._baseline_relations:
+                enriched_relations[uid] = rel
+
+        overlay = {
+            "schema_version": SCHEMA_VERSION,
+            "entities": enriched_entities,
+            "relations": enriched_relations,
+        }
+        overlay_path.parent.mkdir(parents=True, exist_ok=True)
+        overlay_path.write_text(json.dumps(overlay, indent=2, default=str))
+        return overlay_path
+
+    def has_enrichments(self, store: GraphStore) -> bool:
+        """Return True if the store has changes beyond the adapter baseline."""
+        for uid, ent in store._entities.items():
+            if uid not in self._baseline_entities:
+                return True
+            if _hash(ent) != self._baseline_entities[uid]:
+                return True
+        for uid in store._relations:
+            if uid not in self._baseline_relations:
+                return True
+        return False
+
+    @staticmethod
+    def _validate_overlay(data: dict, path: Path) -> None:
+        """Validate overlay JSON has expected structure."""
+        if not isinstance(data, dict):
+            raise ValueError(f"Overlay at {path} must be a JSON object")
+        if "schema_version" not in data:
+            raise ValueError(f"Overlay at {path} missing 'schema_version'")
+        for key in ("entities", "relations"):
+            section = data.get(key)
+            if section is not None and not isinstance(section, dict):
+                raise ValueError(
+                    f"Overlay at {path}: '{key}' must be an object mapping UIDs to dicts"
+                )
+
+    def _apply_overlay(self, store: GraphStore, path: Path) -> None:
+        """Apply overlay with two-phase entity matching (R-023 ADAPT).
+
+        Phase 1: UID match — overlay entity UID exists in baseline → replace.
+        Phase 2: Source anchor fallback — overlay UID not in baseline, but
+                 source_anchor matches a baseline entity → replace + rewrite UID.
+        No match: insert as new entity.
+        """
+        data = json.loads(path.read_text())
+        self._validate_overlay(data, path)
+        uid_rewrites: dict[str, str] = {}
+
+        for overlay_uid, ent in data.get("entities", {}).items():
+            if overlay_uid in store._entities:
+                store.add_entity(ent)
+            else:
+                anchor = _get_source_anchor(ent)
+                if anchor and anchor in self._anchor_index:
+                    baseline_uid = self._anchor_index[anchor]
+                    ent["id"] = baseline_uid
+                    store.add_entity(ent)
+                    uid_rewrites[overlay_uid] = baseline_uid
+                else:
+                    store.add_entity(ent)
+
+        for uid, rel in data.get("relations", {}).items():
+            source = rel.get("source", "")
+            target = rel.get("target", "")
+            source = uid_rewrites.get(source, source)
+            target = uid_rewrites.get(target, target)
+            prop = rel.get("property", "")
+            qualifiers = rel.get("qualifiers")
+            store.add_relation(source, target, prop, qualifiers)

dcg/adapters/graphify.py

@@ -0,0 +1,233 @@
+"""Graphify adapter — reads graphify-out/graph.json into a DCG GraphStore."""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+
+from dcg.core import builders as kb
+from dcg.core.store import GraphStore
+from dcg.core.uid import entity_uid, relation_uid
+
+_log = logging.getLogger(__name__)
+
+GRAPH_FILE = "graph.json"
+
+_DEFAULT_TYPE_MAP: dict[str, str] = {
+    "class": "Class",
+    "function": "Function",
+    "method": "Function",
+    "module": "Module",
+    "file": "File",
+    "interface": "Interface",
+    "struct": "Struct",
+    "endpoint": "Endpoint",
+    "trait": "Trait",
+    "package": "Module",
+}
+
+_DEFAULT_RELATION_MAP: dict[str, str] = {
+    "calls": "calls",
+    "imports": "imports",
+    "imports_from": "imports",
+    "inherits": "inherits from",
+    "contains": "contains",
+    "defines": "contains",
+    "method": "contains",
+    "uses": "depends on",
+    "depends_on": "depends on",
+    "extends": "inherits from",
+    "re_exports": "imports",
+    "references": "references",
+    "semantically_similar_to": "related to",
+    "rationale_for": "references",
+}
+
+_FILE_EXTENSIONS = frozenset({
+    ".py", ".js", ".ts", ".jsx", ".tsx", ".sh", ".bash", ".go", ".rs",
+    ".java", ".c", ".cpp", ".h", ".hpp", ".cs", ".rb", ".php", ".swift",
+    ".kt", ".scala", ".vue", ".svelte", ".css", ".scss", ".html", ".json",
+    ".yaml", ".yml", ".toml", ".xml", ".sql", ".proto", ".graphql",
+    ".tf", ".hcl", ".r", ".jl", ".lua", ".zig", ".nim", ".ex", ".exs",
+})
+
+_LINE_RE = re.compile(r"L(\d+)")
+
+
+def _parse_line(loc: str) -> int | None:
+    m = _LINE_RE.match(loc or "")
+    return int(m.group(1)) if m else None
+
+
+class GraphifyAdapter:
+    """Reads a Graphify graph.json (NetworkX node_link_data) into a DCG GraphStore."""
+
+    def source_exists(self, source: Path) -> bool:
+        return (source / GRAPH_FILE).is_file()
+
+    @staticmethod
+    def _infer_type(node: dict, type_map: dict[str, str]) -> str:
+        explicit = node.get("type", "")
+        if explicit and explicit.lower() in type_map:
+            return type_map[explicit.lower()]
+
+        kind = (node.get("metadata") or {}).get("kind", "")
+        if kind == "file":
+            return "File"
+        if kind in ("bash_entrypoint", "bash_function"):
+            return "Function"
+        if kind == "code":
+            return "Module"
+
+        label = node.get("label", "")
+        if not label:
+            return "Function"
+
+        if "." in label:
+            suffix = Path(label).suffix.lower()
+            if suffix in _FILE_EXTENSIONS:
+                return "File"
+
+        if label.endswith("()"):
+            return "Function"
+
+        if label.startswith("__") and label.endswith("__"):
+            return "Module"
+
+        if (label[0].isupper()
+                and any(c.islower() for c in label)
+                and "." not in label):
+            return "Class"
+
+        return "Function"
+
+    @staticmethod
+    def _extract_repo_name(graphify_repo: str) -> str:
+        """Extract bare repo name (no org prefix) from a Graphify repo field."""
+        if "/" in graphify_repo:
+            return graphify_repo.rsplit("/", 1)[-1]
+        return graphify_repo
+
+    def load(self, source: Path, store: GraphStore, config: dict) -> None:
+        graph_path = source / GRAPH_FILE
+        if not graph_path.is_file():
+            _log.warning("Graphify graph not found: %s", graph_path)
+            return
+
+        data = json.loads(graph_path.read_text())
+        nodes = data.get("nodes", [])
+        links = data.get("links", [])
+
+        type_map = {**_DEFAULT_TYPE_MAP, **config.get("types", {})}
+        rel_map = {**_DEFAULT_RELATION_MAP, **config.get("relations", {})}
+        code_only = config.get("code_only", False)
+
+        self._bootstrap_ontology(store)
+
+        domain_name = config.get("domain", source.name)
+        domain_uid = entity_uid(name=domain_name)
+        store.add_entity(kb.entity(
+            uid=domain_uid,
+            label=domain_name,
+            description=f"Code entities from {domain_name}",
+            attributes=[
+                kb.attribute("instance of", kb.ref_value("dcg:meta:Domain")),
+            ],
+        ))
+
+        # Pass 1: nodes → entities
+        graphify_id_to_uid: dict[str, str] = {}
+        skipped = 0
+
+        for node in nodes:
+            label = node.get("label", "")
+            if not label:
+                skipped += 1
+                continue
+
+            if code_only and node.get("file_type", "code") != "code":
+                skipped += 1
+                continue
+
+            source_file = node.get("source_file", "")
+            line = _parse_line(node.get("source_location", ""))
+            repo = self._extract_repo_name(node.get("repo", ""))
+
+            identity: dict[str, str | int] = {"name": label}
+            if source_file:
+                identity["path"] = source_file
+            if repo:
+                identity["path"] = f"{repo}/{source_file}" if source_file else repo
+            uid = entity_uid(**identity)
+
+            dcg_type = self._infer_type(node, type_map)
+            type_uid = f"dcg:meta:{dcg_type}"
+
+            graphify_id = node.get("id", "")
+            anchor = graphify_id or label
+            if source_file:
+                anchor = f"{source_file}:{label}"
+
+            attrs = [
+                kb.attribute("instance of", kb.ref_value(type_uid)),
+                kb.attribute("part of", kb.ref_value(domain_uid)),
+                kb.attribute("source_anchor", kb.string_value(anchor)),
+            ]
+            if source_file:
+                attrs.append(kb.attribute("file path", kb.string_value(source_file)))
+            if line is not None:
+                attrs.append(kb.attribute("line number", kb.quantity_value(line)))
+            if repo:
+                attrs.append(kb.attribute("repo", kb.string_value(repo)))
+            if node.get("confidence") is not None:
+                attrs.append(kb.attribute("confidence", kb.string_value(str(node["confidence"]))))
+            if node.get("community") is not None:
+                attrs.append(kb.attribute("community", kb.quantity_value(node["community"])))
+
+            store.add_entity(kb.entity(
+                uid=uid,
+                label=label,
+                description=node.get("description", ""),
+                attributes=attrs,
+            ))
+
+            if graphify_id:
+                graphify_id_to_uid[graphify_id] = uid
+
+        # Pass 2: links → relations
+        rel_added = 0
+        for link in links:
+            src_uid = graphify_id_to_uid.get(link.get("source", ""))
+            tgt_uid = graphify_id_to_uid.get(link.get("target", ""))
+            if not src_uid or not tgt_uid:
+                continue
+
+            graphify_rel = link.get("relation", "related to")
+            dcg_prop = rel_map.get(graphify_rel, "related to")
+
+            store.add_relation(src_uid, tgt_uid, dcg_prop)
+            rel_added += 1
+
+        _log.info(
+            "Graphify: loaded %d entities, %d relations (%d nodes skipped)",
+            len(graphify_id_to_uid), rel_added, skipped,
+        )
+
+    @staticmethod
+    def _bootstrap_ontology(store: GraphStore) -> None:
+        pack_names = {p for p in store.ontology._loaded_packs} if hasattr(store.ontology, '_loaded_packs') else set()
+        if "code" not in pack_names:
+            store.ontology.load_pack("code")
+
+        for prop_name, datatype in [
+            ("source_anchor", "string"),
+            ("confidence", "string"),
+            ("community", "quantity"),
+            ("repo", "string"),
+            ("related to", "ref"),
+            ("depends on", "ref"),
+            ("references", "ref"),
+        ]:
+            if prop_name not in store.ontology.known_properties():
+                store.ontology.register_property(prop_name, datatype=datatype)

dcg/adapters/registry.py

@@ -0,0 +1,18 @@
+"""Adapter registry — maps adapter names to classes."""
+from __future__ import annotations
+
+_ADAPTERS: dict[str, type] = {}
+
+
+def register(name: str, adapter_cls: type) -> None:
+    _ADAPTERS[name] = adapter_cls
+
+
+def get(name: str) -> type:
+    if name not in _ADAPTERS:
+        raise ValueError(f"Unknown adapter '{name}'. Available: {sorted(_ADAPTERS)}")
+    return _ADAPTERS[name]
+
+
+def available() -> list[str]:
+    return sorted(_ADAPTERS)

dcg/cli.py

@@ -0,0 +1,206 @@
+"""DCG — Domain Context Graph CLI."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _cmd_init(args: argparse.Namespace) -> None:
+    from dcg.core.project import DomainProject
+
+    proj = DomainProject(args.path)
+    proj.load()
+    if proj.is_valid():
+        print(json.dumps({"status": "already_initialized", **proj.project_info()}, indent=2))
+        return
+    proj.init(name=args.name, description=args.description or "")
+    print(json.dumps({"status": "initialized", **proj.project_info()}, indent=2))
+
+
+def _cmd_compose(args: argparse.Namespace) -> None:
+    from dcg.core.stack import StackLoader
+
+    stack = StackLoader(args.manifest)
+    stack.load()
+    print(json.dumps(stack.stack_info(), indent=2))
+
+
+def _cmd_purge(args: argparse.Namespace) -> None:
+    from dcg.core.project import DomainProject
+    from dcg.ops.lifecycle import purge
+
+    proj = DomainProject(args.path)
+    proj.load()
+    result = purge(proj)
+    print(json.dumps(result, indent=2))
+
+
+
+def _cmd_export_static(args: argparse.Namespace) -> None:
+    from pathlib import Path
+    from dcg.core.stack import StackLoader
+    from dcg.ops.lifecycle import snapshot
+    from dcg.ops.ontology import list_ontology
+
+    stack = StackLoader(args.manifest)
+    stack.load()
+
+    # Merge ontology from all layers
+    merged_store = stack.project(stack.stack_info()["layers"][0]["name"]).store
+    raw_ont = list_ontology(store=merged_store)
+    ontology = {
+        "types": [
+            {"uid": uid, "label": uid.split(":")[-1], "description": desc}
+            for uid, desc in raw_ont.get("types", {}).items()
+        ],
+        "properties": [
+            {"name": name, **info}
+            for name, info in raw_ont.get("properties", {}).items()
+        ],
+    }
+
+    bundle = {
+        "snapshot": snapshot(merged_store),
+        "stack_info": stack.stack_info(),
+        "ontology": ontology,
+        "entities": stack.query(),
+        "relations": stack.get_relations(),
+    }
+
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(bundle, default=str))
+    print(json.dumps({
+        "status": "exported",
+        "output": str(output),
+        "entities": len(bundle["entities"]),
+        "relations": len(bundle["relations"]),
+    }, indent=2))
+
+
+def _cmd_ui(args: argparse.Namespace) -> None:
+    if not args.path and not args.stack:
+        print("Error: provide a project path or --stack manifest", file=sys.stderr)
+        sys.exit(1)
+    try:
+        from dcg.ui import main as ui_main
+    except ImportError:
+        print("Error: dcg[ui] not installed. Run: pip install domain-context-graph[ui]", file=sys.stderr)
+        sys.exit(1)
+    ui_main(
+        project_path=args.path,
+        stack_path=args.stack,
+        host=args.host,
+        port=args.port,
+    )
+
+
+def _cmd_ingest_mcp(args: argparse.Namespace) -> None:
+    from dcg.mcp.dcg_ingest_mcp import main as ingest_mcp_main
+    ingest_mcp_main()
+
+
+def _cmd_ingest(args: argparse.Namespace) -> None:
+    from dcg.ingest import run_ingest
+
+    report = run_ingest(
+        project_path=args.project,
+        seeds_dir=args.seeds,
+        dry_run=args.dry_run,
+    )
+    if report.errors:
+        sys.exit(1)
+
+
+def _cmd_query(args: argparse.Namespace) -> None:
+    from dcg.core.project import DomainProject
+
+    proj = DomainProject(args.path)
+    proj.load()
+
+    instance_of = None
+    if args.type:
+        instance_of = args.type if args.type.startswith("dcg:") else f"dcg:meta:{args.type}"
+
+    part_of = None
+    if args.domain:
+        from dcg.core import entity_uid
+        part_of = entity_uid(name=args.domain)
+
+    results = proj.store.query(instance_of=instance_of, part_of=part_of)
+    print(json.dumps(results, indent=2, default=str))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="dcg",
+        description="Domain Context Graph — CLI for managing domain graph projects.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    init_p = sub.add_parser("init", help="Create a new domain graph project")
+    init_p.add_argument("name", help="Project name")
+    init_p.add_argument("--path", default=".", help="Project directory (default: current)")
+    init_p.add_argument("--description", help="Project description")
+
+    compose_p = sub.add_parser("compose", help="Validate and inspect a stack manifest")
+    compose_p.add_argument("manifest", help="Path to dcg-stack.yml")
+
+    purge_p = sub.add_parser("purge", help="Remove retracted entities and relations")
+    purge_p.add_argument("path", help="Path to a DCG domain project directory")
+
+    query_p = sub.add_parser("query", help="Query entities in a project")
+    query_p.add_argument("path", help="Path to a DCG domain project directory")
+    query_p.add_argument("--type", help="Filter by entity type (e.g. Function, Domain)")
+    query_p.add_argument("--domain", help="Filter by domain name")
+
+    ingest_p = sub.add_parser("ingest", help="Ingest YAML seed files into a DCG project")
+    ingest_p.add_argument("--project", required=True, help="Path to DCG project directory")
+    ingest_p.add_argument("--seeds", default="seeds", help="Seed directory relative to project")
+    ingest_p.add_argument("--dry-run", action="store_true", help="Validate and report without writing")
+
+    ingest_mcp_p = sub.add_parser("ingest-mcp", help="Launch the DCG ingest (write) MCP server")
+    ingest_mcp_src = ingest_mcp_p.add_mutually_exclusive_group(required=True)
+    ingest_mcp_src.add_argument("--project", help="Path to a DCG domain project directory")
+    ingest_mcp_src.add_argument("--stack", help="Path to a dcg-stack.yml stack manifest")
+    ingest_mcp_p.add_argument("--layer", help="Initial active layer (default: first/topmost)")
+    ingest_mcp_p.add_argument("--no-strict", action="store_true", dest="no_strict",
+                               help="Disable strict ontology validation")
+    ingest_mcp_p.add_argument("--http", action="store_true",
+                               help="Use Streamable HTTP transport instead of stdio")
+    ingest_mcp_p.add_argument("--port", type=int, default=8000,
+                               help="Port for HTTP transport (default: 8000)")
+
+    export_p = sub.add_parser("export-static", help="Export stack as static JSON bundle for offline UI")
+    export_p.add_argument("manifest", help="Path to dcg-stack.yml")
+    export_p.add_argument("--output", default="data.json", help="Output file path (default: data.json)")
+
+    ui_p = sub.add_parser("ui", help="Launch the graph explorer web UI")
+    ui_src = ui_p.add_mutually_exclusive_group()
+    ui_src.add_argument("path", nargs="?", default=None, help="Path to a DCG domain project directory")
+    ui_src.add_argument("--stack", help="Path to a dcg-stack.yml manifest")
+    ui_p.add_argument("--port", type=int, default=8080, help="Port for the web server (default: 8080)")
+    ui_p.add_argument("--host", default="localhost", help="Host for the web server (default: localhost)")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    commands = {
+        "init": _cmd_init,
+        "compose": _cmd_compose,
+        "purge": _cmd_purge,
+        "query": _cmd_query,
+        "ingest": _cmd_ingest,
+        "ingest-mcp": _cmd_ingest_mcp,
+        "export-static": _cmd_export_static,
+        "ui": _cmd_ui,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()