codegraph-brain 0.6.0__py3-none-any.whl

cgis/query/drift/ontology_init.py

@@ -0,0 +1,470 @@
+"""Auto-propose a starter patterns.yaml from the measured graph (#174).
+
+Measure-then-label: discover candidate domains from FQN structure, fit each
+against the bundled pattern templates by scoring with the existing
+DriftScorer, and emit a ready-to-edit ontology whose tolerances are the
+measured values plus a margin — green by construction on the same graph.
+"""
+
+import math
+import tempfile
+from collections import Counter
+from pathlib import Path
+
+import yaml
+
+from cgis.core.models import VIRTUAL_FILE_PATH, Node
+from cgis.query.drift.drift import DomainConfig, DriftScorer
+from cgis.query.drift.fingerprint import FingerprintExtractor, PatternFingerprint
+from cgis.storage.sqlite_store import SQLiteStore
+
+# ---------------------------------------------------------------------------
+# Bundled default ontology header (version/profiles/patterns/hygiene only).
+# project_domains and project_level are intentionally excluded — those are
+# the generated output. The staleness pin in the test suite guards this block
+# against drift from docs/ontology/patterns.yaml.
+# ---------------------------------------------------------------------------
+
+_DEFAULT_ONTOLOGY_HEADER = """\
+# Generated by `cgis init-ontology` — a measured baseline, not a verdict.
+# Tolerances are measured + margin: ratchet them DOWN over time.
+# Docs: docs/specs/2026-06-12-init-ontology-design.md
+version: "2.1.0"
+
+# ── Measurement profiles (spec §2.3, §3.3) ───────────────────────────────────
+# drift_weights: v1 per-component weights — now used ONLY for the gate term
+#   (hygiene + template-declared non-triad constraints).
+# layers: fingerprint v2 layer weights (imports TV / calls TV / gates),
+#   must sum to 1.0. The calls layer is discounted by (1 - unresolved_ratio);
+#   a layer with zero connected triples is excluded and the rest renormalize.
+# triad_weights: per-triad w_i for the TV metric; unlisted triads weigh 1.0.
+profiles:
+  python:
+    drift_weights:
+      hub_count:        0.15
+      star_count:       0.15
+      chain_len:        0.10
+      dag_depth:        0.10
+      router_count:     0.10
+      cycle_ratio:      0.25
+      unresolved_ratio: 0.15
+    layers:
+      imports: 0.35
+      calls:   0.35
+      gates:   0.30
+    triad_weights: {}
+  typescript:
+    drift_weights:
+      hub_count:        0.10
+      star_count:       0.10
+      chain_len:        0.10
+      dag_depth:        0.15
+      router_count:     0.10
+      cycle_ratio:      0.30
+      unresolved_ratio: 0.15
+    layers:
+      imports: 0.45
+      calls:   0.25
+      gates:   0.30
+    triad_weights: {}
+
+# ── Global hygiene invariants (spec §2.1) — hard gates, never distances ──────
+hygiene:
+  cycle_ratio:      {max: 0.0}
+  unresolved_ratio: {max: 0.2}
+  tangle_ratio:     {max: 0.25}
+
+# ── The closed alphabet: five templates (spec §2.1, §3.3) ────────────────────
+# ideal: hand-authored points in 13-triad space, one per layer, each summing
+# to 1.0. Counting constraints (hub/star/chain/router) are GONE — topology is
+# measured as TV distance to the ideal. Non-triad structural gates (dag_depth)
+# and template-specific hygiene remain as constraints.
+patterns:
+  pure_utility:
+    description: "Shared library called by many; depends on nothing"
+    ideal:
+      imports: {"021U": 1.0}
+      calls:   {"021U": 1.0}
+    unresolved_ratio: {max: 0.1}
+
+  pipeline_stage:
+    description: "Sequential transformer — one input domain, one output domain"
+    ideal:
+      imports: {"021C": 1.0}
+      calls:   {"021C": 1.0}
+
+  orchestrator:
+    description: "Coordinates N independent services; no leaf-to-leaf edges"
+    ideal:
+      imports: {"021D": 1.0}
+      calls:   {"021D": 1.0}
+
+  layered_dag:
+    description: "Clean layered architecture; no upward dependencies"
+    params:
+      min_depth: 3
+    ideal:
+      imports: {"021D": 0.5, "021C": 0.5}
+      calls:   {"021D": 0.5, "021C": 0.5}
+    dag_depth: {min: $min_depth}
+
+  dispatcher:
+    description: "Routes to the first matching strategy; mutually exclusive paths"
+    ideal:
+      imports: {"021D": 1.0}
+      calls:   {"021D": 1.0}
+
+  funnel:
+    # Transpose of layered_dag — fan-in with internal staging (#186).
+    description: "Convergent aggregation — many inputs funnel through staged sinks"
+    ideal:
+      imports: {"021U": 0.5, "021C": 0.5}
+      calls:   {"021U": 0.5, "021C": 0.5}
+
+"""
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_NO_FIT_THRESHOLD = 0.5
+_TS_EXTENSIONS = frozenset({".ts", ".tsx", ".js", ".jsx", ".vue"})
+
+# Parse the bundled header once at module load (used by _baseline_lines for the
+# hygiene block; template ranking now lives on DriftScorer.fit_templates).
+_PARSED_HEADER: dict[str, object] = yaml.safe_load(_DEFAULT_ONTOLOGY_HEADER)
+
+# Commented-out project_level skeleton appended after project_domains.
+_PROJECT_LEVEL_SKELETON = """\
+# project_level:  # quotient binding is an architectural decision — uncomment and tune:
+#   - name: "whole"
+#     fqn_prefix: "<collapse-prefix>"
+#     expected_pattern: pipeline_stage
+#     profile: python
+#     drift_tolerance: 0.50
+#     enforce: false
+"""
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+
+def _in_prefix(fqn: str, prefix: str) -> bool:
+    """Return True iff fqn equals prefix or is a child of it (segment-boundary-safe)."""
+    return fqn == prefix or fqn.startswith(prefix + ".")
+
+
+def _detect_profile(domain_nodes: list[Node]) -> tuple[str, bool]:
+    """Return (profile, guessed): majority file extension decides the profile.
+
+    Maps ``.py`` → ``python``; ``.ts``/``.tsx``/``.js``/``.jsx``/``.vue`` →
+    ``typescript``. Ties or unknown extensions fall back to ``("python", True)``
+    with a ``# profile guessed`` annotation.
+    """
+    py_count = 0
+    ts_count = 0
+    for n in domain_nodes:
+        ext = Path(n.file_path).suffix.lower()
+        if ext == ".py":
+            py_count += 1
+        elif ext in _TS_EXTENSIONS:
+            ts_count += 1
+
+    if py_count > ts_count:
+        return "python", False
+    if ts_count > py_count:
+        return "typescript", False
+    return "python", True
+
+
+def _fit_templates(
+    fp: PatternFingerprint,
+    profile: str,
+    scorer: DriftScorer,
+) -> list[tuple[str, float]]:
+    """Return ``[(template_name, fit_score)]`` sorted by (score, name).
+
+    Thin wrapper over ``DriftScorer.fit_templates`` — the canonical
+    distance-to-template, shared with fit-quality reporting (#177) so both
+    surfaces rank templates identically.
+    """
+    return scorer.fit_templates(fp, profile)
+
+
+def _ceil2(x: float) -> float:
+    """Ceil x to 2 decimal places (tolerance rounding — always rounds up)."""
+    return math.ceil(x * 100) / 100
+
+
+def _floor2(x: float) -> float:
+    """Floor x to 2 decimal places (min-constraint baseline rounding — always rounds down)."""
+    return math.floor(x * 100) / 100
+
+
+def _hygiene_score(
+    fp: PatternFingerprint, prefix: str, scorer: DriftScorer, profile: str | None
+) -> float:
+    """Return the hygiene drift score for a domain scored with the given profile.
+
+    Used to set tolerances for hygiene-only entries.  The profile MUST match the
+    one emitted into the YAML (detected by ``_detect_profile``): if ``profile``
+    differs from the emitted value the v1 drift_weights used to score
+    ``cycle_ratio`` and ``unresolved_ratio`` will diverge, breaking the
+    round-trip guarantee (spec §4.3) on domains that have cycles.
+    """
+    cfg = DomainConfig(
+        name=prefix,
+        fqn_prefix=prefix,
+        expected_pattern=None,
+        profile=profile,
+        drift_tolerance=1.0,
+    )
+    return scorer.score(fp, cfg).drift_score
+
+
+def _baseline_lines(
+    fp: PatternFingerprint,
+    hygiene: dict[str, object] | None = None,
+) -> list[str]:
+    """Return YAML lines for a ``hygiene_baseline:`` block, if any key breaches its global bound.
+
+    For each hygiene key, if the measured fingerprint value breaches the GLOBAL bound
+    (max → measured > bound; min → measured < bound; exact → skipped entirely),
+    the key is collected with an operator-correct rounded value.
+
+    Rounding is operator-aware (spec §2.2, #221 review):
+    - ``max`` constraints: round UP via ``_ceil2`` — a floored value below the true
+      measurement would gate_fail the proposal on its own graph (the round-trip guarantee).
+    - ``min`` constraints: round DOWN via ``_floor2`` — a ceiled value above the true
+      measurement would gate_fail the proposal on its own graph.
+    - ``exact`` constraints: SKIPPED — an exact-bound acknowledgment would pin the value
+      and re-fail on improvement; exact breaches remain visible as gate_failed in the
+      proposal and cannot be acknowledged by init-ontology by design.
+
+    ``hygiene``: optional parsed hygiene mapping (for testing); defaults to the bundled
+    ``_PARSED_HEADER["hygiene"]`` block when not supplied.
+    Returns an empty list when no key breaches its bound.
+    """
+    if hygiene is None:
+        _hygiene_obj = _PARSED_HEADER.get("hygiene") or {}
+        hygiene = _hygiene_obj if isinstance(_hygiene_obj, dict) else {}
+    items: list[str] = []
+    for key, constraint in hygiene.items():
+        if not isinstance(constraint, dict):
+            continue
+        measured = float(getattr(fp, key, 0.0))
+        if "max" in constraint and measured > float(constraint["max"]):
+            rounded = _ceil2(measured)
+            items.append(
+                f"      {key}: {rounded}"
+                "  # acknowledged at baseline by init-ontology — ratchet down over time"
+            )
+        elif "min" in constraint and measured < float(constraint["min"]):
+            rounded = _floor2(measured)
+            items.append(
+                f"      {key}: {rounded}"
+                "  # acknowledged at baseline by init-ontology — ratchet down over time"
+            )
+        # exact: skipped — pins value and would re-fail on improvement; unacknowledgeable by design.
+    return items
+
+
+def _domain_entry(
+    prefix: str,
+    all_nodes: list[Node],
+    extractor: FingerprintExtractor,
+    scorer: DriftScorer,
+    margin: float,
+    min_nodes: int,
+    name_is_unique: bool,
+) -> str:
+    """Return the YAML block string for one project domain entry.
+
+    Decision ladder (spec §2.1.5):
+    1. node_count < min_nodes → hygiene-only with census-too-small comment.
+    2. edge_count == 0 → hygiene-only with no-intra-domain-edges comment.
+    3. best fit > _NO_FIT_THRESHOLD → hygiene-only with no-template-fits comment.
+    4. Otherwise → labeled with expected_pattern, tolerance, and runner-up comment.
+
+    Tolerances for hygiene-only entries use the v1 hygiene score + margin.
+    Tolerances for labeled entries use the best-fit score + margin.
+    """
+    fp = extractor.extract(prefix)
+    domain_nodes = [
+        n for n in all_nodes if _in_prefix(n.id, prefix) and n.file_path != VIRTUAL_FILE_PATH
+    ]
+    profile, guessed = _detect_profile(domain_nodes)
+    fits = _fit_templates(fp, profile, scorer)
+    best_name, best = fits[0]
+    runner_name, runner = fits[1] if len(fits) > 1 else (fits[0][0], fits[0][1])
+
+    # name: last segment, or full prefix when it collides.
+    short_name = prefix.rsplit(".", maxsplit=1)[-1]
+    entry_name = short_name if name_is_unique else prefix
+
+    lines = [f'  - name: "{entry_name}"', f'    fqn_prefix: "{prefix}"']
+
+    profile_suffix = "  # profile guessed" if guessed else ""
+
+    # Hygiene-only reason, or None when the domain earns a template label.
+    if fp.node_count < min_nodes:
+        reason = f"# below min_nodes ({fp.node_count} nodes) — census too small to label"
+    elif fp.edge_count == 0:
+        reason = "# no intra-domain edges — nothing to fit"
+    elif best > _NO_FIT_THRESHOLD:
+        reason = f"# no template fits (best: {best_name} at {best:.2f})"
+    else:
+        reason = None
+
+    if reason is not None:
+        tolerance = _ceil2(_hygiene_score(fp, prefix, scorer, profile) + margin)
+        comment = reason
+    else:
+        tolerance = _ceil2(best + margin)
+        comment = (
+            f"# measured ≈ {best:.2f} via init-ontology"
+            f" (runner-up: {runner_name} at {runner:.2f}) — ratchet down over time"
+        )
+        lines.append(f"    expected_pattern: {best_name}")
+    lines.append(f"    profile: {profile}{profile_suffix}")
+    lines.append(f"    drift_tolerance: {tolerance:.2f}  {comment}")
+
+    # Emit hygiene_baseline for any measured value that breaches the GLOBAL hygiene bound
+    # (spec §2.2, #176/#170 task 4).  Applies to BOTH labeled and hygiene-only entries.
+    baseline_items = _baseline_lines(fp)
+    if baseline_items:
+        lines.append("    hygiene_baseline:")
+        lines.extend(baseline_items)
+
+    return "\n".join(lines)
+
+
+def _assemble_yaml(entries: list[str]) -> str:
+    """Concatenate the bundled header, generated project_domains, and skeleton comment."""
+    domain_block = "project_domains:\n" + "\n".join(entries) + "\n"
+    return _DEFAULT_ONTOLOGY_HEADER + domain_block + "\n" + _PROJECT_LEVEL_SKELETON
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def discover_domains(nodes: list[Node], depth: int | None = None) -> list[str]:
+    """Candidate domain prefixes from node FQNs (spec §2.1).
+
+    Auto-descent: walk down from the FQN roots while a level has a single
+    child; the first level with >= 2 children yields the candidates. An
+    explicit ``depth`` (segment count, >= 1) overrides auto-descent. Virtual
+    boundary nodes are excluded. Sorted, deduplicated.
+
+    A never-branching lineage yields its deepest id as the single candidate;
+    downstream min_nodes filtering keeps such micro-domains hygiene-only.
+
+    Raises:
+        ValueError: if ``depth`` is not ``None`` and is <= 0.
+    """
+    real_ids = [n.id for n in nodes if n.file_path != VIRTUAL_FILE_PATH]
+    if not real_ids:
+        return []
+    if depth is not None:
+        if depth <= 0:
+            msg = "depth must be a positive integer"
+            raise ValueError(msg)
+        return sorted(
+            {".".join(i.split(".")[:depth]) for i in real_ids if i.count(".") >= depth - 1}
+        )
+    prefix = ""
+    while True:
+        children = {
+            i[len(prefix) :].split(".")[0]
+            for i in real_ids
+            if i.startswith(prefix) and len(i) > len(prefix)
+        }
+        if not children:
+            # Never-branching lineage: the deepest id on this chain is the
+            # single candidate (downstream min_nodes will hygiene-fy it).
+            stub = prefix.removesuffix(".")
+            return [stub] if stub in set(real_ids) else []
+        if len(children) != 1:
+            break
+        prefix = f"{prefix}{next(iter(children))}."
+    return sorted({f"{prefix}{seg}" for seg in children})
+
+
+def propose_ontology(
+    db_path: str,
+    margin: float = 0.03,
+    min_nodes: int = 10,
+    depth: int | None = None,
+) -> str:
+    """Return a ready-to-edit patterns.yaml proposed from the measured graph.
+
+    Measure-then-label: discover candidate domain prefixes via ``discover_domains``,
+    fingerprint each with ``FingerprintExtractor``, fit against the five bundled
+    templates using ``DriftScorer`` (zero new fitting math), and emit YAML whose
+    ``drift_tolerance`` values equal the measured score plus ``margin`` — green by
+    construction when fed back to ``analyze_drift`` on the same graph.
+
+    Args:
+        db_path: Path to the SQLite graph database produced by ``cgis ingest``.
+        margin: Headroom added to every measured score when computing
+            ``drift_tolerance`` (default 0.03).
+        min_nodes: Domains with fewer real nodes than this threshold are
+            emitted as hygiene-only (no ``expected_pattern``).
+        depth: Fixed FQN segment depth for domain discovery; ``None`` triggers
+            auto-descent.
+
+    Returns:
+        YAML text — bundled header (profiles/patterns/hygiene) followed by
+        a generated ``project_domains:`` block.
+
+    Raises:
+        FileNotFoundError: if ``db_path`` does not exist (SQLite would
+            otherwise silently create an empty database).
+    """
+    if not Path(db_path).is_file():
+        msg = f"Graph database not found: {db_path}. Run `cgis ingest` first."
+        raise FileNotFoundError(msg)
+
+    # Write the bundled header to a temp file so DriftScorer can load it
+    # (its constructor strictly requires a path; we keep its surface unchanged).
+    # delete=False: the file persists after the context manager closes it so
+    # DriftScorer can read it; we unlink it explicitly in the finally block.
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".yaml", delete=False, encoding="utf-8"
+    ) as header_fd:
+        header_fd.write(_DEFAULT_ONTOLOGY_HEADER)
+        header_path = header_fd.name
+    try:
+        scorer = DriftScorer(header_path)
+
+        with SQLiteStore(db_path) as store:
+            all_nodes = store.get_all_nodes()
+            extractor = FingerprintExtractor(store)
+
+            prefixes = discover_domains(all_nodes, depth=depth)
+
+            # Detect name collisions: short names (last segment) that appear
+            # more than once across prefixes must use the full prefix as name:.
+            short_names = [p.rsplit(".", maxsplit=1)[-1] for p in prefixes]
+            name_counts = Counter(short_names)
+
+            entries = [
+                _domain_entry(
+                    prefix,
+                    all_nodes,
+                    extractor,
+                    scorer,
+                    margin,
+                    min_nodes,
+                    name_is_unique=(name_counts[prefix.rsplit(".", maxsplit=1)[-1]] == 1),
+                )
+                for prefix in prefixes
+            ]
+    finally:
+        Path(header_path).unlink(missing_ok=True)
+
+    return _assemble_yaml(entries)

cgis/query/drift/quotient.py

@@ -0,0 +1,75 @@
+"""Domain-quotient graph: collapse each domain to one node (spec §3.4).
+
+The quotient is scored by the SAME FingerprintExtractor + DriftScorer as
+module-level domains — that closure under coarsening is the point, not an
+implementation convenience.
+"""
+
+from collections import Counter
+
+from cgis.core.models import Edge, EdgeType, Node, NodeType
+from cgis.query.drift.drift import DomainConfig
+
+#: FQN prefix of quotient nodes; the project_level binding matches it.
+QUOTIENT_PREFIX = "quotient"
+
+_QUOTIENT_EDGE_TYPES = frozenset({EdgeType.IMPORTS, EdgeType.CALLS})
+
+
+def build_quotient(
+    nodes: list[Node], edges: list[Edge], domains: list[DomainConfig]
+) -> tuple[list[Node], list[Edge]]:
+    """Return (quotient_nodes, quotient_edges) for the given domain bindings.
+
+    One MODULE node per domain (id = quotient.<name>); cross-domain IMPORTS
+    and CALLS edges aggregate per (source domain, target domain, type) with
+    weight = aggregated edge count. Intra-domain edges and edges touching
+    nodes outside every domain are dropped (raw_call targets land here, so
+    the quotient's unresolved_ratio is 0 for the observe-only milestone —
+    recorded in tests/self_parsing/test_drift.py).
+    """
+    # Longest-prefix match: if one domain's prefix nests inside another's,
+    # the most specific binding wins regardless of declaration order.
+    by_specificity = sorted(domains, key=lambda d: len(d.fqn_prefix), reverse=True)
+    domain_of: dict[str, str] = {}
+    for n in nodes:
+        for d in by_specificity:
+            if n.id == d.fqn_prefix or n.id.startswith(d.fqn_prefix + "."):
+                domain_of[n.id] = d.name
+                break
+
+    qnodes = [
+        Node(
+            id=f"{QUOTIENT_PREFIX}.{d.name}",
+            type=NodeType.MODULE,
+            name=d.name,
+            file_path=d.fqn_prefix,
+            start_line=0,
+            end_line=0,
+        )
+        for d in domains
+    ]
+
+    counts: Counter[tuple[str, str, EdgeType]] = Counter(
+        (domain_of[e.source], domain_of[e.target], e.type)
+        for e in edges
+        if e.type in _QUOTIENT_EDGE_TYPES
+        and e.source in domain_of
+        and e.target in domain_of
+        and domain_of[e.source] != domain_of[e.target]
+    )
+
+    qedges = [
+        Edge(
+            id=f"{QUOTIENT_PREFIX}.{src}:{etype.value}:{QUOTIENT_PREFIX}.{dst}",
+            source=f"{QUOTIENT_PREFIX}.{src}",
+            target=f"{QUOTIENT_PREFIX}.{dst}",
+            type=etype,
+            weight=float(count),
+            confidence=1.0,
+        )
+        for (src, dst, etype), count in sorted(
+            counts.items(), key=lambda kv: (kv[0][0], kv[0][1], kv[0][2].value)
+        )
+    ]
+    return qnodes, qedges