intract 0.1.1__py3-none-any.whl

intract/__init__.py

@@ -0,0 +1,31 @@
+"""Intract — intent contracts for codebases."""
+
+from .models import (
+    Contract,
+    ContractRecord,
+    ContractSignature,
+    ProjectReport,
+    ValidationResult,
+    ValidationStatus,
+)
+from .parser import extract_contract_records_from_text, parse_contract_line
+from .project import validate_project, validate_sources
+from .signature import build_signature
+from .validation import validate_contract_against_source
+
+__all__ = [
+    "Contract",
+    "ContractRecord",
+    "ContractSignature",
+    "ProjectReport",
+    "ValidationResult",
+    "ValidationStatus",
+    "parse_contract_line",
+    "extract_contract_records_from_text",
+    "build_signature",
+    "validate_contract_against_source",
+    "validate_project",
+    "validate_sources",
+]
+
+__version__ = "0.1.1"

intract/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

intract/cli.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .parser import extract_contract_records_from_text
+from .project import validate_project
+from .yaml_manifest import create_sample_manifest
+
+app = typer.Typer(help="Intract — intent contracts for codebases.")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def main(version: bool = typer.Option(False, "--version", help="Show version.")):
+    if version:
+        console.print(f"intract {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def init(path: Path = typer.Argument(Path("."), help="Project path."), force: bool = typer.Option(False, "--force", help="Overwrite existing intent.yaml.")):
+    """Create a sample intent.yaml manifest."""
+    target = path / "intent.yaml"
+    if target.exists() and not force:
+        console.print(f"[red]File already exists:[/] {target}")
+        raise typer.Exit(1)
+    target.write_text(create_sample_manifest(), encoding="utf-8")
+    console.print(f"[green]Created[/] {target}")
+
+
+@app.command()
+def scan(path: Path = typer.Argument(Path("."), help="File or directory."), json_output: bool = typer.Option(False, "--json", help="Print JSON.")):
+    """Scan files for inline @intract contracts."""
+    records = []
+    if path.is_file():
+        records.extend(extract_contract_records_from_text(path.read_text(encoding="utf-8"), file_path=str(path)))
+    else:
+        for file_path in path.rglob("*"):
+            if not file_path.is_file():
+                continue
+            if file_path.suffix not in {".py", ".js", ".ts", ".cs", ".java", ".go", ".rs", ".md"}:
+                continue
+            try:
+                records.extend(extract_contract_records_from_text(file_path.read_text(encoding="utf-8"), file_path=str(file_path.relative_to(path))))
+            except UnicodeDecodeError:
+                continue
+
+    data = [{"file": r.file_path, "line": r.start_line, "scope": r.contract.scope, "intent": r.contract.key, "priority": r.contract.priority, "domain": r.contract.domain} for r in records]
+    if json_output:
+        console.print_json(json.dumps(data, ensure_ascii=False))
+        return
+
+    table = Table(title="Intract contracts")
+    table.add_column("File")
+    table.add_column("Line")
+    table.add_column("Scope")
+    table.add_column("Intent")
+    table.add_column("Priority")
+    table.add_column("Domain")
+    for item in data:
+        table.add_row(item["file"], str(item["line"]), item["scope"], item["intent"], str(item["priority"]), item["domain"])
+    console.print(table)
+
+
+@app.command()
+def validate(path: Path = typer.Argument(Path("."), help="Project path."), manifest: Path | None = typer.Option(None, "--manifest", help="intent.yaml / intract.yaml."), json_output: bool = typer.Option(False, "--json", help="Print JSON report.")):
+    """Validate project contracts."""
+    report = validate_project(path, manifest_path=manifest)
+    if json_output:
+        console.print_json(json.dumps(report.to_dict(), ensure_ascii=False))
+        return
+
+    console.print(f"[bold]Project:[/] {report.project_path}")
+    console.print(f"[bold]Status:[/] {report.status.value}")
+    table = Table(title="Validation results")
+    table.add_column("Status")
+    table.add_column("Scope")
+    table.add_column("Contract")
+    table.add_column("Score")
+    table.add_column("File")
+    table.add_column("Missing / Violations")
+    for result in report.results:
+        issues = []
+        issues.extend(result.missing)
+        issues.extend(issue.message for issue in result.violations)
+        table.add_row(result.status.value, result.scope, result.contract, str(result.score), result.file_path or "", "\\n".join(issues))
+    console.print(table)

intract/effects.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import re
+
+NETWORK_PATTERNS = [r"\brequests\.", r"\bhttpx\.", r"\burllib\.", r"\bsocket\.", r"\bfetch\s*\(", r"\bHttpClient\b"]
+WRITE_PATTERNS = [r"\.write\s*\(", r"\.write_text\s*\(", r"\bopen\s*\([^)]*['\"]w", r"\bFile\.Write", r"\bDirectory\.Create", r"\bINSERT\b", r"\bUPDATE\b", r"\bDELETE\b"]
+READ_PATTERNS = [r"\.read\s*\(", r"\.read_text\s*\(", r"\bopen\s*\(", r"\bFile\.Read", r"\bDirectory\.GetFiles", r"\bSELECT\b"]
+LOG_PATTERNS = [r"\bprint\s*\(", r"\blogger\.", r"\bconsole\.log\s*\(", r"\bConsole\.Write"]
+
+
+def detect_effects(source: str) -> set[str]:
+    effects: set[str] = set()
+    if any(re.search(pattern, source, re.IGNORECASE) for pattern in NETWORK_PATTERNS):
+        effects.add("network")
+    if any(re.search(pattern, source, re.IGNORECASE) for pattern in WRITE_PATTERNS):
+        effects.add("write")
+    if any(re.search(pattern, source, re.IGNORECASE) for pattern in READ_PATTERNS):
+        effects.add("read")
+    if any(re.search(pattern, source, re.IGNORECASE) for pattern in LOG_PATTERNS):
+        effects.add("log")
+    return effects

intract/models.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ValidationStatus(str, Enum):
+    PASS = "pass"
+    PARTIAL = "partial"
+    FAIL = "fail"
+    VIOLATION = "violation"
+    UNKNOWN = "unknown"
+
+
+VALID_SCOPES = {
+    "line",
+    "block",
+    "function",
+    "method",
+    "class",
+    "file",
+    "module",
+    "package",
+    "project",
+}
+
+
+@dataclass(frozen=True)
+class Contract:
+    action: str
+    object: str
+    scope: str = "block"
+    priority: int = 3
+    domain: str = ""
+    inputs: tuple[str, ...] = field(default_factory=tuple)
+    outputs: tuple[str, ...] = field(default_factory=tuple)
+    effects: tuple[str, ...] = field(default_factory=tuple)
+    forbidden: tuple[str, ...] = field(default_factory=tuple)
+    required: tuple[str, ...] = field(default_factory=tuple)
+    validators: tuple[str, ...] = field(default_factory=tuple)
+    tags: tuple[str, ...] = field(default_factory=tuple)
+    algorithms: tuple[str, ...] = field(default_factory=tuple)
+    relations: tuple[str, ...] = field(default_factory=tuple)
+    contract_id: str = ""
+    meaning: str = ""
+    raw: str = ""
+
+    @property
+    def key(self) -> str:
+        return f"{self.action}.{self.object}"
+
+
+@dataclass(frozen=True)
+class ContractRecord:
+    contract: Contract
+    file_path: str
+    start_line: int
+    end_line: int
+    owner: str = ""
+
+
+@dataclass(frozen=True)
+class ContractSignature:
+    block_id: str
+    file_path: str
+    start_line: int
+    end_line: int
+    scope: str
+    action: str
+    object: str
+    domain: str
+    priority: int
+    inputs: frozenset[str] = field(default_factory=frozenset)
+    outputs: frozenset[str] = field(default_factory=frozenset)
+    effects: frozenset[str] = field(default_factory=frozenset)
+    forbidden: frozenset[str] = field(default_factory=frozenset)
+    required: frozenset[str] = field(default_factory=frozenset)
+    validators: frozenset[str] = field(default_factory=frozenset)
+    tags: frozenset[str] = field(default_factory=frozenset)
+    algorithms: frozenset[str] = field(default_factory=frozenset)
+    relations: frozenset[str] = field(default_factory=frozenset)
+    features: frozenset[str] = field(default_factory=frozenset)
+    exact_hash: str = ""
+    raw: str = ""
+    meaning: str = ""
+
+    @property
+    def key(self) -> str:
+        return f"{self.action}.{self.object}"
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    kind: str
+    message: str
+    severity: str = "error"
+
+
+@dataclass
+class ValidationResult:
+    contract: str
+    scope: str
+    status: ValidationStatus
+    score: float = 0.0
+    file_path: str | None = None
+    lines: tuple[int, int] | None = None
+    matched: dict[str, Any] = field(default_factory=dict)
+    missing: list[str] = field(default_factory=list)
+    violations: list[ValidationIssue] = field(default_factory=list)
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["status"] = self.status.value
+        return data
+
+
+@dataclass
+class ProjectReport:
+    project_path: str
+    status: ValidationStatus
+    results: list[ValidationResult] = field(default_factory=list)
+
+    @property
+    def passed(self) -> list[ValidationResult]:
+        return [item for item in self.results if item.status == ValidationStatus.PASS]
+
+    @property
+    def partial(self) -> list[ValidationResult]:
+        return [item for item in self.results if item.status == ValidationStatus.PARTIAL]
+
+    @property
+    def failed(self) -> list[ValidationResult]:
+        return [item for item in self.results if item.status == ValidationStatus.FAIL]
+
+    @property
+    def violations(self) -> list[ValidationResult]:
+        return [item for item in self.results if item.status == ValidationStatus.VIOLATION]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "project_path": self.project_path,
+            "status": self.status.value,
+            "summary": {
+                "total": len(self.results),
+                "passed": len(self.passed),
+                "partial": len(self.partial),
+                "failed": len(self.failed),
+                "violations": len(self.violations),
+            },
+            "results": [item.to_dict() for item in self.results],
+        }

intract/normalizer.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+
+ACTION_SYNONYMS = {
+    "validate": {"validate", "check", "verify", "ensure", "authorize", "guard"},
+    "build": {"build", "create", "make", "construct", "generate", "assemble"},
+    "parse": {"parse", "read", "load", "deserialize", "extract"},
+    "compare": {"compare", "diff", "match"},
+    "scan": {"scan", "collect", "discover", "find"},
+    "render": {"render", "format", "serialize", "export"},
+    "persist": {"persist", "save", "write", "store"},
+    "transform": {"transform", "normalize", "convert", "map"},
+    "detect": {"detect", "identify", "recognize", "classify"},
+    "calculate": {"calculate", "compute", "count", "measure", "estimate"},
+    "implement": {"implement", "provide", "expose"},
+    "analyze": {"analyze", "inspect", "evaluate"},
+    "group": {"group", "cluster", "merge"},
+    "plan": {"plan", "suggest", "recommend"},
+}
+
+STOP_WORDS = {"a", "an", "the", "to", "from", "of", "for", "before", "after", "with", "without", "and", "or", "by"}
+
+
+def normalize_label(value: str | None) -> str:
+    if not value:
+        return ""
+    text = str(value).strip()
+    text = re.sub(r"(?<=[a-z])(?=[A-Z])", "_", text)
+    text = text.replace("-", "_").replace("/", "_").replace(".", "_").replace(":", "_")
+    text = re.sub(r"[^A-Za-z0-9_]+", "_", text)
+    text = re.sub(r"_+", "_", text).strip("_").lower()
+    parts = []
+    for part in text.split("_"):
+        if not part or part in STOP_WORDS:
+            continue
+        if len(part) > 4 and part.endswith("s"):
+            part = part[:-1]
+        parts.append(part)
+    return "_".join(parts)
+
+
+def normalize_action(action: str | None) -> str:
+    normalized = normalize_label(action)
+    for canonical, variants in ACTION_SYNONYMS.items():
+        if normalized in {normalize_label(item) for item in variants}:
+            return canonical
+    return normalized
+
+
+def normalize_many(values: Iterable[str] | None) -> tuple[str, ...]:
+    if not values:
+        return ()
+    normalized = {normalize_label(value) for value in values if normalize_label(value)}
+    return tuple(sorted(normalized))
+
+
+def normalize_requirement(value: str) -> str:
+    value = str(value).strip().replace(":", ".")
+    parts = [part for part in value.split(".") if part]
+    if len(parts) == 1:
+        return normalize_label(parts[0])
+    action = normalize_action(parts[0])
+    obj = normalize_label("_".join(parts[1:]))
+    if not action or not obj:
+        return normalize_label(value)
+    return f"{action}.{obj}"

intract/parser.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import re
+import shlex
+
+from .models import Contract, ContractRecord, VALID_SCOPES
+
+
+CONTRACT_MARKERS = ("@intract.v1", "@intract", "@ridl.v1")
+
+
+def clean_comment_line(line: str) -> str:
+    text = line.strip()
+    if text.startswith("<!--"):
+        text = text[4:].strip()
+    if text.endswith("-->"):
+        text = text[:-3].strip()
+    if text.startswith("/*"):
+        text = text[2:].strip()
+    if text.endswith("*/"):
+        text = text[:-2].strip()
+    while text.startswith("*"):
+        text = text[1:].strip()
+    for prefix in ("#", "//", "--", ";"):
+        if text.startswith(prefix):
+            return text[len(prefix):].strip()
+    return text
+
+
+def split_csv(value: str | None) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    text = str(value).strip()
+    if not text or text.lower() in {"none", "null", "empty", "-"}:
+        return ()
+    return tuple(part.strip() for part in text.split(",") if part.strip())
+
+
+def parse_priority(token: str) -> int | None:
+    text = token.strip().lower()
+    if text.startswith("!p") and text[2:].isdigit():
+        raw = text[2:]
+    elif text.startswith("p") and text[1:].isdigit():
+        raw = text[1:]
+    else:
+        return None
+    return max(1, min(5, int(raw)))
+
+
+def parse_key_value(token: str) -> tuple[str, str] | None:
+    match = re.match(r"^([A-Za-z_][A-Za-z0-9_-]*)(:|=)(.+)$", token)
+    if not match:
+        return None
+    return match.group(1).lower(), match.group(3).strip()
+
+
+def marker_payload(line: str) -> str | None:
+    cleaned = clean_comment_line(line)
+    for marker in CONTRACT_MARKERS:
+        if marker in cleaned:
+            return cleaned.split(marker, 1)[1].strip()
+    return None
+
+
+def parse_contract_line(line: str, *, default_scope: str = "block") -> Contract | None:
+    payload = marker_payload(line)
+    if payload is None or not payload:
+        return None
+
+    tokens = shlex.split(payload, comments=False, posix=True)
+    action = ""
+    object_name = ""
+    priority = 3
+    scope = default_scope
+    domain = ""
+    inputs: list[str] = []
+    outputs: list[str] = []
+    effects: list[str] = []
+    forbidden: list[str] = []
+    required: list[str] = []
+    validators: list[str] = []
+    tags: list[str] = []
+    algorithms: list[str] = []
+    relations: list[str] = []
+    contract_id = ""
+    meaning = ""
+    positional: list[str] = []
+
+    for token in tokens:
+        priority_value = parse_priority(token)
+        if priority_value is not None:
+            priority = priority_value
+            continue
+        if token.startswith("@") and len(token) > 1:
+            domain = token[1:]
+            continue
+        if token.startswith("#") and len(token) > 1:
+            tags.append(token[1:])
+            continue
+        if token.startswith("~") and len(token) > 1:
+            algorithms.append(token[1:])
+            continue
+
+        kv = parse_key_value(token)
+        if kv is None:
+            if ":" in token and not action and not object_name:
+                action, object_name = token.split(":", 1)
+            else:
+                positional.append(token)
+            continue
+
+        key, value = kv
+        if key == "intent":
+            if ":" in value:
+                action, object_name = value.split(":", 1)
+            else:
+                positional.append(value)
+        elif key in {"action", "act"}:
+            action = value
+        elif key in {"object", "obj", "target"}:
+            object_name = value
+        elif key == "scope":
+            scope = value if value in VALID_SCOPES else default_scope
+        elif key == "priority":
+            if value.isdigit():
+                priority = max(1, min(5, int(value)))
+        elif key == "domain":
+            domain = value
+        elif key in {"input", "inputs", "in"}:
+            inputs.extend(split_csv(value))
+        elif key in {"output", "outputs", "out"}:
+            outputs.extend(split_csv(value))
+        elif key in {"effect", "effects", "fx"}:
+            effects.extend(split_csv(value))
+        elif key in {"forbid", "forbidden", "no"}:
+            forbidden.extend(split_csv(value))
+        elif key in {"require", "requires", "req"}:
+            required.extend(split_csv(value))
+        elif key in {"validate", "validators", "rules"}:
+            validators.extend(split_csv(value))
+        elif key in {"tag", "tags"}:
+            tags.extend(split_csv(value))
+        elif key in {"algorithm", "algorithms", "alg", "algo"}:
+            algorithms.extend(split_csv(value))
+        elif key in {"relation", "relations", "rel", "uses", "partof", "before", "after"}:
+            relations.extend(f"{key}:{item}" for item in split_csv(value))
+        elif key in {"id", "contract_id"}:
+            contract_id = value
+        elif key == "meaning":
+            meaning = value
+        else:
+            tags.append(f"{key}:{value}")
+
+    if not action and positional:
+        action = positional[0]
+    if not object_name and len(positional) > 1:
+        object_name = "_".join(positional[1:])
+    if not action or not object_name:
+        return None
+
+    return Contract(
+        action=action,
+        object=object_name,
+        scope=scope,
+        priority=priority,
+        domain=domain,
+        inputs=tuple(inputs),
+        outputs=tuple(outputs),
+        effects=tuple(effects),
+        forbidden=tuple(forbidden),
+        required=tuple(required),
+        validators=tuple(validators),
+        tags=tuple(tags),
+        algorithms=tuple(algorithms),
+        relations=tuple(relations),
+        contract_id=contract_id,
+        meaning=meaning,
+        raw=payload,
+    )
+
+
+def extract_contract_records_from_text(
+    source: str,
+    *,
+    file_path: str,
+    default_scope: str = "block",
+) -> list[ContractRecord]:
+    records: list[ContractRecord] = []
+    for index, line in enumerate(source.splitlines(), start=1):
+        contract = parse_contract_line(line, default_scope=default_scope)
+        if contract is None:
+            continue
+        records.append(ContractRecord(contract=contract, file_path=file_path, start_line=index, end_line=index))
+    return records

intract/project.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .models import ProjectReport, ValidationResult, ValidationStatus
+from .parser import extract_contract_records_from_text
+from .signature import build_signatures
+from .validation import validate_contract_against_source, validate_required_contracts
+from .yaml_manifest import load_manifest_records
+
+DEFAULT_EXTENSIONS = (".py", ".js", ".ts", ".tsx", ".jsx", ".java", ".cs", ".go", ".rs", ".php", ".rb", ".sh", ".sql", ".html", ".css", ".md", ".yaml", ".yml")
+SKIP_DIRS = {".git", ".venv", "venv", "__pycache__", "node_modules", "dist", "build"}
+
+
+def load_project_sources(root: Path, *, extensions: tuple[str, ...] = DEFAULT_EXTENSIONS) -> dict[str, str]:
+    sources: dict[str, str] = {}
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in SKIP_DIRS for part in path.parts):
+            continue
+        if path.suffix not in extensions:
+            continue
+        rel_path = str(path.relative_to(root))
+        try:
+            sources[rel_path] = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+    return sources
+
+
+def extract_signatures_from_sources(sources: dict[str, str]):
+    records = []
+    for file_path, source in sources.items():
+        records.extend(extract_contract_records_from_text(source, file_path=file_path, default_scope="block"))
+    return build_signatures(records)
+
+
+def validate_sources(sources: dict[str, str], *, manifest_records=None) -> ProjectReport:
+    observed_signatures = extract_signatures_from_sources(sources)
+    observed_by_file = {file_path: source for file_path, source in sources.items()}
+    results: list[ValidationResult] = []
+
+    for signature in observed_signatures:
+        source = observed_by_file.get(signature.file_path, "")
+        results.append(validate_contract_against_source(signature, source))
+
+    if manifest_records:
+        manifest_signatures = build_signatures(manifest_records)
+        for required_signature in manifest_signatures:
+            satisfied, missing = validate_required_contracts(required_signature, observed_signatures)
+            source = observed_by_file.get(required_signature.file_path, "")
+            result = validate_contract_against_source(required_signature, source)
+            if missing:
+                result.status = ValidationStatus.PARTIAL if satisfied else ValidationStatus.FAIL
+                result.missing.extend(f"require:{item}" for item in missing)
+            result.matched["satisfied_requirements"] = satisfied
+            result.evidence["manifest_contract"] = True
+            results.append(result)
+
+    if any(item.status == ValidationStatus.VIOLATION for item in results):
+        status = ValidationStatus.VIOLATION
+    elif results and all(item.status == ValidationStatus.PASS for item in results):
+        status = ValidationStatus.PASS
+    elif any(item.status in {ValidationStatus.PASS, ValidationStatus.PARTIAL} for item in results):
+        status = ValidationStatus.PARTIAL
+    elif results:
+        status = ValidationStatus.FAIL
+    else:
+        status = ValidationStatus.UNKNOWN
+    return ProjectReport(project_path="<sources>", status=status, results=results)
+
+
+def validate_project(root: Path | str, *, manifest_path: Path | str | None = None) -> ProjectReport:
+    project_root = Path(root)
+    sources = load_project_sources(project_root)
+    manifest_records = None
+    if manifest_path:
+        manifest_records = load_manifest_records(Path(manifest_path))
+    else:
+        for candidate in ("intent.yaml", "intract.yaml", ".intract.yaml"):
+            path = project_root / candidate
+            if path.exists():
+                manifest_records = load_manifest_records(path)
+                break
+    report = validate_sources(sources, manifest_records=manifest_records)
+    report.project_path = str(project_root)
+    return report

intract/signature.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import hashlib
+
+from .models import ContractRecord, ContractSignature
+from .normalizer import normalize_action, normalize_label, normalize_many, normalize_requirement
+
+
+def make_block_id(file_path: str, start_line: int, end_line: int, scope: str) -> str:
+    raw = f"{file_path}:{start_line}:{end_line}:{scope}"
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def build_signature(record: ContractRecord) -> ContractSignature:
+    contract = record.contract
+    action = normalize_action(contract.action)
+    object_name = normalize_label(contract.object)
+    domain = normalize_label(contract.domain)
+    inputs = frozenset(normalize_many(contract.inputs))
+    outputs = frozenset(normalize_many(contract.outputs))
+    effects = frozenset(normalize_many(contract.effects))
+    forbidden = frozenset(normalize_many(contract.forbidden))
+    required = frozenset(normalize_requirement(item) for item in contract.required)
+    validators = frozenset(normalize_many(contract.validators))
+    tags = frozenset(normalize_many(contract.tags))
+    algorithms = frozenset(normalize_many(contract.algorithms))
+    relations = frozenset(normalize_many(contract.relations))
+
+    features: set[str] = {
+        f"action:{action}",
+        f"object:{object_name}",
+        f"priority:{contract.priority}",
+        f"scope:{contract.scope}",
+    }
+    if domain:
+        features.add(f"domain:{domain}")
+
+    features.update(f"input:{item}" for item in inputs)
+    features.update(f"output:{item}" for item in outputs)
+    features.update(f"effect:{item}" for item in effects)
+    features.update(f"forbid:{item}" for item in forbidden)
+    features.update(f"require:{item}" for item in required)
+    features.update(f"validate:{item}" for item in validators)
+    features.update(f"tag:{item}" for item in tags)
+    features.update(f"algorithm:{item}" for item in algorithms)
+    features.update(f"relation:{item}" for item in relations)
+
+    exact_hash = hashlib.sha256("\\n".join(sorted(features)).encode("utf-8")).hexdigest()
+    block_id = contract.contract_id or make_block_id(record.file_path, record.start_line, record.end_line, contract.scope)
+
+    return ContractSignature(
+        block_id=block_id,
+        file_path=record.file_path,
+        start_line=record.start_line,
+        end_line=record.end_line,
+        scope=contract.scope,
+        action=action,
+        object=object_name,
+        domain=domain,
+        priority=contract.priority,
+        inputs=inputs,
+        outputs=outputs,
+        effects=effects,
+        forbidden=forbidden,
+        required=frozenset(item for item in required if item),
+        validators=validators,
+        tags=tags,
+        algorithms=algorithms,
+        relations=relations,
+        features=frozenset(features),
+        exact_hash=exact_hash,
+        raw=contract.raw,
+        meaning=contract.meaning,
+    )
+
+
+def build_signatures(records: list[ContractRecord]) -> list[ContractSignature]:
+    return [build_signature(record) for record in records]

intract/validation.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import re
+
+from .effects import detect_effects
+from .models import ContractSignature, ValidationIssue, ValidationResult, ValidationStatus
+from .normalizer import normalize_label
+
+DEFAULT_VALIDATORS = {"input_presence", "output_presence", "return_value", "no_forbidden_effect"}
+
+
+def contains_token_like(source: str, token: str) -> bool:
+    normalized_source = normalize_label(source)
+    normalized_token = normalize_label(token)
+    if not normalized_token:
+        return True
+    if normalized_token in normalized_source:
+        return True
+    parts = [part for part in normalized_token.split("_") if part]
+    return bool(parts) and all(part in normalized_source for part in parts)
+
+
+def has_return_value(source: str) -> bool:
+    return bool(re.search(r"\breturn\b", source) or re.search(r"=>", source) or re.search(r"\byield\b", source))
+
+
+def validate_contract_against_source(
+    signature: ContractSignature,
+    source: str,
+    *,
+    pass_threshold: float = 0.84,
+    partial_threshold: float = 0.65,
+) -> ValidationResult:
+    validators = set(signature.validators) or DEFAULT_VALIDATORS
+    missing: list[str] = []
+    violations: list[ValidationIssue] = []
+    matched: dict[str, object] = {}
+    score_parts: list[float] = []
+
+    if "input_presence" in validators:
+        found = [item for item in signature.inputs if contains_token_like(source, item)]
+        missing_inputs = sorted(signature.inputs - set(found))
+        matched["inputs_found"] = found
+        if missing_inputs:
+            missing.extend(f"input:{item}" for item in missing_inputs)
+        score_parts.append(len(found) / max(1, len(signature.inputs)) if signature.inputs else 1.0)
+
+    if "output_presence" in validators:
+        found = [item for item in signature.outputs if contains_token_like(source, item)]
+        missing_outputs = sorted(signature.outputs - set(found))
+        matched["outputs_found"] = found
+        if missing_outputs:
+            missing.extend(f"output:{item}" for item in missing_outputs)
+        score_parts.append(len(found) / max(1, len(signature.outputs)) if signature.outputs else 1.0)
+
+    if "return_value" in validators:
+        has_return = has_return_value(source)
+        matched["has_return"] = has_return
+        if not has_return:
+            missing.append("return_value")
+        score_parts.append(1.0 if has_return else 0.0)
+
+    observed_effects = detect_effects(source)
+    matched["observed_effects"] = sorted(observed_effects)
+
+    if "no_forbidden_effect" in validators:
+        forbidden_hits = sorted(signature.forbidden & observed_effects)
+        for item in forbidden_hits:
+            violations.append(
+                ValidationIssue(kind="forbidden_effect", message=f"Declared forbid:{item}, but effect '{item}' was detected.")
+            )
+        score_parts.append(1.0 if not forbidden_hits else 0.0)
+
+    score = sum(score_parts) / max(1, len(score_parts))
+    if violations:
+        status = ValidationStatus.VIOLATION
+    elif score >= pass_threshold and not missing:
+        status = ValidationStatus.PASS
+    elif score >= partial_threshold or missing:
+        status = ValidationStatus.PARTIAL
+    else:
+        status = ValidationStatus.FAIL
+
+    return ValidationResult(
+        contract=signature.key,
+        scope=signature.scope,
+        status=status,
+        score=round(score, 4),
+        file_path=signature.file_path,
+        lines=(signature.start_line, signature.end_line),
+        matched=matched,
+        missing=missing,
+        violations=violations,
+        evidence={"meaning": signature.meaning, "validators": sorted(validators)},
+    )
+
+
+def validate_required_contracts(required_signature: ContractSignature, observed_signatures: list[ContractSignature]) -> tuple[list[str], list[str]]:
+    observed_keys = {item.key for item in observed_signatures}
+    satisfied = sorted(item for item in required_signature.required if item in observed_keys)
+    missing = sorted(item for item in required_signature.required if item not in observed_keys)
+    return satisfied, missing

intract/yaml_manifest.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .models import Contract, ContractRecord
+
+
+def _to_tuple(value: Any) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        if value.lower() in {"none", "null", "-"}:
+            return ()
+        return tuple(part.strip() for part in value.split(",") if part.strip())
+    if isinstance(value, (list, tuple, set)):
+        return tuple(str(item) for item in value if str(item).strip())
+    return (str(value),)
+
+
+def _parse_intent(value: str) -> tuple[str, str]:
+    if ":" in value:
+        left, right = value.split(":", 1)
+        return left.strip(), right.strip()
+    if "." in value:
+        left, right = value.split(".", 1)
+        return left.strip(), right.strip()
+    return value.strip(), "unknown"
+
+
+def contract_from_mapping(data: dict[str, Any]) -> Contract:
+    action = str(data.get("action", "")).strip()
+    object_name = str(data.get("object", data.get("obj", ""))).strip()
+    if not action or not object_name:
+        intent = str(data.get("intent", "")).strip()
+        action, object_name = _parse_intent(intent)
+    return Contract(
+        action=action,
+        object=object_name,
+        scope=str(data.get("scope", "block")),
+        priority=int(data.get("priority", 3)),
+        domain=str(data.get("domain", "")),
+        inputs=_to_tuple(data.get("input", data.get("inputs", data.get("in")))),
+        outputs=_to_tuple(data.get("output", data.get("outputs", data.get("out")))),
+        effects=_to_tuple(data.get("effect", data.get("effects", data.get("fx")))),
+        forbidden=_to_tuple(data.get("forbid", data.get("forbidden", data.get("no")))),
+        required=_to_tuple(data.get("require", data.get("requires", data.get("req")))),
+        validators=_to_tuple(data.get("validate", data.get("validators", data.get("rules")))),
+        tags=_to_tuple(data.get("tags", data.get("tag"))),
+        algorithms=_to_tuple(data.get("algorithms", data.get("algorithm", data.get("alg")))),
+        relations=_to_tuple(data.get("relations", data.get("relation", data.get("rel")))),
+        contract_id=str(data.get("id", data.get("contract_id", ""))),
+        meaning=str(data.get("meaning", "")),
+        raw=str(data),
+    )
+
+
+def load_manifest_records(path: Path) -> list[ContractRecord]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    records: list[ContractRecord] = []
+    for index, item in enumerate(data.get("contracts", []) or [], start=1):
+        if isinstance(item, dict):
+            records.append(ContractRecord(contract=contract_from_mapping(item), file_path=str(path), start_line=index, end_line=index))
+    files = data.get("files", {}) or {}
+    if isinstance(files, dict):
+        for file_path, file_contracts in files.items():
+            if not isinstance(file_contracts, list):
+                continue
+            for index, item in enumerate(file_contracts, start=1):
+                if isinstance(item, dict):
+                    records.append(ContractRecord(contract=contract_from_mapping(item), file_path=str(file_path), start_line=index, end_line=index))
+    return records
+
+
+def create_sample_manifest() -> str:
+    return """project:
+  name: intract-sample
+
+contracts:
+  - id: project.analysis
+    scope: project
+    intent: analyze:code_duplication
+    priority: 1
+    domain: project
+    input: [source_tree]
+    output: [DuplicationMap, RefactorSuggestion]
+    effect: [read]
+    forbid: [network]
+    require:
+      - scan.project_files
+      - extract.code_blocks
+      - detect.duplicates
+      - render.report
+    validate:
+      - required_intents
+      - no_forbidden_effect
+    meaning: "Project should analyze source code duplication and produce refactoring guidance."
+
+files:
+  src/scanner.py:
+    - scope: file
+      intent: scan:project_files
+      priority: 1
+      domain: scanner
+      input: [ScanConfig]
+      output: [file_list]
+      effect: [read]
+      forbid: [network]
+      validate: [no_forbidden_effect]
+      meaning: "Scanner should collect project files."
+"""

intract-0.1.1.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: intract
+Version: 0.1.1
+Summary: Intent contract tagging, validation and semantic mapping for codebases.
+Author: Intract Contributors
+Author-email: Tom Sapletta <tom@sapletta.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: code-quality,contract,intent,refactoring,static-analysis,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: costs>=0.1.20; extra == 'dev'
+Requires-Dist: goal>=2.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pfix>=0.1.60; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Intract
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.1-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.15-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-1.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.1500 (1 commits)
+- 👤 **Human dev:** ~$100 (1.0h @ $100/h, 30min dedup)
+
+Generated on 2026-05-29 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+
+
+**Intract** is a lightweight intent-contract system for codebases.
+
+Intract is not primarily a programming language. It is a **contract layer** for code intent.
+A contract may be a single line, an inline comment, or a multi-file `intent.yaml` manifest.
+
+## Inline contract
+
+```python
+# @intract.v1 scope:function intent:validate:user_permission priority:1 domain:security input:user,resource output:allowed effect:none forbid:write,network require:none validate:input_presence,return_value,no_forbidden_effect meaning:"check whether user can modify resource without changing state"
+def can_update_resource(user, resource):
+    return user.is_admin or resource.owner_id == user.id
+```
+
+## Multi-file manifest
+
+```yaml
+project:
+  name: redup
+
+contracts:
+  - id: project.analysis
+    scope: project
+    intent: analyze:code_duplication
+    priority: 1
+    domain: project
+    input: [source_tree]
+    output: [DuplicationMap, RefactorSuggestion]
+    effect: [read]
+    forbid: [network]
+    require:
+      - scan.project_files
+      - extract.code_blocks
+      - detect.duplicates
+      - group.duplicates
+      - render.report
+    validate:
+      - required_intents
+      - no_forbidden_effect
+    meaning: "Project should analyze source code duplication and produce refactoring guidance."
+
+files:
+  src/redup/core/scanner/__init__.py:
+    - scope: file
+      intent: scan:project_files
+      priority: 1
+      domain: scanner
+      input: [ScanConfig]
+      output: [file_list]
+      effect: [read]
+      forbid: [network]
+      meaning: "Scanner file should collect project source files."
+```
+
+## CLI
+
+```bash
+pip install -e .[dev]
+
+intract scan .
+intract validate .
+intract validate . --manifest intent.yaml --json
+intract init .
+```
+
+## Validation statuses
+
+| Status | Meaning |
+|---|---|
+| `pass` | Contract is satisfied. |
+| `partial` | Contract is partly satisfied but missing evidence or sub-intents. |
+| `fail` | Contract is not satisfied. |
+| `violation` | Contract matches but violates a forbidden constraint. |
+| `unknown` | Not enough information to decide. |
+
+## Contract fields
+
+| Field | Example | Meaning |
+|---|---|---|
+| `scope` | `function` | Level: `line`, `block`, `function`, `class`, `file`, `module`, `project`. |
+| `intent` | `validate:user_permission` | Main action and object. |
+| `priority` | `1` | Importance from 1 to 5. |
+| `domain` | `security` | Architectural/business domain. |
+| `input` | `user,resource` | Expected inputs. |
+| `output` | `allowed` | Expected output. |
+| `effect` | `read` | Allowed/declared side effects. |
+| `forbid` | `write,network` | Forbidden effects. |
+| `require` | `scan.project_files` | Required sub-intents. |
+| `validate` | `input_presence,no_forbidden_effect` | Validation rules to apply. |
+| `meaning` | `"..."` | Human-readable explanation. |
+
+
+## License
+
+Licensed under Apache-2.0.

intract-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+intract/__init__.py,sha256=QY2GWIHmCMyQB3oaR9GBiVlENaRTwFnJevsGl7fRRhY,773
+intract/__main__.py,sha256=Qd-f8z2Q2vpiEP2x6PBFsJrpACWDVxFKQk820MhFmHo,59
+intract/cli.py,sha256=Or_crSfLsANbzj8ah4ReQuMOqqGy3LDatfkaXFaR_Yc,3829
+intract/effects.py,sha256=GxlsgFxNYhDgGIH-X8PzMIf45KgnVMYHOjhkD_vAZ1M,1106
+intract/models.py,sha256=XS5s3_99Sp3M6lRrbDMTmtof7CYMepI0nYiPI7GZlzE,4343
+intract/normalizer.py,sha256=UcmY1c5BYtaobnCcCN8J_2KngPc3FJv43IOabqHV4iI,2564
+intract/parser.py,sha256=jIxEKteg5O2sDnLS_PKiq47J1mf3DuRhAxFxlF8tQHQ,6172
+intract/project.py,sha256=7gR4LmUTcy7MDd3dtU-a64y-lZbfZe_B7M2VXuIBEAE,3940
+intract/signature.py,sha256=6xlR89HR_ubs1byj-bRCt07ktAUwL2ZY34PQC60lfqQ,3045
+intract/validation.py,sha256=x6nrCjRYhN3jg8Wb4x91JAGBeJ4sPYCaJOueEhj-Axs,4093
+intract/yaml_manifest.py,sha256=I3rD9Sz6ZTn3xyI72dbpCkU_ADbIxGaONrqTcTjbW5M,4123
+intract-0.1.1.dist-info/METADATA,sha256=GBXIxVdnVC74iY_FmCc42t4mpGpB75BrB_S7DROLmnE,4714
+intract-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+intract-0.1.1.dist-info/entry_points.txt,sha256=1sQtmpFl2Bixux66V-bNqO7Cnnv_q5uLikp1X6pqeo4,44
+intract-0.1.1.dist-info/licenses/LICENSE,sha256=dUHw21hoZ6Lp28rPomB2trHWwBi2N1RaFtnfPtvQmYo,228
+intract-0.1.1.dist-info/RECORD,,

intract-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

intract-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+intract = intract.cli:app

intract-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+MIT License
+
+Copyright (c) 2026 Intract Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files to deal in the Software
+without restriction.