aletheore 0.2.0__py3-none-any.whl

aletheore/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

aletheore/adapters/__init__.py

@@ -0,0 +1 @@
+

aletheore/adapters/base.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+
+class AgentAdapter(ABC):
+    name: str = "unnamed"
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def invoke(self, instruction: str, cwd: str) -> str:
+        raise NotImplementedError

aletheore/adapters/claude_code.py

@@ -0,0 +1,38 @@
+import shutil
+import subprocess
+
+from aletheore.adapters.base import AgentAdapter
+
+INVOCATION_TIMEOUT_SECONDS = 600
+
+
+class AdapterInvocationError(Exception):
+    pass
+
+
+class ClaudeCodeAdapter(AgentAdapter):
+    name = "claude"
+
+    def is_available(self) -> bool:
+        return shutil.which("claude") is not None
+
+    def invoke(self, instruction: str, cwd: str) -> str:
+        try:
+            result = subprocess.run(
+                ["claude", "-p", instruction],
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                timeout=INVOCATION_TIMEOUT_SECONDS,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterInvocationError(
+                f"claude invocation timed out after {INVOCATION_TIMEOUT_SECONDS}s"
+            ) from exc
+
+        if result.returncode != 0:
+            raise AdapterInvocationError(
+                f"claude invocation failed (exit {result.returncode}): {result.stderr}"
+            )
+
+        return result.stdout

aletheore/architecture.py

@@ -0,0 +1,137 @@
+import json
+from pathlib import Path
+
+import networkx as nx
+from networkx.algorithms.community import greedy_modularity_communities
+
+
+def load_architecture_config(repo_path: Path) -> dict | None:
+    config_file = repo_path / ".aletheore.json"
+    if not config_file.exists():
+        return None
+    try:
+        data = json.loads(config_file.read_text(encoding="utf-8", errors="ignore"))
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+
+    layer_markers = data.get("layer_markers", {})
+    if not isinstance(layer_markers, dict):
+        layer_markers = {}
+
+    cluster_resolution = data.get("cluster_resolution", 1.0)
+    if not isinstance(cluster_resolution, (int, float)) or isinstance(cluster_resolution, bool):
+        cluster_resolution = 1.0
+
+    return {"layer_markers": layer_markers, "cluster_resolution": float(cluster_resolution)}
+
+
+LAYER_FOLDER_MARKERS = {
+    "domain": 0,
+    "core": 0,
+    "entities": 0,
+    "application": 1,
+    "services": 1,
+    "use_cases": 1,
+    "infrastructure": 2,
+    "infra": 2,
+    "adapters": 2,
+    "api": 2,
+    "routers": 2,
+    "web": 2,
+    "controllers": 2,
+}
+
+
+def build_clusters(dependency_graph: dict, resolution: float = 1.0) -> tuple[list[dict], list[dict]]:
+    graph = nx.Graph()
+    graph.add_nodes_from(dependency_graph["nodes"])
+    graph.add_edges_from(dependency_graph["edges"])
+
+    communities = list(greedy_modularity_communities(graph, resolution=resolution))
+
+    cluster_of: dict[str, int] = {}
+    clusters = []
+    for cluster_id, community in enumerate(communities):
+        modules = sorted(community)
+        for module in modules:
+            cluster_of[module] = cluster_id
+        clusters.append({"id": cluster_id, "modules": modules, "internal_edges": 0})
+
+    for a, b in dependency_graph["edges"]:
+        if cluster_of.get(a) is not None and cluster_of.get(a) == cluster_of.get(b):
+            clusters[cluster_of[a]]["internal_edges"] += 1
+
+    cross_pairs: dict[tuple[int, int], list[list[str]]] = {}
+    for a, b in dependency_graph["edges"]:
+        ca, cb = cluster_of.get(a), cluster_of.get(b)
+        if ca is None or cb is None or ca == cb:
+            continue
+        cross_pairs.setdefault((ca, cb), []).append([a, b])
+
+    cross_cluster_edges = [
+        {"from_cluster": ca, "to_cluster": cb, "count": len(edges), "edges": edges}
+        for (ca, cb), edges in sorted(cross_pairs.items())
+    ]
+
+    return clusters, cross_cluster_edges
+
+
+def _classify_module_rank(rel_path: str, markers: dict[str, int]) -> tuple[str, int] | None:
+    parts = Path(rel_path).parts
+    for part in parts[:-1]:
+        if part in markers:
+            return part, markers[part]
+    return None
+
+
+def detect_layer_violations(
+    dependency_graph: dict, custom_markers: dict[str, int] | None = None
+) -> dict:
+    effective_markers = {**LAYER_FOLDER_MARKERS, **(custom_markers or {})}
+
+    classifications: dict[str, tuple[str, int]] = {}
+    for node in dependency_graph["nodes"]:
+        result = _classify_module_rank(node, effective_markers)
+        if result is not None:
+            classifications[node] = result
+
+    distinct_ranks = {rank for _, rank in classifications.values()}
+
+    layer_folders: dict[str, set[str]] = {}
+    for node, (name, _rank) in classifications.items():
+        parts = Path(node).parts
+        idx = parts.index(name)
+        folder = str(Path(*parts[: idx + 1]))
+        layer_folders.setdefault(name, set()).add(folder)
+
+    layers = [
+        {"name": name, "rank": effective_markers[name], "folders": sorted(folders)}
+        for name, folders in sorted(layer_folders.items())
+    ]
+
+    custom_markers_contributed = bool(custom_markers) and any(
+        name in custom_markers for name in layer_folders
+    )
+    if len(distinct_ranks) < 2 and not custom_markers_contributed:
+        return {"convention_detected": False, "layers": [], "violations": []}
+
+    violations = []
+    for from_node, to_node in dependency_graph["edges"]:
+        from_info = classifications.get(from_node)
+        to_info = classifications.get(to_node)
+        if from_info is None or to_info is None:
+            continue
+        from_name, from_rank = from_info
+        to_name, to_rank = to_info
+        if from_rank < to_rank:
+            violations.append(
+                {
+                    "from": from_node,
+                    "to": to_node,
+                    "reason": f"inner layer '{from_name}' imports outer layer '{to_name}'",
+                }
+            )
+
+    return {"convention_detected": True, "layers": layers, "violations": violations}

aletheore/cli.py

@@ -0,0 +1,417 @@
+import argparse
+import json
+import sys
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+from aletheore.adapters.claude_code import AdapterInvocationError, ClaudeCodeAdapter
+from aletheore.dashboard import build_app
+from aletheore.evidence import scan_repository, write_evidence
+from aletheore.healthcheck import run_healthcheck, save_healthcheck
+from aletheore.history import compute_diff, list_snapshots, save_snapshot
+from aletheore.mcp_server import build_server
+from aletheore.query import (
+    BranchNotFoundInEvidenceError,
+    ModuleNotFoundInEvidenceError,
+    QUERY_FUNCTIONS,
+)
+from aletheore.report import (
+    AmbiguousAdapterError,
+    NoAdapterAvailableError,
+    run_reasoning_phase,
+    select_adapter,
+)
+
+KNOWN_ADAPTERS = [ClaudeCodeAdapter()]
+
+MANUAL_DIR = str(Path(__file__).resolve().parent.parent / "manual")
+
+SPONSOR_NOTE = """
+┌───────────────────────────────────────────────────────────┐
+│  Aletheore is 100% open-source, local, and free.           │
+│  No accounts, no tracking — nothing leaves this machine.   │
+│                                                            │
+│  If it saved you time, consider supporting development:    │
+│  https://github.com/sponsors/ArihantK15                    │
+└───────────────────────────────────────────────────────────┘
+"""
+
+
+def _scan(
+    repo_path: str,
+    check_vulnerabilities: bool,
+    scan_git_history: bool,
+    check_licenses: bool = True,
+    map_endpoints: bool = True,
+) -> tuple[int, dict, Path]:
+    repo = Path(repo_path).resolve()
+    print(f"Scanning {repo}...")
+    evidence = scan_repository(
+        repo,
+        check_vulnerabilities=check_vulnerabilities,
+        scan_git_history=scan_git_history,
+        check_licenses=check_licenses,
+        map_endpoints=map_endpoints,
+    )
+    evidence_path = write_evidence(evidence, repo)
+    print(f"Evidence written to {evidence_path}")
+    snapshot_path = save_snapshot(evidence, repo)
+    print(f"Snapshot saved to {snapshot_path}")
+    return 0, evidence, evidence_path
+
+
+def _audit(
+    repo_path: str,
+    forced_agent: str | None,
+    check_vulnerabilities: bool,
+    scan_git_history: bool,
+    check_licenses: bool = True,
+    map_endpoints: bool = True,
+) -> int:
+    _exit_code, _evidence, evidence_path = _scan(
+        repo_path, check_vulnerabilities, scan_git_history, check_licenses, map_endpoints
+    )
+    repo = Path(repo_path).resolve()
+
+    try:
+        adapter = select_adapter(
+            KNOWN_ADAPTERS, forced_name=forced_agent, interactive=sys.stdin.isatty()
+        )
+    except (NoAdapterAvailableError, AmbiguousAdapterError) as exc:
+        print(f"error: {exc}")
+        print(f"Evidence is still available at {evidence_path} for manual use.")
+        return 1
+
+    print(f"Running audit with {adapter.name}...")
+    try:
+        report_path = run_reasoning_phase(adapter, repo_path=str(repo), manual_dir=MANUAL_DIR)
+    except AdapterInvocationError as exc:
+        print(f"error: {exc}")
+        print(f"Evidence is still available at {evidence_path} for manual use.")
+        return 1
+
+    print(f"Audit report written to {report_path}")
+    print(SPONSOR_NOTE)
+    return 0
+
+
+def _query_changes(repo_path: str, full: bool) -> int:
+    repo = Path(repo_path).resolve()
+    snapshots = list_snapshots(repo)
+
+    if len(snapshots) < 2:
+        print("no prior snapshot to compare against - run 'aletheore scan' again later to compare")
+        return 0
+
+    try:
+        old = json.loads(snapshots[-2].read_text())
+    except json.JSONDecodeError:
+        print(f"error: most recent snapshot is unreadable ({snapshots[-2]})")
+        return 1
+
+    new = json.loads(snapshots[-1].read_text())
+    diff = compute_diff(old, new, full=full)
+    print(json.dumps(diff, indent=2))
+    return 0
+
+
+def _query(kind: str, target: str | None, repo_path: str, full: bool = False) -> int:
+    if kind == "changes":
+        return _query_changes(repo_path, full)
+
+    repo = Path(repo_path).resolve()
+    evidence_path = repo / ".aletheore" / "evidence.json"
+    if not evidence_path.exists():
+        print(f"error: no evidence found at {evidence_path}")
+        print(f"Run 'aletheore scan {repo}' first.")
+        return 1
+
+    func, requires_target = QUERY_FUNCTIONS[kind]
+    if requires_target and target is None:
+        print(f"error: query type '{kind}' requires a target argument")
+        return 1
+
+    evidence = json.loads(evidence_path.read_text())
+    try:
+        result = func(evidence, target)
+    except (ModuleNotFoundInEvidenceError, BranchNotFoundInEvidenceError) as exc:
+        print(f"error: {exc}")
+        return 1
+
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+def _diff(
+    old_path: str,
+    new_path: str,
+    full: bool,
+    fail_on_new_secrets: bool,
+    fail_on_new_vulnerabilities: bool = False,
+    fail_on_new_layer_violations: bool = False,
+) -> int:
+    old_file = Path(old_path)
+    new_file = Path(new_path)
+
+    if not old_file.exists():
+        print(f"error: evidence file not found: {old_file}")
+        return 1
+    if not new_file.exists():
+        print(f"error: evidence file not found: {new_file}")
+        return 1
+
+    try:
+        old = json.loads(old_file.read_text())
+    except json.JSONDecodeError:
+        print(f"error: {old_file} is not valid JSON")
+        return 1
+    try:
+        new = json.loads(new_file.read_text())
+    except json.JSONDecodeError:
+        print(f"error: {new_file} is not valid JSON")
+        return 1
+
+    diff = compute_diff(old, new, full=full)
+    print(json.dumps(diff, indent=2))
+
+    if fail_on_new_secrets or fail_on_new_vulnerabilities or fail_on_new_layer_violations:
+        curated = diff if not full else compute_diff(old, new, full=False)
+        should_fail = False
+
+        if fail_on_new_secrets:
+            new_real_secrets = [
+                f
+                for f in curated["secrets"]["new"]
+                if not f.get("likely_placeholder", False) and not f.get("accepted", False)
+            ]
+            new_real_history_secrets = [
+                f
+                for f in curated["history_secrets"]["new"]
+                if not f.get("likely_placeholder", False) and not f.get("accepted", False)
+            ]
+            should_fail = should_fail or bool(new_real_secrets or new_real_history_secrets)
+
+        if fail_on_new_vulnerabilities:
+            should_fail = should_fail or bool(curated["vulnerabilities"]["new"])
+
+        if fail_on_new_layer_violations:
+            should_fail = should_fail or bool(curated["layer_violations"]["new"])
+
+        if should_fail:
+            return 1
+
+    return 0
+
+
+def _healthcheck(repo_path: str, base_url: str) -> int:
+    repo = Path(repo_path).resolve()
+    evidence_path = repo / ".aletheore" / "evidence.json"
+    if not evidence_path.exists():
+        print(f"error: no evidence found at {evidence_path}")
+        print(f"Run 'aletheore scan {repo}' first.")
+        return 1
+
+    evidence = json.loads(evidence_path.read_text())
+    endpoints = evidence["repository"].get("api_endpoints", {}).get("endpoints", [])
+    result = run_healthcheck(endpoints, base_url)
+    save_healthcheck(result, repo)
+
+    for entry in result["results"]:
+        method = entry.get("method") or "?"
+        if entry.get("skipped"):
+            print(f"{method:6} {entry['path']:40} SKIPPED ({entry['reason']})")
+        else:
+            status = entry["status_code"] if entry["reachable"] else "UNREACHABLE"
+            note = f" ({entry['note']})" if entry.get("note") else ""
+            print(f"{method:6} {entry['path']:40} {status} {entry['latency_ms']}ms{note}")
+
+    return 0
+
+
+def _mcp(repo_path: str) -> int:
+    repo = Path(repo_path).resolve()
+    server = build_server(repo)
+    server.run(transport="stdio")
+    return 0
+
+
+def _dashboard(repo_path: str, port: int) -> int:
+    repo = Path(repo_path).resolve()
+    app = build_app(repo)
+    url = f"http://127.0.0.1:{port}"
+    print(f"Dashboard running at {url}")
+    webbrowser.open(url)
+    uvicorn.run(app, host="127.0.0.1", port=port)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="aletheore")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    audit_parser = subparsers.add_parser("audit", help="audit a repository")
+    audit_parser.add_argument("path", nargs="?", default=".")
+    audit_parser.add_argument("--agent", default=None, help="force a specific agent adapter by name")
+    audit_parser.add_argument(
+        "--no-check-vulnerabilities",
+        dest="check_vulnerabilities",
+        action="store_false",
+        default=True,
+        help="skip the OSV.dev dependency-vulnerability check (on by default)",
+    )
+    audit_parser.add_argument(
+        "--no-scan-git-history",
+        dest="scan_git_history",
+        action="store_false",
+        default=True,
+        help="skip walking git history for secrets (on by default)",
+    )
+    audit_parser.add_argument(
+        "--no-check-licenses",
+        dest="check_licenses",
+        action="store_false",
+        default=True,
+        help="skip the dependency-license check (on by default)",
+    )
+    audit_parser.add_argument(
+        "--no-map-endpoints",
+        dest="map_endpoints",
+        action="store_false",
+        default=True,
+        help="skip static API endpoint mapping (on by default)",
+    )
+
+    scan_parser = subparsers.add_parser("scan", help="run only the deterministic scan phase")
+    scan_parser.add_argument("path", nargs="?", default=".")
+    scan_parser.add_argument(
+        "--no-check-vulnerabilities",
+        dest="check_vulnerabilities",
+        action="store_false",
+        default=True,
+        help="skip the OSV.dev dependency-vulnerability check (on by default)",
+    )
+    scan_parser.add_argument(
+        "--no-scan-git-history",
+        dest="scan_git_history",
+        action="store_false",
+        default=True,
+        help="skip walking git history for secrets (on by default)",
+    )
+    scan_parser.add_argument(
+        "--no-check-licenses",
+        dest="check_licenses",
+        action="store_false",
+        default=True,
+        help="skip the dependency-license check (on by default)",
+    )
+    scan_parser.add_argument(
+        "--no-map-endpoints",
+        dest="map_endpoints",
+        action="store_false",
+        default=True,
+        help="skip static API endpoint mapping (on by default)",
+    )
+
+    query_parser = subparsers.add_parser("query", help="query an existing evidence.json")
+    query_parser.add_argument("kind", choices=list(QUERY_FUNCTIONS.keys()) + ["changes"])
+    query_parser.add_argument("target", nargs="?", default=None)
+    query_parser.add_argument("--path", dest="repo_path", default=".")
+    query_parser.add_argument(
+        "--full",
+        action="store_true",
+        default=False,
+        help="show the full raw diff instead of the curated summary (only applies to 'changes')",
+    )
+
+    diff_parser = subparsers.add_parser("diff", help="compare two evidence.json files")
+    diff_parser.add_argument("old", help="path to the baseline evidence.json")
+    diff_parser.add_argument("new", help="path to the comparison evidence.json")
+    diff_parser.add_argument(
+        "--full",
+        action="store_true",
+        default=False,
+        help="show the full raw diff instead of the curated summary",
+    )
+    diff_parser.add_argument(
+        "--fail-on-new-secrets",
+        dest="fail_on_new_secrets",
+        action="store_true",
+        default=False,
+        help="exit 1 if a new real (non-placeholder) secret finding appears",
+    )
+    diff_parser.add_argument(
+        "--fail-on-new-vulnerabilities",
+        dest="fail_on_new_vulnerabilities",
+        action="store_true",
+        default=False,
+        help="exit 1 if a new dependency vulnerability finding appears",
+    )
+    diff_parser.add_argument(
+        "--fail-on-new-layer-violations",
+        dest="fail_on_new_layer_violations",
+        action="store_true",
+        default=False,
+        help="exit 1 if a new layer-convention violation appears",
+    )
+
+    mcp_parser = subparsers.add_parser("mcp", help="run an MCP server scoped to a repository")
+    mcp_parser.add_argument("path", nargs="?", default=".")
+
+    dashboard_parser = subparsers.add_parser(
+        "dashboard", help="run a live local dashboard scoped to a repository"
+    )
+    dashboard_parser.add_argument("path", nargs="?", default=".")
+    dashboard_parser.add_argument("--port", type=int, default=8420)
+
+    healthcheck_parser = subparsers.add_parser(
+        "healthcheck", help="GET-only live health check of mapped API endpoints"
+    )
+    healthcheck_parser.add_argument("path", nargs="?", default=".")
+    healthcheck_parser.add_argument("--base-url", required=True, dest="base_url")
+
+    args = parser.parse_args()
+
+    if args.command == "audit":
+        return _audit(
+            args.path,
+            args.agent,
+            args.check_vulnerabilities,
+            args.scan_git_history,
+            args.check_licenses,
+            args.map_endpoints,
+        )
+    if args.command == "scan":
+        exit_code, _evidence, _evidence_path = _scan(
+            args.path,
+            args.check_vulnerabilities,
+            args.scan_git_history,
+            args.check_licenses,
+            args.map_endpoints,
+        )
+        return exit_code
+    if args.command == "query":
+        return _query(args.kind, args.target, args.repo_path, args.full)
+    if args.command == "diff":
+        return _diff(
+            args.old,
+            args.new,
+            args.full,
+            args.fail_on_new_secrets,
+            args.fail_on_new_vulnerabilities,
+            args.fail_on_new_layer_violations,
+        )
+    if args.command == "mcp":
+        return _mcp(args.path)
+    if args.command == "dashboard":
+        return _dashboard(args.path, args.port)
+    if args.command == "healthcheck":
+        return _healthcheck(args.path, args.base_url)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())