continuum-code 0.2.0__py3-none-any.whl

continuum/engine.py

@@ -0,0 +1,214 @@
+"""Scope matcher and evaluator: match_scope() and evaluate()."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+from continuum.contracts import (
+    AskFirstContract,
+    BanContract,
+    ContinuumConfig,
+    Contract,
+    DefineContract,
+    RequireContract,
+)
+from continuum.change_summary import ChangeSummary
+
+
+def _path_matches(path: str, pattern: str) -> bool:
+    """Return True if path matches glob pattern (supports **)."""
+    path = path.replace("\\", "/")
+    pattern = pattern.replace("\\", "/")
+    if "**" not in pattern:
+        return fnmatch.fnmatch(path, pattern)
+    parts = pattern.split("**")
+    if len(parts) == 1:
+        return fnmatch.fnmatch(path, pattern)
+    start = parts[0].rstrip("/")
+    end = parts[-1].lstrip("/")
+    if start and not path.startswith(start if start.endswith("/") else start + "/"):
+        if not path.startswith(start):
+            return False
+    if end and not fnmatch.fnmatch(path, "*" + end):
+        return False
+    return True
+
+
+def _path_matches_any(path: str, patterns: list[str]) -> bool:
+    return any(_path_matches(path, p) for p in patterns)
+
+
+def _scope_applies_to_changes(scope_match_patterns: list[str], change_summary: ChangeSummary) -> bool:
+    """True if this scope applies to the change (any path or dep change considered for contract matching)."""
+    if not change_summary.paths_changed and not change_summary.deps_added and not change_summary.deps_removed:
+        return False
+    # Dependency changes apply to all scopes so dep-based contracts (e.g. ban) can fire
+    if change_summary.deps_added or change_summary.deps_removed:
+        return True
+    for path in change_summary.paths_changed:
+        if _path_matches_any(path, scope_match_patterns):
+            return True
+    return False
+
+
+def _match_diff_patterns(
+    diff_content: str, diff_patterns: list[str], max_offending_lines: int = 10
+) -> tuple[bool, list[str]]:
+    """Run regexes over unified diff; return (True, offending_lines) if any match. Bounded output."""
+    offending: list[str] = []
+    for pattern in diff_patterns:
+        try:
+            pat = re.compile(pattern)
+        except re.error:
+            continue
+        for line in diff_content.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("+") and not stripped.startswith("+++"):
+                if pat.search(line):
+                    offending.append(stripped[:200])  # bound line length
+                    if len(offending) >= max_offending_lines:
+                        return (True, offending)
+    return (bool(offending), offending)
+
+
+def _contract_match_applies(match, change_summary: ChangeSummary) -> bool:
+    """True if the contract's match applies to this change."""
+    if match.deps:
+        all_deps = set(change_summary.deps_added) | set(change_summary.deps_removed)
+        for d in match.deps:
+            for dep in all_deps:
+                if fnmatch.fnmatch(dep.lower(), d.lower()) or d.lower() in dep.lower():
+                    return True
+    if match.paths:
+        for path in change_summary.paths_changed:
+            if _path_matches_any(path, match.paths):
+                return True
+    if match.commands and change_summary.commands_requested:
+        for cmd in change_summary.commands_requested:
+            for pat in match.commands:
+                if fnmatch.fnmatch(cmd, pat) or pat in cmd:
+                    return True
+    if match.patterns:
+        for path in change_summary.paths_changed:
+            for pat in match.patterns:
+                if fnmatch.fnmatch(path, pat):
+                    return True
+    if getattr(match, "diff_patterns", None) and change_summary.diff_content:
+        hit, _ = _match_diff_patterns(change_summary.diff_content, match.diff_patterns)
+        if hit:
+            return True
+    return False
+
+
+def match_scope(config: ContinuumConfig, change_summary: ChangeSummary) -> list[tuple[str, Contract]]:
+    """Return applicable (scope_id, contract) ordered by precedence (higher first). Excludes define (metadata)."""
+    applicable: list[tuple[int, str, Contract]] = []
+    for scope in config.scopes:
+        if not _scope_applies_to_changes(scope.match, change_summary):
+            continue
+        for contract in scope.contracts:
+            if isinstance(contract, DefineContract):
+                continue
+            if not _contract_match_applies(contract.match, change_summary):
+                continue
+            applicable.append((scope.precedence, scope.id, contract))
+    applicable.sort(key=lambda x: (-x[0], x[1], getattr(x[2], "id", "")))
+    return [(scope_id, c) for _, scope_id, c in applicable]
+
+
+@dataclass
+class FiredRule:
+    contract_id: str
+    scope_id: str
+    message: str
+    contract_type: str
+    prompt: str | None = None
+    options: list[str] | None = None
+    offending_lines: list[str] = field(default_factory=list)
+
+
+class EnforcementResult:
+    """Result of evaluate(): status and list of fired rules."""
+
+    status: Literal["allowed", "warn", "blocked", "clarification_required"]
+    fired: list[FiredRule]
+
+    def __init__(
+        self,
+        status: Literal["allowed", "warn", "blocked", "clarification_required"],
+        fired: list[FiredRule] | None = None,
+    ):
+        self.status = status
+        self.fired = fired or []
+
+
+def _require_satisfied(contract: RequireContract, change_summary: ChangeSummary) -> bool:
+    """For kind=tests: require that some test path was touched when src was touched. Uses test_globs if set."""
+    for spec in contract.require:
+        if spec.kind == "tests":
+            if getattr(contract, "test_globs", None):
+                has_test_change = any(
+                    _path_matches_any(p, contract.test_globs) for p in change_summary.paths_changed
+                )
+            else:
+                test_indicators = ("test", "tests", "_test", "spec.", "specs/")
+                has_test_change = any(
+                    any(ind in p for ind in test_indicators) for p in change_summary.paths_changed
+                )
+            if not has_test_change and contract.match.paths:
+                matching = [p for p in change_summary.paths_changed if _path_matches_any(p, contract.match.paths)]
+                if matching:
+                    return False  # src changed but no test change
+        # logging / ADR: v0.1 we don't check content; consider satisfied if paths match and we have changes
+    return True
+
+
+def evaluate(contracts_with_scope: list[tuple[str, Contract]], change_summary: ChangeSummary) -> EnforcementResult:
+    """Evaluate ordered (scope_id, contract) against the change. First blocking/clarification wins."""
+    fired: list[FiredRule] = []
+    for scope_id, contract in contracts_with_scope:
+        if isinstance(contract, BanContract):
+            if _contract_match_applies(contract.match, change_summary):
+                offending: list[str] = []
+                if getattr(contract.match, "diff_patterns", None) and change_summary.diff_content:
+                    _, offending = _match_diff_patterns(
+                        change_summary.diff_content, contract.match.diff_patterns
+                    )
+                fired.append(FiredRule(
+                    contract_id=contract.id,
+                    scope_id=scope_id,
+                    message=contract.message,
+                    contract_type="ban",
+                    offending_lines=offending,
+                ))
+                return EnforcementResult(status="blocked", fired=fired)
+        elif isinstance(contract, RequireContract):
+            if _contract_match_applies(contract.match, change_summary) and not _require_satisfied(contract, change_summary):
+                hint = contract.hint or (contract.require[0].hint if contract.require else "Satisfy the requirement.")
+                severity = getattr(contract, "severity", "block")
+                fired.append(FiredRule(
+                    contract_id=contract.id,
+                    scope_id=scope_id,
+                    message=hint,
+                    contract_type="require",
+                ))
+                if severity == "block":
+                    return EnforcementResult(status="blocked", fired=fired)
+                # severity == "warn": continue evaluating; we'll return warn at the end if nothing else fires
+        elif isinstance(contract, AskFirstContract):
+            if _contract_match_applies(contract.match, change_summary):
+                fired.append(FiredRule(
+                    contract_id=contract.id,
+                    scope_id=scope_id,
+                    message=contract.prompt,
+                    contract_type="ask_first",
+                    prompt=contract.prompt,
+                    options=contract.options,
+                ))
+                return EnforcementResult(status="clarification_required", fired=fired)
+    if fired:
+        return EnforcementResult(status="warn", fired=fired)
+    return EnforcementResult(status="allowed", fired=fired)

continuum/mcp_server.py

@@ -0,0 +1,127 @@
+"""MCP server exposing continuum.check, continuum.explain, continuum.ask_first for Cursor/agents."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from continuum.contracts import load_config, normalize_for_stable_ids
+from continuum.change_summary import from_plan
+from continuum.engine import match_scope, evaluate, EnforcementResult
+
+
+# Module-level state for "last result" so explain/ask_first can use it
+_last_result: tuple[EnforcementResult, Path] | None = None
+
+
+def _find_config() -> Path | None:
+    p = Path.cwd()
+    for _ in range(10):
+        if (p / "continuum.yaml").exists():
+            return p / "continuum.yaml"
+        if (p / "continuum.yml").exists():
+            return p / "continuum.yml"
+        if p.parent == p:
+            break
+        p = p.parent
+    return None
+
+
+mcp = FastMCP(
+    "continuum",
+    description="Continuum rule engine: check plans against repo rules, explain fired rules, get clarification prompts.",
+)
+
+
+@mcp.tool()
+def continuum_check(plan: dict) -> str:
+    """Check a plan (paths_changed, deps_added, deps_removed, commands_requested) against repo rules.
+    Returns JSON with status: allowed | warn | blocked | clarification_required, and fired rules if any."""
+    global _last_result
+    cfg_path = _find_config()
+    if not cfg_path or not cfg_path.exists():
+        return json.dumps({"error": "No continuum.yaml found. Run continuum init first.", "status": "error"})
+    config = load_config(cfg_path)
+    config = normalize_for_stable_ids(config)
+    change_summary = from_plan(plan)
+    contracts_with_scope = match_scope(config, change_summary)
+    result = evaluate(contracts_with_scope, change_summary)
+    _last_result = (result, cfg_path)
+    out = {
+        "status": result.status,
+        "fired": [
+            {
+                "contract_id": r.contract_id,
+                "scope_id": r.scope_id,
+                "message": r.message,
+                "contract_type": r.contract_type,
+                "prompt": r.prompt,
+                "options": r.options,
+                "offending_lines": getattr(r, "offending_lines", None) or [],
+            }
+            for r in result.fired
+        ],
+    }
+    return json.dumps(out, indent=2)
+
+
+@mcp.tool()
+def continuum_explain(contract_id: str | None = None) -> str:
+    """Explain why a rule fired and how to fix. Use contract_id from a previous check, or omit to explain last check result."""
+    global _last_result
+    cfg_path = _find_config()
+    if not cfg_path or not cfg_path.exists():
+        return json.dumps({"error": "No continuum.yaml found."})
+    config = load_config(cfg_path)
+    if contract_id:
+        for scope in config.scopes:
+            for c in scope.contracts:
+                if getattr(c, "id", None) == contract_id:
+                    return json.dumps({
+                        "contract_id": contract_id,
+                        "scope_id": scope.id,
+                        "type": c.type,
+                        "message": getattr(c, "message", None) or getattr(c, "hint", None),
+                        "prompt": getattr(c, "prompt", None),
+                        "hint": getattr(c, "hint", None),
+                    }, indent=2)
+        return json.dumps({"error": f"No contract with id {contract_id!r}."})
+    if _last_result is None:
+        return json.dumps({"error": "No previous check result. Run continuum_check first."})
+    result, _ = _last_result
+    if not result.fired:
+        return json.dumps({"message": "Last check had no fired rules.", "status": result.status})
+    explanations = []
+    for r in result.fired:
+        explanations.append({
+            "contract_id": r.contract_id,
+            "scope_id": r.scope_id,
+            "type": r.contract_type,
+            "message": r.message,
+            "prompt": r.prompt,
+            "options": r.options,
+            "offending_lines": getattr(r, "offending_lines", None) or [],
+        })
+    return json.dumps({"status": result.status, "fired": explanations}, indent=2)
+
+
+@mcp.tool()
+def continuum_ask_first(prompt: str, options: list[str] | None = None) -> str:
+    """Get the clarification prompt and options to present to the user. The agent should show these to the user and get their selection; then revise the plan or proceed accordingly.
+    Returns the same prompt and options (for the client to display). User selection is done in conversation."""
+    return json.dumps({
+        "prompt": prompt,
+        "options": options or [],
+        "instruction": "Present the prompt and options to the user; use their selection to decide intent (e.g. add-only, destructive, refactor) and proceed or revise the plan.",
+    }, indent=2)
+
+
+def run_mcp_server(transport: str = "stdio") -> None:
+    """Run the MCP server. Default stdio for Cursor."""
+    mcp.run(transport=transport)
+
+
+if __name__ == "__main__":
+    run_mcp_server()

continuum/packs/data-dbt-airflow/README.md

@@ -0,0 +1,42 @@
+# data-dbt-airflow pack
+
+Starter Continuum config for repos that use **dbt** and **Apache Airflow**. Enforces rules so agents don’t change marts without tests, don’t touch DAGs without confirmation, and don’t embed risky commands (e.g. `dbt run --full-refresh`, `airflow backfill`).
+
+## 5-minute adoption (dbt + Airflow repos)
+
+1. **Install Continuum** (from repo or PyPI):
+   ```bash
+   pip install -e .   # or: pip install continuum-code
+   ```
+
+2. **Bootstrap config from this pack:**
+   ```bash
+   continuum init --pack data-dbt-airflow
+   ```
+   This writes `continuum.yaml` at the repo root.
+
+3. **Validate the file:**
+   ```bash
+   continuum validate
+   ```
+
+4. **Run a check** (e.g. on your current diff):
+   ```bash
+   continuum check
+   continuum check --base origin/main   # for PRs
+   ```
+
+5. **Wire CI** (GitHub Actions): add the Continuum check action with `base_ref` set to the PR base so every PR is evaluated.
+
+6. **Optional – Cursor/MCP:** Run `continuum mcp --transport stdio` and add the MCP server to Cursor so agents call `continuum_check(plan)` before applying changes.
+
+## What this pack enforces
+
+- **dbt**
+  - **ask_first** on `models/marts/**`: you must confirm additive / breaking / refactor-only.
+  - **require tests** on `models/marts/**`: changes to marts should include or update tests. You can set `severity: warn` on that contract in your repo’s `continuum.yaml` so missing tests are reported but do not block.
+- **Airflow**
+  - **ask_first** on `dags/**`: confirm when changing schedule/retry/SLA.
+  - **ban** on risky commands (e.g. `full-refresh`, `backfill`, `clear`) in matched content; MCP and (after Phase 2) CI/local check will enforce.
+
+Adjust paths or add scopes in `continuum.yaml` to match your layout (e.g. different marts path or extra dbt dirs).

continuum/packs/data-dbt-airflow/continuum.yaml

@@ -0,0 +1,42 @@
+version: 0.1
+scopes:
+  - id: repo
+    match: ["**/*"]
+    contracts:
+      - type: define
+        key: prod_ready
+        value: "dbt models tested; DAG changes reviewed; no full-refresh or backfill in code"
+
+  - id: dbt
+    match: ["dbt_project.yml", "models/**", "macros/**", "snapshots/**"]
+    precedence: 10
+    contracts:
+      - type: ask_first
+        id: confirm_marts
+        match:
+          paths: ["models/marts/**"]
+        prompt: "Touching dbt marts. Confirm intent: (A) additive (B) breaking (C) refactor-only"
+        options: ["additive", "breaking", "refactor-only"]
+      - type: require
+        id: require_tests_marts
+        match:
+          paths: ["models/marts/**"]
+        require:
+          - kind: tests
+            hint: "Add or update dbt tests for changed marts models."
+
+  - id: airflow
+    match: ["dags/**"]
+    precedence: 10
+    contracts:
+      - type: ask_first
+        id: confirm_dag_changes
+        match:
+          paths: ["dags/**"]
+        prompt: "Touching DAGs (schedule/retry/SLA). Confirm you intend to change orchestration."
+        options: ["yes", "no"]
+      - type: ban
+        id: ban_risky_commands
+        match:
+          commands: ["*full-refresh*", "*backfill*", "*clear*"]
+        message: "Risky commands (dbt full-refresh, airflow backfill/clear) must not be embedded in DAGs; use parameterized runs or manual approval."

continuum/packs/node-backend/continuum.yaml

@@ -0,0 +1,29 @@
+version: 0.1
+scopes:
+  - id: repo
+    match: ["**/*"]
+    contracts:
+      - type: define
+        key: prod_ready
+        value: "tests + error handling + logging; no banned deps"
+      - type: ban
+        id: ban_lodash
+        match:
+          deps: ["lodash"]
+        message: "Use native JS or approved utils."
+  - id: backend
+    match: ["src/**", "lib/**", "server/**"]
+    precedence: 10
+    contracts:
+      - type: require
+        id: require_tests
+        match:
+          paths: ["src/**", "lib/**", "server/**"]
+        require:
+          - kind: tests
+            hint: "Add or adjust unit tests for changed modules."
+      - type: ask_first
+        id: confirm_migrations
+        match:
+          paths: ["**/migrations/**", "**/schema/**"]
+        prompt: "This touches migrations/schema. Confirm: (A) add-only (B) destructive (C) refactor"

continuum/packs/python-fastapi/continuum.yaml

@@ -0,0 +1,29 @@
+version: 0.1
+scopes:
+  - id: repo
+    match: ["**/*"]
+    contracts:
+      - type: define
+        key: prod_ready
+        value: "tests + error handling + logging + metrics; migrations need a plan"
+      - type: ban
+        id: ban_requests
+        match:
+          deps: ["requests"]
+        message: "Use httpx for async HTTP in FastAPI."
+  - id: backend
+    match: ["app/**", "src/**", "backend/**"]
+    precedence: 10
+    contracts:
+      - type: require
+        id: require_tests
+        match:
+          paths: ["app/**", "src/**", "backend/**"]
+        require:
+          - kind: tests
+            hint: "Add or adjust tests for changed modules (pytest)."
+      - type: ask_first
+        id: confirm_migrations
+        match:
+          paths: ["**/migrations/**", "**/alembic/**", "**/schema/**"]
+        prompt: "This touches migrations/schema. Confirm: (A) add-only (B) destructive (C) refactor"

continuum/packs/typescript-monorepo/continuum.yaml

@@ -0,0 +1,29 @@
+version: 0.1
+scopes:
+  - id: repo
+    match: ["**/*"]
+    contracts:
+      - type: define
+        key: prod_ready
+        value: "tests + error handling + logging; use workspace packages"
+      - type: ban
+        id: ban_lodash
+        match:
+          deps: ["lodash"]
+        message: "Use native JS/TS or workspace utils."
+  - id: packages
+    match: ["packages/**"]
+    precedence: 10
+    contracts:
+      - type: require
+        id: require_tests
+        match:
+          paths: ["packages/**/src/**"]
+        require:
+          - kind: tests
+            hint: "Add or adjust tests when changing package src."
+      - type: ask_first
+        id: confirm_migrations
+        match:
+          paths: ["**/migrations/**", "**/schema/**"]
+        prompt: "This touches migrations/schema. Confirm: (A) add-only (B) destructive (C) refactor"

continuum/recommend.py

@@ -0,0 +1,63 @@
+"""Recommend: suggest policy changes from .continuum/state.json. Never auto-writes."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def state_path(repo_root: str | Path) -> Path:
+    return Path(repo_root) / ".continuum" / "state.json"
+
+
+def load_state(repo_root: str | Path) -> dict:
+    path = state_path(repo_root)
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def recommend(repo_root: str | Path) -> list[str]:
+    """Produce suggested YAML/policy changes from state. Never writes. Returns list of suggestion strings."""
+    state = load_state(repo_root)
+    suggestions: list[str] = []
+    results = state.get("check_results") or []
+    choices = state.get("choices") or []
+    # If user always chose same option for an ask_first contract, suggest encoding default
+    by_contract: dict[str, list[str]] = {}
+    for c in choices:
+        cid = c.get("contract_id") or ""
+        choice = c.get("choice") or ""
+        if cid:
+            by_contract.setdefault(cid, []).append(choice)
+    for cid, opts in by_contract.items():
+        if len(opts) >= 2 and len(set(opts)) == 1:
+            suggestions.append(
+                f"You always choose '{opts[0]}' for {cid} → consider adding options/default in continuum.yaml"
+            )
+    # If we had repeated warnings that were later fixed, suggest block
+    warn_count = sum(1 for r in results if r.get("status") == "warn")
+    if warn_count >= 3:
+        suggestions.append(
+            "Multiple 'warn' outcomes in history → consider severity: block for stricter rules"
+        )
+    # If repeated violations in a path, suggest ask_first
+    fired_paths: list[str] = []
+    for r in results:
+        for f in r.get("fired") or []:
+            sid = f.get("scope_id") or ""
+            if sid:
+                fired_paths.append(sid)
+    if len(fired_paths) >= 2:
+        from collections import Counter
+        most = Counter(fired_paths).most_common(1)
+        if most and most[0][1] >= 2:
+            suggestions.append(
+                f"Repeated violations in scope '{most[0][0]}' → consider adding ask_first for those paths"
+            )
+    if not suggestions:
+        suggestions.append("No suggestions from state yet. Run continuum check a few times and use ask_first choices.")
+    return suggestions