memproof 0.1.0__py3-none-any.whl

memproof/__init__.py

@@ -0,0 +1,3 @@
+"""memproof — evidence-first health checks for Markdown knowledge vaults."""
+
+__version__ = "0.1.0"

memproof/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

memproof/checks/__init__.py

@@ -0,0 +1,5 @@
+from . import freshness, frontmatter, links, provenance, structure
+
+ALL_CHECKS = (frontmatter, links, provenance, freshness, structure)
+
+__all__ = ["ALL_CHECKS", "freshness", "frontmatter", "links", "provenance", "structure"]

memproof/checks/freshness.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from datetime import date
+
+from ..model import Finding
+from ..vault import Vault, as_date
+
+DRAFT_DAYS = 30
+EVERGREEN_DAYS = 180
+
+
+def run(vault: Vault, today: date | None = None) -> list[Finding]:
+    findings: list[Finding] = []
+    current = today or date.today()
+    for page in vault.pages:
+        frontmatter = page.frontmatter
+        if frontmatter is None:
+            continue
+        status = str(frontmatter.get("status", "")).strip()
+        stamp = as_date(frontmatter.get("updated")) or as_date(frontmatter.get("created"))
+        if stamp is None:
+            continue
+        age = (current - stamp).days
+        if status == "draft" and age > DRAFT_DAYS:
+            findings.append(
+                Finding(
+                    check="freshness",
+                    severity="medium",
+                    path=page.rel,
+                    line=1,
+                    message=f"draft untouched for {age} days",
+                    evidence=f"updated={stamp.isoformat()}, threshold={DRAFT_DAYS} days",
+                    fix="refine, archive, or refresh the draft",
+                )
+            )
+        if status == "evergreen" and age > EVERGREEN_DAYS and page.rel not in vault.inbound:
+            findings.append(
+                Finding(
+                    check="freshness",
+                    severity="medium",
+                    path=page.rel,
+                    line=1,
+                    message=f"evergreen page stale for {age} days with no inbound links",
+                    evidence=f"updated={stamp.isoformat()}, threshold={EVERGREEN_DAYS} days",
+                    fix="review it, link it, or downgrade its status",
+                )
+            )
+    return findings

memproof/checks/frontmatter.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from datetime import date
+
+from ..model import Finding
+from ..vault import Vault, as_date
+
+REQUIRED = ("type", "title", "created", "updated", "status")
+ALLOWED_STATUS = {
+    "active",
+    "archived",
+    "complete",
+    "developing",
+    "draft",
+    "evergreen",
+    "mature",
+    "open",
+    "published",
+    "review",
+    "stale",
+    "template",
+}
+
+
+def run(vault: Vault, today: date | None = None) -> list[Finding]:
+    findings: list[Finding] = []
+    for page in vault.pages:
+        if page.frontmatter_error:
+            findings.append(
+                Finding(
+                    check="frontmatter",
+                    severity="high",
+                    path=page.rel,
+                    line=1,
+                    message="frontmatter cannot be parsed",
+                    evidence=page.frontmatter_error,
+                    fix="fix the YAML block or remove it",
+                )
+            )
+            continue
+        if page.frontmatter is None:
+            findings.append(
+                Finding(
+                    check="frontmatter",
+                    severity="high",
+                    path=page.rel,
+                    line=1,
+                    message="missing frontmatter",
+                    evidence="file does not start with a --- block",
+                    fix="add type/title/created/updated/status",
+                )
+            )
+            continue
+        missing = [key for key in REQUIRED if not str(page.frontmatter.get(key, "")).strip()]
+        if missing:
+            findings.append(
+                Finding(
+                    check="frontmatter",
+                    severity="medium",
+                    path=page.rel,
+                    line=1,
+                    message="missing required keys: " + ", ".join(missing),
+                    evidence="; ".join(f"{key}={page.frontmatter.get(key)!r}" for key in REQUIRED),
+                    fix="add the missing keys",
+                )
+            )
+        status = str(page.frontmatter.get("status", "")).strip()
+        if status and status not in ALLOWED_STATUS:
+            findings.append(
+                Finding(
+                    check="frontmatter",
+                    severity="medium",
+                    path=page.rel,
+                    line=1,
+                    message=f"unknown status: {status}",
+                    evidence="allowed: " + ", ".join(sorted(ALLOWED_STATUS)),
+                    fix="use an allowed status value",
+                )
+            )
+        for key in ("created", "updated"):
+            value = page.frontmatter.get(key)
+            if value is not None and str(value).strip() and as_date(value) is None:
+                findings.append(
+                    Finding(
+                        check="frontmatter",
+                        severity="medium",
+                        path=page.rel,
+                        line=1,
+                        message=f"{key} is not an ISO date: {value!r}",
+                        evidence="expected YYYY-MM-DD",
+                        fix="use an ISO date",
+                    )
+                )
+    return findings

memproof/checks/links.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+from ..model import Finding
+from ..vault import Vault, iter_links, link_target, resolve
+
+
+def run(vault: Vault, today: date | None = None, include_orphans: bool = True) -> list[Finding]:
+    findings: list[Finding] = []
+    for page in vault.pages:
+        for raw, line in iter_links(page.text):
+            target = link_target(raw)
+            if target is None:
+                continue
+            status, matches = resolve(vault, page, target)
+            if status == "dead":
+                findings.append(
+                    Finding(
+                        check="links",
+                        severity="high",
+                        path=page.rel,
+                        line=line,
+                        message=f"dead wikilink: [[{target}]]",
+                        evidence="target not found in vault",
+                        fix="fix the target or remove the link",
+                    )
+                )
+            elif status == "ambiguous":
+                findings.append(
+                    Finding(
+                        check="links",
+                        severity="medium",
+                        path=page.rel,
+                        line=line,
+                        message=f"ambiguous wikilink: [[{target}]]",
+                        evidence="candidates: " + ", ".join(match.rel for match in matches),
+                        fix="use a path-qualified link",
+                    )
+                )
+    for stem, pages in sorted(vault.by_stem.items()):
+        if len(pages) < 2:
+            continue
+        findings.append(
+            Finding(
+                check="links",
+                severity="medium",
+                path=pages[0].rel,
+                line=1,
+                message=f"duplicate basename: {stem}",
+                evidence=", ".join(page.rel for page in pages),
+                fix="rename one page or keep links path-qualified",
+            )
+        )
+    if include_orphans:
+        for page in vault.pages:
+            if page.rel in vault.inbound:
+                continue
+            name = Path(page.rel).name
+            if name in {"index.md", "_index.md", "README.md"}:
+                continue
+            if page.rel.startswith(("archive/", "templates/")):
+                continue
+            findings.append(
+                Finding(
+                    check="links",
+                    severity="medium",
+                    path=page.rel,
+                    line=1,
+                    message="orphan page: no inbound wikilinks",
+                    evidence="no other page links to this file",
+                    fix="link it from an index or remove it",
+                )
+            )
+    return findings

memproof/checks/provenance.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from datetime import date
+
+from ..model import Finding
+from ..vault import Vault
+
+PROVENANCE_KEYS = ("author", "sink", "generated_by")
+
+
+def run(vault: Vault, today: date | None = None) -> list[Finding]:
+    findings: list[Finding] = []
+    for page in vault.pages:
+        frontmatter = page.frontmatter
+        if frontmatter is None:
+            continue
+        author = str(frontmatter.get("author", "")).strip()
+        sink = str(frontmatter.get("sink", "")).strip()
+        if author != "agent" and sink != "agent":
+            continue
+        missing = [key for key in PROVENANCE_KEYS if not str(frontmatter.get(key, "")).strip()]
+        if missing:
+            findings.append(
+                Finding(
+                    check="provenance",
+                    severity="high",
+                    path=page.rel,
+                    line=1,
+                    message="agent-authored note missing: " + ", ".join(missing),
+                    evidence=(
+                        f"author={author or '<empty>'}, sink={sink or '<empty>'}, "
+                        f"generated_by={frontmatter.get('generated_by', '<empty>')!r}"
+                    ),
+                    fix="add the missing provenance keys or remove the agent marker",
+                )
+            )
+    return findings

memproof/checks/structure.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import re
+from datetime import date
+from pathlib import Path
+
+from ..model import Finding
+from ..vault import Page, Vault
+
+HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
+
+
+def _empty_sections(page: Page) -> list[tuple[int, str]]:
+    lines = page.body.splitlines()
+    empty: list[tuple[int, str]] = []
+    for index, line in enumerate(lines):
+        match = HEADING_RE.match(line)
+        if match is None:
+            continue
+        cursor = index + 1
+        while cursor < len(lines) and not lines[cursor].strip():
+            cursor += 1
+        if cursor >= len(lines):
+            empty.append((page.body_line + index, match.group(2)))
+            continue
+        next_heading = HEADING_RE.match(lines[cursor])
+        if next_heading is not None and len(next_heading.group(1)) <= len(match.group(1)):
+            empty.append((page.body_line + index, match.group(2)))
+    return empty
+
+
+def run(vault: Vault, today: date | None = None) -> list[Finding]:
+    findings: list[Finding] = []
+    for page in vault.pages:
+        for line, heading in _empty_sections(page):
+            findings.append(
+                Finding(
+                    check="structure",
+                    severity="medium",
+                    path=page.rel,
+                    line=line,
+                    message=f"empty section: {heading}",
+                    evidence="heading is followed by another heading or end of file",
+                    fix="add content or remove the heading",
+                )
+            )
+        rel = page.rel
+        if "memory/notes/" not in rel or Path(rel).name == "_index.md":
+            continue
+        index = page.path.parent / "_index.md"
+        if not index.is_file():
+            continue
+        index_text = index.read_text(encoding="utf-8", errors="replace")
+        if Path(rel).stem not in index_text:
+            findings.append(
+                Finding(
+                    check="structure",
+                    severity="medium",
+                    path=rel,
+                    line=1,
+                    message="atom not registered in its _index.md",
+                    evidence=index.relative_to(vault.root).as_posix(),
+                    fix="add a wikilink to the atom in the index",
+                )
+            )
+    return findings

memproof/cli.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date
+from pathlib import Path
+
+from . import __version__
+from .checks import ALL_CHECKS
+from .checks import links as links_check
+from .model import Finding
+from .report import render_json, render_markdown, write_report
+from .vault import load_vault
+
+FAIL_RANK = {"high": 0, "medium": 1, "low": 2}
+
+
+def _harden_streams() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (OSError, ValueError):
+            pass
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="memproof",
+        description="Evidence-first health checks for Markdown knowledge vaults.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    check = subparsers.add_parser("check", help="scan a Markdown vault")
+    check.add_argument("path", type=Path, help="vault root")
+    check.add_argument("--format", choices=("markdown", "json"), default="markdown")
+    check.add_argument("--output", type=Path, help="write the report to this file")
+    check.add_argument(
+        "--fail-on",
+        choices=("none", "low", "medium", "high"),
+        default="none",
+        help="exit 1 when a finding at or above this severity exists",
+    )
+    check.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="extra path part or glob to skip (repeatable)",
+    )
+    check.add_argument("--no-orphans", action="store_true", help="skip the orphan-page check")
+    check.add_argument(
+        "--today",
+        type=date.fromisoformat,
+        default=None,
+        help="reference date for freshness checks (YYYY-MM-DD)",
+    )
+    subparsers.add_parser("version", help="print the version")
+    return parser
+
+
+def _collect(vault: object, today: date | None, include_orphans: bool) -> list[Finding]:
+    from .vault import Vault
+
+    assert isinstance(vault, Vault)
+    findings: list[Finding] = []
+    for module in ALL_CHECKS:
+        if module is links_check:
+            findings.extend(module.run(vault, today=today, include_orphans=include_orphans))
+        else:
+            findings.extend(module.run(vault, today=today))
+    return findings
+
+
+def main(argv: list[str] | None = None) -> int:
+    _harden_streams()
+    args = build_parser().parse_args(argv)
+    if args.command == "version":
+        print(__version__)
+        return 0
+
+    root = args.path
+    if not root.is_dir():
+        print(f"memproof: not a directory: {root}", file=sys.stderr)
+        return 2
+    try:
+        vault = load_vault(root, tuple(args.exclude))
+    except OSError as exc:
+        print(f"memproof: cannot read vault: {exc}", file=sys.stderr)
+        return 2
+
+    findings = _collect(vault, args.today, not args.no_orphans)
+    content = (
+        render_markdown(vault, findings, args.today)
+        if args.format == "markdown"
+        else render_json(vault, findings, args.today)
+    )
+    if args.output:
+        write_report(args.output, content)
+        print(f"wrote {args.output}")
+    else:
+        sys.stdout.write(content)
+
+    if args.fail_on == "none":
+        return 0
+    threshold = FAIL_RANK[args.fail_on]
+    worst = min((FAIL_RANK.get(finding.severity, 99) for finding in findings), default=99)
+    return 1 if worst <= threshold else 0

memproof/model.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+SEVERITIES = ("high", "medium", "low")
+
+
+@dataclass(frozen=True)
+class Finding:
+    check: str
+    severity: str
+    path: str
+    line: int
+    message: str
+    evidence: str = ""
+    fix: str = ""
+
+
+@dataclass
+class CheckResult:
+    findings: list[Finding] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+
+
+def normalize_severity(value: str) -> str:
+    lowered = value.strip().lower()
+    if lowered not in SEVERITIES:
+        raise ValueError(f"unknown severity: {value}")
+    return lowered

memproof/report.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from datetime import date
+from pathlib import Path
+
+from .model import SEVERITIES, Finding
+from .vault import Vault
+
+SCHEMA = "memproof.report.v1"
+
+
+def summarize(findings: list[Finding]) -> dict[str, int]:
+    counts = {severity: 0 for severity in SEVERITIES}
+    for finding in findings:
+        counts[finding.severity] = counts.get(finding.severity, 0) + 1
+    return counts
+
+
+def score(findings: list[Finding]) -> int:
+    counts = summarize(findings)
+    penalty = counts["high"] * 10 + counts["medium"] * 3 + counts["low"]
+    return max(0, 100 - penalty)
+
+
+def _sort_key(finding: Finding) -> tuple[int, str, int, str]:
+    order = {severity: index for index, severity in enumerate(SEVERITIES)}
+    return (order.get(finding.severity, 99), finding.path, finding.line, finding.check)
+
+
+def render_markdown(vault: Vault, findings: list[Finding], today: date | None = None) -> str:
+    ordered = sorted(findings, key=_sort_key)
+    counts = summarize(ordered)
+    lines = [
+        f"# memproof report — {vault.root.name or vault.root.as_posix()}",
+        "",
+        (
+            f"Score: {score(ordered)}/100 · Files: {len(vault.pages)} · Links: {vault.link_count} · "
+            f"Findings: {counts['high']} high / {counts['medium']} medium / {counts['low']} low"
+        ),
+        "",
+    ]
+    labels = {"high": "High", "medium": "Medium", "low": "Low"}
+    for severity in SEVERITIES:
+        lines.append(f"## {labels[severity]}")
+        lines.append("")
+        group = [finding for finding in ordered if finding.severity == severity]
+        if not group:
+            lines.append("None.")
+            lines.append("")
+            continue
+        for finding in group:
+            lines.append(f"- [{finding.check}] {finding.path}:{finding.line} — {finding.message}")
+            if finding.evidence:
+                lines.append(f"  Evidence: {finding.evidence}")
+            if finding.fix:
+                lines.append(f"  Fix: {finding.fix}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_json(vault: Vault, findings: list[Finding], today: date | None = None) -> str:
+    ordered = sorted(findings, key=_sort_key)
+    payload = {
+        "schema": SCHEMA,
+        "root": vault.root.as_posix(),
+        "generated_for": (today or date.today()).isoformat(),
+        "summary": {
+            "score": score(ordered),
+            "pages": len(vault.pages),
+            "links": vault.link_count,
+            "findings": summarize(ordered),
+        },
+        "findings": [asdict(finding) for finding in ordered],
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+
+
+def write_report(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")

memproof/vault.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_EXCLUDES: tuple[str, ...] = (
+    ".git",
+    ".obsidian",
+    ".vault-meta",
+    ".trash",
+    ".raw",
+    "node_modules",
+    ".venv",
+    "venv",
+    ".venv-win",
+    "venvtest",
+    "venvtest2",
+    "dist",
+    "build",
+    "__pycache__",
+    "outputs",
+)
+
+WIKILINK_RE = re.compile(r"\[\[([^\]\n]+?)\]\]")
+FENCE_RE = re.compile(r"(?ms)^(```|~~~)[^\n]*\n.*?^\1\s*$")
+INLINE_CODE_RE = re.compile(r"`[^`\n]*`")
+SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+@dataclass
+class Page:
+    path: Path
+    rel: str
+    text: str
+    frontmatter: dict[str, Any] | None
+    body: str
+    body_line: int
+    frontmatter_error: str | None = None
+
+
+@dataclass
+class Vault:
+    root: Path
+    pages: list[Page]
+    by_stem: dict[str, list[Page]]
+    by_rel: dict[str, Page]
+    link_count: int = 0
+    inbound: dict[str, set[str]] = field(default_factory=dict)
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, Any] | None, str, int, str | None]:
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return None, text, 1, None
+    end: int | None = None
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            end = index
+            break
+    if end is None:
+        return None, text, 1, "unterminated frontmatter block"
+    raw = "".join(lines[1:end])
+    body = "".join(lines[end + 1 :])
+    try:
+        data: Any = yaml.safe_load(raw) or {}
+    except yaml.YAMLError as exc:
+        return None, body, end + 2, f"YAML error: {exc}"
+    if not isinstance(data, dict):
+        return None, body, end + 2, "frontmatter is not a mapping"
+    return data, body, end + 2, None
+
+
+def as_date(value: object) -> date | None:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    if isinstance(value, str):
+        try:
+            return date.fromisoformat(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _excluded(rel: str, excludes: tuple[str, ...]) -> bool:
+    parts = rel.split("/")
+    for pattern in excludes:
+        if pattern in parts:
+            return True
+        if fnmatch.fnmatchcase(rel, pattern):
+            return True
+    return False
+
+
+def _code_spans(text: str) -> list[tuple[int, int]]:
+    spans: list[tuple[int, int]] = []
+    for regex in (FENCE_RE, INLINE_CODE_RE):
+        spans.extend((match.start(), match.end()) for match in regex.finditer(text))
+    return spans
+
+
+def iter_links(text: str) -> list[tuple[str, int]]:
+    spans = _code_spans(text)
+    links: list[tuple[str, int]] = []
+    for match in WIKILINK_RE.finditer(text):
+        if any(start <= match.start() < end for start, end in spans):
+            continue
+        line = text.count("\n", 0, match.start()) + 1
+        links.append((match.group(1), line))
+    return links
+
+
+def link_target(raw: str) -> str | None:
+    raw = raw.replace("\\|", "\0")
+    target = raw.split("|", 1)[0].replace("\0", "|")
+    target = target.split("#", 1)[0].strip()
+    if not target or SCHEME_RE.match(target):
+        return None
+    return target.replace("\\", "/")
+
+
+def _page(rel: str) -> str:
+    return rel[:-3] if rel.endswith(".md") else rel
+
+
+def resolve(vault: Vault, source: Page, target: str) -> tuple[str, list[Page]]:
+    cleaned = target.strip().lstrip("/")
+    if cleaned.endswith(".md"):
+        cleaned = cleaned[:-3]
+    if "/" in cleaned:
+        for candidate in (cleaned, f"{cleaned}.md"):
+            page = vault.by_rel.get(candidate)
+            if page is not None:
+                return "ok", [page]
+        base = Path(source.rel).parent
+        relative = _page((base / cleaned).as_posix())
+        for candidate in (relative, f"{relative}.md"):
+            page = vault.by_rel.get(candidate)
+            if page is not None:
+                return "ok", [page]
+        return "dead", []
+    matches = vault.by_stem.get(cleaned.casefold(), [])
+    if len(matches) == 1:
+        return "ok", matches
+    if len(matches) > 1:
+        return "ambiguous", matches
+    return "dead", []
+
+
+def _build_inbound(pages: list[Page], vault: Vault) -> tuple[dict[str, set[str]], int]:
+    inbound: dict[str, set[str]] = {}
+    link_count = 0
+    for page in pages:
+        for raw, _line in iter_links(page.text):
+            target = link_target(raw)
+            if target is None:
+                continue
+            link_count += 1
+            status, matches = resolve(vault, page, target)
+            if status in {"ok", "ambiguous"}:
+                for match in matches:
+                    if match.rel != page.rel:
+                        inbound.setdefault(match.rel, set()).add(page.rel)
+    return inbound, link_count
+
+
+def load_vault(root: Path, excludes: tuple[str, ...] = ()) -> Vault:
+    all_excludes = DEFAULT_EXCLUDES + excludes
+    root = root.resolve()
+    pages: list[Page] = []
+    for path in sorted(root.rglob("*.md")):
+        rel = path.relative_to(root).as_posix()
+        if _excluded(rel, all_excludes):
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        frontmatter, body, body_line, error = parse_frontmatter(text)
+        pages.append(
+            Page(
+                path=path,
+                rel=rel,
+                text=text,
+                frontmatter=frontmatter,
+                body=body,
+                body_line=body_line,
+                frontmatter_error=error,
+            )
+        )
+    by_stem: dict[str, list[Page]] = {}
+    by_rel: dict[str, Page] = {}
+    for page in pages:
+        by_stem.setdefault(Path(page.rel).stem.casefold(), []).append(page)
+        by_rel[page.rel] = page
+        by_rel[_page(page.rel)] = page
+    vault = Vault(root=root, pages=pages, by_stem=by_stem, by_rel=by_rel)
+    inbound, link_count = _build_inbound(pages, vault)
+    vault.inbound = inbound
+    vault.link_count = link_count
+    return vault

memproof-0.1.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: memproof
+Version: 0.1.0
+Summary: Evidence-first health checks for Markdown knowledge vaults.
+Author: memproof contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hsys123/memproof
+Project-URL: Repository, https://github.com/hsys123/memproof
+Project-URL: Issues, https://github.com/hsys123/memproof/issues
+Keywords: markdown,obsidian,knowledge-base,memory,audit,provenance
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+# memproof
+
+Evidence-first health checks for Markdown knowledge vaults.
+
+`memproof` answers one question: **can you prove what your knowledge base claims?**
+Every finding carries a `path:line`, the evidence behind it, and a concrete fix.
+It is read-only, offline, and deterministic.
+
+## Install
+
+```bash
+uv tool install memproof
+# or
+pip install memproof
+```
+
+## Use
+
+```bash
+memproof check ~/my-vault
+memproof check ~/my-vault --format json --fail-on high
+memproof check ~/my-vault --output report.md
+```
+
+Exit codes: `0` clean (or below `--fail-on`), `1` findings at/above the threshold, `2` usage/environment error.
+
+Archives often contain frozen snapshots with dead links. Exclude them explicitly:
+
+```bash
+memproof check ~/my-vault --exclude 'archive/**' --exclude 'templates/**'
+```
+
+## What it checks (v0.1)
+
+| Check | What it catches |
+|---|---|
+| `frontmatter` | missing/unparseable frontmatter, missing required keys, unknown status, invalid dates |
+| `links` | dead wikilinks, ambiguous bare-name targets, duplicate basenames, orphan pages |
+| `provenance` | agent-authored notes missing `author` / `sink` / `generated_by` |
+| `freshness` | drafts older than 30 days; evergreen pages older than 180 days with no inbound links |
+| `structure` | empty sections; memory atoms not registered in their `_index.md` |
+
+## Example
+
+```text
+# memproof report — demo-vault
+Score: 64/100 · Files: 12 · Links: 18 · Findings: 2 high / 6 medium / 1 low
+
+## High
+- [provenance] notes/agent-note.md:1 — agent-authored note missing generated_by
+  Evidence: author=agent, sink=agent, generated_by missing.
+  Fix: add `generated_by: <tool>` or remove the agent marker.
+```
+
+A full generated report is in [`docs/sample-report.md`](docs/sample-report.md).
+
+## Roadmap
+
+- **v0.1** — five vault checks (current).
+- **v0.2** — archive profile, fold/derived checks.
+- **v0.3** — `memproof skills`: capability contracts and with/without evaluation.
+
+## Design principles
+
+- **Read-only**: never edits the vault, no network access, no LLM calls.
+- **Evidence-first**: every finding points to a line; no aggregate-only claims.
+- **Deterministic**: same vault + same date = same report.
+- **Small surface**: five checks, not fifty. Add a check only with a failing fixture.
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+mypy memproof
+```
+
+License: MIT.

memproof-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+memproof/__init__.py,sha256=keHI4TUfoU620fujQ43IZEIrBRlzl8C3Mcrw4OzgtYQ,102
+memproof/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+memproof/cli.py,sha256=tTgqglnEMzHznrI6-r2VdIcWSe7wnDnauVAbaMnNuXg,3538
+memproof/model.py,sha256=MB5QO0LYHkH27pXAiudBlA9lcyWbv4jBFiDPFI8MxSM,609
+memproof/report.py,sha256=E_kzZ-8yNdn2QMNbI3m8Tggyw2TARKpXHqkT76VSb6c,2881
+memproof/vault.py,sha256=NHG2rak6s-62B_JveuIIf9G02YpKKAqgLeSFlgtU2Pw,6126
+memproof/checks/__init__.py,sha256=mpuI7KZjdR0Q_zCR1WtCl3MErJ-9qjDAPu2xpL2eM0w,226
+memproof/checks/freshness.py,sha256=MPY7tx4nDuOk6_DUQECiGP0_NjEiMLBpDVOA9xlO0A4,1749
+memproof/checks/frontmatter.py,sha256=tY-cS05jTvoW0g2b-5pG4seFesEacCbWondT_mWrPLU,3177
+memproof/checks/links.py,sha256=5zzm1rqlMv2hKOo2nhsV0FRW5bSDm3FKkDxIpvd1ado,2794
+memproof/checks/provenance.py,sha256=SoMH8-YUYAbhoolT0iGPk37QQUEXXoPN5imMJFHgaeo,1336
+memproof/checks/structure.py,sha256=TTwm_SxLR-IJjvdOWTsjJyKO4_oOO0GawE8gclJ7U1w,2335
+memproof-0.1.0.dist-info/licenses/LICENSE,sha256=dTpoXBEzaAhD5bJx-KGNt1pUR-cPspqz_1Y9ZULRvFM,1078
+memproof-0.1.0.dist-info/METADATA,sha256=CVsFZ_er0gFrcQtW7e7E7LDR1vB0ypt0Ksdvrtie_3g,3312
+memproof-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+memproof-0.1.0.dist-info/entry_points.txt,sha256=Q71Sdbrp3mA9OP5AFoBQAZkUCszjQ-nhIQzzqgPSt18,47
+memproof-0.1.0.dist-info/top_level.txt,sha256=bGca6Kv98_iJyra1rrzvarLyzYIkog6LFzRORkkrJOE,9
+memproof-0.1.0.dist-info/RECORD,,

memproof-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memproof-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memproof = memproof.cli:main

memproof-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 memproof contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memproof-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+memproof