coding-os 0.3.2__py3-none-any.whl

core/hooks/_helpers/doc_sync_check.py

@@ -0,0 +1,498 @@
+"""
+Coding OS — doc-sync staleness scanner (graph- and FTS-aware).
+
+PURPOSE
+    PostToolUse Write|Edit|MultiEdit helper. Given the just-edited code
+    file (and optionally the pre-edit content), surface docs that look
+    out of sync with the new code.
+
+WHY THIS BEAT THE NAIVE REGEX HOOK
+    1. **Signature drift** — function name unchanged but parameter list
+       grew/shrunk. The regex hook missed this; the user's birthdate
+       example is exactly this case.
+    2. **FTS-backed doc candidates** — instead of guessing docs from
+       path heuristics, query the SQLite FTS5 index thinking_os already
+       maintains over `docs/**/*.md`. Sub-10 ms per query, far more
+       accurate than path-mirror.
+    3. **Optional graph context** — when the graph_os backend is
+       available, add a one-line "this symbol is referenced by N other
+       files" hint via `cos_graph_references`. Capped at 200 ms so the
+       hot path stays fast.
+
+OUTPUT (one line per finding, tab-separated)
+    STALE\t<doc_path>\t<reason>
+Always exits 0 — this is a WARN signal, never a BLOCK.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sqlite3
+import sys
+import time
+from pathlib import Path
+
+# ── Tunables ─────────────────────────────────────────────────────────────
+_MAX_CANDIDATES = 6
+_GRAPH_BUDGET_S = 0.2
+_FTS_BUDGET_S = 0.1
+
+
+CODE_EXT_TO_LANG = {
+    ".py": "python",
+    ".ts": "ts",
+    ".tsx": "ts",
+    ".js": "ts",
+    ".jsx": "ts",
+    ".go": "go",
+    ".rs": "rust",
+}
+
+DOC_EXTENSIONS = {".md", ".mdx"}
+
+# ── Symbol extraction ────────────────────────────────────────────────────
+# We capture the name AND a representation of the parameter list so a
+# pure-rename, a pure-signature-change, and a deletion all surface
+# distinct signals.
+
+_PY_FN_RX = re.compile(r"^\s*(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)")
+_PY_CLASS_RX = re.compile(r"^\s*class\s+([A-Z][A-Za-z0-9_]*)\b")
+_TS_FN_RX = re.compile(
+    r"^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)"
+)
+_TS_CLASS_RX = re.compile(r"^\s*(?:export\s+)?class\s+([A-Z][A-Za-z0-9_]*)\b")
+_TS_CONST_FN_RX = re.compile(
+    r"^\s*(?:export\s+)?(?:const|let)\s+([A-Za-z_][A-Za-z0-9_]*)\s*[:=]\s*"
+    r"(?:async\s+)?\(([^)]*)\)\s*(?::[^=]+)?=>"
+)
+
+
+def _is_public(name: str) -> bool:
+    """Skip dunders, private (underscore-prefix), CamelCase one-shots that
+    look like type aliases. We only care about names a doc would mention."""
+    if not name:
+        return False
+    if name.startswith("__") and name.endswith("__"):
+        return False
+    if name.startswith("_") and not name.startswith("__"):
+        return False
+    return True
+
+
+def _normalise_params(params: str) -> tuple[int, str]:
+    """Return (param_count, normalised_signature_string).
+
+    Crude — strips type annotations and defaults, splits on top-level
+    commas. Fine for the drift signal we want; not a full parser."""
+    if not params or not params.strip():
+        return 0, ""
+    # Strip annotations / defaults to get bare param names.
+    raw_parts: list[str] = []
+    depth = 0
+    cur = []
+    for ch in params:
+        if ch in "([{":
+            depth += 1
+            cur.append(ch)
+        elif ch in ")]}":
+            depth -= 1
+            cur.append(ch)
+        elif ch == "," and depth == 0:
+            raw_parts.append("".join(cur).strip())
+            cur = []
+        else:
+            cur.append(ch)
+    raw_parts.append("".join(cur).strip())
+
+    names: list[str] = []
+    for p in raw_parts:
+        if not p:
+            continue
+        # Drop default value ("x: int = 0" → "x: int")
+        p = p.split("=", 1)[0]
+        # Drop annotation ("x: int" → "x")
+        name = p.split(":", 1)[0].strip()
+        # Drop *, **, ... markers ("**kwargs" → "kwargs")
+        name = name.lstrip("*")
+        if name and name not in ("self", "cls", "/", "*"):
+            names.append(name)
+    return len(names), ",".join(names)
+
+
+def _extract_symbols(text: str, lang: str) -> dict[str, tuple[int, str]]:
+    """name → (param_count, normalised_signature). Class names get
+    placeholder (-1, "") since we don't extract class signatures.
+    Public names only."""
+    out: dict[str, tuple[int, str]] = {}
+    if lang == "python":
+        fn_rxs, class_rx = [_PY_FN_RX], _PY_CLASS_RX
+    elif lang == "ts":
+        fn_rxs, class_rx = [_TS_FN_RX, _TS_CONST_FN_RX], _TS_CLASS_RX
+    else:
+        return out
+
+    for line in text.splitlines():
+        for rx in fn_rxs:
+            m = rx.match(line)
+            if m:
+                name = m.group(1)
+                if _is_public(name):
+                    out[name] = _normalise_params(m.group(2))
+                break
+        else:
+            m = class_rx.match(line)
+            if m and _is_public(m.group(1)):
+                out.setdefault(m.group(1), (-1, ""))
+    return out
+
+
+# ── Doc candidate enumeration ────────────────────────────────────────────
+
+
+def _find_project_root(code_file: Path) -> Path | None:
+    p = code_file.resolve().parent
+    while p != p.parent:
+        if (p / ".coding-os").is_dir() or (p / "AGENTS.md").is_file():
+            return p
+        p = p.parent
+    return None
+
+
+def _doc_anchor_paths(project_root: Path) -> list[Path]:
+    """Files the agent already declared as 'this code traces to'."""
+    out: list[Path] = []
+    state = project_root / ".coding-os"
+    if not state.is_dir():
+        return out
+    for agent_dir in state.iterdir():
+        anchor = agent_dir / ".doc-anchor"
+        if anchor.is_file():
+            try:
+                rel = anchor.read_text(encoding="utf-8").strip()
+                if rel:
+                    p = (project_root / rel).resolve()
+                    if p.is_file() and p.suffix in DOC_EXTENSIONS:
+                        out.append(p)
+            except OSError:
+                continue
+    return out
+
+
+def _fts_candidates(
+    project_root: Path,
+    symbols: list[str],
+    limit: int,
+) -> list[Path]:
+    """Use thinking_os document_chunks_fts to find docs that lexically
+    mention any of the given symbols. ~10 ms total for ≤8 symbols."""
+    db_path = project_root / ".coding-os" / "coding-os.db"
+    if not db_path.is_file() or not symbols:
+        return []
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=0.5)
+    except sqlite3.Error:
+        return []
+    try:
+        # FTS5 OR query — quote symbols to avoid syntax issues.
+        # E.g.: `"register_user" OR "AuthService"`
+        terms = " OR ".join(f'"{s}"' for s in symbols if s.replace("_", "").isalnum())
+        if not terms:
+            return []
+        deadline = time.time() + _FTS_BUDGET_S
+        rows = conn.execute(
+            """
+            SELECT DISTINCT dc.source_path
+            FROM document_chunks_fts
+            JOIN document_chunks dc ON dc.id = document_chunks_fts.rowid
+            WHERE document_chunks_fts MATCH ?
+              AND dc.source_type = 'doc'
+            LIMIT ?
+            """,
+            (terms, limit),
+        ).fetchall()
+        if time.time() > deadline:
+            # Soft budget — the row materialisation already happened, but
+            # if we somehow blew past deadline, bail.
+            return []
+    except sqlite3.OperationalError:
+        return []
+    finally:
+        conn.close()
+
+    out: list[Path] = []
+    for (path,) in rows:
+        try:
+            p = (project_root / path).resolve() if not Path(path).is_absolute() else Path(path)
+            if p.is_file() and p.suffix in DOC_EXTENSIONS:
+                out.append(p)
+        except OSError:
+            continue
+    return out
+
+
+def _fts_is_empty(project_root: Path) -> bool:
+    """True when document_chunks_fts has zero rows — Rule 19 enforcement is
+    effectively off until `make docs-index` populates it."""
+    db_path = project_root / ".coding-os" / "coding-os.db"
+    if not db_path.is_file():
+        return False
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=0.5)
+    except sqlite3.Error:
+        return False
+    try:
+        row = conn.execute("SELECT COUNT(*) FROM document_chunks_fts").fetchone()
+    except sqlite3.OperationalError:
+        return False
+    finally:
+        conn.close()
+    return bool(row) and row[0] == 0
+
+
+def _path_mirror_candidates(project_root: Path, code_file: Path) -> list[Path]:
+    """Last-resort heuristic: domain-typical doc paths. Used to catch the
+    "no FTS index yet" / "doc anchor not set" startup case."""
+    out: list[Path] = []
+    seen: set[Path] = set()
+
+    def _add(p: Path) -> None:
+        if p not in seen and p.exists() and p.is_file() and p.suffix in DOC_EXTENSIONS:
+            out.append(p)
+            seen.add(p)
+
+    try:
+        rel = code_file.resolve().relative_to(project_root.resolve())
+    except ValueError:
+        return out
+    parts = rel.parts
+    docs_dir = project_root / "docs"
+    if not docs_dir.is_dir():
+        return out
+    if parts and parts[0] == "backend":
+        _add(docs_dir / "playbooks" / "backend-api.md")
+        _add(docs_dir / "engineering" / "backend-rules.md")
+    if parts and parts[0] == "frontend":
+        _add(docs_dir / "playbooks" / "frontend-ui.md")
+        _add(docs_dir / "engineering" / "frontend-rules.md")
+    if parts and parts[0] == "core" and len(parts) >= 2:
+        sub = parts[1]
+        _add(docs_dir / "engineering" / f"{sub}.md")
+        _add(docs_dir / "engineering" / f"{sub.replace('_', '-')}.md")
+    return out
+
+
+# ── Drift detection ──────────────────────────────────────────────────────
+
+
+def _check_doc(
+    doc_path: Path,
+    new_syms: dict[str, tuple[int, str]],
+    old_syms: dict[str, tuple[int, str]],
+) -> str | None:
+    """Return a short reason string if `doc_path` references a removed,
+    renamed, or signature-changed symbol from this edit."""
+    try:
+        text = doc_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+
+    findings: list[str] = []
+
+    # Signal 1 — symbol REMOVED (was in old, gone in new), still in doc.
+    removed = set(old_syms) - set(new_syms)
+    for sym in sorted(removed):
+        if re.search(rf"(?<![A-Za-z0-9_]){re.escape(sym)}(?![A-Za-z0-9_])", text):
+            findings.append(f"removed `{sym}` still mentioned")
+            if len(findings) >= 2:
+                break
+
+    # Signal 2 — SIGNATURE CHANGED on a kept symbol (the user's birthdate
+    # example). param count differs → high-confidence drift.
+    for sym, (new_count, _new_sig) in new_syms.items():
+        if sym not in old_syms:
+            continue
+        old_count, _old_sig = old_syms[sym]
+        if old_count == -1 or new_count == -1:
+            continue  # class symbol — skip
+        if old_count != new_count:
+            if re.search(rf"(?<![A-Za-z0-9_]){re.escape(sym)}(?![A-Za-z0-9_])", text):
+                findings.append(
+                    f"`{sym}` signature changed ({old_count}→{new_count} params); "
+                    f"verify doc still describes the right shape"
+                )
+                if len(findings) >= 2:
+                    break
+
+    if findings:
+        return "; ".join(findings[:2])
+
+    # Signal 3 — soft: doc mtime older than code AND mentions any current
+    # symbol. Lower confidence; only fire if no stronger signal hit.
+    return None  # handled in main() with mtime check
+
+
+# ── Optional graph enrichment ────────────────────────────────────────────
+
+
+def _graph_reference_hint(symbol: str, code_file: Path, deadline: float) -> str | None:
+    """If graph_os backend is up, add 'symbol is called from N other files'.
+    Best-effort; silent on any failure."""
+    if time.time() > deadline:
+        return None
+    try:
+        # Lazy import — adds 30 ms but only when we already decided to WARN.
+        sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+        sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+        from graph_os.tools import graph as gtools  # type: ignore
+
+        # cos_graph_references signature varies per version; call defensively.
+        backend = gtools._backend()
+        if backend is None:
+            return None
+        # Match by symbol name + any callsite outside the changed file.
+        envelope = gtools.cos_graph_references(symbol)
+        if not isinstance(envelope, dict) or not envelope.get("ok"):
+            return None
+        items = envelope.get("data", {}).get("references", [])
+        external = [
+            it
+            for it in items
+            if str(it.get("file") or it.get("path") or "")
+            not in (str(code_file), str(code_file.name))
+        ]
+        n = len(external)
+        if n == 0:
+            return None
+        return f"referenced from {n} other location(s)"
+    except Exception:
+        return None
+
+
+# ── Main ─────────────────────────────────────────────────────────────────
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        return 0
+    code_file = Path(argv[1])
+    if not code_file.exists() or code_file.is_dir():
+        return 0
+    if code_file.suffix not in CODE_EXT_TO_LANG:
+        return 0
+    lang = CODE_EXT_TO_LANG[code_file.suffix]
+
+    project_root = _find_project_root(code_file)
+    if project_root is None:
+        return 0
+
+    try:
+        new_text = code_file.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return 0
+    new_syms = _extract_symbols(new_text, lang)
+
+    old_text = argv[2] if len(argv) >= 3 else None
+    old_syms = _extract_symbols(old_text, lang) if old_text else {}
+
+    # If we have no diff context AND no public symbols, nothing to check.
+    if not new_syms and not old_syms:
+        return 0
+
+    # Build candidate doc set (anchor → FTS hits → path mirror, capped).
+    candidates: list[Path] = list(_doc_anchor_paths(project_root))
+    seen: set[Path] = set(candidates)
+
+    # One-shot warning when FTS is empty — Rule 19 enforcement can't fire
+    # without it. Touched marker lives in state dir so we don't spam every Edit.
+    if _fts_is_empty(project_root):
+        marker = project_root / ".coding-os" / ".warn-fts-empty-shown"
+        if not marker.exists():
+            print(
+                "INFO\t-\tdoc-sync inactive — document_chunks_fts is empty; "
+                "run `make docs-index` to enable staleness detection"
+            )
+            try:
+                marker.parent.mkdir(parents=True, exist_ok=True)
+                marker.touch()
+            except OSError as exc:
+                sys.stderr.write(f"doc_sync_check: marker write skipped: {exc}\n")
+
+    fts_query_syms = list(set(new_syms) | set(old_syms))[:8]
+    for p in _fts_candidates(project_root, fts_query_syms, _MAX_CANDIDATES):
+        if p not in seen:
+            candidates.append(p)
+            seen.add(p)
+    if len(candidates) < 3:
+        for p in _path_mirror_candidates(project_root, code_file):
+            if p not in seen:
+                candidates.append(p)
+                seen.add(p)
+    candidates = candidates[:_MAX_CANDIDATES]
+
+    if not candidates:
+        return 0
+
+    findings: list[tuple[Path, str]] = []
+    code_mtime = code_file.stat().st_mtime
+    for doc in candidates:
+        reason = _check_doc(doc, new_syms, old_syms)
+        if reason:
+            findings.append((doc, reason))
+            continue
+        # Soft signal: doc mtime older than code AND mentions any current
+        # public symbol. Only when we have a real diff (old_text given).
+        if old_text is not None:
+            try:
+                doc_mtime = doc.stat().st_mtime
+            except OSError:
+                continue
+            if doc_mtime < code_mtime - 1:
+                try:
+                    text = doc.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    continue
+                touched = [
+                    s
+                    for s in new_syms
+                    if re.search(rf"(?<![A-Za-z0-9_]){re.escape(s)}(?![A-Za-z0-9_])", text)
+                ]
+                if touched:
+                    findings.append(
+                        (
+                            doc,
+                            f"older than code; mentions `{touched[0]}`"
+                            f"{'…' if len(touched) > 1 else ''}",
+                        )
+                    )
+
+    if not findings:
+        return 0
+
+    # Optional graph enrichment — only when we already decided to WARN.
+    # First touched/kept symbol from the strongest signal.
+    enrichment = None
+    enrich_deadline = time.time() + _GRAPH_BUDGET_S
+    for sym in (set(old_syms) - set(new_syms)) | (set(new_syms) & set(old_syms)):
+        hint = _graph_reference_hint(sym, code_file, enrich_deadline)
+        if hint:
+            enrichment = f"`{sym}` {hint}"
+            break
+
+    try:
+        rel_code = code_file.resolve().relative_to(project_root.resolve())
+    except ValueError:
+        rel_code = code_file
+    for doc, reason in findings[:3]:
+        try:
+            rel_doc = doc.resolve().relative_to(project_root.resolve())
+        except ValueError:
+            rel_doc = doc
+        print(f"STALE\t{rel_doc}\t{reason}")
+    if enrichment:
+        print(f"INFO\t-\t{enrichment}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

core/hooks/_helpers/drain_embedding_outbox.py

@@ -0,0 +1,52 @@
+"""Drain the embedding outbox off the interactive path (Stop-hook helper).
+
+Fast-paths out with zero model load when the outbox is empty (the common case),
+so it never adds latency to a normal session end. Fail-open: any missing dep or
+error is a no-op — the outbox is durable, so a later drain / reindex catches up.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    root = os.environ.get("COS_PROJECT_ROOT", os.getcwd())
+    sys.path.insert(0, str(Path(root) / "src" / "core" / "thinking_os"))
+    try:
+        from database import init_db, resolve_db_path  # type: ignore
+
+        conn = init_db(str(resolve_db_path(Path(root))))
+    except Exception as exc:  # deps/db missing → no-op, durable outbox retried later
+        print(f"[outbox] drain skipped: {exc}", file=sys.stderr)
+        return 0
+    try:
+        # Cheap fast-path: nothing pending → exit before importing the model.
+        pending = conn.execute(
+            "SELECT COUNT(*) FROM embedding_outbox WHERE attempts < 3"
+        ).fetchone()[0]
+        if not pending:
+            return 0
+        import embeddings  # type: ignore
+
+        rep = embeddings.drain_outbox(conn, limit=64)
+        if rep.get("drained"):
+            print(
+                f"[outbox] drained {rep['drained']} embedding(s); "
+                f"{rep.get('remaining', 0)} remaining",
+                file=sys.stderr,
+            )
+    except Exception as exc:
+        print(f"[outbox] drain error: {exc}", file=sys.stderr)
+        return 0
+    finally:
+        with contextlib.suppress(Exception):
+            conn.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

core/hooks/_helpers/extract_additional_context.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Extract the inner additionalContext text from a hook's JSON stdout.
+
+Codex dispatchers coalesce several delegate hooks into one
+SessionStart response. The delegates are the SAME scripts Claude runs, and
+many emit a Claude-style envelope on stdout:
+
+    {"hookSpecificOutput": {"hookEventName": "SessionStart",
+                            "additionalContext": "<card text>"}}
+
+Concatenating that raw envelope into the dispatcher's own additionalContext
+would surface literal JSON to the agent. This filter unwraps it: when stdin
+parses as such an envelope it prints only the inner text; otherwise it passes
+the raw bytes through unchanged (plain-text cards, stderr warnings, empty).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def _inner_context(obj: object) -> str | None:
+    if not isinstance(obj, dict):
+        return None
+    hso = obj.get("hookSpecificOutput")
+    if isinstance(hso, dict) and "additionalContext" in hso:
+        return str(hso["additionalContext"])
+    if "additionalContext" in obj:
+        return str(obj["additionalContext"])
+    if "additional_context" in obj:
+        return str(obj["additional_context"])
+    return None
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return 0
+    try:
+        obj = json.loads(raw)
+    except (ValueError, TypeError):
+        sys.stdout.write(raw)
+        return 0
+    ctx = _inner_context(obj)
+    sys.stdout.write(raw if ctx is None else ctx)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

core/hooks/_helpers/extract_commit_msg_arg.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Extract -m/--message bodies from REAL `git commit` invocations only.
+
+Reads the bash command on stdin, emits the commit message(s) joined by a
+blank line (the multi-`-m` paragraph convention). The shared shlex parser
+scopes extraction to segments whose command word is actually `git` — so a
+`git commit -m "bad"` quoted INSIDE an `echo` or `python3 -c "..."` (a
+verification snippet, a doc example) is NOT treated as a commit to validate
+(TASK-567 fixed enforce-commit-message false-positiving on those). Forms
+the tokenizer can't cleanly resolve (heredoc `-F-`, command substitution)
+yield no message and defer to the git-level commit-msg hook, as before.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+from git_command_parse import git_invocations
+
+# `git_command_parse.normalize()` collapses every newline to `; ` before
+# tokenizing — correct for real statement separators, but a heredoc body
+# (`$(cat <<'EOF' ... EOF)`) has embedded newlines that are literal content,
+# not separators. shlex then hands `_messages` one intact-looking quoted
+# token that is actually still-unexpanded shell source (heredoc markers,
+# `$(...)`/backtick command substitution) rather than the string bash would
+# have produced. Validating that raw source AS IF it were the final message
+# is exactly the bug this module's docstring already promises not to have:
+# treat any such value as unparseable and defer, matching a plain `-m` value
+# that legitimately contains none of these constructs.
+_UNEXPANDED_RE = re.compile(r"\$\(|`|<<-?['\"]?\w")
+
+
+def _looks_unexpanded(value: str) -> bool:
+    return bool(_UNEXPANDED_RE.search(value))
+
+
+def _messages(args: list[str]) -> list[str]:
+    out: list[str] = []
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in ("-m", "--message"):
+            if i + 1 < len(args):
+                out.append(args[i + 1])
+                i += 2
+                continue
+        elif a.startswith("--message="):
+            out.append(a[len("--message=") :])
+        elif a.startswith("-m") and len(a) > 2 and not a.startswith("--"):
+            out.append(a[2:])  # `-mfoo` attached value
+        elif len(a) >= 2 and a[0] == "-" and a[1] != "-" and a[1:].isalpha() and a.endswith("m"):
+            if i + 1 < len(args):  # short cluster ending in m (`-am`, `-sm`)
+                out.append(args[i + 1])
+                i += 2
+                continue
+        i += 1
+    if any(_looks_unexpanded(v) for v in out):
+        return []  # can't cleanly resolve this invocation — defer, don't mis-validate
+    return out
+
+
+def main() -> int:
+    command = sys.stdin.read()
+    parts: list[str] = []
+    for inv in git_invocations(command):
+        if inv.subcmd == "commit":
+            parts.extend(_messages(inv.args))
+    sys.stdout.write("\n\n".join(parts))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())