logmind 0.1.0__py3-none-any.whl

logmind/__init__.py

@@ -0,0 +1,8 @@
+"""logmind - AI decision logging system for development projects."""
+
+__version__ = "0.1.0"
+
+from logmind.core.logger import log
+from logmind.decorators import log_choice, log_decision
+
+__all__ = ["log", "log_decision", "log_choice"]

logmind/actions/__init__.py

@@ -0,0 +1,5 @@
+"""GitHub Action entry points shipped with logmind.
+
+These modules are designed to run inside CI (`python -m logmind.actions.<name>`)
+but are also importable so they can be unit-tested without a full CI harness.
+"""

logmind/actions/aggregate.py

@@ -0,0 +1,108 @@
+"""Aggregate per-branch decision logs into docs/decisions.md on PR merge.
+
+Designed to be invoked by ``.github/workflows/logmind-aggregate.yml`` after a
+pull request is merged. Reads the per-branch decisions file written by Phase 5
+and appends a single summary entry to the canonical decisions log so the
+default branch's history shows merged work alongside its detail link.
+
+Importable for unit testing; ``main()`` adapts environment variables for use
+with ``python -m logmind.actions.aggregate``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from logmind.core.logger import _sanitize_branch
+from logmind.core.parser import iter_decisions
+
+
+def aggregate(
+    branch: str,
+    pr_number: int,
+    pr_url: str,
+    docs_path: Path,
+    timestamp: Optional[datetime] = None,
+) -> Optional[Path]:
+    """
+    Append a merge-summary entry to ``docs/decisions.md``.
+
+    Returns the path to the updated file, or ``None`` if the per-branch file is
+    missing / empty (in which case there is nothing to summarise and the main
+    log is left untouched).
+    """
+    if timestamp is None:
+        timestamp = datetime.now()
+
+    sanitized = _sanitize_branch(branch)
+    branch_file = docs_path / "decisions-branches" / f"{sanitized}.md"
+    if not branch_file.exists():
+        return None
+
+    decision_count = sum(1 for _ in iter_decisions(branch_file))
+    if decision_count == 0:
+        return None
+
+    rel_link = f"decisions-branches/{sanitized}.md"
+    entry = (
+        f"## {timestamp.strftime('%Y-%m-%d %H:%M')} - "
+        f"Merged: {branch} (#{pr_number})\n"
+        "\n"
+        f"- **PR:** {pr_url}\n"
+        f"- **Decisions:** {decision_count} from this branch\n"
+        f"- **Detail:** [{rel_link}]({rel_link})\n"
+        "\n"
+        "---\n"
+    )
+
+    decisions_path = docs_path / "decisions.md"
+    existing = decisions_path.read_text(encoding="utf-8") if decisions_path.exists() else ""
+    decisions_path.write_text(existing + entry, encoding="utf-8")
+    return decisions_path
+
+
+def main() -> int:
+    """Entry point for ``python -m logmind.actions.aggregate``."""
+    branch = os.environ.get("BRANCH_NAME") or os.environ.get("GITHUB_HEAD_REF")
+    pr_number_str = os.environ.get("PR_NUMBER")
+    pr_url = os.environ.get("PR_URL")
+
+    if not branch or not pr_number_str or not pr_url:
+        print(
+            "logmind aggregate: BRANCH_NAME, PR_NUMBER, and PR_URL must be set",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        pr_number = int(pr_number_str)
+    except ValueError:
+        print(f"logmind aggregate: PR_NUMBER must be an integer, got {pr_number_str!r}",
+              file=sys.stderr)
+        return 2
+
+    docs_path = Path(os.environ.get("LOGMIND_DOCS", "docs"))
+    if not docs_path.is_absolute():
+        docs_path = Path.cwd() / docs_path
+
+    result = aggregate(
+        branch=branch,
+        pr_number=pr_number,
+        pr_url=pr_url,
+        docs_path=docs_path,
+    )
+
+    if result is None:
+        print(f"logmind aggregate: no per-branch decisions for {branch}; nothing to do.")
+        return 0
+
+    print(f"logmind aggregate: appended merge summary for {branch} to {result}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

logmind/actions/link_check.py

@@ -0,0 +1,193 @@
+"""Markdown link integrity checker.
+
+Walks a configurable set of root files/directories, parses every relative
+``[text](target)`` markdown link, and reports two failure modes:
+
+- **Broken**: the link target does not exist on disk.
+- **Orphan**: a tracked ``.md`` file under ``docs/`` that no other tracked
+  file links to AND is not on an allowlist.
+
+Importable for unit testing; ``main()`` is the entry point for the
+``logmind check-links`` CLI subcommand and the matching GitHub Action.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Iterable, List, Optional, Set, Tuple
+
+LINK_PATTERN = re.compile(r"\[([^\]]+)\]\(([^)\s]+)\)")
+
+DEFAULT_ALLOW_ORPHANS = (
+    "docs/decisions.md",
+    "docs/decisions-archive.md",
+    "docs/file-structure.md",
+    # The whole branch-decisions tree is aggregator-managed: files appear
+    # during a feature branch's lifetime and are linked into decisions.md
+    # only on PR merge. Trailing slash → directory prefix (any .md under it).
+    "docs/decisions-branches/",
+)
+
+DEFAULT_ROOTS = ("README.md", "AGENTS.md", "CLAUDE.md", "docs")
+
+_EXTERNAL_PREFIXES = ("http://", "https://", "mailto:", "ftp://", "//", "#")
+
+
+def _is_external(target: str) -> bool:
+    return target.startswith(_EXTERNAL_PREFIXES)
+
+
+def _strip_anchor(target: str) -> str:
+    return target.split("#", 1)[0]
+
+
+def _collect_md_files(roots: Iterable[Path]) -> Set[Path]:
+    found: Set[Path] = set()
+    for root in roots:
+        if not root.exists():
+            continue
+        if root.is_file() and root.suffix == ".md":
+            found.add(root.resolve())
+        elif root.is_dir():
+            for p in root.rglob("*.md"):
+                found.add(p.resolve())
+    return found
+
+
+def _extract_links(md_path: Path) -> List[Tuple[str, str]]:
+    try:
+        text = md_path.read_text(errors="ignore")
+    except OSError:
+        return []
+    return LINK_PATTERN.findall(text)
+
+
+def check(
+    repo_root: Path,
+    roots: Optional[Iterable[Path]] = None,
+    allow_orphans: Iterable[str] = DEFAULT_ALLOW_ORPHANS,
+) -> Tuple[List[str], List[str]]:
+    """
+    Run the link check against ``repo_root``.
+
+    Returns ``(broken, orphans)``. Each list is empty on a clean run; both
+    lists contain repo-relative path strings (broken includes the link text).
+    """
+    repo_root = repo_root.resolve()
+    if roots is None:
+        roots = [repo_root / r for r in DEFAULT_ROOTS]
+    else:
+        roots = list(roots)
+
+    md_files = _collect_md_files(roots)
+    incoming = {p: set() for p in md_files}
+
+    broken: List[str] = []
+    for source in md_files:
+        for _text, target in _extract_links(source):
+            if _is_external(target):
+                continue
+            stripped = _strip_anchor(target)
+            if not stripped:
+                # Pure-anchor link to current file; skip.
+                continue
+            resolved = (source.parent / stripped).resolve()
+            if not resolved.exists():
+                try:
+                    rel_source = source.relative_to(repo_root).as_posix()
+                except ValueError:
+                    rel_source = source.as_posix()
+                broken.append(f"{rel_source}: missing -> {target}")
+                continue
+            if resolved.suffix == ".md" and resolved in incoming:
+                incoming[resolved].add(source)
+
+    orphans: List[str] = []
+    for md, sources in incoming.items():
+        try:
+            rel = md.relative_to(repo_root)
+        except ValueError:
+            continue
+        if not rel.parts or rel.parts[0] != "docs":
+            continue
+        if _is_allowed_orphan(rel, allow_orphans):
+            continue
+        if not sources:
+            orphans.append(rel.as_posix())
+
+    return sorted(broken), sorted(orphans)
+
+
+def _is_allowed_orphan(rel_path: Path, allow_orphans: Iterable[str]) -> bool:
+    """An entry matches if it equals rel_path OR is a parent directory of it.
+
+    Directory prefixes are signalled by a trailing ``/`` in the entry, but
+    we also tolerate plain dir paths (no slash) by checking the exact match
+    against parents. Comparison is done in POSIX form so this works on
+    Windows where Path renders with backslashes.
+    """
+    s = rel_path.as_posix()
+    for entry in allow_orphans:
+        e = entry.rstrip("/")
+        if s == e:
+            return True
+        if s.startswith(e + "/"):
+            return True
+    return False
+
+
+def format_report(broken: List[str], orphans: List[str]) -> str:
+    lines: List[str] = []
+    if broken:
+        lines.append(f"Broken links ({len(broken)}):")
+        for b in broken:
+            lines.append(f"  - {b}")
+    if orphans:
+        if lines:
+            lines.append("")
+        lines.append(f"Orphan markdown files ({len(orphans)}):")
+        for o in orphans:
+            lines.append(f"  - {o}")
+    if not lines:
+        lines.append("All markdown links resolve and no orphans found.")
+    return "\n".join(lines)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Entry point for ``logmind check-links`` and the GH Action.
+
+    Always operates on the current working directory. GH Actions runs
+    ``run:`` steps with cwd set to ``$GITHUB_WORKSPACE`` automatically, so
+    we don't need to special-case it (and reading the env var would
+    actually defeat tests that monkeypatch.chdir into a temp dir while
+    running on a CI runner that has GITHUB_WORKSPACE pointed elsewhere).
+    """
+    repo_root = Path(os.getcwd())
+
+    # Optional config overrides via .logmind/config.yml
+    allow_orphans = list(DEFAULT_ALLOW_ORPHANS)
+    roots: Optional[List[Path]] = None
+    config_path = repo_root / ".logmind" / "config.yml"
+    if config_path.exists():
+        try:
+            from logmind.core.config import load_config
+
+            cfg = load_config(config_path)
+            extra = cfg.get("linkcheck.allow_orphans") or []
+            allow_orphans = list(DEFAULT_ALLOW_ORPHANS) + list(extra)
+            configured_roots = cfg.get("linkcheck.roots") or []
+            if configured_roots:
+                roots = [repo_root / r for r in configured_roots]
+        except Exception:
+            pass  # ignore config errors; defaults still work
+
+    broken, orphans = check(repo_root, roots=roots, allow_orphans=allow_orphans)
+    print(format_report(broken, orphans))
+    return 0 if not broken and not orphans else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())