graphcoding 0.1.0__tar.gz → 0.2.0__tar.gz

{graphcoding-0.1.0/src/graphcoding.egg-info → graphcoding-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphcoding
-Version: 0.1.0
+Version: 0.2.0
 Summary: Draw the graph of the system you want — then code until the repo matches. Future files and scheduled deletions are graph data; a drift gate blocks commits until code and declared design converge.
 Author: Mosab Sayyed
 License: MIT
@@ -72,8 +72,6 @@ GraphCoding is that layer, with a gate on it — and only that layer, on purpose
 
 ```bash
 pip install graphcoding        # or: pipx install graphcoding
-# until the first PyPI release lands:
-# pip install git+https://github.com/mosabsayyed/graphcoding
 
 cd your-repo
 graphcoding init --hooks       # scan the repo into a graph + install the gate
@@ -154,6 +152,7 @@ The [playbooks](docs/playbooks.md) give the exact command sequence for each case
 | [Core concepts](docs/core-concepts.md) | nodes, edges, statuses, the graph file format |
 | [The loop](docs/lifecycle.md) | QUERY → DESIGN → CODE → SYNC → VERIFY, in depth |
 | [Playbooks](docs/playbooks.md) | every SDLC situation, exact commands |
+| [The whole architecture](docs/whole-system-graph.md) | db schema, settings tables, MCP servers, queues, external APIs as graph nodes |
 | [Migrating an existing repo](docs/migrating-existing-repos.md) | zero to gated in an afternoon |
 | [Starting a new project](docs/starting-new-projects.md) | graph-first greenfield |
 | [AI agents](docs/agents.md) | Claude Code, Cursor, Copilot, custom harnesses |

{graphcoding-0.1.0 → graphcoding-0.2.0}/README.md

@@ -51,8 +51,6 @@ GraphCoding is that layer, with a gate on it — and only that layer, on purpose
 
 ```bash
 pip install graphcoding        # or: pipx install graphcoding
-# until the first PyPI release lands:
-# pip install git+https://github.com/mosabsayyed/graphcoding
 
 cd your-repo
 graphcoding init --hooks       # scan the repo into a graph + install the gate
@@ -133,6 +131,7 @@ The [playbooks](docs/playbooks.md) give the exact command sequence for each case
 | [Core concepts](docs/core-concepts.md) | nodes, edges, statuses, the graph file format |
 | [The loop](docs/lifecycle.md) | QUERY → DESIGN → CODE → SYNC → VERIFY, in depth |
 | [Playbooks](docs/playbooks.md) | every SDLC situation, exact commands |
+| [The whole architecture](docs/whole-system-graph.md) | db schema, settings tables, MCP servers, queues, external APIs as graph nodes |
 | [Migrating an existing repo](docs/migrating-existing-repos.md) | zero to gated in an afternoon |
 | [Starting a new project](docs/starting-new-projects.md) | graph-first greenfield |
 | [AI agents](docs/agents.md) | Claude Code, Cursor, Copilot, custom harnesses |

{graphcoding-0.1.0 → graphcoding-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphcoding"
-version = "0.1.0"
+version = "0.2.0"
 description = "Draw the graph of the system you want — then code until the repo matches. Future files and scheduled deletions are graph data; a drift gate blocks commits until code and declared design converge."
 readme = "README.md"
 requires-python = ">=3.9"

{graphcoding-0.1.0 → graphcoding-0.2.0}/src/graphcoding/__init__.py

@@ -3,4 +3,4 @@
 Query before you touch code. Design in the graph. Sync as you go.
 Drift is caught by tooling, not memory.
 """
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{graphcoding-0.1.0 → graphcoding-0.2.0}/src/graphcoding/cli.py

@@ -100,7 +100,8 @@ def cmd_scan(args) -> None:
 def cmd_plan(args) -> None:
     root = _root_or_die(args)
     g = Graph.load(root)
-    node = Node(name=args.name, type=args.type, status="planned",
+    status = "ok" if args.existing else "planned"
+    node = Node(name=args.name, type=args.type, status=status,
                 summary=args.summary or "")
     for spec in args.edge or []:
         try:
@@ -116,7 +117,7 @@ def cmd_plan(args) -> None:
         sys.exit(f"{args.name} already exists with status={existing.status}; "
                  "use --force to re-plan it")
     if existing:
-        existing.status = "planned"
+        existing.status = status
         if args.summary:
             existing.summary = args.summary
         for e in node.edges:
@@ -124,7 +125,8 @@ def cmd_plan(args) -> None:
     else:
         g.nodes[node.name] = node
     g.save()
-    print(f"planned: {args.name}" + (f" — {args.summary}" if args.summary else ""))
+    verb = "recorded (existing)" if args.existing else "planned"
+    print(f"{verb}: {args.name}" + (f" — {args.summary}" if args.summary else ""))
 
 
 def cmd_link(args) -> None:
@@ -156,6 +158,13 @@ def cmd_mark_delete(args) -> None:
             print(f"  <-[{t}]- {s}")
         sys.exit("refusing to mark for deletion — update the callers first, "
                  "or pass --force if they are part of the same removal")
+    from .store import is_external
+    if is_external(args.name, load_config(root)):
+        # nothing on disk to remove — the declaration itself is retired
+        g.delete(args.name)
+        g.save()
+        print(f"removed external node: {args.name}")
+        return
     node.status = "to-be-deleted"
     g.save()
     print(f"marked to-be-deleted: {args.name} "
@@ -314,11 +323,15 @@ def build_parser() -> argparse.ArgumentParser:
     s.set_defaults(func=cmd_scan)
 
     s = sub.add_parser("plan", help="declare a node you intend to build (DESIGN)")
-    s.add_argument("name", help="repo-relative path, or path::Symbol")
+    s.add_argument("name", help="repo-relative path, path::Symbol, or an external "
+                                "name like db:orders / api:stripe (see external_prefixes)")
     s.add_argument("--summary", "-s", help="one line: what it will do")
     s.add_argument("--type", "-t", default="CodeFile", choices=NODE_TYPES)
     s.add_argument("--edge", "-e", action="append",
                    help="TYPE:target (repeatable), e.g. -e IMPORTS:src/db.py")
+    s.add_argument("--existing", action="store_true",
+                   help="record something that already exists (status ok) — "
+                        "e.g. a live db table or external API")
     s.add_argument("--force", action="store_true")
     s.set_defaults(func=cmd_plan)
 

{graphcoding-0.1.0 → graphcoding-0.2.0}/src/graphcoding/drift.py

@@ -14,12 +14,13 @@ from __future__ import annotations
 import os
 
 from .scan import tracked_files
-from .store import Graph
+from .store import Graph, is_external
 
 
 def compute_drift(root: str, cfg: dict, graph: Graph) -> dict:
     disk = set(tracked_files(root, cfg))
-    file_nodes = graph.file_nodes()
+    file_nodes = {k: v for k, v in graph.file_nodes().items()
+                  if not is_external(k, cfg)}
     missing = sorted(disk - set(file_nodes))
     ghosts, unbuilt, not_deleted = [], [], []
     for path, node in sorted(file_nodes.items()):

{graphcoding-0.1.0 → graphcoding-0.2.0}/src/graphcoding/scan.py

@@ -235,13 +235,17 @@ def scan_repo(root: str, cfg: dict, graph: Graph) -> dict:
         node, subs = scan_file(root, path, cfg)
         old = graph.nodes.get(path)
         if old:
-            # never clobber intent: keep richer summary and lifecycle statuses
+            # never clobber intent: keep richer summary, lifecycle statuses,
+            # and every hand-recorded edge (scanner owns IMPORTS only)
             if old.summary and not node.summary:
                 node.summary = old.summary
             if len(old.summary) > len(node.summary):
                 node.summary = old.summary
             if old.status == "to-be-deleted":
                 node.status = old.status
+            for e in old.edges:
+                if e["type"] != "IMPORTS":
+                    node.add_edge(e["to"], e["type"])
             updated += 1
         else:
             added += 1

{graphcoding-0.1.0 → graphcoding-0.2.0}/src/graphcoding/store.py

@@ -52,9 +52,22 @@ DEFAULT_CONFIG = {
     ],
     "ignore_tests": True,
     "scan_symbols": False,
+    # nodes whose names start with these prefixes describe architecture that
+    # is not a repo file — drift never expects one on disk:
+    #   db:     database objects (db:orders, db:settings::llm_provider)
+    #   mcp:    MCP servers and their tools (mcp:router::get_blast_radius)
+    #   svc:    deployed services / processes (svc:api-gateway)
+    #   queue:  queues / topics (queue:invoice-events)
+    #   api:    third-party APIs (api:stripe::charges)
+    #   ext:    anything else outside the repo
+    "external_prefixes": ["db:", "mcp:", "svc:", "queue:", "api:", "ext:"],
 }
 
 
+def is_external(name: str, cfg: dict) -> bool:
+    return any(name.startswith(p) for p in cfg.get("external_prefixes", []))
+
+
 @dataclass
 class Node:
     name: str

{graphcoding-0.1.0 → graphcoding-0.2.0}/src/graphcoding/sync.py

@@ -73,8 +73,13 @@ def sync(root: str, cfg: dict, graph: Graph,
         else:
             node, subs = scan_file(root, path, cfg)
             old = graph.nodes.get(path)
-            if old and len(old.summary) > len(node.summary):
-                node.summary = old.summary
+            if old:
+                if len(old.summary) > len(node.summary):
+                    node.summary = old.summary
+                # scanner owns IMPORTS; every hand-recorded edge type survives
+                for e in old.edges:
+                    if e["type"] != "IMPORTS":
+                        node.add_edge(e["to"], e["type"])
             graph.nodes[path] = node
             for s in subs:
                 prev = graph.nodes.get(s.name)

{graphcoding-0.1.0 → graphcoding-0.2.0/src/graphcoding.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphcoding
-Version: 0.1.0
+Version: 0.2.0
 Summary: Draw the graph of the system you want — then code until the repo matches. Future files and scheduled deletions are graph data; a drift gate blocks commits until code and declared design converge.
 Author: Mosab Sayyed
 License: MIT
@@ -72,8 +72,6 @@ GraphCoding is that layer, with a gate on it — and only that layer, on purpose
 
 ```bash
 pip install graphcoding        # or: pipx install graphcoding
-# until the first PyPI release lands:
-# pip install git+https://github.com/mosabsayyed/graphcoding
 
 cd your-repo
 graphcoding init --hooks       # scan the repo into a graph + install the gate
@@ -154,6 +152,7 @@ The [playbooks](docs/playbooks.md) give the exact command sequence for each case
 | [Core concepts](docs/core-concepts.md) | nodes, edges, statuses, the graph file format |
 | [The loop](docs/lifecycle.md) | QUERY → DESIGN → CODE → SYNC → VERIFY, in depth |
 | [Playbooks](docs/playbooks.md) | every SDLC situation, exact commands |
+| [The whole architecture](docs/whole-system-graph.md) | db schema, settings tables, MCP servers, queues, external APIs as graph nodes |
 | [Migrating an existing repo](docs/migrating-existing-repos.md) | zero to gated in an afternoon |
 | [Starting a new project](docs/starting-new-projects.md) | graph-first greenfield |
 | [AI agents](docs/agents.md) | Claude Code, Cursor, Copilot, custom harnesses |

{graphcoding-0.1.0 → graphcoding-0.2.0}/tests/test_e2e.py

@@ -206,6 +206,40 @@ def test_show_discloses_recorded_only(repo, capsys):
     assert "scanner-visible edges only" not in capsys.readouterr().out
 
 
+def test_manual_edges_survive_rescan_and_sync(repo):
+    run(repo, "init")
+    run(repo, "link", "src/app.py", "CALLS", "db:orders")
+    # edit the file -> sync rescans it; the hand-recorded edge must survive
+    with open(os.path.join(repo, "src", "app.py"), "a") as f:
+        f.write("\nX = 1\n")
+    run(repo, "sync", "--files", "src/app.py")
+    g = Graph.load(repo)
+    assert {"to": "db:orders", "type": "CALLS"} in g.nodes["src/app.py"].edges
+    run(repo, "scan")  # full rescan must preserve it too
+    g = Graph.load(repo)
+    assert {"to": "db:orders", "type": "CALLS"} in g.nodes["src/app.py"].edges
+
+
+def test_external_nodes_db_mcp(repo, capsys):
+    run(repo, "init")
+    run(repo, "plan", "db:orders", "--existing", "-t", "ServiceDef",
+        "-s", "Order ledger; written only by app")
+    run(repo, "plan", "mcp:router::search", "--existing", "-t", "ServiceDef",
+        "-s", "Semantic search tool")
+    g = Graph.load(repo)
+    assert g.nodes["db:orders"].status == "ok"
+    run(repo, "drift", expect_exit=0)          # externals are never ghosts
+    run(repo, "link", "src/app.py", "CALLS", "db:orders")
+    capsys.readouterr()
+    run(repo, "show", "db:orders")
+    assert "src/app.py" in capsys.readouterr().out
+    run(repo, "mark-delete", "db:orders", expect_exit=1)   # caller recorded
+    run(repo, "mark-delete", "mcp:router::search", expect_exit=0)
+    g = Graph.load(repo)
+    assert "mcp:router::search" not in g.nodes  # externals retire immediately
+    run(repo, "drift", expect_exit=0)
+
+
 def test_graph_file_is_sorted_and_stable(repo):
     run(repo, "init")
     p = os.path.join(repo, ".graphcoding", "graph.jsonl")