code-atlas-forge 1.1.0__py3-none-any.whl

code_atlas/indexing/reuse.py

@@ -0,0 +1,85 @@
+"""Reuse path do lf-0020: resultados reutilizados via cache versionado.
+
+Contrato (grill): reuso nunca por path — a ``CacheKey`` cobre
+``content_sha256`` + idioma + versões de parser/grammar/extractor/
+resolver/builder + ``config_digest``. O payload é ``ParseResult``
+serializado — artefato sintático puro (símbolos, spans, relações
+**não resolvidas**).
+
+Política conservadora: só arquivos ``REUSE`` (conjunto de
+dependências inalterado no plano) são servidos do cache; arquivos
+``REVALIDATE_RELATIONS`` são re-parseados — "reevaluate" = re-extração
++ re-resolução. Relações nunca são copiadas prontas: o graph builder
+re-resolve ``to_name`` de cada aresta sobre o universo do snapshot
+novo.
+
+Materialização: resultados reutilizados entram no ``build`` junto com
+os parseados — ``persist_graph`` grava linhas **novas** amarradas ao
+``snapshot_id`` novo (isolamento lógico entre snapshots).
+
+Cache miss (primeira indexação incremental, GC, corrupção): o arquivo
+é lido e parseado de verdade — fallback correto, nunca inventa dados.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import TYPE_CHECKING
+
+from code_atlas.indexing.cache import CacheKey
+
+if TYPE_CHECKING:
+    from code_atlas.discovery.models import SourceFile
+    from code_atlas.parsers.contracts import ParserAdapter
+    from code_atlas.parsers.engine import ParseEngine
+
+
+def config_digest(engine: ParseEngine) -> str:
+    """Digest da configuração efetiva que influencia o output do parse.
+
+    Cobre os limites do engine e a identidade completa dos adaptadores
+    (id, parser/grammar versions, extensões) — qualquer mudança de
+    configuração efetiva muda a chave e invalida o cache.
+    """
+    adapters = []
+    for lang in sorted(engine.registry.languages):
+        ad = engine.registry.for_language(lang)
+        if ad is not None:
+            adapters.append([
+                ad.adapter_id, ad.parser_version, ad.grammar_version,
+                list(ad.extensions),
+            ])
+    doc = {
+        "adapters": adapters,
+        "limits": [
+            engine.limits.max_file_size,
+            engine.limits.timeout_us,
+            engine.limits.max_diagnostics,
+        ],
+    }
+    blob = json.dumps(doc, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(blob.encode()).hexdigest()
+
+
+def cache_key_for(
+    f: SourceFile,
+    adapter: ParserAdapter,
+    cfg_digest: str,
+) -> CacheKey | None:
+    """Chave de validade do arquivo; ``None`` se sha indisponível.
+
+    ``extractor_version`` = ``adapter_id`` (identifica o extrator que
+    gerou o resultado); parser/grammar versions vêm do adaptador.
+    """
+    if f.sha256 is None:
+        return None
+    return CacheKey(
+        path=f.path,
+        content_sha256=f.sha256,
+        language=adapter.language,
+        parser_version=adapter.parser_version,
+        grammar_version=adapter.grammar_version,
+        extractor_version=adapter.adapter_id,
+        config_digest=cfg_digest,
+    )

code_atlas/install/__init__.py

@@ -0,0 +1,7 @@
+"""Install lifecycle — provision local environment and record a receipt.
+
+Scope: ``project`` provisions workspace config + repository registration;
+``user`` provisions the global data dir only. Every mutation writes a
+receipt under ``<data-dir>/install/`` so ``install-status`` can prove
+what happened without trusting the caller's memory.
+"""

code_atlas/install/cli.py

@@ -0,0 +1,168 @@
+"""`code-atlas install` — guided wizard (TTY) + flag path (JSON).
+
+Same UX contract as `sparkforge-aws install` / `productforge install`:
+the shared ui/kit wizard drives scope -> install profile -> components
+-> real dry-run plan -> confirm -> apply -> doctor. Atlas-honest
+differences: no host payloads and no gateway profile (a local-first
+engine, not a content forge), so those steps are skipped by passing
+empty vocabularies to the wizard.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import lifecycle
+
+_COMPONENT_LABELS = {
+    "config": "Config",
+    "data-dir": "Data dir",
+    "repository": "Repository",
+}
+_COMPONENT_DETAILS = {
+    "config": "workspace config.toml (schema_version + root)",
+    "data-dir": "local data dir — atlas.db, receipts, manifests",
+    "repository": "repo registered in the index database",
+}
+
+
+def _tty() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _install(**kw: Any) -> dict[str, Any]:
+    """Map the wizard's keyword contract onto the real lifecycle.
+
+    ``host``/``gateway_profile`` are accepted and ignored — the atlas
+    installs no host payloads and has no execution profile.
+    """
+    return lifecycle.install(
+        scope=kw.get("scope", "project"),
+        profile=kw.get("profile", "recommended"),
+        components=kw.get("components"),
+        dry_run=bool(kw.get("dry_run")),
+        yes=bool(kw.get("yes")),
+    )
+
+
+def _doctor(**kw: Any) -> dict[str, Any]:
+    return lifecycle.doctor(scope=kw.get("scope", "project"))
+
+
+def run_guided_install() -> int:
+    """Interactive wizard via the vendored ui/kit — arrow-key menus."""
+    from ..ui.kit import UIContext
+    from ..ui.wizard import run_wizard
+
+    return run_wizard(
+        forge_name="code-atlas-forge",
+        install_fn=_install,
+        doctor_fn=_doctor,
+        hosts_available=(),
+        gateway_profiles=(),
+        scopes=("project", "user"),
+        component_order=lifecycle.COMPONENTS,
+        component_labels=_COMPONENT_LABELS,
+        component_details=_COMPONENT_DETAILS,
+        component_defaults={
+            p: set(c) for p, c in lifecycle.PROFILE_COMPONENTS.items()
+        },
+        env_hosts=(),
+        next_hint="code-atlas doctor · code-atlas index",
+        ctx=UIContext.detect(),
+    )
+
+
+def run_flag_install(
+    *,
+    scope: str,
+    profile: str,
+    components: str | None,
+    root: str | None,
+    dry_run: bool,
+    yes: bool,
+) -> dict[str, Any]:
+    """Non-interactive flag path — returns the receipt doc."""
+    comps = (
+        tuple(c.strip() for c in components.split(",") if c.strip())
+        if components
+        else None
+    )
+    return lifecycle.install(
+        scope=scope,
+        profile=profile,
+        components=comps,
+        root=Path(root) if root else None,
+        dry_run=dry_run,
+        yes=yes,
+    )
+
+
+def _render_install_doc(doc: dict[str, Any]) -> None:
+    print(f"install: {doc.get('status', '?')}")
+    for s in doc.get("applied", []):
+        print(f"  {s['component']:<10} {s['action']:<22} {s['target']}")
+    for s in doc.get("skipped", []):
+        print(f"  skipped    {s['component']:<10} {s['target']}")
+    for s in doc.get("unverified", []):
+        print(f"  unverified {s['component']:<10} {s['result']}")
+    if doc.get("status") == "planned":
+        for s in doc.get("plan", []):
+            print(f"  plan       {s['component']:<10} {s['action']:<22} {s['target']}")
+    if doc.get("error"):
+        print(f"  refused    {doc['error'].get('kind')}: {doc['error'].get('detail')}")
+
+
+def _render_check_doc(doc: dict[str, Any]) -> None:
+    for k, v in doc.items():
+        if k == "checks":
+            for c in v:
+                print(f"  {c['state']:<10} {c['check']:<18} {c['target']}")
+        elif k != "receipt":
+            print(f"{k}: {v}")
+    if doc.get("receipt") is not None:
+        print(f"receipt: {json.dumps(doc['receipt'], ensure_ascii=False)}")
+
+
+def run_install(args: Any) -> int:
+    """argparse handler — ``install|status|doctor`` actions."""
+    from code_atlas.observability.logging import escape_control
+
+    action = getattr(args, "action", "install")
+    try:
+        if action == "status":
+            doc = lifecycle.status()
+        elif action == "doctor":
+            doc = lifecycle.doctor(scope=args.scope)
+        else:
+            doc = run_flag_install(
+                scope=args.scope,
+                profile=args.profile,
+                components=args.components,
+                root=args.root,
+                dry_run=args.dry_run,
+                yes=args.yes,
+            )
+    except ValueError as exc:
+        print(f"error: {escape_control(str(exc))}", file=sys.stderr)
+        return 2
+
+    if getattr(args, "json", False):
+        print(json.dumps(doc, indent=2, ensure_ascii=False))
+    elif action == "install":
+        _render_install_doc(doc)
+    else:
+        _render_check_doc(doc)
+
+    if action == "install":
+        return 0 if doc.get("status") in ("completed", "planned") else 1
+    if action == "doctor":
+        return 0 if doc.get("status") == "healthy" else 1
+    return 0
+
+
+def guided_install_available() -> bool:
+    """Bare `install` may route to the wizard only on a real TTY."""
+    return _tty()

code_atlas/install/lifecycle.py

@@ -0,0 +1,286 @@
+"""Code Atlas install lifecycle — plan, apply, receipt, doctor.
+
+Honest local-first semantics: install provisions the local environment
+(data dir, workspace config, repository registration) and records a
+receipt — it never touches hosts, clouds or providers. ``dry_run``
+returns the plan and writes nothing; apply requires ``yes``.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from code_atlas import __version__
+from code_atlas.config import (
+    ConfigError,
+    config_file,
+    data_dir,
+    resolve_root,
+    write_config,
+)
+
+FORGE_ID = "code-atlas-forge"
+SCOPES = ("project", "user")
+PROFILES = ("minimal", "recommended", "full")
+COMPONENTS = ("config", "data-dir", "repository")
+PROFILE_COMPONENTS = {
+    "minimal": ("data-dir",),
+    "recommended": ("config", "data-dir", "repository"),
+    "full": ("config", "data-dir", "repository"),
+}
+_RECEIPT_SCHEMA = "forge/CodeAtlasInstallReceipt/v1"
+
+
+def _receipt_path() -> Path:
+    return data_dir() / "install" / "receipt.json"
+
+
+def read_receipt() -> dict[str, Any] | None:
+    p = _receipt_path()
+    if not p.exists():
+        return None
+    try:
+        doc: dict[str, Any] = json.loads(p.read_text(encoding="utf-8"))
+        return doc
+    except json.JSONDecodeError:
+        return None
+
+
+def _profile_components(
+    profile: str, components: tuple[str, ...] | None
+) -> tuple[str, ...]:
+    if components:
+        unknown = [c for c in components if c not in COMPONENTS]
+        if unknown:
+            raise ValueError(
+                f"unknown components: {unknown} (valid: {list(COMPONENTS)})"
+            )
+        return components
+    return PROFILE_COMPONENTS.get(profile, PROFILE_COMPONENTS["recommended"])
+
+
+def _plan(
+    *, scope: str, root: Path | None, comps: tuple[str, ...]
+) -> list[dict[str, Any]]:
+    """Deterministic plan — the same entries apply() will produce.
+
+    ``config``/``repository`` are workspace-scoped: under ``user`` they
+    are skipped with a reason instead of pretending to apply."""
+    steps: list[dict[str, Any]] = []
+    if "data-dir" in comps:
+        steps.append({"component": "data-dir", "action": "mkdir",
+                      "target": str(data_dir())})
+    if "config" in comps:
+        if scope == "project":
+            steps.append({"component": "config",
+                          "action": "write-if-absent",
+                          "target": str(config_file())})
+        else:
+            steps.append({"component": "config", "action": "skipped",
+                          "target": "workspace-scoped — needs a project root"})
+    if "repository" in comps:
+        if scope == "project":
+            steps.append({"component": "repository",
+                          "action": "register",
+                          "target": str(root)})
+        else:
+            steps.append({"component": "repository", "action": "skipped",
+                          "target": "workspace-scoped — needs a project root"})
+    steps.append({"component": "receipt", "action": "write",
+                  "target": str(_receipt_path())})
+    return steps
+
+
+def install(
+    *,
+    scope: str = "project",
+    root: Path | None = None,
+    profile: str = "recommended",
+    components: tuple[str, ...] | None = None,
+    dry_run: bool = False,
+    yes: bool = False,
+) -> dict[str, Any]:
+    """Plan (dry_run) or apply the install. Returns a receipt doc."""
+    if scope not in SCOPES:
+        raise ValueError(f"unknown scope {scope!r} (valid: {list(SCOPES)})")
+    if profile not in PROFILES:
+        raise ValueError(
+            f"unknown profile {profile!r} (valid: {list(PROFILES)})")
+    comps = _profile_components(profile, components)
+    resolved = (
+        resolve_root(str(root) if root else None)
+        if scope == "project"
+        else None
+    )
+    if scope == "project" and resolved is not None and not resolved.is_dir():
+        raise ValueError(f"root {resolved} is not a directory")
+    steps = _plan(scope=scope, root=resolved, comps=comps)
+
+    doc: dict[str, Any] = {
+        "schema": _RECEIPT_SCHEMA,
+        "forge_id": FORGE_ID,
+        "version": __version__,
+        "operation": "install",
+        "status": "planned" if dry_run else "completed",
+        "scope": scope,
+        "profile": profile,
+        "components": list(comps),
+        "root": str(resolved) if resolved else None,
+        "data_dir": str(data_dir()),
+        "plan": steps,
+        "applied": [],
+        "skipped": [],
+        "unverified": [],
+        "receipt": None,
+        "installed_at": None,
+    }
+    if dry_run:
+        return doc
+    if not yes:
+        return {**doc, "status": "declined",
+                "error": {"kind": "CA-INSTALL-DECLINED",
+                          "detail": "needs --yes - nothing written"}}
+
+    applied: list[dict[str, Any]] = []
+    skipped: list[dict[str, Any]] = []
+    unverified: list[dict[str, Any]] = []
+    for s in steps:
+        comp, action, target = s["component"], s["action"], s["target"]
+        try:
+            bucket, result = _apply_step(
+                comp, action, target,
+                resolved=resolved, scope=scope,
+                profile=profile, comps=comps,
+            )
+        except OSError as exc:
+            unverified.append({**s, "result": f"unverified:{exc}"})
+            continue
+        (applied if bucket == "applied" else skipped).append(
+            {**s, "result": result})
+        if action == "write" and comp == "receipt" and bucket == "applied":
+            doc["receipt"] = result
+
+    doc["applied"] = applied
+    doc["skipped"] = skipped
+    doc["unverified"] = unverified
+    doc["installed_at"] = time.time()
+    if unverified:
+        doc["status"] = "partial"
+    return doc
+
+
+def _apply_step(
+    comp: str, action: str, target: str, *,
+    resolved: Path | None, scope: str, profile: str,
+    comps: tuple[str, ...],
+) -> tuple[str, str]:
+    """One plan step -> ("applied"|"skipped", result). May raise OSError."""
+    if action == "skipped":
+        return "skipped", target
+    if action == "mkdir":
+        Path(target).mkdir(parents=True, exist_ok=True)
+        return "applied", "ok"
+    if action == "write-if-absent":
+        if resolved is None:
+            return "skipped", "user-scope"
+        try:
+            write_config(resolved)  # raises if config exists
+        except ConfigError as exc:
+            return "skipped", str(exc)
+        return "applied", "written"
+    if action == "register":
+        if resolved is None:
+            return "skipped", "user-scope"
+        repo_id = _register_repo(resolved)
+        return "applied", f"repository_id={repo_id}"
+    if action == "write" and comp == "receipt":
+        p = _receipt_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(
+            {"schema": _RECEIPT_SCHEMA, "forge_id": FORGE_ID,
+             "version": __version__, "scope": scope,
+             "profile": profile, "components": list(comps),
+             "root": str(resolved) if resolved else None,
+             "installed_at": time.time()}, indent=2,
+            sort_keys=True), encoding="utf-8")
+        return "applied", str(p)
+    return "skipped", "no-handler"
+
+
+def _register_repo(resolved: Path) -> int:
+    from code_atlas.discovery.identity import identity_key_for_root
+    from code_atlas.storage import connect, migrate
+    from code_atlas.storage.store import Store
+
+    conn = connect(data_dir() / "atlas.db")
+    try:
+        migrate(conn)
+        repo_id = Store(conn).get_or_create_repository(
+            identity_key_for_root(resolved), str(resolved)
+        )
+        conn.commit()
+        return repo_id
+    finally:
+        conn.close()
+
+
+def status() -> dict[str, Any]:
+    r = read_receipt()
+    return {"forge_id": FORGE_ID, "installed": r is not None, "receipt": r}
+
+
+def doctor(*, scope: str = "project", root: Path | None = None) -> dict[str, Any]:
+    """Health check — receipt readable, data dir writable, db openable."""
+    checks: list[dict[str, Any]] = []
+    r = read_receipt()
+    checks.append({"check": "receipt", "state": "ok" if r else "missing",
+                   "target": str(_receipt_path())})
+    dd = data_dir()
+    try:
+        dd.mkdir(parents=True, exist_ok=True)
+        probe = dd / ".atlas-probe"
+        probe.write_text("ok")
+        probe.unlink()
+        state = "ok"
+    except OSError:
+        state = "unwritable"
+    checks.append({"check": "data-dir", "state": state, "target": str(dd)})
+    cfg = config_file()
+    if scope == "project":
+        checks.append({"check": "config",
+                       "state": "ok" if cfg.exists() else "missing",
+                       "target": str(cfg)})
+    db = dd / "atlas.db"
+    try:
+        conn = sqlite3.connect(db)
+        conn.execute("SELECT 1")
+        conn.close()
+        db_state = "ok"
+    except sqlite3.Error:
+        db_state = "error"
+    checks.append({"check": "database", "state": db_state, "target": str(db)})
+    checks.append({"check": "python>=3.12",
+                   "state": "ok" if sys.version_info >= (3, 12) else "fail",
+                   "target": sys.version.split()[0]})
+    bad = {"unwritable", "error", "fail"}
+    ok = r is not None and all(c["state"] not in bad for c in checks)
+    return {"forge_id": FORGE_ID, "scope": scope, "checks": checks,
+            "status": "healthy" if ok else "degraded"}
+
+
+__all__ = [
+    "COMPONENTS",
+    "FORGE_ID",
+    "PROFILES",
+    "PROFILE_COMPONENTS",
+    "SCOPES",
+    "doctor",
+    "install",
+    "read_receipt",
+    "status",
+]