codemble 0.3.0__py3-none-any.whl

codemble/checks/__init__.py

@@ -0,0 +1,19 @@
+"""Active checks generated FROM the graph; answers never come from the LLM."""
+
+from codemble.checks.service import (
+    Check,
+    CheckKind,
+    CheckService,
+    InvalidCheckSubmission,
+    UnknownCheckError,
+    generate_checks,
+)
+
+__all__ = [
+    "Check",
+    "CheckKind",
+    "CheckService",
+    "InvalidCheckSubmission",
+    "UnknownCheckError",
+    "generate_checks",
+]

codemble/checks/service.py

@@ -0,0 +1,380 @@
+"""Deterministic active checks whose answers come only from the graph."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Literal
+
+from codemble.adapters.base import Edge, Graph, Node
+from codemble.graph.layout import with_entrypoint
+from codemble.progress import ProgressStore
+
+CheckKind = Literal["first-call", "direct-importer", "removal-impact", "entrypoint"]
+
+# Wrong options a check offers beyond its answers, when the graph holds that many.
+_MINIMUM_DISTRACTORS = 2
+
+
+class UnknownCheckError(KeyError):
+    """Raised for a region or check absent from the current graph."""
+
+
+class InvalidCheckSubmission(ValueError):
+    """Raised when a submitted option was not offered by the check."""
+
+
+@dataclass(frozen=True, slots=True)
+class CheckOption:
+    id: str
+    label: str
+
+
+@dataclass(frozen=True, slots=True)
+class Check:
+    id: str
+    region_id: str
+    kind: CheckKind
+    prompt: str
+    options: tuple[CheckOption, ...]
+    answer_ids: tuple[str, ...]
+    evidence: tuple[str, ...]
+
+    def public(self, *, passed: bool) -> dict[str, object]:
+        """Serialize the question without exposing its graph-derived answer."""
+
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "prompt": self.prompt,
+            "multiple": len(self.answer_ids) > 1,
+            "options": [
+                {"id": option.id, "label": option.label} for option in self.options
+            ],
+            "passed": passed,
+        }
+
+
+class CheckService:
+    """Generate, validate, and persist one graph-owned region check flow."""
+
+    def __init__(self, graph: Graph, progress: ProgressStore | None = None) -> None:
+        self._graph = graph
+        self._progress = progress or ProgressStore(graph)
+        self._checks = {
+            region.id: generate_checks(graph, region.id) for region in graph.regions
+        }
+        self._passed: dict[str, set[str]] = {}
+
+    def graph(self) -> Graph:
+        """Return render data hydrated from currently valid local progress."""
+
+        hydrated = self._progress.hydrated_graph()
+        return (
+            with_entrypoint(hydrated, self._graph.selected_entrypoint)
+            if self._graph.selected_entrypoint
+            else hydrated
+        )
+
+    def select_entrypoint(self, node_id: str) -> Graph:
+        """Apply an explicit parser-ranked Home choice to graph and check suites."""
+
+        self._graph = with_entrypoint(self._graph, node_id)
+        self._checks = {
+            region.id: generate_checks(self._graph, region.id)
+            for region in self._graph.regions
+        }
+        return self.graph()
+
+    def for_region(self, region_id: str) -> dict[str, object]:
+        """Return a region suite with answer values withheld."""
+
+        checks = self._region_checks(region_id)
+        understood = region_id in self._progress.understood_regions()
+        passed = self._passed.get(region_id, set())
+        return {
+            "region_id": region_id,
+            "region_understood": understood,
+            "checks": [
+                check.public(passed=understood or check.id in passed) for check in checks
+            ],
+        }
+
+    def submit(
+        self, region_id: str, check_id: str, selected_ids: list[str]
+    ) -> dict[str, object]:
+        """Score exact option IDs against the immutable generated answer."""
+
+        checks = self._region_checks(region_id)
+        check = next((candidate for candidate in checks if candidate.id == check_id), None)
+        if check is None:
+            raise UnknownCheckError(check_id)
+        offered = {option.id for option in check.options}
+        selected = set(selected_ids)
+        if not selected or not selected <= offered:
+            raise InvalidCheckSubmission("Select one or more offered answers.")
+
+        correct = selected == set(check.answer_ids)
+        if correct:
+            self._passed.setdefault(region_id, set()).add(check.id)
+        passed = self._passed.get(region_id, set())
+        complete = bool(checks) and all(candidate.id in passed for candidate in checks)
+        if complete:
+            self._progress.mark_understood(region_id)
+
+        answer_labels = [
+            option.label for option in check.options if option.id in check.answer_ids
+        ]
+        return {
+            "correct": correct,
+            "check_id": check.id,
+            "answer_ids": list(check.answer_ids),
+            "answer_labels": answer_labels,
+            "evidence": list(check.evidence),
+            "message": (
+                "Correct. That answer is fixed by the parser graph."
+                if correct
+                else "Not yet. Re-read the graph relationship and try again."
+            ),
+            "region_understood": complete,
+        }
+
+    def _region_checks(self, region_id: str) -> tuple[Check, ...]:
+        if region_id not in self._checks:
+            raise UnknownCheckError(region_id)
+        return self._checks[region_id]
+
+
+def generate_checks(graph: Graph, region_id: str) -> tuple[Check, ...]:
+    """Build up to four stable questions from parser-owned evidence."""
+
+    if not any(region.id == region_id for region in graph.regions):
+        raise UnknownCheckError(region_id)
+    nodes = {node.id: node for node in graph.nodes}
+    checks: list[Check] = []
+
+    first_call = _first_call_check(graph, region_id, nodes)
+    if first_call:
+        checks.append(first_call)
+    importer = _importer_check(graph, region_id, nodes)
+    if importer:
+        checks.append(importer)
+    impact = _impact_check(graph, region_id, nodes)
+    if impact:
+        checks.append(impact)
+    entrypoint = _entrypoint_check(graph, region_id, nodes)
+    if entrypoint:
+        checks.append(entrypoint)
+    return tuple(check for check in checks if _proves_understanding(check))
+
+
+def _proves_understanding(check: Check) -> bool:
+    """Reject a question every option answers; passing it would prove nothing."""
+
+    return bool({option.id for option in check.options} - set(check.answer_ids))
+
+
+def _first_call_check(
+    graph: Graph, region_id: str, nodes: dict[str, Node]
+) -> Check | None:
+    calls_by_source: dict[str, list[Edge]] = {}
+    for edge in graph.edges:
+        source = nodes.get(edge.src)
+        if (
+            edge.kind == "call"
+            and edge.certain
+            and not edge.external
+            and source is not None
+            and source.region == region_id
+            and edge.dst in nodes
+        ):
+            calls_by_source.setdefault(edge.src, []).append(edge)
+    if not calls_by_source:
+        return None
+    source_id = sorted(calls_by_source)[0]
+    edge = min(calls_by_source[source_id], key=lambda item: (item.lineno, item.dst))
+    answers = (edge.dst,)
+    return _check(
+        graph,
+        region_id,
+        "first-call",
+        source_id,
+        f"Which structure does {source_id} call first?",
+        answers,
+        _node_options(nodes, answers, kind="function"),
+        (f"{nodes[source_id].file}:{edge.lineno}",),
+    )
+
+
+def _importer_check(
+    graph: Graph, region_id: str, nodes: dict[str, Node]
+) -> Check | None:
+    incoming = sorted(
+        (
+            edge
+            for edge in graph.edges
+            if edge.kind == "import"
+            and edge.certain
+            and not edge.external
+            and edge.dst == region_id
+            and edge.src in nodes
+        ),
+        key=lambda edge: (edge.src, edge.lineno),
+    )
+    if incoming:
+        answers = tuple(sorted({edge.src for edge in incoming}))
+        return _check(
+            graph,
+            region_id,
+            "direct-importer",
+            region_id,
+            f"Which project module imports {region_id} directly?",
+            answers,
+            _node_options(nodes, answers, kind="module"),
+            tuple(f"{nodes[edge.src].file}:{edge.lineno}" for edge in incoming),
+        )
+
+    outgoing = sorted(
+        (
+            edge
+            for edge in graph.edges
+            if edge.kind == "import"
+            and edge.certain
+            and not edge.external
+            and edge.src == region_id
+            and edge.dst in nodes
+        ),
+        key=lambda edge: (edge.lineno, edge.dst),
+    )
+    if not outgoing:
+        return None
+    first = outgoing[0]
+    answers = (first.dst,)
+    return _check(
+        graph,
+        region_id,
+        "direct-importer",
+        region_id,
+        f"Which project module does {region_id} import first?",
+        answers,
+        _node_options(nodes, answers, kind="module"),
+        (f"{nodes[region_id].file}:{first.lineno}",),
+    )
+
+
+def _impact_check(
+    graph: Graph, region_id: str, nodes: dict[str, Node]
+) -> Check | None:
+    callers_by_target: dict[str, list[Edge]] = {}
+    for edge in graph.edges:
+        target = nodes.get(edge.dst)
+        if (
+            edge.kind == "call"
+            and edge.certain
+            and not edge.external
+            and target is not None
+            and target.region == region_id
+            and edge.src in nodes
+        ):
+            callers_by_target.setdefault(edge.dst, []).append(edge)
+    if not callers_by_target:
+        return None
+    target_id = sorted(
+        callers_by_target,
+        key=lambda candidate: (-len(callers_by_target[candidate]), candidate),
+    )[0]
+    callers = sorted(callers_by_target[target_id], key=lambda edge: (edge.src, edge.lineno))
+    answers = tuple(sorted({edge.src for edge in callers}))
+    return _check(
+        graph,
+        region_id,
+        "removal-impact",
+        target_id,
+        f"Which structure directly depends on {target_id} and could break if it disappeared?",
+        answers,
+        _node_options(nodes, answers, kind="function"),
+        tuple(f"{nodes[edge.src].file}:{edge.lineno}" for edge in callers),
+    )
+
+
+def _entrypoint_check(
+    graph: Graph, region_id: str, nodes: dict[str, Node]
+) -> Check | None:
+    ranked = [candidate for candidate in graph.entrypoint_candidates if candidate in nodes]
+    selected = graph.selected_entrypoint
+    if not ranked or selected is None or nodes[selected].region != region_id:
+        return None
+    answers = (selected,)
+    pool = ranked + [node.id for node in graph.nodes if node.id not in ranked]
+    return _check(
+        graph,
+        region_id,
+        "entrypoint",
+        selected,
+        "Which parser-ranked structure is selected as Home for this run?",
+        answers,
+        _options(nodes, answers, pool),
+        (f"{nodes[selected].file}:{nodes[selected].lineno}",),
+    )
+
+
+def _node_options(
+    nodes: dict[str, Node], answers: tuple[str, ...], *, kind: str
+) -> tuple[CheckOption, ...]:
+    pool = [node.id for node in nodes.values() if node.kind == kind]
+    if len(set(pool) | set(answers)) < 2:
+        pool = list(nodes)
+    return _options(nodes, answers, pool)
+
+
+def _options(
+    nodes: dict[str, Node], answers: tuple[str, ...], pool: list[str]
+) -> tuple[CheckOption, ...]:
+    """Offer every answer plus wrong options, or nothing if none exist.
+
+    The ceiling must clear ``len(answers)``; capping at four alone offered a
+    multi-answer check no wrong option, so selecting everything always passed.
+    """
+
+    candidates = list(answers)
+    ceiling = max(4, len(answers) + _MINIMUM_DISTRACTORS)
+    for candidate in sorted(set(pool)):
+        if candidate not in candidates and len(candidates) < ceiling:
+            candidates.append(candidate)
+    if len(candidates) == len(answers):
+        return ()
+    return tuple(CheckOption(candidate, nodes[candidate].id) for candidate in candidates)
+
+
+def _check(
+    graph: Graph,
+    region_id: str,
+    kind: CheckKind,
+    subject: str,
+    prompt: str,
+    answers: tuple[str, ...],
+    options: tuple[CheckOption, ...],
+    evidence: tuple[str, ...],
+) -> Check:
+    check_id = hashlib.sha256(
+        f"{graph.schema_version}|{region_id}|{kind}|{subject}".encode()
+    ).hexdigest()[:16]
+    return Check(
+        id=check_id,
+        region_id=region_id,
+        kind=kind,
+        prompt=prompt,
+        options=options,
+        answer_ids=answers,
+        evidence=evidence,
+    )
+
+
+__all__ = [
+    "Check",
+    "CheckKind",
+    "CheckService",
+    "InvalidCheckSubmission",
+    "UnknownCheckError",
+    "generate_checks",
+]

codemble/cli.py

@@ -0,0 +1,161 @@
+"""Codemble command-line entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Callable, Sequence
+
+from codemble import __version__
+from codemble.adapters.project import (
+    ProjectIntake,
+    ProjectParseError,
+    ProjectParser,
+    ProjectScaleError,
+)
+from codemble.server.runtime import serve_picker, serve_project
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codemble",
+        description="Turn parser-proven project structure into Codemble graph data.",
+    )
+    parser.add_argument("--version", action="version", version=f"codemble {__version__}")
+    commands = parser.add_subparsers(dest="command")
+    parse_command = commands.add_parser("parse", help="parse a project into graph JSON")
+    parse_command.add_argument("path", type=Path, help="source file or project directory")
+    parse_command.add_argument(
+        "--out", required=True, type=Path, help="destination for deterministic graph JSON"
+    )
+    parse_command.add_argument(
+        "--entrypoint", help="parser-ranked node ID to mark as Home"
+    )
+    serve_command = commands.add_parser("serve", help=argparse.SUPPRESS)
+    serve_command.add_argument(
+        "path", nargs="?", default=None, type=Path, help="source file or project directory"
+    )
+    serve_command.add_argument(
+        "--path",
+        dest="scope_path",
+        type=Path,
+        help="explicit project or subdirectory scope; skips the large-project prompt",
+    )
+    serve_command.add_argument(
+        "--entrypoint", help="parser-ranked node ID to mark as Home"
+    )
+    serve_command.add_argument("--host", default="127.0.0.1")
+    serve_command.add_argument("--port", default=0, type=int)
+    serve_command.add_argument("--no-open", action="store_true", help="do not open a browser")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI, returning a process exit status for testability."""
+
+    parser = _parser()
+    raw_arguments = list(argv) if argv is not None else list(sys.argv[1:])
+    if not raw_arguments or raw_arguments[0] not in {
+        "parse",
+        "serve",
+        "--version",
+        "-h",
+        "--help",
+    }:
+        raw_arguments.insert(0, "serve")
+    arguments = parser.parse_args(raw_arguments)
+
+    if arguments.command == "parse":
+        try:
+            graph = ProjectParser().parse(
+                arguments.path,
+                entrypoint=arguments.entrypoint,
+                explicit=True,
+            )
+            graph.write_json(arguments.out)
+        except (OSError, ProjectParseError) as error:
+            print(f"codemble: {error}", file=sys.stderr)
+            return 2
+        print(
+            f"Wrote {len(graph.nodes)} nodes and {len(graph.edges)} edges to "
+            f"{arguments.out}"
+        )
+    elif arguments.command == "serve":
+        try:
+            if arguments.path is None and arguments.scope_path is None:
+                serve_picker(
+                    host=arguments.host,
+                    port=arguments.port,
+                    open_browser=not arguments.no_open,
+                    entrypoint=arguments.entrypoint,
+                )
+                return 0
+            requested = arguments.scope_path or arguments.path
+            selected_path = choose_project_scope(
+                requested,
+                explicit=arguments.scope_path is not None,
+                interactive=sys.stdin.isatty(),
+            )
+            serve_project(
+                selected_path,
+                host=arguments.host,
+                port=arguments.port,
+                open_browser=not arguments.no_open,
+                entrypoint=arguments.entrypoint,
+            )
+        except (OSError, ProjectParseError) as error:
+            print(f"codemble: {error}", file=sys.stderr)
+            return 2
+    return 0
+
+
+def choose_project_scope(
+    requested: Path,
+    *,
+    explicit: bool,
+    interactive: bool,
+    input_fn: Callable[[str], str] = input,
+    output_fn: Callable[[str], None] = print,
+) -> ProjectIntake:
+    """Require an intentional subdirectory for projects above the v1 scale cap."""
+
+    parser = ProjectParser()
+    try:
+        return parser.intake(requested, explicit=explicit)
+    except ProjectScaleError as error:
+        if not interactive:
+            raise
+        intake = error.intake
+        scale_cap = error.scale_cap
+
+    suggestions = ", ".join(
+        f"{directory} ({count})" for directory, count in intake.scope_counts()[:6]
+    )
+    output_fn(
+        f"Codemble found {len(intake.files)} supported source files; "
+        f"the limit is {scale_cap}."
+    )
+    if suggestions:
+        output_fn(f"Top scopes: {suggestions}")
+
+    while True:
+        answer = input_fn("Subdirectory to map (or q to quit): ").strip()
+        if answer.lower() in {"q", "quit"}:
+            raise ProjectParseError("project scope selection cancelled")
+        candidate = (intake.root / answer).expanduser().resolve()
+        if not candidate.is_relative_to(intake.root):
+            output_fn("Choose a subdirectory inside the project root.")
+            continue
+        try:
+            return parser.intake(candidate)
+        except ProjectScaleError as error:
+            output_fn(
+                f"That scope still has {len(error.intake.files)} supported source files; "
+                "choose a smaller one."
+            )
+        except ProjectParseError as error:
+            output_fn(str(error))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codemble/graph/__init__.py

@@ -0,0 +1,17 @@
+"""Language-tagged graph helpers and render-ready metadata."""
+
+from codemble.adapters.base import ConceptAnnotation, Edge, Graph, Node, Region, RegionEdge
+from codemble.graph.finalize import GraphFinalizationError, finalize_graph
+from codemble.graph.layout import layout_graph
+
+__all__ = [
+    "ConceptAnnotation",
+    "Edge",
+    "Graph",
+    "GraphFinalizationError",
+    "Node",
+    "Region",
+    "RegionEdge",
+    "finalize_graph",
+    "layout_graph",
+]

codemble/graph/finalize.py

@@ -0,0 +1,91 @@
+"""Canonical graph finalization shared by every language adapter."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import replace
+
+from codemble.adapters.base import ConceptAnnotation, Edge, Graph
+from codemble.graph.layout import layout_graph
+
+
+class GraphFinalizationError(ValueError):
+    """Parser evidence cannot be finalized into one honest graph."""
+
+
+def finalize_graph(graph: Graph, *, entrypoint: str | None = None) -> Graph:
+    """Canonicalize parser evidence and return one render-ready graph."""
+
+    edges = tuple(sorted(set(graph.edges), key=_edge_key))
+    node_ids = {node.id for node in graph.nodes}
+    indegree = Counter(
+        edge.dst
+        for edge in edges
+        if edge.kind == "call" and not edge.external and edge.dst in node_ids
+    )
+    nodes = tuple(
+        sorted(
+            (replace(node, centrality=indegree[node.id]) for node in graph.nodes),
+            key=lambda node: node.id,
+        )
+    )
+    node_by_id = {node.id: node for node in nodes}
+    candidates = tuple(
+        node.id
+        for node in sorted(
+            (node for node in nodes if node.entrypoint_rank is not None),
+            key=lambda node: (node.entrypoint_rank, node.id),  # type: ignore[arg-type]
+        )
+    )
+    if entrypoint is not None and entrypoint not in candidates:
+        choices = ", ".join(candidates) or "none"
+        raise GraphFinalizationError(
+            f"entrypoint is not parser-ranked: {entrypoint} (candidates: {choices})"
+        )
+    rank_zero = [
+        candidate
+        for candidate in candidates
+        if node_by_id[candidate].entrypoint_rank == 0
+    ]
+    selected_entrypoint = entrypoint or (rank_zero[0] if len(rank_zero) == 1 else None)
+    finalized = replace(
+        graph,
+        nodes=nodes,
+        edges=edges,
+        entrypoint_candidates=candidates,
+        file_hashes=dict(sorted(graph.file_hashes.items())),
+        selected_entrypoint=selected_entrypoint,
+        concept_annotations=tuple(
+            sorted(set(graph.concept_annotations), key=_annotation_key)
+        ),
+        regions=(),
+        region_edges=(),
+        partial_files=tuple(sorted(set(graph.partial_files))),
+    )
+    return layout_graph(finalized)
+
+
+def _edge_key(edge: Edge) -> tuple[str, str, str, int, bool, bool]:
+    return (
+        edge.src,
+        edge.dst,
+        edge.kind,
+        edge.lineno,
+        edge.certain,
+        edge.external,
+    )
+
+
+def _annotation_key(
+    annotation: ConceptAnnotation,
+) -> tuple[str, str, int, str, int]:
+    return (
+        annotation.language,
+        annotation.node_id,
+        annotation.lineno,
+        annotation.concept,
+        annotation.end_lineno,
+    )
+
+
+__all__ = ["GraphFinalizationError", "finalize_graph"]