obey-cli 0.1.0__py3-none-any.whl

obey_cli/lint.py

@@ -0,0 +1,125 @@
+"""obey lint: checks that need no agent runs, for CI.
+
+1. obey.yaml is valid, and every active rule has a checker (rules that need judgement are `uncheckable`).
+2. The instruction files are unchanged since obey.yaml was written (a hash mismatch means "re-extract").
+3. Generated enforcement files match what `obey enforce` would write for the rules they were compiled from.
+4. The badge JSON is present (lint writes it).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from obey_cli import config as cfg
+
+
+@dataclass
+class LintResult:
+    ok: bool = True
+    lines: list[str] = field(default_factory=list)
+
+    def good(self, text: str) -> None:
+        self.lines.append(f"ok    {text}")
+
+    def bad(self, text: str) -> None:
+        self.ok = False
+        self.lines.append(f"FAIL  {text}")
+
+    def note(self, text: str) -> None:
+        self.lines.append(f"note  {text}")
+
+
+def lint(root: Path, config_name: str = cfg.CONFIG_NAME, write_badge: bool = True) -> LintResult:
+    from obey_cli.discover import discover
+    from obey_cli.enforce import in_sync, installed_targets
+    from obey_cli.report import badge
+
+    res = LintResult()
+    try:
+        config = cfg.load(root / config_name)
+    except cfg.ConfigError as exc:
+        res.bad(str(exc))
+        return res
+    rules = config["rules"]
+    active = [r for r in rules if r["status"] == "active"]
+    res.good(
+        f"{config_name} is valid: {len(rules)} rules, {len(active)} active, "
+        f"{sum(r['status'] == 'uncheckable' for r in rules)} uncheckable"
+    )
+    missing = [r["id"] for r in active if not r.get("checker")]
+    if missing:
+        res.bad(f"active rules without a checker: {', '.join(missing)} (add one or mark them uncheckable)")
+    proposed = [r["id"] for r in rules if r["status"] == "proposed"]
+    if proposed:
+        res.note(f"{len(proposed)} proposed rule(s) wait for review: set status active or disabled")
+    no_probe = [r["id"] for r in active if not r.get("probes")]
+    if no_probe:
+        res.note(f"{len(no_probe)} active rule(s) have no probe yet (obey probe)")
+
+    recorded = {s["file"]: s["sha256"] for s in config.get("sources") or []}
+    current = {f.path: f.sha256 for f in discover(root)}
+    changed = sorted(p for p in recorded if p in current and current[p] != recorded[p])
+    gone = sorted(p for p in recorded if p not in current)
+    new = sorted(p for p in current if p not in recorded)
+    if changed or gone or new:
+        detail = "; ".join(
+            x
+            for x in (
+                f"changed: {', '.join(changed)}" if changed else "",
+                f"removed: {', '.join(gone)}" if gone else "",
+                f"new: {', '.join(new)}" if new else "",
+            )
+            if x
+        )
+        res.bad(f"instruction files differ from {config_name} ({detail}); run `obey extract`")
+    else:
+        res.good(f"{len(current)} instruction file(s) match {config_name}")
+
+    targets = installed_targets(root)
+    compiled_path = root / ".obey" / "hooks" / "rules.json"
+    if targets:
+        if not compiled_path.exists():
+            res.bad("enforcement files exist but .obey/hooks/rules.json is missing; run `obey enforce`")
+        else:
+            compiled = json.loads(compiled_path.read_text(encoding="utf-8"))
+            by_id = {r["id"]: r for r in rules}
+            stale = [
+                r["id"]
+                for r in compiled["rules"]
+                if r["id"] not in by_id
+                or by_id[r["id"]].get("status") != "active"
+                or by_id[r["id"]].get("checker") != r["checker"]
+            ]
+            if stale:
+                res.bad(f"enforced rules no longer match {config_name}: {', '.join(stale)}; run `obey enforce`")
+            else:
+                current_rules = [by_id[r["id"]] for r in compiled["rules"]]
+                drift = in_sync(root, current_rules, targets)
+                if drift:
+                    res.bad(f"enforcement files out of date: {', '.join(drift)}; run `obey enforce`")
+                else:
+                    res.good(f"enforcement in sync for {', '.join(targets)} ({len(compiled['rules'])} rule(s))")
+    else:
+        res.note("no enforcement installed (obey enforce)")
+
+    badge_path = root / "obey-badge.json"
+    if write_badge:
+        report_path = root / ".obey" / "report.json"
+        report = json.loads(report_path.read_text(encoding="utf-8")) if report_path.exists() else None
+        data = badge(report, rules_total=len(active))
+        text = json.dumps(data) + "\n"
+        if not badge_path.exists() or badge_path.read_text(encoding="utf-8") != text:
+            badge_path.write_text(text, encoding="utf-8")
+        res.good(f"badge written to obey-badge.json ({data['message']})")
+    elif badge_path.exists():
+        res.good("obey-badge.json present")
+    else:
+        res.bad("obey-badge.json missing (run `obey lint` without --no-badge, or `obey run`)")
+    return res
+
+
+def sha256_file(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()

obey_cli/llm.py

@@ -0,0 +1,129 @@
+"""Minimal client for any OpenAI-compatible chat endpoint, returning schema-validated JSON.
+
+Configuration comes from the environment: OBEY_LLM_BASE_URL (default OpenRouter), OBEY_LLM_API_KEY (falls back
+to OPENROUTER_API_KEY) and OBEY_LLM_MODEL. Every call is written to the spend ledger.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from obey_cli.runner.ledger import Entry, Ledger, Price, now, provider_cost, usage_from_response
+
+DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+@dataclass
+class LLMConfig:
+    base_url: str
+    api_key: str
+    model: str
+
+    @classmethod
+    def from_env(cls, model: str | None = None) -> LLMConfig:
+        key = os.environ.get("OBEY_LLM_API_KEY") or os.environ.get("OPENROUTER_API_KEY") or ""
+        if not key:
+            raise LLMError("set OBEY_LLM_API_KEY (or OPENROUTER_API_KEY) to use --llm")
+        chosen = model or os.environ.get("OBEY_LLM_MODEL")
+        if not chosen:
+            raise LLMError("set OBEY_LLM_MODEL or pass --llm-model")
+        return cls(os.environ.get("OBEY_LLM_BASE_URL", DEFAULT_BASE_URL).rstrip("/"), key, chosen)
+
+
+def _first_json_object(text: str) -> Any:
+    text = re.sub(r"^```(?:json)?\s*|\s*```$", "", text.strip())
+    try:
+        return json.loads(text)
+    except ValueError:
+        pass
+    for open_, close in (("{", "}"), ("[", "]")):
+        start = text.find(open_)
+        end = text.rfind(close)
+        if start >= 0 and end > start:
+            try:
+                return json.loads(text[start : end + 1])
+            except ValueError:
+                continue
+    raise ValueError("no JSON object in the response")
+
+
+def chat_json(
+    config: LLMConfig,
+    system: str,
+    user: str,
+    schema: dict[str, Any],
+    ledger: Ledger | None = None,
+    price: Price | None = None,
+    run_id: str = "llm",
+    max_tokens: int = 2000,
+    attempts: int = 2,
+    normalize: Any = None,
+) -> dict[str, Any]:
+    """Ask for a JSON object and validate it against `schema`; retries once with the validation error.
+
+    `normalize`, when given, maps the parsed JSON (object or array) to the object the schema describes.
+    """
+    import httpx
+    import jsonschema
+
+    messages: list[dict[str, str]] = [{"role": "system", "content": system}, {"role": "user", "content": user}]
+    last_error = ""
+    for _ in range(attempts):
+        if ledger is not None:
+            ledger.check()
+        payload: dict[str, Any] = {
+            "model": config.model,
+            "messages": messages,
+            "temperature": 0,
+            "max_tokens": max_tokens,
+            "response_format": {"type": "json_object"},
+            "usage": {"include": True},
+        }
+        resp = httpx.post(
+            f"{config.base_url}/chat/completions",
+            headers={"Authorization": f"Bearer {config.api_key}", "Content-Type": "application/json"},
+            json=payload,
+            timeout=120.0,
+        )
+        if resp.status_code >= 400:
+            raise LLMError(f"model endpoint returned HTTP {resp.status_code}: {resp.text[:300]}")
+        body = resp.json()
+        usage = usage_from_response(body)
+        cost = provider_cost(body)
+        if ledger is not None:
+            ledger.record(
+                Entry(
+                    ts=now(),
+                    run_id=run_id,
+                    kind="llm",
+                    model=config.model,
+                    cost_usd=cost if cost is not None else (price.cost(usage) if price else 0.0),
+                    cost_source="provider" if cost is not None else "price_table",
+                    **usage,
+                )
+            )
+        try:
+            content = body["choices"][0]["message"]["content"] or ""
+            data = _first_json_object(content)
+            if normalize is not None:
+                data = normalize(data)
+            jsonschema.validate(data, schema)
+            if not isinstance(data, dict):
+                raise ValueError("top-level JSON value is not an object")
+            return data
+        except (KeyError, IndexError, ValueError, jsonschema.ValidationError) as exc:
+            last_error = str(exc)[:500]
+            messages = [
+                *messages,
+                {"role": "assistant", "content": str(body.get("choices", [{}])[0].get("message", {}).get("content"))},
+                {"role": "user", "content": f"That was not valid: {last_error}. Reply with the JSON object only."},
+            ]
+    raise LLMError(f"no valid JSON after {attempts} attempts: {last_error}")

obey_cli/parse_md.py

@@ -0,0 +1,260 @@
+"""Turn instruction-file Markdown into rule candidates.
+
+A candidate is a list item, a table row, or a prose sentence that contains a directive word. Fenced code,
+HTML comments and front matter are never candidates. Every candidate keeps its line span and the headings
+above it, because a bullet under a "Don't" heading means the opposite of the same bullet under "Do".
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+_STRONG_DIRECTIVE_RE = re.compile(
+    r"\b(always|never|must|mustn't|must not|shall|should|shouldn't|should not|do not|don't|avoid|prefer|"
+    r"required|forbidden|prohibited|not allowed|ensure|make sure|instead of|rather than)\b",
+    re.IGNORECASE,
+)
+_IMPERATIVE_VERBS = (
+    r"use|run|add|keep|write|follow|put|name|commit|push|edit|modify|touch|change|prefer|avoid|never|always|do|don't|"
+    r"ensure|make|place|create|update|include|end|start|begin|check|import|install|"
+    r"log|return|wrap|ask|leave|treat|store|limit|stick|rely|mark|annotate|declare|be|plan|co-locate|colocate|"
+    r"mention|match|say|tell|reply|respond|split|move|delete|remove|rename|bump|pin|call|raise|"
+    r"handle|validate|escape|prefix|suffix|reuse|guard|mock|stub|skip|verify|confirm|cite"
+)
+_IMPERATIVE_START_RE = re.compile(rf"^({_IMPERATIVE_VERBS})\b", re.IGNORECASE)
+# "After changing Python files, run X." / "We review quickly, so keep changes small."
+_CLAUSE_IMPERATIVE_RE = re.compile(rf"(,|;|:|\bso|\bplease|\bthen)\s+({_IMPERATIVE_VERBS})\b", re.IGNORECASE)
+_NORMATIVE_RE = re.compile(
+    r"\b(needs? (approval|sign-?off|review|a test|tests|to be)|has no place|not welcome|(is|are) (banned|off-limits|"
+    r"required|mandatory|immutable|read-only)|(kebab|snake|pascal|camel)[- _]?case|(starts?|begins?|ends?) with|"
+    r"(is|are) named|names? (are|is|use))\b",
+    re.IGNORECASE,
+)
+_LEADING_SYMBOLS_RE = re.compile(r"^[^\w`(\[\"']+")
+_FENCE_RE = re.compile(r"^\s{0,3}(`{3,}|~{3,})")
+_LIST_RE = re.compile(r"^(\s*)(?:[-*+]|\d{1,3}[.)])\s+(?:\[[ xX]\]\s+)?(.*)$")
+_HEADING_RE = re.compile(r"^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$")
+_TABLE_RE = re.compile(r"^\s*\|(.*)\|\s*$")
+_TABLE_SEP_RE = re.compile(r"^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$")
+_SENTENCE_SPLIT_RE = re.compile(r"(?<=[.!?])\s+(?=[A-Z`*_\"'(])")
+_CODE_SPAN_RE = re.compile(r"`([^`]+)`")
+_EMPHASIS_RE = re.compile(r"(\*\*|(?<!\w)__|\*|(?<!\w)_)(\S(?:.*?\S)?)\1(?!\w)")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\([^)]*\)")
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.S)
+_IMPORT_RE = re.compile(r"(?:(?<=\s)|^)@((?:~/|\.{1,2}/|[\w])[\w./~-]*[\w/])")
+
+
+@dataclass
+class Candidate:
+    """A piece of instruction text that may be a rule."""
+
+    text: str
+    raw: str
+    line_start: int
+    line_end: int
+    kind: str  # "list" | "table" | "sentence"
+    headings: list[str] = field(default_factory=list)
+    code_spans: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ParsedFile:
+    frontmatter: dict[str, Any]
+    candidates: list[Candidate]
+    imports: list[tuple[str, int]]  # (import path as written, line number)
+    body_start_line: int
+
+
+def split_frontmatter(text: str) -> tuple[dict[str, Any], str, int]:
+    """Return (front matter, body, line number where the body starts)."""
+    if not text.startswith("---"):
+        return {}, text, 1
+    lines = text.split("\n")
+    if lines[0].strip() != "---":
+        return {}, text, 1
+    for i in range(1, len(lines)):
+        if lines[i].strip() in ("---", "..."):
+            raw = "\n".join(lines[1:i])
+            try:
+                data = yaml.safe_load(raw) or {}
+            except yaml.YAMLError:
+                data = _loose_frontmatter(raw)
+            if not isinstance(data, dict):
+                data = {}
+            return data, "\n".join(lines[i + 1 :]), i + 2
+    return {}, text, 1
+
+
+def _loose_frontmatter(raw: str) -> dict[str, Any]:
+    # .mdc files often hold unquoted globs such as `globs: *.ts`, which is invalid YAML.
+    data: dict[str, Any] = {}
+    for line in raw.splitlines():
+        if ":" in line:
+            key, _, value = line.partition(":")
+            data[key.strip()] = value.strip().strip("\"'")
+    return data
+
+
+def plain(text: str) -> str:
+    """Strip inline Markdown while keeping code-span content (`snake_case` keeps its underscore)."""
+    spans: list[str] = []
+
+    def stash(m: re.Match[str]) -> str:
+        spans.append(m.group(1))
+        return f"\x00{len(spans) - 1}\x00"
+
+    out = _LINK_RE.sub(r"\1", text)
+    out = _CODE_SPAN_RE.sub(stash, out)
+    for _ in range(2):
+        out = _EMPHASIS_RE.sub(r"\2", out)
+    out = re.sub(r"<[^>]+>", "", out)
+    out = re.sub("\x00(\\d+)\x00", lambda m: spans[int(m.group(1))], out)
+    return re.sub(r"\s+", " ", out).strip()
+
+
+def is_directive(text: str) -> bool:
+    bare = _LEADING_SYMBOLS_RE.sub("", text.strip())
+    return bool(
+        _STRONG_DIRECTIVE_RE.search(bare)
+        or _IMPERATIVE_START_RE.match(bare)
+        or _CLAUSE_IMPERATIVE_RE.search(bare)
+        or _NORMATIVE_RE.search(bare)
+    )
+
+
+def _blank_comments(text: str) -> str:
+    # Replace HTML comments with blank lines so line numbers stay right.
+    return _HTML_COMMENT_RE.sub(lambda m: "\n" * m.group(0).count("\n"), text)
+
+
+def parse(text: str) -> ParsedFile:
+    frontmatter, body, start = split_frontmatter(text)
+    body = _blank_comments(body)
+    lines = body.split("\n")
+    candidates: list[Candidate] = []
+    imports: list[tuple[str, int]] = []
+    headings: list[tuple[int, str]] = []
+    in_fence: str | None = None
+    para: list[tuple[int, str]] = []
+    item: list[tuple[int, str]] = []
+    item_indent = 0
+
+    def flush_para() -> None:
+        if para:
+            _emit_sentences(para, [h for _, h in headings], candidates)
+            para.clear()
+
+    def flush_item() -> None:
+        if item:
+            raw = " ".join(s.strip() for _, s in item)
+            _emit(raw, item[0][0], item[-1][0], "list", [h for _, h in headings], candidates)
+            item.clear()
+
+    for offset, line in enumerate(lines):
+        lineno = start + offset
+        fence = _FENCE_RE.match(line)
+        if in_fence is not None:
+            if fence and fence.group(1)[0] == in_fence[0] and len(fence.group(1)) >= len(in_fence):
+                in_fence = None
+            continue
+        if fence:
+            flush_para()
+            flush_item()
+            in_fence = fence.group(1)
+            continue
+        for m in _IMPORT_RE.finditer(_strip_code_spans(line)):
+            imports.append((m.group(1), lineno))
+        if not line.strip():
+            flush_para()
+            flush_item()
+            continue
+        heading = _HEADING_RE.match(line)
+        if heading:
+            flush_para()
+            flush_item()
+            level = len(heading.group(1))
+            headings = [(lvl, h) for lvl, h in headings if lvl < level]
+            headings.append((level, plain(heading.group(2))))
+            continue
+        if _TABLE_RE.match(line):
+            flush_para()
+            flush_item()
+            if not _TABLE_SEP_RE.match(line):
+                cells = [c.strip() for c in _TABLE_RE.match(line).group(1).split("|")]  # type: ignore[union-attr]
+                cells = [c for c in cells if c]
+                labels = [h for _, h in headings]
+                # A short first cell ("Errors", "Lint") is a label for the rule in the next cell.
+                first = plain(cells[0]) if cells else ""
+                if (
+                    len(cells) >= 2
+                    and len(first.split()) <= 3
+                    and not is_directive(first)
+                    and not first.lower().startswith(("no ", "not ", "only "))
+                ):
+                    labels = [*labels, plain(cells[0])]
+                    cells = cells[1:]
+                _emit(" — ".join(cells), lineno, lineno, "table", labels, candidates)
+            continue
+        listed = _LIST_RE.match(line)
+        if listed:
+            flush_para()
+            flush_item()
+            item_indent = len(listed.group(1))
+            item.append((lineno, listed.group(2)))
+            continue
+        if item and (len(line) - len(line.lstrip())) > item_indent:
+            item.append((lineno, line))
+            continue
+        if line.lstrip().startswith(">"):
+            line = line.lstrip()[1:]
+        flush_item()
+        para.append((lineno, line))
+    flush_para()
+    flush_item()
+    return ParsedFile(frontmatter=frontmatter, candidates=candidates, imports=imports, body_start_line=start)
+
+
+def _strip_code_spans(line: str) -> str:
+    return _CODE_SPAN_RE.sub(lambda m: " " * len(m.group(0)), line)
+
+
+def _emit(raw: str, start: int, end: int, kind: str, headings: list[str], out: list[Candidate]) -> None:
+    text = plain(raw)
+    if len(text) < 3 or not re.search(r"[A-Za-z]{2}", text):
+        return
+    out.append(
+        Candidate(
+            text=text,
+            raw=raw.strip(),
+            line_start=start,
+            line_end=end,
+            kind=kind,
+            headings=list(headings),
+            code_spans=_CODE_SPAN_RE.findall(raw),
+        )
+    )
+
+
+def _emit_sentences(para: list[tuple[int, str]], headings: list[str], out: list[Candidate]) -> None:
+    # Join the paragraph, split it into sentences, and map each sentence back to its first line.
+    joined = ""
+    starts: list[tuple[int, int]] = []  # (char offset, line number)
+    for lineno, text in para:
+        if joined:
+            joined += " "
+        starts.append((len(joined), lineno))
+        joined += text.strip()
+    pos = 0
+    for sentence in _SENTENCE_SPLIT_RE.split(joined):
+        idx = joined.find(sentence, pos)
+        if idx < 0:
+            idx = pos
+        pos = idx + len(sentence)
+        first = max((ln for off, ln in starts if off <= idx), default=para[0][0])
+        last = max((ln for off, ln in starts if off < pos), default=first)
+        if is_directive(plain(sentence)):
+            _emit(sentence, first, last, "sentence", headings, out)

obey_cli/probes/facts.py

@@ -0,0 +1,162 @@
+"""Facts about a repository that probe templates fill in: languages, package manager, test command, layout."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+
+from obey_cli.discover import list_files
+
+_LANG_EXT = {
+    ".py": "python",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".go": "go",
+    ".rs": "rust",
+}
+_SKIP_PARTS = {"generated", "gen", "vendor", "dist", "build", "migrations", "node_modules", "__pycache__"}
+
+
+@dataclass
+class Facts:
+    root: Path
+    files: list[str]
+    language: str  # python | typescript | javascript | go | rust | unknown
+    package_manager: str | None  # pnpm | npm | yarn | bun | uv | poetry | pip | go | cargo
+    test_command: str | None
+    lint_command: str | None
+    source_files: list[str] = field(default_factory=list)  # ordinary source files, most central first
+    test_files: list[str] = field(default_factory=list)
+    source_dir: str = "src"
+    test_dir: str = "tests"
+    migrations: list[str] = field(default_factory=list)
+    generated: list[str] = field(default_factory=list)
+
+    @property
+    def ext(self) -> str:
+        return {"python": ".py", "typescript": ".ts", "javascript": ".js", "go": ".go", "rust": ".rs"}.get(
+            self.language, ".txt"
+        )
+
+
+def _read(root: Path, rel: str) -> str:
+    try:
+        return (root / rel).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def detect(root: Path) -> Facts:
+    files = list_files(root)
+    langs = Counter(_LANG_EXT[PurePosixPath(f).suffix] for f in files if PurePosixPath(f).suffix in _LANG_EXT)
+    language = langs.most_common(1)[0][0] if langs else "unknown"
+    if language == "javascript" and langs.get("typescript"):
+        language = "typescript"
+    names = set(files)
+    pm = None
+    pkg = json.loads(_read(root, "package.json") or "{}") if "package.json" in names else {}
+    declared = str(pkg.get("packageManager", ""))
+    for candidate, marker in (
+        ("pnpm", "pnpm-lock.yaml"),
+        ("yarn", "yarn.lock"),
+        ("bun", "bun.lock"),
+        ("bun", "bun.lockb"),
+        ("npm", "package-lock.json"),
+    ):
+        if marker in names or declared.startswith(candidate + "@"):
+            pm = candidate
+            break
+    if pm is None and "package.json" in names:
+        pm = "npm"
+    if pm is None:
+        pyproject = _read(root, "pyproject.toml")
+        if "uv.lock" in names or "[tool.uv]" in pyproject or "[dependency-groups]" in pyproject:
+            pm = "uv"
+        elif "poetry.lock" in names or "[tool.poetry]" in pyproject:
+            pm = "poetry"
+        elif pyproject or any(f.startswith("requirements") for f in names):
+            pm = "uv" if "uv" in _read(root, "Makefile") else "pip"
+        elif "go.mod" in names:
+            pm = "go"
+        elif "Cargo.toml" in names:
+            pm = "cargo"
+    test_cmd = lint_cmd = None
+    makefile = _read(root, "Makefile")
+    if re.search(r"^test:", makefile, re.M):
+        test_cmd = "make test"
+    if re.search(r"^lint:", makefile, re.M):
+        lint_cmd = "make lint"
+    scripts = pkg.get("scripts") or {}
+    if test_cmd is None and "test" in scripts:
+        test_cmd = f"{pm or 'npm'} test"
+    if lint_cmd is None and "lint" in scripts:
+        lint_cmd = f"{pm or 'npm'} run lint" if pm in (None, "npm") else f"{pm} lint"
+    if test_cmd is None and language == "python":
+        test_cmd = "uv run pytest" if pm == "uv" else "pytest"
+    if test_cmd is None and language == "go":
+        test_cmd = "go test ./..."
+    if test_cmd is None and language == "rust":
+        test_cmd = "cargo test"
+    ext = {"python": ".py", "typescript": ".ts", "javascript": ".js", "go": ".go", "rust": ".rs"}.get(language, "")
+
+    def is_test(f: str) -> bool:
+        name = PurePosixPath(f).name
+        return bool(re.match(r"test_.*\.py$|.*_test\.(py|go)$|.*\.(test|spec)\.[jt]sx?$", name)) or f.startswith(
+            ("tests/", "test/")
+        )
+
+    sources = [
+        f
+        for f in files
+        if f.endswith(ext)
+        and not is_test(f)
+        and not (set(PurePosixPath(f).parts) & _SKIP_PARTS)
+        and not f.startswith(("scripts/", "tools/"))
+        and PurePosixPath(f).name not in ("__init__.py", "main.ts")
+    ]
+    sources.sort(key=lambda f: (-len(_read(root, f)), f))
+    tests = [f for f in files if is_test(f)]
+    src_dir = Counter(PurePosixPath(f).parts[0] for f in sources if len(PurePosixPath(f).parts) > 1).most_common(1)
+    test_dir = (
+        "tests"
+        if any(f.startswith("tests/") for f in files)
+        else "test"
+        if any(f.startswith("test/") for f in files)
+        else (PurePosixPath(tests[0]).parent.as_posix() if tests else "tests")
+    )
+    migrations = sorted(
+        f for f in files if "/migrations/" in f"/{f}" and f.endswith((".sql", ".py")) and not f.endswith("__init__.py")
+    )
+    generated = (
+        sorted(
+            f
+            for f in files
+            if "generated" in PurePosixPath(f).parts
+            or re.search(r"(do not edit|generated by|auto-?generated)", _read(root, f)[:400], re.I)
+        )
+        if files
+        else []
+    )
+    generated = [g for g in generated if not g.endswith((".md", "__init__.py")) and g not in ("AGENTS.md", "CLAUDE.md")]
+    generated.sort(
+        key=lambda g: (not re.search(r"(do not edit|generated by|generated from)", _read(root, g)[:400], re.I), g)
+    )
+    return Facts(
+        root=root,
+        files=files,
+        language=language,
+        package_manager=pm,
+        test_command=test_cmd,
+        lint_command=lint_cmd,
+        source_files=sources,
+        test_files=tests,
+        source_dir=src_dir[0][0] if src_dir else "src",
+        test_dir=test_dir,
+        migrations=migrations,
+        generated=generated,
+    )