codmap 0.0.3__py3-none-any.whl

codemap/diagnostics.py

@@ -0,0 +1,256 @@
+"""Build-level diagnostics derived from a graph (R1-C21 / design D5).
+
+A graph can be *well-formed and vacuous*: if the extractor did not understand the
+target's layout, whole edge classes come out empty and every conclusion drawn from
+them inverts. The worst case found in the wild (issues #4/#5) was a flat module
+directory: 0 ``imports`` edges, after which ``architecture`` reports "no layer
+violations / acyclic" and ``dead-code`` calls every live module an orphan. Absence of
+data rendered as a clean bill of health.
+
+These checks name that condition wherever the graph is presented. They are
+**derived, never stored** — ``graph.json`` keeps no diagnostic field, so there is
+nothing to keep in sync, and any consumer recomputes the signal from the graph it
+already holds.
+"""
+
+from __future__ import annotations
+
+NO_IMPORT_EDGES = "no_import_edges"
+NAMESPACE_TARGET = "namespace_target"
+NO_CROSS_ROOT_EDGES = "no_cross_root_edges"
+SCHEMA_MISMATCH = "schema_mismatch"
+UNREAD_INPUTS = "unread_inputs"
+MODULE_COUNT_MISMATCH = "module_count_mismatch"
+
+#: A ``warning`` invalidates the conclusions a surface draws from the graph — read them as
+#: unknown. A ``note`` states a fact about how the graph was built and invalidates nothing.
+#: Each check owns its own ``consequence`` sentence: presenters must not supply one, or a
+#: correct result ends up captioned with another check's meaning (issue #8).
+WARNING = "warning"
+NOTE = "note"
+
+
+def import_graph_diagnostic(graph) -> dict | None:
+    """Flag an empty import graph over a multi-module target, else ``None``.
+
+    A single-module package legitimately has no imports, so the check needs ≥2
+    modules; beyond that, a Python package whose modules never import one another
+    is far rarer than a layout the extractor failed to parse.
+    """
+    modules = sum(1 for n in graph.nodes.values() if n.kind == "module")
+    if modules < 2:
+        return None
+    if any(e.type == "imports" for e in graph.edges):
+        return None
+    return {
+        "code": NO_IMPORT_EDGES,
+        "severity": WARNING,
+        "modules": modules,
+        "consequence": ("Findings below are derived from that empty import graph — read "
+                        "them as **unknown**, not as a clean bill of health."),
+        "message": (
+            f"0 import edges across {modules} modules — the import graph is empty, so "
+            "layers, cycles, coupling and orphan detection are vacuous rather than clean. "
+            "This usually means a layout the extractor did not understand (e.g. a flat "
+            "module directory whose files import each other by bare name)."
+        ),
+    }
+
+
+def namespace_target_diagnostic(graph) -> dict | None:
+    """Flag a target that is a **namespace package** (a directory with no ``__init__.py``).
+
+    Derived, like the rest: griffe gives such a directory no source file, so the target's
+    own module node carries ``file=None`` while its children have real files. Worth naming
+    because the layout is a silent fork in behaviour — sibling imports resolve only by the
+    flat-layout inference (labelled ``resolution="flat"`` on the edge), not by packaging.
+    """
+    root = graph.nodes.get(graph.target)
+    if root is None or root.kind != "module" or root.file is not None:
+        return None
+    children = [n for n in graph.nodes.values() if n.kind == "module" and n.id != root.id]
+    if not children:
+        return None
+    return {
+        "code": NAMESPACE_TARGET,
+        "severity": NOTE,   # a fact about provenance; it invalidates nothing (issue #8)
+        "target": graph.target,
+        "message": (
+            f"`{graph.target}` has no __init__.py — it is a namespace package, so its "
+            "modules are only a package by directory. Imports between them are resolved "
+            "by codemap's flat-layout inference (edges labelled resolution=\"flat\"), "
+            "not by packaging."
+        ),
+    }
+
+
+def cross_root_diagnostic(graph) -> dict | None:
+    """Flag consumer/doc roots that reach the core **not at all** (R1-C21-f1, issue #6).
+
+    ``--consumer`` exists so ``impact`` can answer "who uses X across the whole repo".
+    If roots were supplied and *nothing* in them references the core, the answer to that
+    question is a confident zero — and the far likelier cause is that their imports were
+    not understood than that four directories of code genuinely use none of it.
+
+    Deliberately separate from :func:`import_graph_diagnostic`: the case that prompted it
+    had 75 import edges (so the "empty graph" check stayed quiet) and none of them crossing
+    a root boundary. One check per dimension, rather than one check trying to be general.
+    """
+    root_of = {n.id: (n.extras.get("root") or "core") for n in graph.nodes.values()}
+    outer = sorted({r for r in root_of.values() if r != "core"})
+    if not outer:
+        return None  # single-package graph: no boundary to cross
+    for e in graph.edges:
+        if root_of.get(e.source, "core") != "core" and root_of.get(e.target, "core") == "core":
+            return None
+    return {
+        "code": NO_CROSS_ROOT_EDGES,
+        "severity": WARNING,
+        "roots": outer,
+        "consequence": ("Any cross-root finding below — who uses a symbol outside its own "
+                        "root — is **unknown**, not empty."),
+        "message": (
+            f"{len(outer)} non-core root(s) supplied ({', '.join(outer)}) but not one "
+            "reference from them reaches the core — cross-root `impact` will read as "
+            "\"isolated\" for every symbol. Usually an import form the scanner did not "
+            "understand, not an unused core."
+        ),
+    }
+
+
+def schema_diagnostic(graph) -> dict | None:
+    """Flag a stored graph whose schema is not the running tool's (R1-C25 / D3).
+
+    ``codemap_schema`` was written and never read: a graph built before an extraction
+    change was consumed by a later tool without a word, and answered with that tool's
+    confidence over the older tool's blindness. Measured: one frozen tree, two codemap
+    builds four commits apart — 30 edges vs 38, and ``dead-code high`` 12 vs 7 — with
+    **both files declaring 0.11**, because only open ``extras`` had changed. So the
+    check cannot prove semantic equivalence; what it can do is stop a *known* mismatch
+    from passing silently.
+
+    Only fires for a graph that came from a file (``loaded_schema is None`` on a fresh
+    build). Never a refusal: every stored graph in existence predates 0.12, and turning
+    an upgrade into an outage is not the honest option — a labelled answer is (R1-C13).
+    """
+    from codemap.model import SCHEMA_VERSION
+    from codemap.provenance import MATCH, NEWER, OLDER, describe, schema_status
+    if graph.loaded_schema is None:
+        return None
+    status = schema_status(graph.loaded_schema or None, SCHEMA_VERSION)
+    if status == MATCH:
+        return None
+    declared = graph.loaded_schema or "none declared"
+    direction = {OLDER: "predates this tool",
+                 NEWER: "is newer than this tool"}.get(status, "declares no usable version")
+    return {
+        "code": SCHEMA_MISMATCH,
+        "severity": WARNING,
+        "loaded": graph.loaded_schema,
+        "running": SCHEMA_VERSION,
+        "status": status,
+        "provenance": describe(graph.provenance),
+        "consequence": ("Findings below may differ from a fresh build of the same source "
+                        "— rebuild before trusting a close call."),
+        "message": (
+            f"graph declares schema {declared}, this codemap writes {SCHEMA_VERSION} "
+            f"— the artifact {direction}. Extraction semantics change without a schema "
+            f"bump (open `extras`), so the two are not interchangeable. "
+            f"Built by: {describe(graph.provenance)}."
+        ),
+    }
+
+
+def unread_inputs_diagnostic(graph) -> dict | None:
+    """Flag input files the extractor could not read (R1-C23 / design D2).
+
+    A file with a syntax error or a non-UTF-8 byte used to vanish from the graph in
+    silence, after which every report answered over a tree it had not fully seen —
+    the same shape as issue #5, where absence of data rendered as a clean bill of health.
+    """
+    skipped = ((graph.provenance or {}).get("inputs") or {}).get("skipped") or []
+    if not skipped:
+        return None
+    by_reason = {}
+    for s in skipped:
+        by_reason.setdefault(s.get("reason", "unread"), []).append(s.get("path"))
+    listed = ", ".join(f"{len(v)} {k}" for k, v in sorted(by_reason.items()))
+    sample = ", ".join(sorted(p for v in by_reason.values() for p in v)[:5])
+    return {
+        "code": UNREAD_INPUTS,
+        "severity": WARNING,
+        "skipped": skipped,
+        "consequence": ("Anything those files define or depend on is **missing**, not "
+                        "absent — dead-code, layers and impact are all short by that much."),
+        "message": (
+            f"{len(skipped)} input file(s) produced no module ({listed}): {sample}"
+            + (" …" if len(skipped) > 5 else "")
+        ),
+    }
+
+
+def module_count_diagnostic(graph) -> dict | None:
+    """Conservation law over the build: modules cannot outnumber the files that define
+    them, nor silently fall short of them (R1-C23 / design D6).
+
+    Deliberately not a heuristic and deliberately not tuned — both directions are
+    *provably* wrong states, so there is no threshold to argue about. It is the check
+    that catches a cause we have not met yet: it flags the symlink-cycle explosion
+    without knowing what a symlink is, and an unexplained shortfall without knowing what
+    a syntax error is. It would have fired on issue #5.
+    """
+    inputs = (graph.provenance or {}).get("inputs") or {}
+    expected = inputs.get("python_files")
+    if expected is None:
+        return None  # pre-0.12 graph, or a build that recorded no input count
+    # Core only: ``inputs`` counts the extractor's walk of the target package, so a
+    # repo-scoped graph's consumer modules (``--consumer tests``) are not in that number
+    # and must not be compared against it.
+    from_py = sum(1 for n in graph.nodes.values()
+                  if n.kind == "module" and (n.file or "").endswith(".py")
+                  and (n.extras.get("root") or "core") == "core")
+    skipped = len(inputs.get("skipped") or [])
+    if from_py > expected:
+        direction = (f"{from_py} modules built from {expected} input file(s) — a module "
+                     "cannot outnumber the files that define it. The tree was probably "
+                     "walked more than once (a directory symlink into its own ancestry).")
+    elif from_py < expected - skipped:
+        direction = (f"{from_py} modules built from {expected} input file(s), only "
+                     f"{skipped} of which are accounted for as unreadable — "
+                     f"{expected - skipped - from_py} file(s) went missing unexplained.")
+    else:
+        return None
+    return {
+        "code": MODULE_COUNT_MISMATCH,
+        "severity": WARNING,
+        "modules": from_py,
+        "input_files": expected,
+        "consequence": ("Every aggregate below — counts, layers, cycles, hotspots, "
+                        "dead-code — is computed over that graph, so read it as "
+                        "**unknown**."),
+        "message": direction,
+    }
+
+
+def diagnostics(graph) -> list[dict]:
+    """Every diagnostic that applies to ``graph`` (empty list when it looks sound)."""
+    checks = (import_graph_diagnostic(graph), namespace_target_diagnostic(graph),
+              cross_root_diagnostic(graph), schema_diagnostic(graph),
+              unread_inputs_diagnostic(graph), module_count_diagnostic(graph))
+    return [d for d in checks if d is not None]
+
+
+def render_lines(graph) -> list[str]:
+    """Markdown blockquote lines for a report header (empty when the graph looks sound).
+
+    Presenters call this instead of formatting diagnostics themselves — a caption that
+    belongs to one check must never end up under another (issue #8: the namespace *note*
+    was rendered with the empty-import-graph *warning*'s "everything below is unknown",
+    on a graph with 404 import edges).
+    """
+    lines: list[str] = []
+    for d in diagnostics(graph):
+        mark = "⚠️" if d.get("severity", WARNING) == WARNING else "ℹ️"
+        text = " ".join(part for part in (d["message"], d.get("consequence")) if part)
+        lines.extend([f"> {mark} {text}", ""])
+    return lines

codemap/extract/__init__.py

@@ -0,0 +1,10 @@
+"""Extractors: source -> neutral graph. v1 ships the Python (griffe) extractor.
+
+Extractors are the only language-aware layer (DESIGN §12): each emits into the
+neutral model, so adding a language later is additive, not a core rewrite.
+"""
+
+from codemap.extract.griffe_extractor import extract
+from codemap.extract.roots import extract_repo
+
+__all__ = ["extract", "extract_repo"]

codemap/extract/attrflow.py

@@ -0,0 +1,230 @@
+"""Attribute-access pass — function → attribute read/write edges (R1-C20, issue #1).
+
+codemap models relationships between *symbols* (calls/imports/inherits/…) and
+between functions and *string-keyed columns* (reads/writes, M12) — but **not**
+between code and Python *attributes*. So ``impact`` on a class field returned
+``refs: []`` / ``risk: "none"`` (an affirmative "nothing depends on this") even
+when the field had many real read/write sites: attribute nodes exist but nothing
+in the graph pointed at them (gaps/attribute_impact_gap_2026-08-22).
+
+This pass makes attribute access first-class, mirroring what ``dataflow.py`` did
+for columns:
+
+- an ``accesses`` edge (function → the ``attribute`` node it touches), with
+  ``extras.access`` (``read`` | ``write``) and ``extras.resolution``.
+
+**Access forms and how each resolves** (only edges whose target is a real
+``attribute`` node are emitted — R1-C13-f2 soundness; everything else is a
+counter, never an edge to nothing):
+
+- ``self.field`` / ``cls.field`` → the enclosing class's attribute, via the same
+  ``members`` owner-map behavior.py uses (``self.<inherited>`` → the base that
+  defines it, R1-C13-f1). ``resolution = "self"``. Fast tier.
+- ``ClassName.field`` → the named class's attribute, class resolved through
+  imports / module members. ``resolution = "class"``. Fast tier.
+- construction kwargs ``Cls(field=…)`` → a *write* to ``Cls.field`` (this is how
+  dataclass fields are most often set). ``resolution = "construct"``. Fast tier.
+- ``obj.field`` on a typed local → jedi types ``obj`` → its attribute.
+  ``resolution = "deep"``. Deep tier only (``deep=True``).
+- ``obj.field`` on an untyped local → **unresolved** (counter, no edge). Honest.
+
+**Boundaries.** Method / ``property`` access is *not* an attribute access — the
+target there is a ``function`` node, so the ``kind == "attribute"`` gate excludes
+it (properties are functions in griffe; out of scope, by design). Dynamic access
+(``getattr``/``setattr``) is never guessed. Value-level dataflow (which value
+flows into the field) is out of scope — this is *access* modelling, not taint.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from codemap.extract.behavior import (
+    _SKIP_RECEIVERS,
+    _class_members,
+    _index_modules,
+    _jedi_project,
+    _jedi_script,
+    _named_functions,
+    _node_id,
+    _own_nodes,
+)
+from codemap.extract.gsource import module_file, module_imports
+from codemap.model import Edge
+
+
+def add_attrflow(graph, griffe_root, target_pkg: str, *, deep: bool = False,
+                 search_path=None, only=None) -> None:
+    """Add ``accesses`` edges (function → attribute) for read/write sites.
+
+    ``deep=True`` enables the jedi tier for ``obj.field`` on typed locals; the fast
+    tier (``self.``/``ClassName.``/construction kwargs) needs only stdlib ``ast``.
+    Per-function ``extras.attr_access`` coverage counts (out / resolved / unresolved)
+    are recorded so the graph reports its own honesty, like ``extras.calls``.
+    ``only`` (a set of module paths) restricts the pass — the incremental hook
+    (R1-C9), mirroring :func:`add_behavior`.
+    """
+    modules = _index_modules(griffe_root)
+    known_modules = set(modules)  # R1-C21: flat-layout sibling lookup
+    project = _jedi_project(search_path) if deep else None
+    pkg = target_pkg + "."
+    # (func_id, attr_id, access, resolution) — dedup collapses repeated sites.
+    edges: set[tuple[str, str, str, str]] = set()
+    for modpath in sorted(modules):
+        if only is not None and modpath not in only:
+            continue
+        if "samples.embedded" in modpath:
+            continue  # embedded datasets are data, not code (matches dataflow.py)
+        mod = modules[modpath]
+        fp = module_file(mod)  # None for a namespace dir (R1-C21)
+        if fp is None:
+            continue
+        try:
+            source = fp.read_text(encoding="utf-8")
+            tree = ast.parse(source)
+        except (OSError, SyntaxError):
+            continue
+        imports = module_imports(mod, modpath, known_modules)  # R1-C21: flat-aware
+        modmembers = set(mod.members.keys())
+        script = _jedi_script(source, fp, project) if deep else None
+        for fnode, class_stack in _named_functions(tree):
+            node_id = _node_id(modpath, class_stack, fnode.name)
+            if node_id not in graph.nodes:
+                continue  # nested closure — not a definition node
+            members = _class_members(mod, class_stack, modules) if class_stack else {}
+            counts = {"out": 0, "resolved": 0, "unresolved": 0}
+            for attr_id, access, resolution in _own_attr_uses(
+                fnode, graph, modpath, members, imports, modmembers, pkg, script
+            ):
+                counts["out"] += 1
+                if attr_id is None:
+                    counts["unresolved"] += 1
+                    continue
+                counts["resolved"] += 1
+                edges.add((node_id, attr_id, access, resolution))
+            if counts["out"]:
+                graph.nodes[node_id].extras["attr_access"] = counts
+
+    for src, attr_id, access, resolution in sorted(edges):
+        graph.add_edge(Edge("accesses", src, attr_id,
+                            extras={"access": access, "resolution": resolution}))
+
+
+def _is_attribute_node(graph, node_id: str) -> bool:
+    """True iff ``node_id`` is a real ``attribute`` node.
+
+    The soundness gate (R1-C13-f2): only emit ``accesses`` to an attribute — this
+    also excludes methods and ``property`` (function nodes) that share the ``.name``
+    shape, so those stay in the calls layer where they belong.
+    """
+    node = graph.nodes.get(node_id)
+    return node is not None and node.kind == "attribute"
+
+
+def _resolve_class(name: str, modpath: str, imports: dict, modmembers: set,
+                   pkg: str) -> str | None:
+    """Canonical id of the package class ``name`` refers to (imports / module), else None.
+
+    Mirrors behavior.py's call-target resolution: an imported name maps to its
+    (griffe-resolved) target path; a module-level name to ``{modpath}.{name}``.
+    """
+    if name in imports:
+        tgt = imports[name]
+        return tgt if tgt.startswith(pkg) else None
+    if name in modmembers:
+        return f"{modpath}.{name}"
+    return None
+
+
+def _own_attr_uses(fnode, graph, modpath, members, imports, modmembers, pkg, script):
+    """Yield (attr_id | None, access, resolution) for attribute uses in a function body.
+
+    ``attr_id is None`` marks an access site we saw but could not resolve to an
+    attribute node (an honest unresolved counter — never an edge to nothing).
+    Skips nested defs/classes (their own scope), matching ``_own_nodes``.
+    """
+    nodes = list(_own_nodes(fnode))
+    # Attributes that are the callee of a call (``self.foo()``) are *method calls*,
+    # handled by the behavioral layer — not field access. Skip exactly those.
+    call_funcs = {id(n.func) for n in nodes if isinstance(n, ast.Call)}
+
+    for node in nodes:
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+            # construction kwargs: Cls(field=…) → write to Cls.field
+            cls_id = _resolve_class(node.func.id, modpath, imports, modmembers, pkg)
+            if cls_id is not None:
+                for kw in node.keywords:
+                    if kw.arg is None:
+                        continue  # **kwargs splat — arity unknown, don't guess
+                    attr_id = f"{cls_id}.{kw.arg}"
+                    if _is_attribute_node(graph, attr_id):
+                        yield attr_id, "write", "construct"
+                    else:
+                        yield None, "write", "construct"
+            continue
+
+        if not isinstance(node, ast.Attribute) or id(node) in call_funcs:
+            continue
+        recv = node.value
+        if not isinstance(recv, ast.Name):
+            # obj.attr where obj is itself an expression — deep tier only.
+            yield from _deep_attr(node, graph, pkg, script)
+            continue
+        access = "write" if isinstance(node.ctx, ast.Store) else "read"
+        if recv.id in _SKIP_RECEIVERS:
+            # self.field / cls.field — resolve via the class member owner-map.
+            owner = members.get(node.attr)
+            attr_id = f"{owner}.{node.attr}" if owner else None
+            if attr_id and _is_attribute_node(graph, attr_id):
+                yield attr_id, access, "self"
+            else:
+                yield None, access, "self"
+        else:
+            cls_id = _resolve_class(recv.id, modpath, imports, modmembers, pkg)
+            if cls_id is not None:
+                # ClassName.field
+                attr_id = f"{cls_id}.{node.attr}"
+                if _is_attribute_node(graph, attr_id):
+                    yield attr_id, access, "class"
+                else:
+                    yield None, access, "class"
+            else:
+                # obj.field on a local — deep tier resolves the type, else unresolved.
+                yield from _deep_attr(node, graph, pkg, script)
+
+
+def _deep_attr(node, graph, pkg, script):
+    """Resolve ``obj.field`` via jedi (deep tier); yield (attr_id | None, access, 'deep').
+
+    Infers the **type of the receiver** (``obj`` in ``obj.field``) → its class →
+    ``{class}.{field}``, rather than ``goto``-ing the attribute name: jedi's goto on
+    an instance attribute lands on whichever assignment statement it can see
+    (``Class.method.field``), not the class-level field node. Inferring the receiver
+    is exact and also threads chains (``self.cfg.field`` — the receiver ``self.cfg``
+    is itself typed). Yields nothing on the fast tier (no jedi script) so a typed
+    local isn't even counted as unresolved there — the fast tier makes no claim.
+    """
+    if script is None:
+        return
+    access = "write" if isinstance(node.ctx, ast.Store) else "read"
+    recv = node.value
+    end_line = getattr(recv, "end_lineno", None)
+    end_col = getattr(recv, "end_col_offset", None)
+    if end_line is None or end_col is None:
+        yield None, access, "deep"
+        return
+    try:
+        types = script.infer(end_line, end_col)
+    except Exception:
+        yield None, access, "deep"
+        return
+    for t in sorted(types, key=lambda d: d.full_name or ""):
+        cls = t.full_name
+        if not cls or not cls.startswith(pkg):
+            continue
+        attr_id = f"{cls}.{node.attr}"
+        if _is_attribute_node(graph, attr_id):
+            yield attr_id, access, "deep"
+            return
+    yield None, access, "deep"