cjm-python-decompose-core 0.0.6__py3-none-any.whl

cjm_python_decompose_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.6"

cjm_python_decompose_core/emit.py

@@ -0,0 +1,336 @@
+"""Project a module BACK out of the graph (graph -> .py) — the canonical emit leg.
+
+The inverse of `extract`: reassemble a module's `.py` source from its ordered top-level
+regions (top-level `CodeSymbol` verbatim bodies + `CodeText` verbatim regions), with
+the SEAMS regenerated canonically. This is the graph→`.py` half of authoring-on-graph
+([[graph-as-source-of-truth-inversion]]): the graph OWNS formatting, so a human never
+hand-edits the export. Mirrors the notebook compositor's `project.py` (graph -> .ipynb).
+
+Operates on `CodeSymbolNode`/`CodeTextNode` objects OR queried graph wire dicts (so emit
+reads the GRAPH as source — the real "graph is a sufficient source" proof). The fidelity
+bar: symbol/region BODIES are byte-exact, only the inter-region seams are canonical
+(2 blank lines around a def/class, 1 between text regions) — semantically equal, not
+necessarily byte-identical to a non-PEP-8 original.
+"""
+
+import ast
+import re
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+from .parse import emit_regions, SourceRegion
+
+_SYMBOL_LABELS = {"CodeSymbol"}
+_TEXT_LABELS = {"CodeText"}
+
+
+def _binding_key(b: Dict[str, Any]) -> Tuple:
+    """A binding's dedup/identity key (one import across symbols that share it)."""
+    return (b.get("kind"), b.get("level", 0), b.get("module", ""),
+            b.get("imported", ""), b.get("alias", ""))
+
+
+def render_binding(b: Dict[str, Any]) -> str:  # One `import ...` / `from ... import ...` line
+    """Render one import-binding descriptor back to its canonical import statement.
+
+    `{kind:import, module:os}` -> `import os`; `{kind:import, module:a.b, alias:c}` ->
+    `import a.b as c`; `{kind:from, level:1, module:util, imported:helper, alias:h}` ->
+    `from .util import helper as h`; `{kind:from, level:1, module:'', imported:sib}` ->
+    `from . import sib`."""
+    if b.get("kind") == "import":
+        line = f"import {b['module']}"
+        if b.get("alias"):
+            line += f" as {b['alias']}"
+        return line
+    src = "." * b.get("level", 0) + (b.get("module") or "")
+    name = b.get("imported", "")
+    line = f"from {src} import {name}"
+    if b.get("alias") and b["alias"] != name:
+        line += f" as {b['alias']}"
+    return line
+
+
+def _from_name(b: Dict[str, Any]) -> str:
+    """The `name` / `name as alias` clause of one `from ... import` binding."""
+    name = b.get("imported", "")
+    return f"{name} as {b['alias']}" if b.get("alias") and b["alias"] != name else name
+
+
+_IMPORT_WRAP_WIDTH = 100  # A from-import line longer than this wraps in aligned parentheses
+
+
+def _import_section(level: int, module: str) -> int:
+    """The isort-style section a binding sorts into: 0 stdlib · 1 third-party · 2 relative."""
+    if level:
+        return 2
+    top = (module or "").split(".")[0]
+    return 0 if top in sys.stdlib_module_names else 1
+
+
+def _render_from_line(level: int, module: str, names: List[str]) -> str:
+    """One merged `from ... import a, b, c` line, parenthesized+aligned when over-width."""
+    head = f"from {'.' * level}{module} import "
+    line = head + ", ".join(names)
+    if len(line) <= _IMPORT_WRAP_WIDTH:
+        return line
+    indent = " " * (len(head) + 1)
+    lines, cur = [], head + "("
+    for i, name in enumerate(names):
+        piece = name + ("," if i < len(names) - 1 else ")")
+        if cur.endswith("("):
+            cur += piece
+        elif len(cur) + 1 + len(piece) <= _IMPORT_WRAP_WIDTH:
+            cur += " " + piece
+        else:
+            lines.append(cur)
+            cur = indent + piece
+    lines.append(cur)
+    return "\n".join(lines)
+
+
+def render_import_block(
+    bindings: List[Dict[str, Any]],  # Import-binding descriptors (per-symbol + module-level, unioned)
+) -> str:  # The canonical import block text ("" when none)
+    """Derive a module's canonical import block from its used import bindings.
+
+    The imports-as-projection emit: the block is GENERATED from the bindings the module's
+    symbols actually use (so an unused import is auto-pruned), deterministically ordered —
+    `from __future__` first, then isort-style SECTIONS separated by a blank line (stdlib,
+    third-party, relative — classified via `sys.stdlib_module_names`), each section's
+    `import` statements before its `from` imports, all sorted by module; same-source `from`
+    imports MERGE onto one line, parenthesized+aligned when over-width. Faithful at the SET
+    level (the round-trip bar is semantic equality of the import set, not byte-identity to
+    a hand-ordered original)."""
+    seen: set = set()
+    uniq: List[Dict[str, Any]] = []
+    for b in bindings:
+        k = _binding_key(b)
+        if k not in seen:
+            seen.add(k)
+            uniq.append(b)
+
+    future: List[str] = []
+    plain_by_section: Dict[int, List[Dict[str, Any]]] = {}
+    from_groups: Dict[Tuple[int, int, str], List[str]] = {}
+    for b in uniq:
+        level, module = b.get("level", 0), b.get("module") or ""
+        if b.get("kind") == "import":
+            plain_by_section.setdefault(_import_section(level, module), []).append(b)
+        elif module == "__future__" and not level:
+            future.append(_from_name(b))
+        else:
+            from_groups.setdefault((_import_section(level, module), level, module),
+                                   []).append(_from_name(b))
+
+    sections: List[List[str]] = []
+    if future:
+        sections.append([f"from __future__ import {', '.join(sorted(set(future)))}"])
+    for sec in (0, 1, 2):
+        lines: List[str] = []
+        for b in sorted(plain_by_section.get(sec, []), key=lambda x: (x.get("module") or "").lower()):
+            lines.append(render_binding(b))
+        for (s, level, module) in sorted((k for k in from_groups if k[0] == sec),
+                                         key=lambda k: (k[1], k[2].lower())):
+            names = sorted(set(from_groups[(s, level, module)]), key=str.lower)
+            lines.append(_render_from_line(level, module, names))
+        if lines:
+            sections.append(lines)
+    return "\n\n".join("\n".join(lines) for lines in sections)
+
+
+def synth_import(local_name: str, import_name: str) -> Dict[str, Any]:
+    """A synthetic `from <import_name> import <local_name>` binding (USES-derived).
+
+    For an INTRA-corpus reference that has no import statement of its own — a symbol that
+    referenced a same-module sibling and then MOVED, so the sibling is now cross-module.
+    Absolute form (the target module's dotted import name); the round-trip bar is semantic."""
+    return {"name": local_name, "kind": "from", "module": import_name,
+            "imported": local_name, "alias": "", "level": 0}
+
+
+def module_used_bindings(
+    symbol_nodes: Any,         # The module's CodeSymbol nodes (objects or wire dicts) — carry per-symbol import_bindings
+    module_node: Any = None,   # The CodeModule node (carries module-level import_bindings) — optional
+    uses_derived: Any = None,  # USES-derived synthetic bindings (intra-corpus imports the frozen bindings can't carry)
+) -> List[Dict[str, Any]]:  # The unioned import bindings this module needs
+    """Union of every contained symbol's import bindings + the module-level ones (+ any
+    USES-derived synthetics for names no binding covers).
+
+    This is the input to `render_import_block`: which imports the module's CURRENT members
+    actually use. The frozen per-symbol bindings carry external + already-cross-module deps;
+    `uses_derived` adds the imports that only become cross-module AFTER a move (a former
+    same-module reference) — together they make the relocate ZERO-RESIDUAL."""
+    def get(node: Any, key: str) -> List[Dict[str, Any]]:
+        if node is None:
+            return []
+        if isinstance(node, dict):
+            return (node.get("properties") or node).get(key, []) or []
+        props = getattr(node, "properties", None)       # graph node object carrying a props dict
+        if isinstance(props, dict):
+            return props.get(key, []) or []
+        return getattr(node, key, []) or []              # plain object with the attr directly
+
+    out: List[Dict[str, Any]] = []
+    if module_node is not None:
+        out.extend(get(module_node, "import_bindings"))
+    for s in symbol_nodes:
+        out.extend(get(s, "import_bindings"))
+    if uses_derived:                                     # add only names no explicit binding covers
+        covered = {b.get("name") for b in out}
+        for b in uses_derived:
+            if b.get("name") not in covered:
+                out.append(b)
+                covered.add(b.get("name"))
+    return out
+
+
+def _region_from_node(
+    node: Any,  # A CodeSymbolNode / CodeTextNode object, or a queried wire dict
+) -> Optional[Tuple[int, SourceRegion]]:  # (order_index, region) or None when the node is not a top-level region
+    """Pull (order_index, verbatim region) from a node — None for non-region nodes.
+
+    A region is a node carrying an `order_index` (top-level symbols + code-text regions);
+    nested symbols (no body, no order_index) and any other node kind return None."""
+    if isinstance(node, dict):
+        label = node.get("label", "")
+        p = node.get("properties", {})
+        order = p.get("order_index")
+        if order is None:
+            return None
+        if label in _SYMBOL_LABELS:
+            return order, SourceRegion(kind="symbol", text=p.get("body", ""),
+                                       start_line=0, end_line=0,
+                                       qualname=p.get("qualname", ""),
+                                       symbol_kind=p.get("symbol_kind", ""))
+        if label in _TEXT_LABELS:
+            return order, SourceRegion(kind="text", text=p.get("text", ""),
+                                       start_line=0, end_line=0,
+                                       region_key=p.get("region_key", ""))
+        return None
+    # Node object: distinguish by the presence of a `body` (symbol) vs `text` (region) attr.
+    order = getattr(node, "order_index", None)
+    if order is None:
+        return None
+    if hasattr(node, "body"):
+        return order, SourceRegion(kind="symbol", text=node.body, start_line=0, end_line=0,
+                                   qualname=getattr(node, "qualname", ""),
+                                   symbol_kind=getattr(node, "symbol_kind", ""))
+    if hasattr(node, "text"):
+        return order, SourceRegion(kind="text", text=node.text, start_line=0, end_line=0,
+                                   region_key=getattr(node, "region_key", ""))
+    return None
+
+
+def regions_from_nodes(
+    nodes: Any,  # CodeSymbol/CodeText nodes (objects or wire dicts) belonging to ONE module
+) -> List[SourceRegion]:  # The module's ordered top-level regions
+    """Collect a module's top-level regions from its nodes, ordered by `order_index`.
+
+    Non-region nodes (nested symbols, the module node itself, anything else) are
+    skipped — only the ordered verbatim regions reassemble the source."""
+    found = [r for r in (_region_from_node(n) for n in nodes) if r is not None]
+    found.sort(key=lambda t: t[0])
+    return [region for _order, region in found]
+
+
+def _label_of(node: Any) -> str:
+    """A node's label ('CodeSymbol' / 'CodeText' / …) from a wire dict or object."""
+    if isinstance(node, dict):
+        return node.get("label", "")
+    return getattr(node, "label", node.__class__.__name__)
+
+
+def _looks_like_docstring(text: str) -> bool:
+    """Whether a text region opens with a string literal (a module docstring)."""
+    return text.lstrip().startswith(('"""', "'''", '"', "'"))
+
+
+_IMPORT_LINE = re.compile(r"\s*(from|import)\s")
+
+
+def _strip_import_lines(text: str) -> str:  # The region text with top-level import statements removed
+    """Drop top-level `import`/`from ... import` statements (paren/backslash continuations
+    included) from a text region, keeping any non-import lines — so a region that mixes
+    imports with a constant keeps the constant while the imports are regenerated.
+
+    AST-located: only lines spanned by a real top-level Import/ImportFrom statement drop —
+    a DOCSTRING line that merely starts with `from ...` survives (the line-regex fallback,
+    for a region that doesn't parse standalone, would eat it), and an import nested in an
+    `if`/`try` is conditional logic, not a derivable binding, so it stays too."""
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return _strip_import_lines_regex(text)
+    drop: set = set()
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            drop.update(range(node.lineno, (node.end_lineno or node.lineno) + 1))
+    return "\n".join(ln for i, ln in enumerate(text.splitlines(), 1) if i not in drop)
+
+
+def _strip_import_lines_regex(text: str) -> str:  # The pre-AST fallback (unparseable region)
+    """Line-regex import stripping — only for a region `ast.parse` rejects."""
+    lines = text.splitlines()
+    out: List[str] = []
+    i = 0
+    while i < len(lines):
+        ln = lines[i]
+        if _IMPORT_LINE.match(ln):
+            depth = ln.count("(") - ln.count(")")
+            cont = ln.rstrip().endswith("\\")
+            i += 1
+            while (depth > 0 or cont) and i < len(lines):
+                depth += lines[i].count("(") - lines[i].count(")")
+                cont = lines[i].rstrip().endswith("\\")
+                i += 1
+            continue
+        out.append(ln)
+        i += 1
+    return "\n".join(out)
+
+
+def emit_module_from_nodes(
+    nodes: Any,  # The module's CodeSymbol (incl. methods, for bindings) + CodeText nodes
+    module_node: Any = None,        # The CodeModule node (module-level import bindings) — for derive_imports
+    derive_imports: bool = False,   # Regenerate the import block from bindings instead of the verbatim region
+    uses_derived: Any = None,       # USES-derived synthetic imports (zero-residual move) — for derive_imports
+) -> str:  # The reconstructed canonical `.py` source
+    """Reassemble a module's canonical `.py` source from its graph nodes (the round-trip).
+
+    With `derive_imports`, the verbatim import region is replaced by the block DERIVED from
+    the module's used import bindings (imports-as-projection): unused imports drop, ordering
+    is canonical, and a moved symbol's imports recompute — at the SEMANTIC fidelity bar
+    (bodies byte-exact, the import set equal/canonical), not byte-identity."""
+    regions = regions_from_nodes(nodes)
+    if not derive_imports:
+        return emit_regions(regions)
+    symbols = [n for n in nodes if _label_of(n) == "CodeSymbol"]
+    block = render_import_block(module_used_bindings(symbols, module_node, uses_derived))
+    rebuilt: List[SourceRegion] = []
+    for r in regions:
+        if r.kind == "text":
+            kept = _strip_import_lines(r.text).strip("\n")
+            if kept.strip():
+                rebuilt.append(SourceRegion(kind="text", text=kept, start_line=0, end_line=0,
+                                            region_key=getattr(r, "region_key", "")))
+        else:
+            rebuilt.append(r)
+    if block:
+        imp = SourceRegion(kind="text", text=block, start_line=0, end_line=0, region_key="imports")
+        pos = 1 if (rebuilt and rebuilt[0].kind == "text"
+                    and _looks_like_docstring(rebuilt[0].text)) else 0
+        rebuilt.insert(pos, imp)
+    return emit_regions(rebuilt)
+
+
+def nodes_for_module(
+    nodes: Any,         # Queried CodeSymbol/CodeText wire dicts (e.g. find_nodes_by_label)
+    module_id: str,     # The CodeModule id to filter to
+) -> List[Any]:  # The region nodes belonging to that module
+    """Filter queried region nodes down to one module (by `module_id` property)."""
+    out = []
+    for n in nodes:
+        p = n.get("properties", {}) if isinstance(n, dict) else {}
+        if p.get("module_id") == module_id:
+            out.append(n)
+    return out

cjm_python_decompose_core/extract.py

@@ -0,0 +1,202 @@
+"""Bind parsed Python onto dev-graph-schema code nodes (the dev-domain binding).
+
+Turns a `ParsedModule` into a `CodeModuleNode` + its `CodeSymbolNode`s, carrying
+file-hash provenance and the LOCAL edges (ABOUT -> the repo Entity; DEFINES
+module->top-level symbol and class->method). The CORPUS-level edges (IMPORTS/CALLS,
+which need the whole decomposed corpus to resolve) are added in `ingest`. This is
+the analogue of `cjm_markdown_decompose_core.extract` for the code source type.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Tuple
+
+from cjm_context_graph_primitives.provenance import SourceRef
+from cjm_dev_graph_schema.nodes import CodeModuleNode, CodeSymbolNode, CodeTextNode
+
+from .parse import parse_module, parse_regions, ParsedModule, SourceRegion
+
+# Directories never decomposed as source (generated / virtualenv / packaging cruft).
+_SKIP_DIRS = {"__pycache__", ".git", ".ipynb_checkpoints", "build", "dist", ".eggs"}
+
+
+@dataclass
+class DecomposedModule:
+    """One module bound to schema nodes: the module + its symbols + local edges.
+
+    `parsed` is retained so the ingest layer can resolve corpus-level IMPORTS/CALLS
+    (which need every module's import-name / every symbol's name to be known).
+    `texts` are the non-def verbatim regions (the round-trip substrate between symbols);
+    the module's CONTAINS edges (in `local_edges`) order all top-level regions for emit."""
+    module: CodeModuleNode               # The CodeModule node
+    symbols: List[CodeSymbolNode]        # All symbols, flattened (every nesting level)
+    local_edges: List[Dict[str, Any]] = field(default_factory=list)  # ABOUT + structural DEFINES + CONTAINS edges
+    parsed: Optional[ParsedModule] = None  # The raw parse (for corpus IMPORTS/CALLS resolution)
+    texts: List[CodeTextNode] = field(default_factory=list)  # Non-def verbatim regions (imports/docstring/constants/__main__)
+
+
+def _text_region_kind(
+    region: SourceRegion,  # A "text" region
+) -> str:  # Coarse flavor for relevance/render ("imports" | "docstring" | "code")
+    """Classify a non-def text region for display (imports / module docstring / code)."""
+    stripped = region.text.lstrip()
+    if stripped.startswith(("import ", "from ")):
+        return "imports"
+    if stripped.startswith(('"""', "'''", '"', "'")):
+        return "docstring"
+    return "code"
+
+
+def module_path_for(
+    path: str,       # The file path
+    repo_root: str,  # The repo root the module path is relative to
+) -> str:  # Repo-relative POSIX module path (e.g. "cjm_dev_graph_schema/nodes.py")
+    """The repo-relative POSIX path used as the module's identity input.
+
+    Falls back to the bare filename when the path is not under `repo_root`."""
+    p = Path(path)
+    try:
+        rel = p.relative_to(repo_root)
+    except ValueError:
+        rel = Path(p.name)
+    return rel.as_posix()
+
+
+def import_name_for(
+    module_path: str,  # Repo-relative module path
+) -> str:  # Dotted import name ("pkg/sub/mod.py" -> "pkg.sub.mod"; "pkg/__init__.py" -> "pkg")
+    """The dotted import name a module is reachable by (drops a trailing `__init__`)."""
+    parts = list(Path(module_path).with_suffix("").parts)
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _build_symbols(
+    module: CodeModuleNode,   # The enclosing module node
+    parsed: ParsedModule,     # Its parse
+    content_hash: str,        # The module file's content hash (symbols share their file's source)
+    path: str,                # The file path (provenance locator)
+) -> Tuple[List[CodeSymbolNode], List[Dict[str, Any]]]:  # (flat symbol nodes, DEFINES edges)
+    """Flatten the parse tree into symbol nodes + structural DEFINES edges.
+
+    DEFINES runs module->top-level symbol and parent-symbol->nested-symbol, so the
+    nesting (class -> its methods) is preserved as edges, not just qualname text."""
+    symbols: List[CodeSymbolNode] = []
+    edges: List[Dict[str, Any]] = []
+
+    def make(ps) -> CodeSymbolNode:
+        node = CodeSymbolNode(
+            module_id=module.id, qualname=ps.qualname, symbol_kind=ps.kind,
+            path=path, content_hash=content_hash, lineno=ps.lineno,
+            docstring=ps.docstring, calls=list(ps.calls), refs=list(ps.refs),
+            import_bindings=list(ps.import_bindings),
+            properties={"decorators": list(ps.decorators)} if ps.decorators else {},
+        )
+        symbols.append(node)
+        children = [make(c) for c in ps.children]
+        if children:
+            edges.extend(node.defines_edges([c.id for c in children]))
+        return node
+
+    top = [make(ps) for ps in parsed.symbols]
+    edges[:0] = module.defines_edges([t.id for t in top])  # module->top DEFINES first
+    return symbols, edges
+
+
+def decompose_text(
+    repo_key: str,                    # The repo's durable conceptual slug (caller-supplied; the federation anchor)
+    module_path: str,                 # Repo-relative module path (identity input)
+    path: str,                        # File path (provenance locator)
+    text: str,                        # The module source text
+    content_hash: Optional[str] = None,  # Precomputed file hash (else hashed over the UTF-8 text)
+    import_name: Optional[str] = None,   # Override the derived dotted import name
+) -> DecomposedModule:  # The decomposed module
+    """Parse + bind in one step from in-memory source text."""
+    ch = content_hash if content_hash is not None else SourceRef.compute_hash(text.encode("utf-8"))
+    parsed = parse_module(text)
+    module = CodeModuleNode(
+        repo_key=repo_key, module_path=module_path, path=path, content_hash=ch,
+        import_name=import_name if import_name is not None else import_name_for(module_path),
+        docstring=parsed.docstring, imports=list(parsed.imports),
+        import_bindings=list(parsed.module_used_bindings),
+    )
+    symbols, defines = _build_symbols(module, parsed, ch, path)
+
+    # Verbatim-region overlay (the authoring / round-trip substrate): attach each
+    # top-level symbol's VERBATIM body + order, mint CodeText nodes for the non-def
+    # regions, and order ALL top-level regions under the module via CONTAINS.
+    top_by_qual = {s.qualname: s for s in symbols if "." not in s.qualname}
+    texts: List[CodeTextNode] = []
+    region_ids: List[str] = []
+    for i, region in enumerate(parse_regions(text)):
+        if region.kind == "symbol":
+            sym = top_by_qual.get(region.qualname)
+            if sym is None:  # defensive: a top-level def with no matching ParsedSymbol (shouldn't happen)
+                continue
+            sym.body = region.text
+            sym.body_hash = SourceRef.compute_hash(region.text.encode("utf-8"))
+            sym.order_index = i
+            region_ids.append(sym.id)
+        else:
+            ct = CodeTextNode(
+                module_id=module.id, region_key=region.region_key, text=region.text,
+                content_hash=SourceRef.compute_hash(region.text.encode("utf-8")),
+                order_index=i, path=path, kind=_text_region_kind(region))
+            texts.append(ct)
+            region_ids.append(ct.id)
+
+    local_edges = [module.about_edge(), *defines, *module.contains_edges(region_ids)]
+    return DecomposedModule(module=module, symbols=symbols, local_edges=local_edges,
+                            parsed=parsed, texts=texts)
+
+
+def decompose_file(
+    repo_key: str,    # The repo's durable conceptual slug
+    path: str,        # Path to the .py file
+    repo_root: str,   # Repo root (for the repo-relative module path)
+) -> DecomposedModule:  # The decomposed module
+    """Read a `.py` file and decompose it (hash over the raw file bytes)."""
+    raw = Path(path).read_bytes()
+    mp = module_path_for(path, repo_root)
+    return decompose_text(repo_key, mp, str(path), raw.decode("utf-8"),
+                          content_hash=SourceRef.compute_hash(raw))
+
+
+def iter_py_files(
+    root: str,  # Directory to walk
+) -> Iterator[str]:  # Paths to .py files (skipping generated/packaging dirs)
+    """Yield `.py` file paths under `root`, skipping `__pycache__`/build/etc."""
+    base = Path(root)
+    for p in sorted(base.rglob("*.py")):
+        if any(part in _SKIP_DIRS for part in p.relative_to(base).parts):
+            continue
+        yield str(p)
+
+
+def decompose_paths(
+    repo_key: str,           # The repo's durable conceptual slug
+    paths: Iterable[str],    # The .py files to decompose
+    repo_root: str,          # Repo root (for repo-relative module paths)
+) -> List[DecomposedModule]:  # One DecomposedModule per parseable file
+    """Decompose an explicit set of files; unparseable files are skipped (recorded by the caller)."""
+    out: List[DecomposedModule] = []
+    for path in paths:
+        try:
+            out.append(decompose_file(repo_key, path, repo_root))
+        except SyntaxError:
+            continue
+    return out
+
+
+def decompose_package(
+    repo_key: str,                    # The repo's durable conceptual slug
+    package_dir: str,                 # The importable package directory (e.g. ".../cjm_dev_graph_schema")
+    repo_root: Optional[str] = None,  # Repo root for relative module paths (default = package_dir's parent)
+) -> List[DecomposedModule]:  # The decomposed package modules
+    """Decompose every `.py` under a package dir (the lib's own importable source).
+
+    `repo_root` defaults to the package dir's parent, so module paths read like
+    `cjm_dev_graph_schema/nodes.py` (the importable form)."""
+    root = repo_root if repo_root is not None else str(Path(package_dir).parent)
+    return decompose_paths(repo_key, iter_py_files(package_dir), root)

cjm_python_decompose_core/ingest.py

@@ -0,0 +1,103 @@
+"""Flatten a decomposed Python corpus into graph elements (the queue-free half).
+
+Turns `DecomposedModule`s into the `(nodes, edges)` wire-dict lists that
+`cjm_context_graph_layer.ops.extend_graph` commits — adding the CORPUS-level edges
+that need the whole corpus to resolve:
+
+- `IMPORTS` (module -> module): each module's raw imports are resolved (relative
+  imports against the importer's own package) and matched to a module in the corpus.
+- `CALLS` (symbol -> symbol): best-effort, by UNAMBIGUOUS bare name — a call name
+  that maps to exactly one symbol in the corpus links; ambiguous/external names are
+  skipped (precision over recall — never mint a wrong edge).
+
+External/stdlib targets are simply absent from the maps and skipped (never
+phantom-minted), mirroring the markdown core's dangling-reference discipline. The
+queue/capability wiring is the projection-CLI driver's concern; the flattening here
+is reusable and unit-testable without a running graph.
+"""
+
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from .extract import DecomposedModule
+
+
+def resolve_import(
+    raw: str,                  # Raw import as captured by parse ("os", "pkg.mod", ".identity", "..pkg")
+    importer_import_name: str,  # The importing module's dotted import name (e.g. "pkg.sub.mod")
+    is_package: bool,          # Whether the importer is a package (__init__) — its package is itself
+) -> Optional[str]:  # Absolute dotted module name, or None when it escapes the corpus root
+    """Resolve a (possibly relative) import to an absolute dotted module name.
+
+    Absolute imports pass through unchanged. A relative import's leading dots are a
+    level (1 = the importer's own package, each extra dot goes one package up); the
+    remainder is appended. Returns None when the dots climb above the top package."""
+    if not raw.startswith("."):
+        return raw
+    n_dots = len(raw) - len(raw.lstrip("."))
+    suffix = raw[n_dots:]
+    parts = importer_import_name.split(".") if importer_import_name else []
+    base = parts if is_package else parts[:-1]  # the importer's package
+    up = n_dots - 1
+    if up > len(base):
+        return None
+    pkg = list(base[:len(base) - up]) if up else list(base)
+    if suffix:
+        pkg += suffix.split(".")
+    return ".".join(pkg) if pkg else None
+
+
+def build_import_map(
+    decomposed: Iterable[DecomposedModule],  # The decomposed corpus
+) -> Dict[str, str]:  # {dotted import name: CodeModule id}
+    """Map every module's dotted import name to its node id (the IMPORTS target table)."""
+    return {d.module.import_name: d.module.id for d in decomposed if d.module.import_name}
+
+
+def build_call_map(
+    decomposed: Iterable[DecomposedModule],  # The decomposed corpus
+) -> Dict[str, str]:  # {bare symbol name: CodeSymbol id}, UNAMBIGUOUS names only
+    """Map UNAMBIGUOUS bare symbol names to their node ids (the CALLS target table).
+
+    A name defined by more than one symbol is omitted — resolving it would guess.
+    This favors precision: distinctively-named free functions link, shared method
+    names (`id`, `to_graph_node`, ...) do not."""
+    name_to_ids: Dict[str, set] = {}
+    for d in decomposed:
+        for s in d.symbols:
+            name_to_ids.setdefault(s.qualname.split(".")[-1], set()).add(s.id)
+    return {name: next(iter(ids)) for name, ids in name_to_ids.items() if len(ids) == 1}
+
+
+def corpus_graph_elements(
+    decomposed: Iterable[DecomposedModule],  # The decomposed corpus (one entry per module)
+) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:  # (node wire dicts, edge wire dicts)
+    """Collect a decomposed corpus into the node + edge wire-dict lists `extend_graph` expects.
+
+    Nodes: one `CodeModule` per file + one `CodeSymbol` per definition. Edges: the
+    per-module local edges (ABOUT to the repo Entity + structural DEFINES) plus the
+    resolved corpus-level IMPORTS/CALLS. Deterministic ids make this idempotent
+    under `extend_graph` (re-ingesting collides into verified no-ops)."""
+    decs = list(decomposed)
+    import_map = build_import_map(decs)
+    call_map = build_call_map(decs)
+
+    nodes: List[Dict[str, Any]] = []
+    edges: List[Dict[str, Any]] = []
+    for d in decs:
+        nodes.append(d.module.to_graph_node())
+        nodes.extend(s.to_graph_node() for s in d.symbols)
+        nodes.extend(t.to_graph_node() for t in d.texts)  # non-def verbatim regions (round-trip substrate)
+        edges.extend(d.local_edges)
+
+        is_pkg = d.module.module_path.endswith("__init__.py")
+        local_imports: Dict[str, str] = {}
+        for raw in d.module.imports:
+            target = resolve_import(raw, d.module.import_name, is_pkg)
+            if target and target in import_map and import_map[target] != d.module.id:
+                local_imports[raw] = import_map[target]
+        edges.extend(d.module.import_edges(local_imports))
+
+        for s in d.symbols:
+            edges.extend(s.calls_edges(call_map))
+            edges.extend(s.uses_edges(call_map))
+    return nodes, edges