agsync 0.1.0__py3-none-any.whl

agsync/__init__.py

@@ -0,0 +1,24 @@
+"""agsync — lint the memory your AI agents read and write."""
+
+__version__ = "0.1.0"
+
+from .engine import Config, Report, check
+from .model import ERROR, OFF, STATUSES, WARN, Finding, Memory
+from .parser import parse
+from .replay import ReplayResult, replay
+
+__all__ = [
+    "ERROR",
+    "OFF",
+    "STATUSES",
+    "WARN",
+    "Config",
+    "Finding",
+    "Memory",
+    "ReplayResult",
+    "Report",
+    "__version__",
+    "check",
+    "parse",
+    "replay",
+]

agsync/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agsync/cli.py

@@ -0,0 +1,211 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import subprocess
+import sys
+
+from . import __version__
+from .engine import BASELINE_NAME, Config, check, write_baseline
+from .replay import ReplayError, render_text, replay
+from .reporters import FORMATS
+from .rules import all_rules
+from .scaffold import HOOK_DISPATCHER, PRE_COMMIT, scaffold
+
+EPILOG = """\
+examples:
+  agsync check                    lint the current repository
+  agsync check --format github    emit inline annotations in CI
+  agsync check --baseline         record today's violations and start clean
+  agsync replay .                 how many past pushes the gate would have caught
+  agsync init                     scaffold a memory structure
+  agsync install-hooks            gate commits locally
+"""
+
+
+def _cmd_check(args) -> int:
+    root = os.path.abspath(args.path)
+    try:
+        config = Config.load(root)
+    except ValueError as exc:
+        print(f"agsync: invalid config: {exc}", file=sys.stderr)
+        return 2
+
+    if args.baseline:
+        report = check(root, config, use_baseline=False)
+        path = write_baseline(root, report.findings)
+        print(
+            f"Wrote {len(report.findings)} existing violation(s) to "
+            f"{os.path.relpath(path, root)}.\n"
+            f"These are now ignored; new ones will fail. Delete entries as you fix them."
+        )
+        return 0
+
+    report = check(root, config, use_baseline=not args.no_baseline)
+    FORMATS[args.format](report)
+    if args.warn_only:
+        return 0
+    return 0 if report.ok else 1
+
+
+def _cmd_replay(args) -> int:
+    """Report on history; never gate it.
+
+    Exit 0 even when every commit would have been rejected — a non-zero exit
+    here would mean "replay failed", and scripts have to be able to tell those
+    apart.
+    """
+    tty = sys.stderr.isatty()
+    emitted = False
+
+    def progress(done: int, total: int, sha: str) -> None:
+        nonlocal emitted
+        if tty:
+            emitted = True
+            print(f"\r  {done}/{total}  {sha[:7]}", end="", file=sys.stderr, flush=True)
+
+    def clear() -> None:
+        nonlocal emitted
+        if emitted:
+            print("\r\033[K", end="", file=sys.stderr, flush=True)
+            emitted = False
+
+    try:
+        result = replay(args.repo, args.ref, progress=progress)
+    except ReplayError as exc:
+        clear()
+        print(f"agsync: {exc}", file=sys.stderr)
+        return 1
+    clear()
+
+    if args.format == "json":
+        json.dump(result.as_dict(), sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        render_text(result, show_first_seen=args.first_seen)
+    return 0
+
+
+def _cmd_init(args) -> int:
+    root = os.path.abspath(args.path)
+    created = scaffold(root, force=args.force)
+    if not created:
+        print("Nothing to do — memory structure already exists (use --force to overwrite).")
+        return 0
+    for path in created:
+        print(f"created  {path}")
+    print("\nNext: describe your project's objective in memory/goal.md, then run "
+          "`agsync check`.")
+    return 0
+
+
+def _cmd_install_hooks(args) -> int:
+    root = os.path.abspath(args.path)
+    if not os.path.isdir(os.path.join(root, ".git")):
+        print("agsync: not a git repository", file=sys.stderr)
+        return 2
+
+    hooks_dir = os.path.join(root, ".agsync", "hooks")
+    os.makedirs(hooks_dir, exist_ok=True)
+
+    # Preserve whatever hook system is already installed: the dispatcher
+    # chains to the previous hooksPath instead of replacing it.
+    previous = _git(root, "config", "--get", "core.hooksPath") or ""
+    if previous and not previous.startswith(".agsync"):
+        chain = previous
+    else:
+        chain = ".git/hooks"
+
+    for name, template in (("_dispatch", HOOK_DISPATCHER), ("pre-commit", PRE_COMMIT)):
+        path = os.path.join(hooks_dir, name)
+        with open(path, "w", encoding="utf-8") as handle:
+            handle.write(template.replace("@CHAIN@", chain))
+        os.chmod(path, os.stat(path).st_mode | stat.S_IEXEC | stat.S_IXGRP)
+        print(f"created  {os.path.relpath(path, root)}")
+
+    _git(root, "config", "core.hooksPath", ".agsync/hooks")
+    print("set      core.hooksPath = .agsync/hooks")
+    print(f"chaining to {chain}")
+    print("\nUndo with: git config --unset core.hooksPath")
+    return 0
+
+
+def _cmd_rules(args) -> int:
+    width = max(len(rule.name) for rule in all_rules())
+    for rule in all_rules():
+        print(f"{rule.name:<{width}}  {rule.default_severity:<5}  {rule.description}")
+    return 0
+
+
+def _git(root: str, *args: str) -> str:
+    try:
+        out = subprocess.run(
+            ["git", *args], cwd=root, capture_output=True, text=True, check=False
+        )
+        return out.stdout.strip()
+    except FileNotFoundError:
+        return ""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agsync",
+        description="Lint the memory your AI agents read and write.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"agsync {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    check_parser = subparsers.add_parser("check", help="report integrity violations")
+    check_parser.add_argument("path", nargs="?", default=".")
+    check_parser.add_argument("--format", choices=sorted(FORMATS), default="text")
+    check_parser.add_argument("--warn-only", action="store_true",
+                              help="always exit 0 (use on first run)")
+    check_parser.add_argument("--baseline", action="store_true",
+                              help=f"record current violations into {BASELINE_NAME}")
+    check_parser.add_argument("--no-baseline", action="store_true",
+                              help="ignore the baseline file and report everything")
+    check_parser.set_defaults(fn=_cmd_check)
+
+    replay_parser = subparsers.add_parser(
+        "replay", help="replay history and count the pushes that would have been rejected"
+    )
+    replay_parser.add_argument("repo", help="path or clone URL of the repository to replay")
+    replay_parser.add_argument("--ref", default="main",
+                               help="branch, remote branch or tag to walk (default: main)")
+    replay_parser.add_argument("--first-seen", action="store_true",
+                               help="also show when each rule first started failing")
+    replay_parser.add_argument("--format", choices=("text", "json"), default="text")
+    replay_parser.set_defaults(fn=_cmd_replay)
+
+    init_parser = subparsers.add_parser("init", help="scaffold a memory structure")
+    init_parser.add_argument("path", nargs="?", default=".")
+    init_parser.add_argument("--force", action="store_true")
+    init_parser.set_defaults(fn=_cmd_init)
+
+    hooks_parser = subparsers.add_parser("install-hooks", help="gate commits locally")
+    hooks_parser.add_argument("path", nargs="?", default=".")
+    hooks_parser.set_defaults(fn=_cmd_install_hooks)
+
+    rules_parser = subparsers.add_parser("rules", help="list every rule")
+    rules_parser.set_defaults(fn=_cmd_rules)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "fn", None):
+        parser.print_help()
+        return 0
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agsync/engine.py

@@ -0,0 +1,147 @@
+"""Configuration, baseline filtering, and the check engine."""
+
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from dataclasses import dataclass, field, replace
+
+from .model import ERROR, OFF, WARN, Finding, Memory
+from .parser import parse
+from .rules import all_rules
+
+CONFIG_NAMES = (".agsync.toml", "agsync.toml")
+BASELINE_NAME = ".agsync-baseline.json"
+VALID_SEVERITIES = (ERROR, WARN, OFF)
+
+
+@dataclass
+class Config:
+    """Severity per rule, plus paths to ignore.
+
+    Severity is configuration; rule logic is not. This split is what allows a
+    repo with existing violations to adopt the tool gradually — turn everything
+    to ``warn``, then promote rules to ``error`` one at a time.
+    """
+
+    severities: dict[str, str] = field(default_factory=dict)
+    exclude: list[str] = field(default_factory=list)
+
+    @classmethod
+    def load(cls, root: str) -> Config:
+        for name in CONFIG_NAMES:
+            path = os.path.join(root, name)
+            if os.path.isfile(path):
+                with open(path, "rb") as handle:
+                    data = tomllib.load(handle)
+                return cls.from_dict(data)
+        return cls()
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Config:
+        section = data.get("tool", {}).get("agsync", data)
+        _validate_config_keys(section)
+        severities = {}
+        for name, value in (section.get("rules") or {}).items():
+            value = str(value).lower()
+            if value not in VALID_SEVERITIES:
+                raise ValueError(
+                    f"invalid severity {value!r} for rule {name!r}; "
+                    f"expected one of {', '.join(VALID_SEVERITIES)}"
+                )
+            severities[name] = value
+        return cls(severities=severities, exclude=list(section.get("exclude") or []))
+
+    def severity_for(self, rule_name: str, default: str) -> str:
+        return self.severities.get(rule_name, default)
+
+
+@dataclass
+class Report:
+    findings: list[Finding]
+    memory: Memory
+    suppressed: int = 0
+
+    @property
+    def errors(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == ERROR]
+
+    @property
+    def warnings(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == WARN]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def load_baseline(root: str) -> set:
+    path = os.path.join(root, BASELINE_NAME)
+    if not os.path.isfile(path):
+        return set()
+    with open(path, encoding="utf-8") as handle:
+        data = json.load(handle)
+    return set(data.get("fingerprints", []))
+
+
+def write_baseline(root: str, findings: list[Finding]) -> str:
+    path = os.path.join(root, BASELINE_NAME)
+    payload = {
+        "version": 1,
+        "note": "Pre-existing violations, ignored by `agsync check`. "
+                "Delete entries as you fix them; never add by hand.",
+        "fingerprints": sorted({f.fingerprint() for f in findings}),
+    }
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2)
+        handle.write("\n")
+    return path
+
+
+def _excluded(path: str, patterns: list[str]) -> bool:
+    normalized = path.replace(os.sep, "/")
+    return any(
+        normalized == pattern or normalized.startswith(pattern.rstrip("/") + "/")
+        for pattern in patterns
+    )
+
+
+def check(root: str, config: Config | None = None, use_baseline: bool = True) -> Report:
+    """Parse ``root`` and run every enabled rule over it."""
+    config = config or Config.load(root)
+    memory = parse(root)
+    baseline = load_baseline(root) if use_baseline else set()
+
+    findings: list[Finding] = []
+    suppressed = 0
+    for rule in all_rules():
+        severity = config.severity_for(rule.name, rule.default_severity)
+        if severity == OFF:
+            continue
+        for finding in rule.fn(memory):
+            if _excluded(finding.path, config.exclude):
+                continue
+            if finding.fingerprint() in baseline:
+                suppressed += 1
+                continue
+            # Config overrides the severity the rule declared for itself.
+            # `replace` rather than a rebuild: a new field added to Finding
+            # must not be silently dropped here, which would change the
+            # fingerprint of every re-severitied finding.
+            findings.append(
+                finding if finding.severity == severity
+                else replace(finding, severity=severity)
+            )
+
+    findings.sort(key=lambda f: (f.path, f.line, f.rule))
+    return Report(findings=findings, memory=memory, suppressed=suppressed)
+
+
+def _validate_config_keys(section: dict) -> None:
+    """Guard against the TOML footgun where a top-level key lands inside [rules]."""
+    unknown = set(section) - {"rules", "exclude"}
+    if unknown:
+        raise ValueError(
+            f"unknown config key(s): {', '.join(sorted(unknown))}"
+        )

agsync/model.py

@@ -0,0 +1,138 @@
+"""Normalized data model.
+
+Rules operate exclusively on these objects, never on raw markdown. Keeping the
+parser and the rules separated by a stable structure is what lets the parser
+absorb messy real-world formats without every rule learning about them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+
+#: The only task statuses that carry machine-readable meaning.
+STATUSES = ("todo", "in-progress", "done", "superseded")
+
+ERROR = "error"
+WARN = "warn"
+OFF = "off"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A single rule violation.
+
+    The report contract is deliberately fixed and minimal: every consumer
+    (text output, JSON, GitHub annotations, editors) derives from these five
+    fields alone.
+    """
+
+    rule: str
+    path: str
+    line: int
+    message: str
+    severity: str = ERROR
+    #: What the finding is *about* — a decision ID, a task number, a link
+    #: target. Stable identity for the baseline; see :meth:`fingerprint`.
+    subject: str = ""
+
+    def fingerprint(self) -> str:
+        """Stable identity for the baseline file.
+
+        Hashes structured fields, never the rendered message. Messages are
+        prose written for humans: they embed line numbers, counts and
+        truncated quotes, all of which change when the surrounding file is
+        edited even though the violation has not. Hashing them meant a
+        baselined finding could resurrect itself after an unrelated edit, which
+        is the exact failure that excluding ``line`` was meant to prevent.
+
+        ``subject`` falls back to ``message`` so that a rule which does not
+        supply one still gets a usable fingerprint rather than colliding with
+        every other finding of its rule in the same file.
+        """
+        raw = f"{self.rule}\x00{self.path}\x00{self.subject or self.message}"
+        return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+    def as_dict(self) -> dict:
+        return {
+            "rule": self.rule,
+            "path": self.path,
+            "line": self.line,
+            "message": self.message,
+            "severity": self.severity,
+            "subject": self.subject,
+            "fingerprint": self.fingerprint(),
+        }
+
+
+@dataclass
+class Decision:
+    """One entry in the decision ledger."""
+
+    id: str
+    title: str
+    path: str
+    line: int
+    #: field name (lowercased) -> (folded value, line number)
+    fields: dict[str, tuple[str, int]] = field(default_factory=dict)
+    supersedes: list[str] = field(default_factory=list)
+    amends: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Task:
+    """One task file.
+
+    ``status_base`` is the enum candidate; ``status_qualifier`` is whatever
+    free text trailed it. Splitting them is what lets an existing repo become
+    parseable without rewriting every file at once.
+    """
+
+    num: str
+    path: str
+    line: int = 1
+    title: str = ""
+    status_raw: str = ""
+    status_base: str = ""
+    status_qualifier: str = ""
+    status_line: int = 1
+    depends_on: list[str] = field(default_factory=list)
+    blocks: list[str] = field(default_factory=list)
+    decisions: list[str] = field(default_factory=list)
+
+
+@dataclass
+class IndexRow:
+    """One row of a task table in the index file."""
+
+    num: str
+    target: str
+    status_raw: str
+    status_base: str
+    line: int
+
+
+@dataclass
+class Memory:
+    """The parsed memory graph handed to every rule."""
+
+    root: str
+    decisions: dict[str, Decision] = field(default_factory=dict)
+    #: (redefinition, first definition) pairs — duplicates never enter ``decisions``
+    duplicate_decisions: list[tuple[Decision, Decision]] = field(default_factory=list)
+    tasks: dict[str, Task] = field(default_factory=dict)
+    index: list[IndexRow] = field(default_factory=list)
+    index_path: str = "tasks/README.md"
+    protocol_path: str = "AGENTS.md"
+    #: every markdown file in the repo, repo-relative
+    markdown: list[str] = field(default_factory=list)
+    #: the subset that is actually agent memory — the protocol file and
+    #: anything under memory/ or tasks/. A ``D-021`` in a README is prose;
+    #: the same token inside the memory surface is a reference that must
+    #: resolve. Rules that scan text use this, never ``markdown``.
+    surface: list[str] = field(default_factory=list)
+    #: path -> lines, populated lazily by the parser and reused by rules
+    sources: dict[str, list[str]] = field(default_factory=dict)
+
+    def lines(self, path: str) -> list[str]:
+        return self.sources.get(path, [])