coding-os 0.3.2__py3-none-any.whl

core/skills/clean-code/scripts/audit-fail-closed.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Audit a Python codebase for fail-open exception patterns.
+
+Detects:
+  - `except: pass` and `except Exception: pass` (silent swallow)
+  - `except:` / `except Exception:` followed only by a `logger.*` call
+    (log-and-allow — fail-open in disguise)
+  - `return None` / `return {}` / `return []` from an except block
+    (silent fallback)
+  - `except (...,):` with non-specific broad exception groups
+
+Usage:
+  python audit-fail-closed.py [paths...]
+  python audit-fail-closed.py --json [paths...]   # for CI ingestion
+
+Exit code:
+  0 — no findings
+  1 — findings present
+  2 — error
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass
+class Finding:
+    path: str
+    line: int
+    kind: str  # silent_swallow | log_and_allow | silent_fallback | broad_except
+    snippet: str
+
+
+def _is_log_call(node: ast.AST) -> bool:
+    if not isinstance(node, ast.Expr):
+        return False
+    call = node.value
+    if not isinstance(call, ast.Call):
+        return False
+    func = call.func
+    if isinstance(func, ast.Attribute):
+        # Match: logger.info / log.warning / logging.error / etc.
+        if func.attr in {"debug", "info", "warning", "warn", "error", "exception", "critical"}:
+            return True
+    return False
+
+
+def _is_silent_return(node: ast.AST) -> bool:
+    if not isinstance(node, ast.Return):
+        return False
+    val = node.value
+    if val is None:
+        return True
+    if isinstance(val, ast.Constant) and val.value is None:
+        return True
+    if isinstance(val, ast.Dict) and not val.keys:
+        return True
+    if isinstance(val, (ast.List, ast.Set, ast.Tuple)) and not val.elts:
+        return True
+    return False
+
+
+def _is_pass(node: ast.AST) -> bool:
+    return isinstance(node, ast.Pass)
+
+
+def _exception_is_broad(handler: ast.ExceptHandler) -> bool:
+    """True if catches bare except or a top-level Exception/BaseException."""
+    if handler.type is None:
+        return True
+    if isinstance(handler.type, ast.Name) and handler.type.id in {"Exception", "BaseException"}:
+        return True
+    if isinstance(handler.type, ast.Tuple):
+        for elt in handler.type.elts:
+            if isinstance(elt, ast.Name) and elt.id in {"Exception", "BaseException"}:
+                return True
+    return False
+
+
+def audit_file(path: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    try:
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source, filename=str(path))
+    except (UnicodeDecodeError, SyntaxError):
+        return findings
+
+    src_lines = source.splitlines()
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ExceptHandler):
+            continue
+        body = node.body
+        line = node.lineno
+        snippet = src_lines[line - 1].strip() if line <= len(src_lines) else ""
+
+        # Pattern 1: pure `pass`
+        if len(body) == 1 and _is_pass(body[0]):
+            findings.append(Finding(str(path), line, "silent_swallow", snippet))
+            continue
+
+        # Pattern 2: log-only (allows execution past block, no raise)
+        if all(_is_log_call(stmt) or _is_pass(stmt) for stmt in body):
+            if _exception_is_broad(node):
+                findings.append(Finding(str(path), line, "log_and_allow", snippet))
+                continue
+
+        # Pattern 3: silent return None / {} / []
+        for stmt in body:
+            if _is_silent_return(stmt) and _exception_is_broad(node):
+                findings.append(Finding(str(path), line, "silent_fallback", snippet))
+                break
+
+    return findings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("paths", nargs="*", default=["."], help="Files or directories to audit")
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of human text")
+    parser.add_argument(
+        "--exclude",
+        default=".venv,venv,node_modules,.build,__pycache__,.git",
+        help="Comma-separated dir names to skip",
+    )
+    args = parser.parse_args()
+
+    excluded = set(s for s in args.exclude.split(",") if s)
+    py_files: list[Path] = []
+    for root in args.paths:
+        p = Path(root)
+        if p.is_file() and p.suffix == ".py":
+            py_files.append(p)
+        elif p.is_dir():
+            for f in p.rglob("*.py"):
+                if any(part in excluded for part in f.parts):
+                    continue
+                py_files.append(f)
+
+    findings: list[Finding] = []
+    for f in py_files:
+        findings.extend(audit_file(f))
+
+    if args.json:
+        json.dump([asdict(x) for x in findings], sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        if not findings:
+            print(f"[audit-fail-closed] OK: {len(py_files)} files scanned, no findings.")
+        else:
+            print(
+                f"[audit-fail-closed] FOUND {len(findings)} finding(s) across {len(py_files)} files:\n"
+            )
+            for f in findings:
+                print(f"  {f.path}:{f.line}  {f.kind}  | {f.snippet}")
+
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

core/skills/codebase-explorer/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: codebase-explorer
+tier: exploration
+domain: [universal]
+description: Conceptual code-reading for unfamiliar areas — trace a feature, follow a data flow, understand a domain. Use when the question is conceptual ("how does auth work?", "what happens when a user buys X?"); for symbol-precise queries (callers, blast radius, rename) use graph-explorer instead. The two are complementary — codebase-explorer reads code as prose; graph-explorer queries it as a graph.
+context: fork
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+argument-hint: "Conceptual area to explore (e.g., 'auth flow', 'payment integration', 'blog comments')"
+last_reviewed: "2026-05-11"
+---
+
+Explore the specified conceptual area of the codebase and produce a structured map. **Boundary with [graph-explorer](../graph-explorer/SKILL.md):**
+
+| Question shape | Use |
+|---|---|
+| "How does X work end-to-end?" | codebase-explorer |
+| "What happens when a user does Y?" | codebase-explorer |
+| "Where does this domain live?" | codebase-explorer |
+| "What calls function `foo`?" | graph-explorer (`cos_graph_references`) |
+| "What breaks if I rename `Bar`?" | graph-explorer (`cos_graph_rename_plan`) |
+| "Blast radius of changing `baz`?" | graph-explorer (`cos_graph_impact`) |
+
+codebase-explorer always *consults* graph-explorer for symbol-precise sub-questions during a conceptual walk — they compose, they don't compete.
+
+## Process
+
+1. **Graph gate** — If the query is an identifier-shaped symbol
+   (`camelCase`, `snake_case`, `Class.method`, `TASK-NNN`, dotted path),
+   try `cos_graph_query` first. It is faster + more accurate than grep
+   for named symbols AND returns confidence-scored edges. Fall back to
+   grep only if the graph returns zero hits (fresh repo, unindexed file)
+   or the query is conceptual ("auth flow", "money handling").
+2. **Entry points** — Use Grep to find the main files related to the topic.
+3. **Trace the flow** — Read key files, follow imports. When symbols
+   cross file boundaries, prefer `cos_graph_context(uid, depth=1)` over
+   chasing imports by hand — it returns the neighbourhood in a single
+   MCP call.
+4. **Dependencies** — Identify what this area depends on (models,
+   services, external APIs). For impact analysis, use
+   `cos_graph_impact(uid, direction="downstream")` — the plan's
+   Formula-2 Step-10 tool.
+5. **Test coverage** — Use Glob to find related test files. Graph edges
+   of type `tested_by` (when present) point directly at them.
+
+## Output Format
+
+Return a structured summary:
+
+```
+## [Area Name] — Codebase Map
+
+### Entry Points
+- file:line — description
+
+### Data Flow
+source → transform → destination
+
+### Key Files
+- path — responsibility
+
+### Dependencies
+- internal: models, services used
+- external: APIs, packages
+
+### Test Coverage
+- test files found
+- gaps identified
+
+### Risks
+- anything fragile, tightly coupled, or undocumented
+```
+
+Do NOT make any changes. This is read-only exploration.
+
+## Tooling
+
+Get a file's structure in one call (stdlib, no graph/MCP needed):
+`python3 scripts/outline.py src/foo.py`
+
+## See also
+
+- [references/reading-strategies.md](references/reading-strategies.md) — top-down reading, conceptual vs structural, orientation moves.
+- [assets/reading-checklist.md](assets/reading-checklist.md) — the orientation gate.
+- [graph-explorer](../graph-explorer/SKILL.md) — switch here for symbol-precise queries (callers, blast radius, rename).
+- [search](../search/SKILL.md) — grep for literals; [technical-writing](../technical-writing/SKILL.md) — write the model down.

core/skills/codebase-explorer/assets/reading-checklist.md

@@ -0,0 +1,24 @@
+<!-- domain:UNIVERSAL | layer:asset | ssot:false | updated:2026-06-04 -->
+# Code-Reading Checklist
+
+Use when picking up an unfamiliar area before changing it.
+
+## Orient (cheap, first)
+- [ ] Found the entry point (route/command/handler) for the feature.
+- [ ] `python3 scripts/outline.py <file>` — have the file's shape.
+- [ ] Read the README / docs for the area.
+- [ ] Read the tests — intended usage + edge cases.
+
+## Trace
+- [ ] Followed the spine of the feature, skimmed off-path helpers.
+- [ ] Named the core entity and tracked its shape through transforms.
+- [ ] Identified the boundaries (DB / queue / HTTP / other service).
+
+## Switch tools when the question turns precise
+- [ ] "who calls / what breaks / rename" → graph-explorer, not more reading.
+- [ ] "where is this literal" → search (grep).
+
+## Confirm understanding
+- [ ] Can state the model in two sentences; gaps resolved.
+- [ ] (If non-trivial) wrote the model down for the next reader.
+- [ ] `git log -p --follow <file>` consulted for any surprising code.

core/skills/codebase-explorer/references/reading-strategies.md

@@ -0,0 +1,52 @@
+<!-- domain:UNIVERSAL | layer:reference | ssot:true | updated:2026-06-04 -->
+# Code-Reading Strategies
+
+> P: Understand an unfamiliar feature or data flow efficiently, top-down then drill.
+> R: "How does X work?" — tracing a feature, following a flow, learning a domain.
+> S: Symbol-precise queries (callers, blast radius, rename) — that's [graph-explorer](../../graph-explorer/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [reading-checklist.md](../assets/reading-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Read top-down, not line-by-line
+
+1. **Entry point first** — find where the feature starts (a route, a CLI command,
+   an event handler). `outline.py` on the file gives the shape in one call.
+2. **Follow the call, skim the rest** — read the function on the path; skip
+   sibling helpers until they're on the path.
+3. **Name the data** — what's the core entity flowing through? Track its shape as
+   it transforms.
+4. **Note the boundaries** — where does control leave this code (DB, queue, HTTP,
+   another service)? Those are the seams.
+
+Reading every line of a 2000-line module to answer one question is the trap.
+Read the *spine* of the feature, drill only where you must.
+
+## Conceptual vs structural (pick the tool)
+
+| Question | Tool |
+|---|---|
+| "how does auth work end to end?" | code-reading (this skill) + `outline.py` |
+| "who calls `validate_token`?" | [graph-explorer](../../graph-explorer/SKILL.md) `references` |
+| "what breaks if I change this?" | graph-explorer `impact` |
+| "where is the string 'X' used?" | [search](../../search/SKILL.md) (grep) |
+
+This skill reads code as prose (narrative understanding); graph-explorer queries
+it as a graph (precise symbol relationships). They are complementary — start
+conceptual, switch to the graph when you need exact call-sites.
+
+## Build a mental model, write it down
+
+After tracing, state the model in two sentences ("a request hits the router →
+the service validates via the policy layer → the repository persists"). If you
+can't, you haven't understood it yet — find the gap. A model written into a doc
+([technical-writing](../../technical-writing/SKILL.md)) saves the next reader the
+trace.
+
+## Orientation moves
+
+- `outline.py src/foo.py` — the file's classes/functions at a glance.
+- Read the tests — they show intended usage and edge cases, often clearer than
+  the implementation.
+- `git log -p --follow <file>` — how it got this way; the *why* behind odd code.
+- README / docs first — the author may have already explained it.

core/skills/codebase-explorer/scripts/outline.py

@@ -0,0 +1,99 @@
+"""Print a fast structural outline of a source file (classes, functions, exports).
+
+PURPOSE:      Orient in an unfamiliar file in one call — the shape (what's
+              defined, where) without reading every line or needing the graph.
+INPUT:        one or more source paths (.py / .ts / .tsx / .js / .jsx). [--json]
+OUTPUT:       An indented outline per file on stdout. Exit 0; 2 on usage.
+DEPENDENCIES: stdlib only (ast for Python, regex for TS/JS) — works in any repo.
+NOTES:        Python uses the real AST (accurate); TS/JS uses a regex heuristic
+              (top-level decls). Pure outline_python()/outline_ts() are
+              unit-testable. Complements graph-explorer (this is zero-dependency,
+              single-file, no MCP). Spec: docs/playbooks/skill-authoring.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def outline_python(text: str) -> list[dict]:
+    tree = ast.parse(text)
+    items: list[dict] = []
+
+    def visit(node: ast.AST, depth: int) -> None:
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                items.append(
+                    {"kind": "func", "name": child.name, "line": child.lineno, "depth": depth}
+                )
+                visit(child, depth + 1)
+            elif isinstance(child, ast.ClassDef):
+                items.append(
+                    {"kind": "class", "name": child.name, "line": child.lineno, "depth": depth}
+                )
+                visit(child, depth + 1)
+
+    visit(tree, 0)
+    return items
+
+
+_TS_DECL = re.compile(
+    r"^(?P<indent>\s*)(export\s+)?(default\s+)?"
+    r"(?P<kind>class|interface|type|enum|function|const|let)\s+(?P<name>\w+)",
+)
+
+
+def outline_ts(text: str) -> list[dict]:
+    items: list[dict] = []
+    for n, line in enumerate(text.splitlines(), 1):
+        m = _TS_DECL.match(line)
+        if m:
+            depth = len(m.group("indent")) // 2
+            items.append(
+                {"kind": m.group("kind"), "name": m.group("name"), "line": n, "depth": depth}
+            )
+    return items
+
+
+def outline_file(path: Path) -> list[dict]:
+    text = path.read_text(encoding="utf-8")
+    if path.suffix == ".py":
+        return outline_python(text)
+    return outline_ts(text)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    result: dict[str, list[dict]] = {}
+    for p in args.files:
+        path = Path(p)
+        try:
+            result[p] = outline_file(path)
+        except FileNotFoundError:
+            print(f"error: {p} not found", file=sys.stderr)
+            return 2
+        except SyntaxError as exc:
+            print(f"error: {p}: {exc}", file=sys.stderr)
+            return 2
+
+    if args.as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        for p, items in result.items():
+            print(p)
+            for it in items:
+                print(f"  {'  ' * it['depth']}{it['kind']} {it['name']}  :{it['line']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))