gator-command 1.0.0__py3-none-any.whl

gator_command/scripts/memex-lint.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""
+memex-lint.py — Mechanical invariant checker for the .gator/ knowledge layer.
+
+Read-only. Reports findings, changes nothing. Cross-platform (no bash).
+
+Checks:
+  1. Budget — always-loaded files under 400 lines total
+  2. Thread size — active threads over 60 lines flagged for split
+  3. Frontmatter — required fields (last-touched, category, hits)
+  4. Summary — every thread has ## Summary
+  5. Cross-references — markdown links resolve to existing files
+  6. Orphans — threads with no inbound references
+  7. Active thread count — target 5-8
+
+Usage:
+    python memex-lint.py [--path /repo] [--json]
+
+@reads: .gator/ knowledge layer (or gator-command/ for source repo)
+@writes: stdout only
+"""
+
+import argparse
+import json as json_mod
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPTS_DIR))
+from gator_core import find_gator_root, ensure_utf8_stdout  # noqa: E402
+
+BUDGET = 400
+SPLIT_THRESHOLD = 60
+ACTIVE_TARGET = (3, 8)
+SKIP_FILES = {"_TEMPLATE.md", "_template.md", "README.md"}
+
+
+# ── output helpers ─────────────────────────────────────────────────────────
+
+errors = 0
+warnings = 0
+findings = []
+
+
+def error(msg):
+    global errors
+    errors += 1
+    findings.append({"level": "error", "message": msg})
+    print(f"  ERROR: {msg}")
+
+
+def warn(msg):
+    global warnings
+    warnings += 1
+    findings.append({"level": "warn", "message": msg})
+    print(f"  WARN:  {msg}")
+
+
+def ok(msg):
+    findings.append({"level": "ok", "message": msg})
+    print(f"  OK:    {msg}")
+
+
+# ── checks ─────────────────────────────────────────────────────────────────
+
+def count_lines(path):
+    try:
+        return len(path.read_text(encoding="utf-8", errors="replace").splitlines())
+    except OSError:
+        return 0
+
+
+def get_threads(memex_dir):
+    """Collect all thread files from active-threads/ and threads/."""
+    threads = []
+    for subdir in ("active-threads", "threads"):
+        d = memex_dir / subdir
+        if d.is_dir():
+            for f in sorted(d.glob("*.md")):
+                if f.name not in SKIP_FILES:
+                    threads.append(f)
+    return threads
+
+
+def check_budget(memex_dir):
+    """Check 1: always-loaded files under budget."""
+    print("-- Budget Check --")
+    budget_files = []
+
+    for name in ("identity.md", "inbox.md"):
+        f = memex_dir / name
+        if f.exists():
+            budget_files.append(f)
+
+    at_dir = memex_dir / "active-threads"
+    if at_dir.is_dir():
+        for f in sorted(at_dir.glob("*.md")):
+            if f.name not in SKIP_FILES:
+                budget_files.append(f)
+
+    patterns_dir = memex_dir / "patterns"
+    if patterns_dir.is_dir():
+        for f in sorted(patterns_dir.glob("*.md")):
+            if f.name not in SKIP_FILES:
+                budget_files.append(f)
+    elif (memex_dir / "patterns.md").exists():
+        budget_files.append(memex_dir / "patterns.md")
+
+    total = sum(count_lines(f) for f in budget_files)
+    if total > BUDGET:
+        error(f"Always-loaded budget: {total} / {BUDGET} lines (OVER by {total - BUDGET})")
+    else:
+        ok(f"Always-loaded budget: {total} / {BUDGET} lines ({BUDGET - total} headroom)")
+    print()
+
+
+def check_thread_size(memex_dir):
+    """Check 2: active threads over 60 lines."""
+    print("-- Thread Size Check (active threads > 60 lines) --")
+    at_dir = memex_dir / "active-threads"
+    if not at_dir.is_dir():
+        ok("No active-threads/ directory")
+        print()
+        return
+
+    for f in sorted(at_dir.glob("*.md")):
+        if f.name in SKIP_FILES:
+            continue
+        lines = count_lines(f)
+        if lines > SPLIT_THRESHOLD:
+            warn(f"{f.name}: {lines} lines -- evaluate for split")
+        else:
+            ok(f"{f.name}: {lines} lines")
+    print()
+
+
+def check_frontmatter(threads):
+    """Check 3: required frontmatter fields."""
+    print("-- Frontmatter Check --")
+    required = ["last-touched"]  # category, hits, tags are optional in modern Gator
+
+    for f in threads:
+        text = f.read_text(encoding="utf-8", errors="replace")
+        for field in required:
+            if f"\n{field}:" not in text and not text.startswith(f"{field}:"):
+                error(f"{f.name}: missing {field}")
+
+    ok("Frontmatter check complete")
+    print()
+
+
+def check_summaries(threads):
+    """Check 4: every thread has ## Summary."""
+    print("-- Summary Check --")
+    for f in threads:
+        text = f.read_text(encoding="utf-8", errors="replace")
+        if "## Summary" not in text:
+            error(f"{f.name}: missing ## Summary section")
+
+    ok("Summary check complete")
+    print()
+
+
+def check_crossrefs(threads, memex_dir):
+    """Check 5: markdown links resolve."""
+    print("-- Cross-Reference Integrity --")
+    link_pattern = re.compile(r'\[([^\]]+)\]\(([^)]+\.md)\)')
+
+    for f in threads:
+        text = f.read_text(encoding="utf-8", errors="replace")
+        for match in link_pattern.finditer(text):
+            link_path = match.group(2)
+            if link_path.startswith("http"):
+                continue
+            resolved = (f.parent / link_path).resolve()
+            if not resolved.is_file():
+                error(f"{f.name}: broken link -> {link_path}")
+
+    ok("Cross-reference check complete")
+    print()
+
+
+def check_orphans(threads, memex_dir):
+    """Check 6: threads with no inbound references."""
+    print("-- Orphan Check (threads with no inbound references) --")
+
+    # Build reference map
+    all_text = {}
+    for f in threads:
+        all_text[f] = f.read_text(encoding="utf-8", errors="replace")
+
+    for f in threads:
+        name = f.name
+        inbound = sum(1 for other, text in all_text.items()
+                      if other != f and name in text)
+        if inbound == 0:
+            warn(f"{name}: no inbound references (potential orphan)")
+
+    print()
+
+
+def check_active_count(memex_dir):
+    """Check 7: active thread count in target range."""
+    print("-- Active Thread Count --")
+    at_dir = memex_dir / "active-threads"
+    if not at_dir.is_dir():
+        ok("No active-threads/ directory")
+        print()
+        return
+
+    count = sum(1 for f in at_dir.glob("*.md") if f.name not in SKIP_FILES)
+    lo, hi = ACTIVE_TARGET
+    if count > hi:
+        error(f"Active threads: {count} (max {hi})")
+    elif count < lo:
+        warn(f"Active threads: {count} (unusually low)")
+    else:
+        ok(f"Active threads: {count} (target: {lo}-{hi})")
+    print()
+
+
+# ── main ───────────────────────────────────────────────────────────────────
+
+def main():
+    ensure_utf8_stdout()
+
+    parser = argparse.ArgumentParser(description="Gator knowledge layer lint")
+    parser.add_argument("--path", "-p", help="Path to repo (default: cwd)")
+    parser.add_argument("--json", "-j", action="store_true", help="JSON output")
+    args = parser.parse_args()
+
+    repo_root = find_gator_root(args.path)
+    if not repo_root:
+        print("Error: no .gator/ found.", file=sys.stderr)
+        sys.exit(1)
+
+    # Detect knowledge layer location
+    # gator-command source repo uses gator-command/, fleet repos use .gator/
+    gc_dir = repo_root / "gator-command"
+    gator_dir = repo_root / ".gator"
+    if gc_dir.is_dir() and (gc_dir / "active-threads").is_dir():
+        memex_dir = gc_dir
+    else:
+        memex_dir = gator_dir
+
+    today = datetime.now().strftime("%Y-%m-%d")
+    print(f"==============================")
+    print(f"  Gator Lint -- {today}")
+    print(f"  {memex_dir}")
+    print(f"==============================")
+    print()
+
+    threads = get_threads(memex_dir)
+
+    check_budget(memex_dir)
+    check_thread_size(memex_dir)
+    check_frontmatter(threads)
+    check_summaries(threads)
+    check_crossrefs(threads, memex_dir)
+    check_orphans(threads, memex_dir)
+    check_active_count(memex_dir)
+
+    print("==============================")
+    if errors == 0 and warnings == 0:
+        print("All checks passed.")
+    elif errors == 0:
+        print(f"{warnings} warning(s), 0 errors.")
+    else:
+        print(f"{errors} error(s), {warnings} warning(s).")
+    print("==============================")
+
+    if args.json:
+        print()
+        print(json_mod.dumps({
+            "errors": errors,
+            "warnings": warnings,
+            "findings": findings,
+        }, indent=2))
+
+    sys.exit(errors)
+
+
+if __name__ == "__main__":
+    main()

gator_command/scripts/memex-lint.sh

@@ -0,0 +1,205 @@
+#!/bin/bash
+# memex-lint.sh — Mechanical invariant checker for the Memex
+# Read-only. Reports findings, changes nothing.
+# Usage: bash scripts/memex-lint.sh
+
+MEMEX_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ERRORS=0
+WARNINGS=0
+
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+error() { echo -e "${RED}ERROR:${NC} $1"; ((ERRORS++)); }
+warn()  { echo -e "${YELLOW}WARN:${NC}  $1"; ((WARNINGS++)); }
+ok()    { echo -e "${GREEN}OK:${NC}    $1"; }
+
+echo "=============================="
+echo "  Memex Lint — $(date +%Y-%m-%d)"
+echo "=============================="
+echo ""
+
+# ── 1. Budget Check ──────────────────────────────────────────────
+echo "── Budget Check ──"
+
+# Budget includes: identity.md + active-threads (excluding _TEMPLATE.md) + patterns/*.md (excluding README.md) + inbox.md
+BUDGET_FILES=()
+BUDGET_FILES+=("$MEMEX_DIR/identity.md")
+BUDGET_FILES+=("$MEMEX_DIR/inbox.md")
+
+for f in "$MEMEX_DIR"/active-threads/*.md; do
+    [[ "$(basename "$f")" == "_TEMPLATE.md" ]] && continue
+    BUDGET_FILES+=("$f")
+done
+
+for f in "$MEMEX_DIR"/patterns/*.md; do
+    [[ "$(basename "$f")" == "README.md" ]] && continue
+    BUDGET_FILES+=("$f")
+done
+
+TOTAL_LINES=0
+for f in "${BUDGET_FILES[@]}"; do
+    lines=$(wc -l < "$f" 2>/dev/null || echo 0)
+    TOTAL_LINES=$((TOTAL_LINES + lines))
+done
+
+BUDGET=400
+if [ "$TOTAL_LINES" -gt "$BUDGET" ]; then
+    error "Always-loaded budget: $TOTAL_LINES / $BUDGET lines (OVER by $((TOTAL_LINES - BUDGET)))"
+else
+    ok "Always-loaded budget: $TOTAL_LINES / $BUDGET lines ($((BUDGET - TOTAL_LINES)) headroom)"
+fi
+
+# Constitution line count (informational, not budgeted)
+CONST_LINES=$(wc -l < "$REPO_ROOT/constitution.md" 2>/dev/null || echo 0)
+echo "     Constitution: $CONST_LINES lines (budget-exempt)"
+echo ""
+
+# ── 2. Thread Size Check ─────────────────────────────────────────
+echo "── Thread Size Check (active threads > 60 lines) ──"
+
+SPLIT_THRESHOLD=60
+for f in "$MEMEX_DIR"/active-threads/*.md; do
+    [[ "$(basename "$f")" == "_TEMPLATE.md" ]] && continue
+    lines=$(wc -l < "$f")
+    name=$(basename "$f")
+    if [ "$lines" -gt "$SPLIT_THRESHOLD" ]; then
+        warn "$name: $lines lines — evaluate for split or compression"
+    else
+        ok "$name: $lines lines"
+    fi
+done
+echo ""
+
+# ── 3. Frontmatter Check ─────────────────────────────────────────
+echo "── Frontmatter Check ──"
+
+ALL_THREADS=()
+for f in "$MEMEX_DIR"/active-threads/*.md "$MEMEX_DIR"/threads/*.md; do
+    [[ "$(basename "$f")" == "_TEMPLATE.md" ]] && continue
+    [ -f "$f" ] && ALL_THREADS+=("$f")
+done
+
+for f in "${ALL_THREADS[@]}"; do
+    name=$(basename "$f")
+
+    if ! grep -q "^last-touched:" "$f"; then
+        error "$name: missing last-touched"
+    fi
+    if ! grep -q "^category:" "$f"; then
+        error "$name: missing category"
+    fi
+    if ! grep -q "^hits:" "$f"; then
+        error "$name: missing hits"
+    fi
+    if ! grep -q "^tags:" "$f"; then
+        error "$name: missing tags"
+    fi
+done
+
+# Check for valid categories
+VALID_CATEGORIES="mathematics|cognition|systems|ventures|economics|civic"
+for f in "${ALL_THREADS[@]}"; do
+    name=$(basename "$f")
+    cat_line=$(grep "^category:" "$f" 2>/dev/null || echo "")
+    if [ -n "$cat_line" ]; then
+        cat_value=$(echo "$cat_line" | sed 's/^category: *//')
+        if ! echo "$cat_value" | grep -qE "^($VALID_CATEGORIES)$"; then
+            error "$name: invalid category '$cat_value'"
+        fi
+    fi
+done
+
+ok "Frontmatter check complete"
+echo ""
+
+# ── 4. Summary Check ─────────────────────────────────────────────
+echo "── Summary Check ──"
+
+for f in "${ALL_THREADS[@]}"; do
+    name=$(basename "$f")
+    if ! grep -q "^## Summary" "$f"; then
+        error "$name: missing ## Summary section"
+    fi
+done
+
+ok "Summary check complete"
+echo ""
+
+# ── 5. Cross-Reference Integrity ─────────────────────────────────
+echo "── Cross-Reference Integrity ──"
+
+for f in "${ALL_THREADS[@]}"; do
+    name=$(basename "$f")
+    dir=$(dirname "$f")
+
+    # Extract markdown links: [text](path.md)
+    grep -oE '\[([^]]+)\]\(([^)]+\.md)\)' "$f" 2>/dev/null | while read -r match; do
+        link_path=$(echo "$match" | grep -oE '\(([^)]+)\)' | tr -d '()')
+
+        # Skip external URLs
+        [[ "$link_path" == http* ]] && continue
+
+        # Resolve relative path
+        resolved="$dir/$link_path"
+        resolved=$(cd "$dir" 2>/dev/null && realpath -m "$link_path" 2>/dev/null || echo "$resolved")
+
+        if [ ! -f "$resolved" ]; then
+            error "$name: broken link → $link_path"
+        fi
+    done
+done
+
+ok "Cross-reference check complete"
+echo ""
+
+# ── 6. Orphan Check ──────────────────────────────────────────────
+echo "── Orphan Check (threads with no inbound references) ──"
+
+for f in "${ALL_THREADS[@]}"; do
+    name=$(basename "$f")
+    name_no_ext="${name%.md}"
+
+    # Search all threads for references to this file
+    inbound=$(grep -rl "$name" "$MEMEX_DIR"/active-threads/ "$MEMEX_DIR"/threads/ 2>/dev/null | grep -v "$f" | grep -v "_TEMPLATE.md" | wc -l)
+
+    if [ "$inbound" -eq 0 ]; then
+        warn "$name: no inbound references (potential orphan)"
+    fi
+done
+
+echo ""
+
+# ── 7. Active Thread Count ───────────────────────────────────────
+echo "── Active Thread Count ──"
+
+ACTIVE_COUNT=0
+for f in "$MEMEX_DIR"/active-threads/*.md; do
+    [[ "$(basename "$f")" == "_TEMPLATE.md" ]] && continue
+    ((ACTIVE_COUNT++))
+done
+
+if [ "$ACTIVE_COUNT" -gt 8 ]; then
+    error "Active threads: $ACTIVE_COUNT (max 8)"
+elif [ "$ACTIVE_COUNT" -lt 3 ]; then
+    warn "Active threads: $ACTIVE_COUNT (unusually low)"
+else
+    ok "Active threads: $ACTIVE_COUNT (target: 5-8)"
+fi
+echo ""
+
+# ── Summary ──────────────────────────────────────────────────────
+echo "=============================="
+if [ "$ERRORS" -eq 0 ] && [ "$WARNINGS" -eq 0 ]; then
+    echo -e "${GREEN}All checks passed.${NC}"
+elif [ "$ERRORS" -eq 0 ]; then
+    echo -e "${YELLOW}$WARNINGS warning(s), 0 errors.${NC}"
+else
+    echo -e "${RED}$ERRORS error(s), $WARNINGS warning(s).${NC}"
+fi
+echo "=============================="
+
+exit $ERRORS