refactorai-core 3.2.2__tar.gz → 3.2.3__tar.gz

{refactorai_core-3.2.2 → refactorai_core-3.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-core
-Version: 3.2.2
+Version: 3.2.3
 Summary: Public client core for the refactor platform: indexing, constitution parsing, models, gate evaluation, rules, security prefilter, RR/compliance classification. Contains no proprietary inference engine.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{refactorai_core-3.2.2 → refactorai_core-3.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "refactorai-core"
-version = "3.2.2"
+version = "3.2.3"
 description = "Public client core for the refactor platform: indexing, constitution parsing, models, gate evaluation, rules, security prefilter, RR/compliance classification. Contains no proprietary inference engine."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -38,6 +38,7 @@ include = [
   "refactor_core.security",
   "refactor_core.compliance",
   "refactor_core.compliance.packs",
+  "refactor_core.intent",
 ]
 # Defensive: never ship engine subpackages in the public client wheel even if a
 # future refactor accidentally makes one discoverable.

{refactorai_core-3.2.2 → refactorai_core-3.2.3}/refactor_core/__init__.py

@@ -24,4 +24,4 @@ __all__ = [
     "__version__",
 ]
 
-__version__ = "3.2.2"
+__version__ = "3.2.3"

refactorai_core-3.2.3/refactor_core/intent/__init__.py

@@ -0,0 +1,36 @@
+"""Shared, pure intent-capture and contract-normalization primitives (`R27`/`R28`).
+
+Single source of truth for the deterministic intent math used by both the server
+(`backend/app/services/intent*.py`) and the local commit-scoped review loop
+(docs/41). Everything here is provider- and storage-independent.
+"""
+
+from refactor_core.intent.capture import (
+    build_payload,
+    derive_contract,
+    extract_statements,
+    summarize_intent,
+)
+from refactor_core.intent.contract import (
+    ELEVATED_RISK_TIERS,
+    STRUCTURAL_ASSERTIONS,
+    compute_content_hash,
+    infer_verifier,
+    normalize_contract_input,
+    required_permission_for_risk_tier,
+    summarize_verdicts,
+)
+
+__all__ = [
+    "build_payload",
+    "derive_contract",
+    "extract_statements",
+    "summarize_intent",
+    "ELEVATED_RISK_TIERS",
+    "STRUCTURAL_ASSERTIONS",
+    "compute_content_hash",
+    "infer_verifier",
+    "normalize_contract_input",
+    "required_permission_for_risk_tier",
+    "summarize_verdicts",
+]

refactorai_core-3.2.3/refactor_core/intent/capture.py

@@ -0,0 +1,296 @@
+"""Deterministic implicit intent capture (docs/39 FR-01, Part D INTENT CAPTURE).
+
+Intent does **not** have to be authored by hand. This module derives the same
+canonical acceptance-criteria structure an explicit contract produces from the
+free-form context that already surrounds a change:
+
+- a coding agent's prompt (Cursor / Claude Code) submitted at trigger time,
+- a commit message (local commit trigger, docs/41 `R28`),
+- a pull-request title/description (webhook path),
+- a linked ticket, or a design/spec doc.
+
+The derived structure is fed through :func:`contract.normalize_contract_input`,
+so capture shares one normalization/keying/verifier-routing path with explicit
+contracts, on both the server and the local CLI.
+
+Design constraints:
+
+- **Deterministic and provider-independent.** No LLM call, so every execution
+  mode behaves identically and the extractor is fully unit-testable. Richer LLM
+  extraction can layer on later behind the same ``derive_contract`` interface.
+- **Never fabricate a verified verdict.** Extraction only *captures* criteria;
+  structural ones route to the deterministic ``code-scan`` verifier, everything
+  else stays ``behavioral`` (recorded, escalatable) rather than silently passing
+  (docs/39 Part C hard boundary).
+"""
+
+from __future__ import annotations
+
+import re
+
+from refactor_core.intent import contract as contract_mod
+
+# A statement looks like a requirement when it carries an imperative/modal verb.
+_MODAL = re.compile(
+    r"\b(must|should|shall|need(?:s)? to|has to|have to|will|ensure|add|adds|"
+    r"implement|implements|introduce|create|creates|fix|fixes|support|supports|"
+    r"expose|exposes|return|returns|handle|handles|remove|removes|rename|renames|"
+    r"update|updates|allow|allows|prevent|prevents|validate|validates|require|"
+    r"requires|guarantee|guarantees|enforce|enforces)\b",
+    re.IGNORECASE,
+)
+
+# Section headers that flip parsing into "these bullets are non-goals".
+_NON_GOAL_HINT = re.compile(r"\b(non[-\s]?goals?|out[-\s]?of[-\s]?scope|not in scope|will not)\b", re.IGNORECASE)
+# Section headers that mark an explicit list of acceptance criteria.
+_CRITERIA_HINT = re.compile(
+    r"\b(acceptance criteri\w+|requirements?|criteria|tasks?|checklist|to[-\s]?do)\b", re.IGNORECASE
+)
+
+_BULLET = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]?\]\s+)?(.*\S)\s*$")
+_HEADER = re.compile(r"^\s*(?:#{1,6}\s*|\*\*)\s*(.+?)\s*(?:\*\*)?\s*:?\s*$")
+_QUOTED = re.compile(r"`([^`]+)`|\"([^\"]+)\"|'([^']+)'")
+_BARE_PATH = re.compile(r"(?<![\w./-])([\w./-]+\.[A-Za-z0-9]{1,6})(?![\w/])")
+_CONTAINS_VERB = re.compile(
+    r"\b(contain|contains|mention|mentions|include|includes|reference|references|say|says|document|documents)\b",
+    re.IGNORECASE,
+)
+
+_MAX_CRITERIA = 12
+_MAX_STATEMENT = 200
+
+
+def _looks_like_path(token: str) -> bool:
+    token = (token or "").strip()
+    if not token or " " in token or "\t" in token:
+        return False
+    if not re.fullmatch(r"[\w./@+-]+", token):
+        return False
+    return "/" in token or bool(re.search(r"\.[A-Za-z0-9]{1,6}$", token))
+
+
+def _find_path(statement: str) -> str:
+    """Return the first path-like token mentioned in a statement, else ``""``."""
+    for match in _QUOTED.finditer(statement):
+        token = next((g for g in match.groups() if g), "")
+        if _looks_like_path(token):
+            return token.strip().lstrip("/")
+    bare = _BARE_PATH.search(statement)
+    if bare and _looks_like_path(bare.group(1)):
+        return bare.group(1).strip().lstrip("/")
+    return ""
+
+
+def _detect_structural(statement: str) -> tuple[str, str, str, str]:
+    """Classify a statement into (kind, assertion, path, expected).
+
+    A statement that names a concrete file/path is treated as a deterministically
+    checkable structural criterion; if it also asks for that file to *contain* a
+    quoted term it becomes ``path_contains``. Everything else is ``behavioral``
+    (routed to the runtime verifier, escalatable, never silently passed).
+    """
+    path = _find_path(statement)
+    if not path:
+        return "behavioral", "", "", ""
+
+    if _CONTAINS_VERB.search(statement):
+        for match in _QUOTED.finditer(statement):
+            token = next((g for g in match.groups() if g), "").strip()
+            if token and token.lstrip("/") != path and not _looks_like_path(token):
+                return "structural", "path_contains", path, token
+    return "structural", "path_exists", path, ""
+
+
+def _clean_statement(text: str) -> str:
+    text = re.sub(r"\s+", " ", (text or "").strip())
+    text = text.rstrip(".;")
+    return text[:_MAX_STATEMENT].strip()
+
+
+def _sentences(line: str) -> list[str]:
+    # Split a prose line into candidate requirement sentences.
+    parts = re.split(r"(?<=[.!?])\s+", line.strip())
+    return [p for p in (part.strip() for part in parts) if p]
+
+
+def extract_statements(text: str) -> tuple[list[str], list[str]]:
+    """Extract (criterion statements, non-goal statements) from one text blob.
+
+    Bullet/checklist lines become criteria (or non-goals under a non-goal
+    heading); free prose contributes sentences that carry a modal/imperative verb.
+    """
+    if not text:
+        return [], []
+
+    criteria: list[str] = []
+    non_goals: list[str] = []
+    section = "body"  # body | non_goal | criteria
+
+    for raw in str(text).splitlines():
+        line = raw.rstrip()
+        if not line.strip():
+            continue
+
+        bullet = _BULLET.match(line)
+        header = None if bullet else _HEADER.match(line)
+
+        if header:
+            label = header.group(1)
+            if _NON_GOAL_HINT.search(label):
+                section = "non_goal"
+            elif _CRITERIA_HINT.search(label):
+                section = "criteria"
+            else:
+                section = "body"
+            continue
+
+        if bullet:
+            content = _clean_statement(bullet.group(1))
+            if not content:
+                continue
+            if section == "non_goal":
+                non_goals.append(content)
+            else:
+                criteria.append(content)
+            continue
+
+        # Non-bullet prose: harvest imperative sentences (and non-goals when the
+        # current section says so).
+        for sentence in _sentences(line):
+            if section == "non_goal":
+                non_goals.append(_clean_statement(sentence))
+            elif _MODAL.search(sentence):
+                criteria.append(_clean_statement(sentence))
+
+    return [c for c in criteria if c], [n for n in non_goals if n]
+
+
+def _dedupe(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for value in values:
+        key = value.lower()
+        if key and key not in seen:
+            seen.add(key)
+            ordered.append(value)
+    return ordered
+
+
+def _source_label(sources: list[dict]) -> str:
+    kinds = {str(s.get("type", "") or "").strip().lower() for s in sources if str(s.get("type", "") or "").strip()}
+    if len(kinds) == 1:
+        return next(iter(kinds))
+    return "derived"
+
+
+def _title_from(sources: list[dict], statements: list[str]) -> str:
+    for source in sources:
+        title = str(source.get("title", "") or "").strip()
+        if title:
+            return title[:_MAX_STATEMENT]
+    for source in sources:
+        for line in str(source.get("text", "") or "").splitlines():
+            stripped = line.strip().lstrip("#").strip()
+            if stripped:
+                return _clean_statement(stripped)
+    return statements[0] if statements else ""
+
+
+def build_payload(sources: list[dict]) -> dict | None:
+    """Build a raw intent-contract *input* payload from free-form sources.
+
+    Returns the payload shape consumed by
+    :func:`contract.normalize_contract_input` (or ``None`` when nothing usable
+    was found). Kept separate from :func:`derive_contract` so it is trivially
+    unit-testable without touching the normalization layer.
+    """
+    if not sources:
+        return None
+
+    # Keep first-seen provenance for each distinct statement so every derived
+    # criterion stays auditable even when we aggregate multiple source types.
+    all_criteria: list[tuple[str, str, str]] = []
+    all_non_goals: list[str] = []
+    for source in sources:
+        source_type = str(source.get("type", "derived") or "derived").strip().lower() or "derived"
+        source_ref = str(source.get("ref", "") or "").strip()
+        source_title = str(source.get("title", "") or "").strip()
+        source_text = str(source.get("text", "") or "").strip()
+        # Parse both title and body: webhook PR events and commit subjects often
+        # encode intent in the title while the body may be empty/minimal.
+        merged_text = "\n".join(part for part in [source_title, source_text] if part)
+        crit, non_goals = extract_statements(merged_text)
+        for statement in crit:
+            all_criteria.append((statement, source_type, source_ref))
+        all_non_goals.extend(non_goals)
+
+    statement_provenance: dict[str, tuple[str, str]] = {}
+    statements: list[str] = []
+    for statement, source_type, source_ref in all_criteria:
+        key = statement.lower()
+        if key in statement_provenance:
+            continue
+        statement_provenance[key] = (source_type, source_ref)
+        statements.append(statement)
+        if len(statements) >= _MAX_CRITERIA:
+            break
+    non_goals = _dedupe(all_non_goals)[:_MAX_CRITERIA]
+    title = _title_from(sources, statements)
+
+    if not title and not statements:
+        return None
+
+    label = _source_label(sources)
+    criteria: list[dict] = []
+    for index, statement in enumerate(statements, start=1):
+        kind, assertion, path, expected = _detect_structural(statement)
+        source_type, source_ref = statement_provenance.get(statement.lower(), (label, ""))
+        note = f"derived from {source_type}"
+        if source_ref:
+            note = f"{note} ({source_ref})"
+        criteria.append(
+            {
+                "id": f"criterion-{index}",
+                "statement": statement,
+                "kind": kind,
+                "risk_tier": "standard",
+                "assert": assertion,
+                "path": path,
+                "contains": expected,
+                "notes": note,
+            }
+        )
+
+    return {"title": title, "source": label, "non_goals": non_goals, "criteria": criteria}
+
+
+def derive_contract(sources: list[dict] | None) -> dict | None:
+    """Derive a canonical intent contract from free-form authoring context.
+
+    ``sources`` is a list of ``{type, title, text, ref}`` dicts. Returns the
+    canonical structure (same shape as an explicitly-submitted contract), or
+    ``None`` when no intent could be derived (callers treat that as the
+    non-blocking "no intent" case).
+    """
+    payload = build_payload([s for s in (sources or []) if isinstance(s, dict)])
+    if payload is None:
+        return None
+    return contract_mod.normalize_contract_input(payload)
+
+
+def summarize_intent(canonical: dict | None) -> str:
+    """One-line human summary of a derived contract for terminal display (R28).
+
+    Prefers the contract title, else the first criterion statement; returns an
+    empty string when there is no usable intent.
+    """
+    if not isinstance(canonical, dict):
+        return ""
+    title = str(canonical.get("title", "") or "").strip()
+    if title:
+        return title[:_MAX_STATEMENT]
+    for criterion in canonical.get("criteria", []) or []:
+        statement = str((criterion or {}).get("statement", "") or "").strip()
+        if statement:
+            return statement[:_MAX_STATEMENT]
+    return ""

refactorai_core-3.2.3/refactor_core/intent/contract.py

@@ -0,0 +1,154 @@
+"""Pure intent-contract normalization and verdict aggregation (docs/39 `R27`).
+
+This is the single, provider- and storage-independent implementation of the
+intent-contract math shared by the server (`backend/app/services/intent.py`) and
+the local CLI (docs/41 `R28`). It contains only pure functions over plain dicts:
+
+- ``normalize_contract_input`` coerces a raw payload into a canonical,
+  deterministically-keyed structure (shared shape for persistence and the local
+  commit-scoped review).
+- ``_infer_verifier`` routes a criterion to exactly one verifier.
+- ``compute_content_hash`` produces a stable hash over the canonical contract.
+- ``summarize_verdicts`` aggregates per-criterion verdicts into a gate decision.
+
+No database, no execution mode, no provider selection — so ``local`` /
+``cloud_managed`` / ``cloud_byok`` behave identically wherever this is imported.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+# Structural assertions the deterministic ``code-scan`` verifier understands.
+STRUCTURAL_ASSERTIONS = {"path_exists", "path_contains"}
+
+# Criteria that carry organizational risk require elevated permission to amend
+# (docs/39 FR-08). Kept here so the risk vocabulary has one definition.
+ELEVATED_RISK_TIERS = {"high", "security", "compliance"}
+
+_VALID_RISK_TIERS = {"standard", "high", "security", "compliance"}
+
+
+def infer_verifier(kind: str, assertion: str) -> str:
+    """Route a criterion to exactly one verifier (docs/39 FR-03).
+
+    Only the deterministic ``code-scan`` verifier is implemented for structural
+    criteria; behavioral criteria route to ``runtime`` (recorded, escalatable,
+    never silently passed); anything else is ``pending``.
+    """
+    if kind == "structural" and assertion in STRUCTURAL_ASSERTIONS:
+        return "code-scan"
+    if kind == "behavioral":
+        return "runtime"
+    return "pending"
+
+
+# Backwards-compatible private alias (backend historically referenced the
+# underscore-prefixed name).
+_infer_verifier = infer_verifier
+
+
+def normalize_contract_input(payload: dict | None) -> dict | None:
+    """Coerce a raw intent payload into a canonical contract structure.
+
+    Returns ``None`` when no meaningful contract was supplied (no criteria and no
+    title), so callers can treat "no intent" as a first-class, non-blocking case.
+    Criterion keys are assigned deterministically (``criterion-1``, ...) so the
+    persisted rows and any downstream verdicts reference the same identifiers.
+    """
+    if not isinstance(payload, dict):
+        return None
+
+    title = str(payload.get("title", "") or "").strip()
+    source = str(payload.get("source", "api") or "api").strip().lower() or "api"
+    raw_non_goals = payload.get("non_goals")
+    non_goals = (
+        [str(item).strip() for item in raw_non_goals if str(item).strip()]
+        if isinstance(raw_non_goals, list)
+        else []
+    )
+
+    raw_criteria = payload.get("criteria")
+    criteria: list[dict] = []
+    if isinstance(raw_criteria, list):
+        for index, item in enumerate(raw_criteria, start=1):
+            if not isinstance(item, dict):
+                continue
+            kind = str(item.get("kind", "structural") or "structural").strip().lower()
+            if kind not in {"structural", "behavioral"}:
+                kind = "structural"
+            assertion = str(item.get("assert", item.get("assertion", "")) or "").strip().lower()
+            key = str(item.get("id", "") or f"criterion-{index}").strip() or f"criterion-{index}"
+            risk_tier = str(item.get("risk_tier", "standard") or "standard").strip().lower()
+            if risk_tier not in _VALID_RISK_TIERS:
+                risk_tier = "standard"
+            criteria.append(
+                {
+                    "criterion_key": key,
+                    "statement": str(item.get("statement", "") or "").strip(),
+                    "kind": kind,
+                    "risk_tier": risk_tier,
+                    "verifier": infer_verifier(kind, assertion),
+                    "assertion": assertion,
+                    "path": str(item.get("path", "") or "").strip().lstrip("/"),
+                    "expected": str(item.get("expected", item.get("contains", "")) or "").strip(),
+                    "notes": str(item.get("notes", "") or "").strip(),
+                }
+            )
+
+    if not title and not criteria:
+        return None
+
+    return {"title": title, "source": source, "non_goals": non_goals, "criteria": criteria}
+
+
+def compute_content_hash(canonical: dict) -> str:
+    """Stable content hash over the canonical contract (docs/39 Part E)."""
+    encoded = json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def required_permission_for_risk_tier(risk_tier: str) -> str:
+    """Minimum permission required to amend a criterion of this tier (FR-08)."""
+    return "admin" if str(risk_tier or "standard").strip().lower() in ELEVATED_RISK_TIERS else "write"
+
+
+def summarize_verdicts(verdicts: list[str]) -> dict:
+    """Aggregate criterion verdicts into a gate decision (pure).
+
+    Result values:
+    - ``not_provided``: no verdicts, or only ``not_applicable``.
+    - ``pending``: some criteria still unverified.
+    - ``passed``: at least one satisfied and none failed/pending.
+    - ``blocked``: at least one ``failed``/``escalated``.
+    """
+    passed = failed = pending = not_applicable = 0
+    for verdict in verdicts:
+        if verdict == "passed":
+            passed += 1
+        elif verdict in {"failed", "escalated"}:
+            failed += 1
+        elif verdict == "pending":
+            pending += 1
+        else:
+            not_applicable += 1
+
+    if failed:
+        result, reason = "blocked", "one_or_more_criteria_failed"
+    elif pending:
+        result, reason = "pending", "verification_incomplete"
+    elif passed:
+        result, reason = "passed", "all_verifiable_criteria_satisfied"
+    else:
+        result, reason = "not_provided", "no_verifiable_criteria"
+
+    return {
+        "result": result,
+        "criteria_total": len(verdicts),
+        "criteria_passed": passed,
+        "criteria_failed": failed,
+        "criteria_pending": pending,
+        "criteria_not_applicable": not_applicable,
+        "reason": reason,
+    }

{refactorai_core-3.2.2 → refactorai_core-3.2.3}/refactorai_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-core
-Version: 3.2.2
+Version: 3.2.3
 Summary: Public client core for the refactor platform: indexing, constitution parsing, models, gate evaluation, rules, security prefilter, RR/compliance classification. Contains no proprietary inference engine.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{refactorai_core-3.2.2 → refactorai_core-3.2.3}/refactorai_core.egg-info/SOURCES.txt

@@ -31,6 +31,9 @@ refactor_core/compliance/packs/iso27001-sdlc.json
 refactor_core/compliance/packs/pci-payments.json
 refactor_core/compliance/packs/privacy-gdpr.json
 refactor_core/compliance/packs/soc2-core.json
+refactor_core/intent/__init__.py
+refactor_core/intent/capture.py
+refactor_core/intent/contract.py
 refactor_core/rules/__init__.py
 refactor_core/rules/injection.py
 refactor_core/rules/loader.py