ctxfire 0.1.0__py3-none-any.whl

ctxfire/__init__.py

@@ -0,0 +1,3 @@
+"""Explain and budget static context graphs for coding agents."""
+
+__version__ = "0.1.0"

ctxfire/__main__.py

@@ -0,0 +1,5 @@
+"""Support ``python -m ctxfire``."""
+
+from .cli import main
+
+raise SystemExit(main())

ctxfire/adapters.py

@@ -0,0 +1,185 @@
+"""Versioned loading-semantics adapters."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import PurePosixPath
+
+from .config import AgentConfig
+
+
+@dataclass(frozen=True)
+class Inclusion:
+    pattern: str
+    activation: str
+    reason: str
+
+
+@lru_cache(maxsize=512)
+def _glob_regex(pattern: str) -> re.Pattern[str]:
+    normalized = pattern.removeprefix("./")
+    index = 0
+    translated = ""
+    while index < len(normalized):
+        character = normalized[index]
+        if character == "*":
+            if index + 1 < len(normalized) and normalized[index + 1] == "*":
+                index += 2
+                if index < len(normalized) and normalized[index] == "/":
+                    translated += "(?:.*/)?"
+                    index += 1
+                else:
+                    translated += ".*"
+                continue
+            translated += "[^/]*"
+        elif character == "?":
+            translated += "[^/]"
+        elif character == "[":
+            closing = normalized.find("]", index + 1)
+            if closing == -1:
+                translated += r"\["
+            else:
+                content = normalized[index + 1 : closing]
+                if content.startswith("!"):
+                    content = "^" + content[1:]
+                translated += "[" + content.replace("\\", r"\\") + "]"
+                index = closing
+        else:
+            translated += re.escape(character)
+        index += 1
+    return re.compile(f"^{translated}$")
+
+
+def matches(path: str, pattern: str) -> bool:
+    """Match a root-relative POSIX path with ``*`` and recursive ``**`` globs."""
+
+    return _glob_regex(pattern).fullmatch(path) is not None
+
+
+def _chain_directories(working_directory: str) -> tuple[PurePosixPath, ...]:
+    current = PurePosixPath() if working_directory == "." else PurePosixPath(working_directory)
+    return tuple(PurePosixPath(*current.parts[:depth]) for depth in range(len(current.parts) + 1))
+
+
+def _under(directory: PurePosixPath, relative: str) -> str:
+    return (directory / relative).as_posix()
+
+
+def inclusions(
+    agent: AgentConfig, available: Mapping[str, int] | None = None
+) -> tuple[Inclusion, ...]:
+    """Expand an adapter to ordered, explainable include rules."""
+
+    available = available or {}
+    result: list[Inclusion] = []
+    directories = _chain_directories(agent.working_directory)
+    if agent.adapter == "agents-md@1":
+        result.extend(
+            Inclusion(_under(directory, "AGENTS.md"), "always", "agents-md@1 chain")
+            for directory in directories
+        )
+    if agent.adapter == "codex@1":
+        for directory in directories:
+            candidates = (
+                "AGENTS.override.md",
+                "AGENTS.md",
+                *agent.instruction_fallback_filenames,
+            )
+            for filename in candidates:
+                path = _under(directory, filename)
+                if available.get(path, 0) > 0:
+                    result.append(Inclusion(path, "always", "codex@1 instruction chain precedence"))
+                    break
+            result.append(
+                Inclusion(
+                    _under(directory, ".agents/skills/*/SKILL.md"),
+                    "conditional",
+                    "codex@1 skill body; loaded only when selected",
+                )
+            )
+    if agent.adapter == "claude-code@1":
+        for directory in directories:
+            for filename in ("CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md"):
+                result.append(
+                    Inclusion(
+                        _under(directory, filename),
+                        "always",
+                        "claude-code@1 project memory ancestor chain",
+                    )
+                )
+            result.append(
+                Inclusion(
+                    _under(directory, ".claude/rules/**/*.md"),
+                    agent.claude_rules_activation,
+                    "claude-code@1 project rule; metadata-only mode cannot parse paths frontmatter",
+                )
+            )
+            result.append(
+                Inclusion(
+                    _under(directory, ".claude/skills/*/SKILL.md"),
+                    "conditional",
+                    "claude-code@1 skill body; loaded only when selected",
+                )
+            )
+        working_prefix = "" if agent.working_directory == "." else f"{agent.working_directory}/"
+        result.extend(
+            [
+                Inclusion(
+                    f"{working_prefix}**/CLAUDE.md",
+                    "conditional",
+                    "claude-code@1 descendant memory; loaded when that subtree is read",
+                ),
+                Inclusion(
+                    f"{working_prefix}**/CLAUDE.local.md",
+                    "conditional",
+                    "claude-code@1 descendant local memory; loaded when that subtree is read",
+                ),
+                Inclusion(
+                    f"{working_prefix}**/.claude/skills/*/SKILL.md",
+                    "conditional",
+                    "claude-code@1 descendant skill body; available when that subtree is read",
+                ),
+            ]
+        )
+    result.extend(Inclusion(pattern, "always", "explicit include") for pattern in agent.include)
+    result.extend(
+        Inclusion(pattern, "conditional", "explicit conditional include")
+        for pattern in agent.conditional
+    )
+    return tuple(result)
+
+
+def exact_probe_paths(agent: AgentConfig) -> tuple[str, ...]:
+    """Return known exact paths that engines load even when Git ignores them."""
+
+    result: list[str] = []
+    directories = _chain_directories(agent.working_directory)
+    if agent.adapter == "agents-md@1":
+        result.extend(_under(directory, "AGENTS.md") for directory in directories)
+    elif agent.adapter == "codex@1":
+        for directory in directories:
+            result.extend(
+                _under(directory, filename)
+                for filename in (
+                    "AGENTS.override.md",
+                    "AGENTS.md",
+                    *agent.instruction_fallback_filenames,
+                )
+            )
+    elif agent.adapter == "claude-code@1":
+        for directory in directories:
+            result.extend(
+                _under(directory, filename)
+                for filename in ("CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md")
+            )
+    for pattern in (*agent.include, *agent.conditional):
+        if not any(character in pattern for character in "*?["):
+            result.append(pattern)
+    return tuple(dict.fromkeys(result))
+
+
+def excluded(path: str, patterns: tuple[str, ...]) -> bool:
+    return any(matches(path, pattern) for pattern in patterns)

ctxfire/cli.py

@@ -0,0 +1,297 @@
+"""Command-line interface for ctxfire."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+from . import __version__
+from .config import load_config
+from .render import explain_text, json_text, sarif, scan_text
+from .scanner import scan
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_BUDGET_EXCEEDED = 2
+
+
+def _write(text: str, output: Path | None) -> None:
+    if output is None:
+        print(text, end="")
+    else:
+        output.write_text(text, encoding="utf-8")
+
+
+def _report(args: argparse.Namespace):  # type: ignore[no-untyped-def]
+    return scan(load_config(args.config))
+
+
+def command_scan(args: argparse.Namespace) -> int:
+    report = _report(args)
+    if args.format == "json":
+        rendered = json_text(report.as_dict())
+    elif args.format == "sarif":
+        findings = [
+            {
+                "rule_id": "ctxfire/context-surface",
+                "title": "Agent context surface",
+                "help": (
+                    "Review the versioned adapter assumptions and use ctxfire explain "
+                    "for attribution."
+                ),
+                "level": "note",
+                "message": (
+                    f"{agent.name}: estimated {agent.estimated_tokens_per_day} input tokens/day."
+                ),
+            }
+            for agent in report.agents
+        ]
+        rendered = json_text(
+            sarif(findings, report.tool["version"], report.as_dict()["assumptions"])
+        )
+    else:
+        rendered = scan_text(report)
+    _write(rendered, args.output)
+    return EXIT_OK
+
+
+def command_explain(args: argparse.Namespace) -> int:
+    report = _report(args)
+    if args.format == "json":
+        agents = []
+        for agent in report.as_dict()["agents"]:
+            if args.agent and agent["name"] != args.agent:
+                continue
+            agent["files"] = [
+                item for item in agent["files"] if not args.file or item["path"] == args.file
+            ]
+            agents.append(agent)
+        rendered = json_text(
+            {
+                "schema_version": report.schema_version,
+                "tool": report.tool,
+                "assumptions": report.as_dict()["assumptions"],
+                "agents": agents,
+            }
+        )
+    else:
+        rendered = explain_text(report, args.agent, args.file)
+    _write(rendered, args.output)
+    return EXIT_OK
+
+
+def _load_snapshot(path: Path) -> dict[str, Any]:
+    payload = cast(dict[str, Any], json.loads(path.read_text(encoding="utf-8")))
+    if payload.get("schema_version") != "1.0" or not isinstance(payload.get("agents"), list):
+        raise ValueError(f"not a ctxfire report schema 1.0: {path}")
+    return payload
+
+
+def command_diff(args: argparse.Namespace) -> int:
+    before = _load_snapshot(args.before)
+    after = _load_snapshot(args.after)
+    old = {agent["name"]: agent for agent in before["agents"]}
+    new = {agent["name"]: agent for agent in after["agents"]}
+    changes = []
+    for name in sorted(old.keys() | new.keys()):
+        old_tokens = int(old.get(name, {}).get("estimated_tokens_per_day", 0))
+        new_tokens = int(new.get(name, {}).get("estimated_tokens_per_day", 0))
+        old_paths = {item["path"] for item in old.get(name, {}).get("files", [])}
+        new_paths = {item["path"] for item in new.get(name, {}).get("files", [])}
+        old_files = {item["path"]: item for item in old.get(name, {}).get("files", [])}
+        new_files = {item["path"]: item for item in new.get(name, {}).get("files", [])}
+        changed_files = []
+        for path in sorted(old_paths & new_paths):
+            old_file = old_files[path]
+            new_file = new_files[path]
+            compared = ("exact_bytes", "counted_bytes", "estimated_tokens", "activation_rate")
+            if any(old_file.get(field) != new_file.get(field) for field in compared):
+                changed_files.append(
+                    {
+                        "path": path,
+                        "before": {field: old_file.get(field) for field in compared},
+                        "after": {field: new_file.get(field) for field in compared},
+                    }
+                )
+        changes.append(
+            {
+                "agent": name,
+                "fires_per_day_before": old.get(name, {}).get("fires_per_day", 0),
+                "fires_per_day_after": new.get(name, {}).get("fires_per_day", 0),
+                "estimated_tokens_per_day_before": old_tokens,
+                "estimated_tokens_per_day_after": new_tokens,
+                "estimated_tokens_per_day_delta": new_tokens - old_tokens,
+                "added_files": sorted(new_paths - old_paths),
+                "removed_files": sorted(old_paths - new_paths),
+                "changed_files": changed_files,
+            }
+        )
+    payload = {
+        "schema_version": "1.0",
+        "kind": "ctxfire-diff",
+        "assumptions_before": before.get("assumptions"),
+        "assumptions_after": after.get("assumptions"),
+        "assumptions_changed": before.get("assumptions") != after.get("assumptions"),
+        "changes": changes,
+    }
+    if args.format == "json":
+        rendered = json_text(payload)
+    else:
+        lines = [
+            "ctxfire diff",
+            "Estimated token deltas use each snapshot's recorded assumptions.",
+            "",
+        ]
+        if payload["assumptions_changed"]:
+            lines.append("WARNING: estimation assumptions changed between snapshots.")
+        for item in changes:
+            lines.append(
+                f"{item['agent']}: {item['estimated_tokens_per_day_delta']:+d} estimated tokens/day"
+            )
+            lines.extend(f"  + {path}" for path in item["added_files"])
+            lines.extend(f"  - {path}" for path in item["removed_files"])
+            for changed in item["changed_files"]:
+                lines.append(
+                    f"  ~ {changed['path']}: {changed['before']['exact_bytes']} -> "
+                    f"{changed['after']['exact_bytes']} exact bytes; "
+                    f"~{changed['before']['estimated_tokens']} -> "
+                    f"~{changed['after']['estimated_tokens']} tokens"
+                )
+            if item["fires_per_day_before"] != item["fires_per_day_after"]:
+                lines.append(
+                    f"  schedule: {item['fires_per_day_before']:g} -> "
+                    f"{item['fires_per_day_after']:g} fires/day"
+                )
+        rendered = "\n".join(lines) + "\n"
+    _write(rendered, args.output)
+    return EXIT_OK
+
+
+def command_check(args: argparse.Namespace) -> int:
+    report = _report(args)
+    for option, value in (
+        ("--max-tokens-per-fire", args.max_tokens_per_fire),
+        ("--max-tokens-per-day", args.max_tokens_per_day),
+        ("--max-usd-per-day", args.max_usd_per_day),
+    ):
+        if value is not None and value < 0:
+            raise ValueError(f"{option} cannot be negative")
+    findings: list[dict[str, str]] = []
+    checks = [
+        (
+            "tokens-per-fire",
+            args.max_tokens_per_fire,
+            max((item.estimated_tokens_per_fire for item in report.agents), default=0),
+        ),
+        ("tokens-per-day", args.max_tokens_per_day, int(report.totals["estimated_tokens_per_day"])),
+    ]
+    for name, limit, actual in checks:
+        if limit is not None and actual > limit:
+            findings.append(
+                {
+                    "rule_id": f"ctxfire/{name}",
+                    "title": f"Context budget exceeded: {name}",
+                    "help": (
+                        "Run ctxfire explain to attribute context files, then adjust "
+                        "context or the explicit budget."
+                    ),
+                    "level": "error",
+                    "message": f"Estimated {name} is {actual}, above configured CLI limit {limit}.",
+                }
+            )
+    if args.max_usd_per_day is not None:
+        cost = report.totals["estimated_usd_per_day"]
+        if cost is None:
+            raise ValueError("--max-usd-per-day requires usd_per_million_input_tokens in config")
+        if float(cost) > args.max_usd_per_day:
+            findings.append(
+                {
+                    "rule_id": "ctxfire/usd-per-day",
+                    "title": "API-equivalent cost budget exceeded",
+                    "help": (
+                        "Review the dated price and cache assumptions before changing the budget."
+                    ),
+                    "level": "error",
+                    "message": (
+                        "Estimated API-equivalent input cost/day is "
+                        f"${float(cost):.6f}, above ${args.max_usd_per_day:.6f}."
+                    ),
+                }
+            )
+    if args.format == "sarif":
+        rendered = json_text(
+            sarif(findings, report.tool["version"], report.as_dict()["assumptions"])
+        )
+    elif args.format == "json":
+        rendered = json_text(
+            {
+                "schema_version": "1.0",
+                "passed": not findings,
+                "findings": findings,
+                "report": report.as_dict(),
+            }
+        )
+    else:
+        assumptions = report.assumptions
+        rendered = (
+            ("ctxfire check: PASS\n" if not findings else "ctxfire check: FAIL\n")
+            + (
+                f"Estimates: {assumptions.tokenizer} ({assumptions.tokenizer_version}), "
+                f"{assumptions.bytes_per_token:g} bytes/token, model {assumptions.model}, "
+                f"price date {assumptions.price_date}, cache {assumptions.cache_assumption}.\n"
+            )
+            + "\n".join(f"  - {item['message']}" for item in findings)
+            + ("\n" if findings else "")
+        )
+    _write(rendered, args.output)
+    return EXIT_OK if not findings else EXIT_BUDGET_EXCEEDED
+
+
+def _common(parser: argparse.ArgumentParser, formats: tuple[str, ...]) -> None:
+    parser.add_argument("--config", type=Path, default=Path("ctxfire.toml"))
+    parser.add_argument("--format", choices=formats, default=formats[0])
+    parser.add_argument("--output", type=Path)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ctxfire",
+        description="Explain and budget the static context graph of coding agents.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    scan_parser = subparsers.add_parser(
+        "scan", help="build a context graph and estimate its daily cost"
+    )
+    _common(scan_parser, ("text", "json", "sarif"))
+    scan_parser.set_defaults(handler=command_scan)
+    explain_parser = subparsers.add_parser("explain", help="show why each file is included")
+    _common(explain_parser, ("text", "json"))
+    explain_parser.add_argument("--agent")
+    explain_parser.add_argument("--file")
+    explain_parser.set_defaults(handler=command_explain)
+    diff_parser = subparsers.add_parser("diff", help="compare two JSON scan snapshots")
+    diff_parser.add_argument("before", type=Path)
+    diff_parser.add_argument("after", type=Path)
+    diff_parser.add_argument("--format", choices=("text", "json"), default="text")
+    diff_parser.add_argument("--output", type=Path)
+    diff_parser.set_defaults(handler=command_diff)
+    check_parser = subparsers.add_parser("check", help="enforce stable CI budgets")
+    _common(check_parser, ("text", "json", "sarif"))
+    check_parser.add_argument("--max-tokens-per-fire", type=int)
+    check_parser.add_argument("--max-tokens-per-day", type=int)
+    check_parser.add_argument("--max-usd-per-day", type=float)
+    check_parser.set_defaults(handler=command_check)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        args = build_parser().parse_args(argv)
+        return int(args.handler(args))
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"ctxfire: error: {error}", file=sys.stderr)
+        return EXIT_ERROR

ctxfire/config.py

@@ -0,0 +1,149 @@
+"""Configuration parsing and validation."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from .model import CONFIG_SCHEMA_VERSION, Assumptions
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    name: str
+    adapter: str
+    engine: str
+    working_directory: str
+    fires_per_day: float
+    include: tuple[str, ...]
+    conditional: tuple[str, ...]
+    exclude: tuple[str, ...]
+    instruction_fallback_filenames: tuple[str, ...]
+    instruction_max_bytes: int | None
+    claude_rules_activation: str
+
+
+@dataclass(frozen=True)
+class Config:
+    path: Path
+    root: Path
+    project_name: str
+    assumptions: Assumptions
+    agents: tuple[AgentConfig, ...]
+
+
+def _patterns(raw: dict[str, Any], key: str) -> tuple[str, ...]:
+    value = raw.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ValueError(f"{key} must be an array of strings")
+    for pattern in value:
+        pure = PurePosixPath(pattern)
+        if pure.is_absolute() or ".." in pure.parts:
+            raise ValueError(f"{key} pattern must stay inside project root: {pattern}")
+    return tuple(value)
+
+
+def load_config(path: Path) -> Config:
+    """Load a ctxfire v1 TOML file without reading repository content."""
+
+    resolved = path.resolve()
+    data = tomllib.loads(resolved.read_text(encoding="utf-8"))
+    if str(data.get("schema_version", "")) != CONFIG_SCHEMA_VERSION:
+        raise ValueError(f'schema_version must be "{CONFIG_SCHEMA_VERSION}"')
+    project = data.get("project", {})
+    if not isinstance(project, dict):
+        raise ValueError("[project] must be a table")
+    root_value = Path(str(project.get("root", ".")))
+    root = root_value if root_value.is_absolute() else resolved.parent / root_value
+    root = root.resolve()
+    if not root.is_dir():
+        raise ValueError(f"project root is not a directory: {root}")
+
+    bytes_per_token = float(project.get("bytes_per_token", 4.0))
+    conditional_rate = float(project.get("conditional_activation_rate", 0.0))
+    if bytes_per_token <= 0:
+        raise ValueError("bytes_per_token must be greater than zero")
+    if not 0 <= conditional_rate <= 1:
+        raise ValueError("conditional_activation_rate must be between 0 and 1")
+    price_raw = project.get("usd_per_million_input_tokens")
+    price = None if price_raw is None else float(price_raw)
+    if price is not None and price < 0:
+        raise ValueError("usd_per_million_input_tokens cannot be negative")
+    tokenizer = str(project.get("tokenizer", "byte-estimate"))
+    if tokenizer == "byte-estimate":
+        tokenizer_version = "approximation-v1"
+    elif tokenizer.startswith("tiktoken:") and tokenizer.partition(":")[2]:
+        try:
+            tokenizer_version = version("tiktoken")
+        except PackageNotFoundError as error:
+            raise ValueError("tiktoken tokenizer requested; install ctxfire[tokenizers]") from error
+    else:
+        raise ValueError("tokenizer must be byte-estimate or tiktoken:<encoding>")
+    assumptions = Assumptions(
+        tokenizer=tokenizer,
+        tokenizer_version=tokenizer_version,
+        bytes_per_token=bytes_per_token,
+        model=str(project.get("model", "unspecified")),
+        price_date=str(project.get("price_date", "unspecified")),
+        usd_per_million_input_tokens=price,
+        cache_assumption=str(project.get("cache_assumption", "no-cache-credit")),
+        conditional_activation_rate=conditional_rate,
+    )
+
+    raw_agents = data.get("agents", [])
+    if not isinstance(raw_agents, list) or not raw_agents:
+        raise ValueError("configure at least one [[agents]] table")
+    agents: list[AgentConfig] = []
+    names: set[str] = set()
+    for raw in raw_agents:
+        if not isinstance(raw, dict) or not str(raw.get("name", "")).strip():
+            raise ValueError("every [[agents]] table needs a non-empty name")
+        name = str(raw["name"])
+        if name in names:
+            raise ValueError(f"duplicate agent name: {name}")
+        names.add(name)
+        fires = float(raw.get("fires_per_day", 1.0))
+        if fires < 0:
+            raise ValueError(f"fires_per_day cannot be negative for {name}")
+        working_directory = str(raw.get("working_directory", ".")).strip("/") or "."
+        work_path = PurePosixPath(working_directory)
+        if work_path.is_absolute() or ".." in work_path.parts:
+            raise ValueError(f"working_directory must stay inside project root: {name}")
+        adapter = str(raw.get("adapter", "explicit@1"))
+        if adapter not in {"explicit@1", "agents-md@1", "codex@1", "claude-code@1"}:
+            raise ValueError(f"unsupported adapter {adapter!r} for {name}")
+        fallback_names = _patterns(raw, "instruction_fallback_filenames")
+        if any("/" in item or "\\" in item for item in fallback_names):
+            raise ValueError(f"instruction fallback names must be filenames for {name}")
+        max_bytes_raw = raw.get("instruction_max_bytes", 32768 if adapter == "codex@1" else None)
+        instruction_max_bytes = None if max_bytes_raw is None else int(max_bytes_raw)
+        if instruction_max_bytes is not None and instruction_max_bytes <= 0:
+            raise ValueError(f"instruction_max_bytes must be positive for {name}")
+        claude_rules_activation = str(raw.get("claude_rules_activation", "always"))
+        if claude_rules_activation not in {"always", "conditional"}:
+            raise ValueError(f"claude_rules_activation must be always or conditional for {name}")
+        agents.append(
+            AgentConfig(
+                name=name,
+                adapter=adapter,
+                engine=str(raw.get("engine", adapter.partition("@")[0])),
+                working_directory=working_directory,
+                fires_per_day=fires,
+                include=_patterns(raw, "include"),
+                conditional=_patterns(raw, "conditional"),
+                exclude=_patterns(raw, "exclude"),
+                instruction_fallback_filenames=fallback_names,
+                instruction_max_bytes=instruction_max_bytes,
+                claude_rules_activation=claude_rules_activation,
+            )
+        )
+    return Config(
+        path=resolved,
+        root=root,
+        project_name=str(project.get("name", root.name)),
+        assumptions=assumptions,
+        agents=tuple(agents),
+    )