brain-wiki 0.1.0.dev0__py3-none-any.whl

brainwiki/lint/_model.py

@@ -0,0 +1,103 @@
+"""Lint problems, fixes, and results."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from brainwiki.lint._catalog import fixable as catalog_fixable
+
+
+@dataclass
+class Fix:
+    description: str
+    edit: Callable[[str], str] | None = None  # text transform of the target file
+    move_to: str | None = None
+    create: str | None = None  # full content for a file that does not exist yet
+    target: str | None = None  # file the fix changes, when it is not the problem's file
+
+
+@dataclass
+class Problem:
+    code: str
+    path: str
+    line: int | None
+    message: str
+    severity: str = ""
+    fix: Fix | None = None
+    fixable: bool = False
+
+    def __post_init__(self) -> None:
+        if self.fix is not None:
+            self.fixable = True
+        self.fixable = self.fixable and catalog_fixable(self.code)
+
+    def key(self) -> tuple[str, int, str]:
+        return (self.path, self.line or 0, self.code)
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "code": self.code,
+            "severity": self.severity,
+            "path": self.path,
+            "line": self.line,
+            "message": self.message,
+            "fixable": self.fixable,
+        }
+
+    def __str__(self) -> str:
+        where = f"{self.path}:{self.line}" if self.line else self.path
+        return f"{where} {self.code} {self.message}"
+
+
+@dataclass
+class LintResult:
+    problems: list[Problem] = field(default_factory=list)
+    files_checked: int = 0
+    seconds: float = 0.0
+
+    def count(self, severity: str) -> int:
+        return sum(1 for p in self.problems if p.severity == severity)
+
+    @property
+    def errors(self) -> int:
+        return self.count("error")
+
+    @property
+    def fixable(self) -> int:
+        return sum(1 for p in self.problems if p.fixable)
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "problems": [p.to_json() for p in self.problems],
+            "errors": self.errors,
+            "warnings": self.count("warning"),
+            "info": self.count("info"),
+            "fixable": self.fixable,
+            "files_checked": self.files_checked,
+        }
+
+    def format_text(self) -> str:
+        lines: list[str] = []
+        current = None
+        for p in self.problems:
+            if p.path != current:
+                lines.append(p.path)
+                current = p.path
+            line = str(p.line) if p.line else "-"
+            fix = "  (fixable)" if p.fixable else ""
+            lines.append(f"  {line:>4}  {p.severity:<7}  {p.code}  {p.message}{fix}")
+        total = len(self.problems)
+        if not total:
+            return f"No problems ({self.files_checked} files checked)."
+        parts = [f"{self.errors} error{'s' if self.errors != 1 else ''}"]
+        warnings = self.count("warning")
+        parts.append(f"{warnings} warning{'s' if warnings != 1 else ''}")
+        if self.count("info"):
+            parts.append(f"{self.count('info')} info")
+        summary = f"{total} problem{'s' if total != 1 else ''} ({', '.join(parts)})"
+        if self.fixable:
+            summary += f", {self.fixable} fixable with --fix"
+        lines.append(summary)
+        return "\n".join(lines)

brainwiki/lint/_reports.py

@@ -0,0 +1,242 @@
+"""`reports/`: index queries rendered as Markdown pages for people (design doc 06 §7)."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from brainwiki.ids import is_ulid, ulid_datetime
+from brainwiki.lint._model import LintResult
+
+if TYPE_CHECKING:
+    from brainwiki.engine import Engine
+
+_HEADER = "<!-- Generated by brain-wiki. Do not edit: `brain report` rewrites this file. -->"
+_REPORTS = (
+    "index",
+    "contradictions",
+    "stale",
+    "unverified",
+    "inbox",
+    "duplicates",
+    "orphans",
+    "lint",
+)
+
+
+def _link(path: str, title: str | None = None) -> str:
+    target = path[:-3] if path.lower().endswith(".md") else path
+    label = (title or "").replace("|", "/").replace("]", ")")
+    return f"[[{target}|{label}]]" if label and label != target else f"[[{target}]]"
+
+
+def _page(title: str, intro: str, lines: list[str], empty: str) -> str:
+    body = lines or [empty]
+    return "\n".join([_HEADER, f"# {title}", "", intro, "", *body]) + "\n"
+
+
+def _contradictions(engine: Engine) -> str:
+    seen: set[frozenset[str]] = set()
+    lines = []
+    for row in engine.db.execute(
+        """SELECT a.id AS a_id, a.path AS a_path, a.title AS a_title, b.id AS b_id, b.path AS b_path,
+                  b.title AS b_title, e.qualifier, e.note, e.attrs
+           FROM edges e JOIN nodes a ON a.id = e.src JOIN nodes b ON b.id = e.dst
+           WHERE e.rel = 'conflicts_with' AND a.status = 'active' AND b.status = 'active'
+           ORDER BY a.path, b.path"""
+    ):
+        pair = frozenset((row["a_id"], row["b_id"]))
+        if pair in seen:
+            continue
+        seen.add(pair)
+        extra = " ".join(
+            bit
+            for bit in (
+                f"({row['qualifier']})" if row["qualifier"] else "",
+                f"— {row['note']}" if row["note"] else "",
+            )
+            if bit
+        )
+        lines.append(
+            f"- {_link(row['a_path'], row['a_title'])} ↔ {_link(row['b_path'], row['b_title'])} {extra}".rstrip()
+        )
+    return _page(
+        "Contradictions",
+        "Active notes that conflict with each other. Read both before acting on either.",
+        lines,
+        "No open contradictions.",
+    )
+
+
+def _stale(engine: Engine) -> str:
+    lines = [
+        f"- {_link(r['a_path'], r['a_title'])} depends on {_link(r['b_path'], r['b_title'])} ({r['status']})"
+        for r in engine.db.execute(
+            """SELECT a.path AS a_path, a.title AS a_title, b.path AS b_path, b.title AS b_title, b.status
+               FROM edges e JOIN nodes a ON a.id = e.src JOIN nodes b ON b.id = e.dst
+               WHERE e.rel = 'depends_on' AND a.status = 'active' AND b.status IN ('superseded', 'archived')
+               ORDER BY a.path"""
+        )
+    ]
+    return _page(
+        "Stale dependencies",
+        "Active notes that depend on superseded or archived notes; they may need updating.",
+        lines,
+        "No stale dependencies.",
+    )
+
+
+def _unverified(engine: Engine) -> str:
+    lines = [
+        f"- {_link(r['path'], r['title'])}: {r['c']} unverified claim{'s' if r['c'] != 1 else ''}"
+        for r in engine.db.execute(
+            """SELECT n.path, n.title, COUNT(*) AS c FROM claims c JOIN nodes n ON n.id = c.node_id
+               WHERE c.inputs IN ('external', 'unknown') AND c.status = 'active'
+               GROUP BY n.id ORDER BY c DESC, n.path"""
+        )
+    ]
+    return _page(
+        "Unverified claims",
+        "Notes with active claims derived from untrusted or unknown sources (shown as [unverified] in reads).",
+        lines,
+        "No unverified claims.",
+    )
+
+
+def _inbox(engine: Engine) -> str:
+    now = datetime.now(UTC)
+    by_agent: dict[str, list[tuple[float, str]]] = defaultdict(list)
+    for row in engine.db.execute("SELECT path, fm_id, agent FROM nodes WHERE kind = 'episode'"):
+        age = (
+            (now - ulid_datetime(row["fm_id"])).total_seconds() / 86400
+            if is_ulid(row["fm_id"] or "")
+            else 0.0
+        )
+        by_agent[row["agent"] or "unknown"].append((age, row["path"]))
+    lines = ["## Pending episodes", ""]
+    if not by_agent:
+        lines.append("None.")
+    for agent, items in sorted(by_agent.items()):
+        items.sort(reverse=True)
+        lines.append(f"- **{agent}**: {len(items)} pending, oldest {items[0][0]:.0f} days")
+        for age, path in items[:20]:
+            lines.append(f"  - {_link(path)} ({age:.0f} days)")
+        if len(items) > 20:
+            lines.append(f"  - … {len(items) - 20} more")
+    lines += ["", "## Open proposals", ""]
+    proposals = [
+        r["path"]
+        for r in engine.db.execute("SELECT path FROM files WHERE kind = 'proposal' ORDER BY path")
+    ]
+    lines += [f"- {_link(p)}" for p in proposals] or ["None."]
+    return _page(
+        "Inbox", "Episodes waiting for consolidation, and proposals waiting for review.", lines, ""
+    )
+
+
+def _duplicates(result: LintResult) -> str:
+    lines = [
+        f"- {_link(p.path)} line {p.line}: {p.message}"
+        for p in result.problems
+        if p.code == "BW206"
+    ]
+    return _page(
+        "Duplicate claims",
+        "Claims that cite the same source span with near-identical text, usually from consolidating twice.",
+        lines,
+        "No duplicates.",
+    )
+
+
+def _orphans(engine: Engine) -> str:
+    lines = [
+        f"- {_link(r['path'], r['title'])}"
+        for r in engine.db.execute(
+            """SELECT n.path, n.title FROM nodes n WHERE n.kind = 'note' AND NOT EXISTS (
+                 SELECT 1 FROM edges e WHERE e.other = n.id AND e.declared_in != n.id)
+               ORDER BY n.path"""
+        )
+    ]
+    return _page("Orphans", "Notes nothing links to and no hub lists.", lines, "No orphans.")
+
+
+def _lint_page(result: LintResult) -> str:
+    lines = []
+    current = None
+    for p in result.problems:
+        if p.path != current:
+            lines.append(f"- {_link(p.path) if p.path.endswith('.md') else '`' + p.path + '`'}")
+            current = p.path
+        where = f"line {p.line}: " if p.line else ""
+        lines.append(f"  - {p.severity} {p.code}: {where}{p.message}")
+    intro = (
+        f"{result.errors} errors, {result.count('warning')} warnings, {result.count('info')} info."
+    )
+    return _page("Lint", intro, lines, "No problems.")
+
+
+def _index_page(engine: Engine, result: LintResult) -> str:
+    conn = engine.db
+
+    def count(sql: str) -> int:
+        return int(conn.execute(sql).fetchone()[0])
+
+    stats = [
+        ("Notes", count("SELECT COUNT(*) FROM nodes WHERE kind = 'note'")),
+        ("Hubs", count("SELECT COUNT(*) FROM nodes WHERE kind = 'hub'")),
+        ("Active claims", count("SELECT COUNT(*) FROM claims WHERE status = 'active'")),
+        ("Relations", count("SELECT COUNT(*) FROM edges WHERE rel != 'links_to'")),
+        ("Pending episodes", count("SELECT COUNT(*) FROM nodes WHERE kind = 'episode'")),
+        ("Archived episodes", count("SELECT COUNT(*) FROM nodes WHERE kind = 'archived_episode'")),
+    ]
+    last = "never"
+    try:
+        for line in engine.store.read_text("log.md").splitlines():
+            if line.startswith("## ") and "· consolidate ·" in line:
+                last = line[3:].split(" · ")[0]
+    except OSError:
+        pass
+    lines = [f"- {name}: {value}" for name, value in stats]
+    lines += [
+        f"- Last consolidation: {last}",
+        f"- Lint: {result.errors} errors, {result.count('warning')} warnings",
+        "",
+        "## Reports",
+        "",
+    ]
+    lines += [
+        f"- [[{engine.manifest.layout.reports_dir}/{name}|{name.title()}]]"
+        for name in _REPORTS
+        if name != "index"
+    ]
+    generated = datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+    return _page(f"Brain report: {engine.brain.display_name}", f"Generated {generated}.", lines, "")
+
+
+def generate(engine: Engine, result: LintResult | None = None) -> list[str]:
+    """Rewrite every report whose content changed. Returns the paths written."""
+    from brainwiki.lint._runner import lint
+
+    result = result or lint(engine)
+    pages = {
+        "contradictions": _contradictions(engine),
+        "stale": _stale(engine),
+        "unverified": _unverified(engine),
+        "inbox": _inbox(engine),
+        "duplicates": _duplicates(result),
+        "orphans": _orphans(engine),
+        "lint": _lint_page(result),
+    }
+    written = []
+    directory = engine.manifest.layout.reports_dir
+    for name, content in pages.items():
+        rel = f"{directory}/{name}.md"
+        if engine.store.exists(rel) and engine.store.read_text(rel) == content:
+            continue
+        engine.store.write_text(rel, content)
+        written.append(rel)
+    index_rel = f"{directory}/index.md"
+    engine.store.write_text(index_rel, _index_page(engine, result))
+    written.append(index_rel)
+    return written

brainwiki/lint/_runner.py

@@ -0,0 +1,156 @@
+"""Run lint over a brain: file rules (cached by content hash) plus cross-file rules from the index."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from fnmatch import fnmatch
+from typing import TYPE_CHECKING
+
+from brainwiki.lint._catalog import severity
+from brainwiki.lint._cross import cross_checks
+from brainwiki.lint._files import LINT_VERSION, FileContext, check_file, check_text
+from brainwiki.lint._model import LintResult, Problem
+
+if TYPE_CHECKING:
+    from brainwiki.engine import Engine
+
+_CHECKED_KINDS = (
+    "note",
+    "hub",
+    "episode",
+    "archived_episode",
+    "agent_file",
+    "rules",
+    "agents_md",
+    "proposal",
+    "log",
+)
+
+
+def _cache_prefix(engine: Engine) -> str:
+    budgets = json.dumps(vars(engine.manifest.budgets), sort_keys=True)
+    return f"{LINT_VERSION}:{hashlib.sha256(budgets.encode()).hexdigest()[:8]}:"
+
+
+def _in_scope(path: str, scope: list[str] | None) -> bool:
+    if scope is None:
+        return True
+    for item in scope:
+        item = item.rstrip("/")
+        if item in ("", ".") or path == item or path.startswith(item + "/"):
+            return True
+    return False
+
+
+def _match(code: str, patterns: list[str] | None) -> bool:
+    return bool(patterns) and any(code.startswith(p.strip().upper()) for p in patterns or [] if p)
+
+
+def lint(
+    engine: Engine,
+    *,
+    paths: list[str] | None = None,
+    profile: str | None = None,
+    select: list[str] | None = None,
+    ignore: list[str] | None = None,
+    fixes: bool = False,
+    staged: dict[str, bytes] | None = None,
+) -> LintResult:
+    """Lint the brain, or only `paths`. `staged` maps paths to the bytes git would commit."""
+    started = time.monotonic()
+    engine.scan(force=True)
+    conn = engine.db
+    ctx = FileContext.for_engine(engine)
+    manifest = engine.manifest
+    scope = list(staged) if staged is not None else paths
+
+    def profile_for(path: str) -> str:
+        for pattern, value in manifest.lint.overrides.items():
+            if fnmatch(path, pattern):
+                return value
+        return profile or manifest.lint.profile
+
+    problems: list[Problem] = []
+    prefix = _cache_prefix(engine)
+    cache = {
+        row["path"]: (row["sha256"], row["problems"])
+        for row in conn.execute("SELECT path, sha256, problems FROM lint_cache")
+    }
+    updates: list[tuple[str, str, str]] = []
+    checked = 0
+    rows = conn.execute(
+        """SELECT f.path, f.kind, f.sha256, n.kind AS node_kind
+           FROM files f LEFT JOIN nodes n ON n.id = f.node_id ORDER BY f.path"""
+    ).fetchall()
+    kinds = {row["path"]: row["node_kind"] or row["kind"] for row in rows}
+    if staged is not None:
+        from brainwiki.index import classify
+
+        for path, data in staged.items():
+            kind = kinds.get(path) or classify(engine, path, ctx.topics)
+            if kind not in _CHECKED_KINDS or profile_for(path) == "off":
+                continue
+            checked += 1
+            problems += check_file(ctx, path, kind, data, fixes=False)
+    else:
+        for row in rows:
+            path = row["path"]
+            kind = kinds[path]
+            if kind not in _CHECKED_KINDS or not _in_scope(path, scope):
+                continue
+            if profile_for(path) == "off":
+                continue
+            checked += 1
+            key = prefix + row["sha256"]
+            hit = cache.get(path)
+            if hit and hit[0] == key and not fixes:
+                problems += [Problem(**p) for p in json.loads(hit[1])]
+                continue
+            try:
+                data = engine.store.read_bytes(path)
+            except OSError:
+                continue
+            found = check_file(ctx, path, kind, data, fixes=fixes)
+            problems += found
+            stored = [
+                {
+                    "code": p.code,
+                    "path": p.path,
+                    "line": p.line,
+                    "message": p.message,
+                    "fixable": p.fixable,
+                }
+                for p in found
+            ]
+            updates.append((path, key, json.dumps(stored)))
+    if updates:
+        conn.execute("BEGIN IMMEDIATE")
+        conn.executemany(
+            "INSERT OR REPLACE INTO lint_cache(path, sha256, problems) VALUES (?, ?, ?)", updates
+        )
+        conn.execute("COMMIT")
+    problems += [p for p in cross_checks(engine, ctx, fixes=fixes) if _in_scope(p.path, scope)]
+
+    kept: list[Problem] = []
+    for problem in problems:
+        if _match(problem.code, ignore) or (select and not _match(problem.code, select)):
+            continue
+        problem.severity = severity(problem.code, profile_for(problem.path))
+        if problem.severity == "off":
+            continue
+        kept.append(problem)
+    kept.sort(key=lambda p: (p.path, p.line or 0, p.code))
+    return LintResult(kept, files_checked=checked, seconds=time.monotonic() - started)
+
+
+def lint_text(engine: Engine, path: str, text: str) -> list[Problem]:
+    """File rules for one file's proposed content (strict), for previews and tests."""
+    from brainwiki.index import classify
+
+    ctx = FileContext.for_engine(engine)
+    problems = check_text(ctx, path, classify(engine, path, ctx.topics), text)
+    for problem in problems:
+        problem.severity = severity(problem.code, "strict")
+    return [p for p in problems if p.severity != "off"]

brainwiki/logs.py

@@ -0,0 +1,34 @@
+"""Local log file for long-running processes whose stdout belongs to a protocol (07 §2.2)."""
+
+from __future__ import annotations
+
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from brainwiki.config import state_dir
+
+_configured = False
+
+
+def log_path() -> Path:
+    return state_dir() / "logs" / "brain-wiki.log"
+
+
+def setup_logging(verbose: bool = False) -> logging.Logger:
+    """Send brain-wiki logs to the rotating state-dir log, never to stdout."""
+    global _configured
+    logger = logging.getLogger("brainwiki")
+    if _configured:
+        return logger
+    path = log_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handler = RotatingFileHandler(path, maxBytes=2_000_000, backupCount=3, encoding="utf-8")
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s %(process)d %(levelname)s %(name)s: %(message)s")
+    )
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG if verbose else logging.INFO)
+    logger.propagate = False
+    _configured = True
+    return logger

brainwiki/mcp/__init__.py

@@ -0,0 +1,7 @@
+"""The MCP server. The SDK is imported only here, never by the core."""
+
+from __future__ import annotations
+
+from brainwiki.mcp._server import main, serve
+
+__all__ = ["main", "serve"]