klapcontext 0.1.2__tar.gz → 0.1.3__tar.gz

{klapcontext-0.1.2 → klapcontext-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: klapcontext
-Version: 0.1.2
+Version: 0.1.3
 Summary: Make your repository understandable to humans and AI.
 Author: Willy Cordon
 License-Expression: Apache-2.0
@@ -29,7 +29,12 @@ Dynamic: license-file
 
 # KlapContext
 
-Make your repository understandable to humans and AI.
+**Understand an unfamiliar codebase before changing it.**
+
+KlapContext convierte evidencia de código en un modelo del sistema: puntos de
+entrada, flujos, automatizaciones, integraciones y sus incertidumbres.
+Graphify funciona como proveedor de análisis técnico; KlapContext es la capa
+que transforma esa evidencia en comprensión para personas y agentes de IA.
 
 KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
 portal estático para personas y un briefing compacto para agentes de IA. Usa

{klapcontext-0.1.2 → klapcontext-0.1.3}/README.md

@@ -1,6 +1,11 @@
 # KlapContext
 
-Make your repository understandable to humans and AI.
+**Understand an unfamiliar codebase before changing it.**
+
+KlapContext convierte evidencia de código en un modelo del sistema: puntos de
+entrada, flujos, automatizaciones, integraciones y sus incertidumbres.
+Graphify funciona como proveedor de análisis técnico; KlapContext es la capa
+que transforma esa evidencia en comprensión para personas y agentes de IA.
 
 KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
 portal estático para personas y un briefing compacto para agentes de IA. Usa

{klapcontext-0.1.2 → klapcontext-0.1.3}/src/klapcontext/__init__.py

@@ -1,3 +1,3 @@
 """KlapContext local engineering-context generator."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"

{klapcontext-0.1.2 → klapcontext-0.1.3}/src/klapcontext/cli.py

@@ -6,18 +6,20 @@ from . import __version__
 from .agent_context import write as write_agent
 from .context_builder import build
 from .git import commit, dirty_files, exclude_klap, is_repository
-from .graphify import GraphifyError, copy_outputs, generate, load_graph, version
+from .graphify import GraphifyError
 from .portal import write as write_portal
+from .providers import default_provider
 
 def root_path(value: str | None) -> Path: return Path(value or os.getcwd()).resolve()
 
 def generate_all(root: Path, update: bool=False) -> dict:
     if not is_repository(root): raise RuntimeError(f"Not a Git repository: {root}")
     exclude_klap(root); klap=root/".klap"; klap.mkdir(exist_ok=True)
-    graph_path=generate(root, update); files=copy_outputs(root, klap/"graphify")
-    context=build(root, load_graph(graph_path)); (klap/"context.json").write_text(json.dumps(context, indent=2)+"\n", encoding="utf-8")
+    provider=default_provider()
+    graph_path=provider.generate(root, update); files=provider.copy_outputs(root, klap/"graphify")
+    context=build(root, provider.load_graph(graph_path)); (klap/"context.json").write_text(json.dumps(context, indent=2)+"\n", encoding="utf-8")
     agent=write_agent(context, klap/"agent-context.md"); write_portal(context, agent, files, klap/"index.html")
-    state={"schema_version":"0.1","generated_at":datetime.now(timezone.utc).isoformat(),"git_commit":commit(root),"graphify_version":version(),"klap_version":__version__}
+    state={"schema_version":"0.2","generated_at":datetime.now(timezone.utc).isoformat(),"git_commit":commit(root),"provider":{"name":provider.name,"version":provider.version()},"klap_version":__version__}
     (klap/"state.json").write_text(json.dumps(state, indent=2)+"\n", encoding="utf-8")
     return context
 

klapcontext-0.1.3/src/klapcontext/context_builder.py

@@ -0,0 +1,113 @@
+"""Build the product-level system model from deterministic evidence providers."""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .detector import detect_project
+from .frameworks.laravel import analyze as analyze_laravel
+from .git import commit
+from .system import deployment, documents, entry_points, external_systems, purpose
+
+
+def _nodes(graph: dict) -> list[dict]:
+    return graph.get("nodes", []) if isinstance(graph.get("nodes"), list) else graph.get("graph", {}).get("nodes", [])
+
+
+def _modules(nodes: list[dict]) -> list[dict]:
+    return [{"name": node.get("label") or node.get("name") or node.get("id"), "path": node.get("file") or node.get("path"), "kind": node.get("type", "module"), "description": None, "status": "CONFIRMED", "evidence": []} for node in nodes if (node.get("label") or node.get("name") or node.get("id")) and (node.get("file") or node.get("path"))][:100]
+
+
+def _runtime(points: list[dict], background: list[dict], frameworks: list[str]) -> dict:
+    modes, descriptions = [], []
+    if any(point["type"] == "http" for point in points): modes.append("http"); descriptions.append("Las solicitudes HTTP ingresan por las rutas detectadas.")
+    if any(point["type"] in {"cli", "artisan_command"} for point in points): modes.append("cli"); descriptions.append("La aplicación expone comandos ejecutables.")
+    if background: modes.append("scheduler"); descriptions.append("La aplicación declara procesamiento en segundo plano.")
+    return {"modes": modes, "layers": frameworks, "description": " ".join(descriptions) or None, "status": "CONFIRMED" if descriptions else "UNKNOWN"}
+
+
+def _io(points: list[dict], systems: list[dict], stores: list[dict]) -> tuple[list[dict], list[dict]]:
+    inputs, outputs = [], []
+    if any(point["type"] == "http" for point in points):
+        inputs.append({"type": "http_request", "description": "Solicitudes HTTP", "status": "CONFIRMED"})
+        outputs.append({"type": "http_response", "description": "Respuestas HTTP", "status": "INFERRED"})
+    if any(point["type"] in {"cli", "artisan_command"} for point in points): inputs.append({"type": "cli", "description": "Invocación por línea de comandos", "status": "CONFIRMED"})
+    if stores:
+        inputs.append({"type": "datastore", "description": "Base de datos", "status": "INFERRED"})
+        outputs.append({"type": "datastore", "description": "Escrituras de base de datos", "status": "INFERRED"})
+    return inputs, outputs
+
+
+def _flows(root: Path, laravel: dict, stores: list[dict], systems: list[dict]) -> list[dict]:
+    flows = []
+    for route in laravel["routes"][:8]:
+        steps = [{"name": route["name"], "kind": "route", "path": route["source"], "status": "CONFIRMED"}]
+        if route.get("target"):
+            steps.append({"name": route["target"], "kind": "controller", "path": route["source"], "status": "CONFIRMED"})
+            controller = root / "app" / "Http" / "Controllers" / (route["target"].split("::")[0] + ".php")
+            if controller.exists():
+                names = re.findall(r"\b(\w*(?:Service|Repository))\b", controller.read_text(encoding="utf-8", errors="replace"))
+                if names: steps.append({"name": names[0], "kind": "service", "path": str(controller.relative_to(root)), "status": "INFERRED"})
+        if stores: steps.append({"name": stores[0]["name"], "kind": "datastore", "path": None, "status": "INFERRED"})
+        elif systems: steps.append({"name": systems[0]["name"], "kind": "external_system", "path": None, "status": "INFERRED"})
+        if len(steps) > 1:
+            status = "CONFIRMED" if all(step["status"] == "CONFIRMED" for step in steps) else "INFERRED"
+            flows.append({"name": route["name"], "trigger": "http", "entry_point": route["name"], "steps": steps, "status": status, "confidence": 1.0 if status == "CONFIRMED" else .7, "evidence": route["evidence"], "inputs": [], "outputs": [], "external_systems": [], "datastores": [], "tests": []})
+    for command in laravel["scheduled_processes"][:3]:
+        flows.append({"name": command["name"], "trigger": "scheduler", "entry_point": command["name"], "steps": [{"name": "Scheduler", "kind": "scheduler", "path": command["path"], "status": "CONFIRMED"}, {"name": command["name"], "kind": "command", "path": command["path"], "status": "CONFIRMED"}], "status": "CONFIRMED", "confidence": 1.0, "evidence": command["evidence"], "inputs": [], "outputs": [], "external_systems": [], "datastores": [], "tests": []})
+    return flows[:10]
+
+
+def _interactions(flows: list[dict], systems: list[dict], stores: list[dict]) -> dict:
+    nodes, edges = [], []
+    def add_node(name, kind):
+        if not any(item["name"] == name for item in nodes): nodes.append({"name": name, "type": kind})
+    for flow in flows:
+        previous = None
+        for step in flow["steps"]:
+            add_node(step["name"], step["kind"])
+            if previous: edges.append({"source": previous, "target": step["name"], "label": "uses" if step["kind"] in {"datastore", "external_system"} else "calls"})
+            previous = step["name"]
+    for store in stores: add_node(store["name"], "datastore")
+    for system in systems: add_node(system["name"], "external_system")
+    return {"nodes": nodes[:30], "edges": edges[:45], "status": "INFERRED" if edges else "UNKNOWN"}
+
+
+def _start(root: Path, laravel: dict, systems: list[dict]) -> list[dict]:
+    result = []
+    for path, intent in (("routes/api.php", "Entender la API"), ("routes/web.php", "Entender las rutas web"), ("routes/console.php", "Entender procesamiento programado"), ("composer.json", "Entender dependencias"), ("config/database.php", "Entender acceso a datos")):
+        if (root / path).exists(): result.append({"intent": intent, "paths": [path], "reason": "Archivo Laravel relevante detectado"})
+    if systems: result.append({"intent": "Entender integraciones", "paths": sorted({path for system in systems for path in system["configuration"]}), "reason": "Sistemas externos detectados"})
+    return result
+
+
+def _analysis_evidence(laravel: dict) -> list[dict]:
+    seen, result = set(), []
+    for group in ("routes", "commands", "scheduled_processes", "queue_jobs", "events", "listeners", "components", "dependencies"):
+        for item in laravel.get(group, []):
+            for evidence in item.get("evidence", []):
+                key = (evidence.get("path"), evidence.get("line"), evidence.get("reason"), evidence.get("symbol"))
+                if key not in seen: seen.add(key); result.append(evidence)
+    return result
+
+
+def build(root: Path, graph: dict) -> dict:
+    stack, detector_evidence = detect_project(root)
+    docs = documents(root); value = purpose(root, docs)
+    systems, stores = external_systems(root); deploy, observability, _ = deployment(root)
+    empty_laravel = {"routes": [], "commands": [], "scheduled_processes": [], "queue_jobs": [], "events": [], "listeners": [], "components": [], "dependencies": [], "runtime_surfaces": [], "important_files": [], "framework": None}
+    laravel = analyze_laravel(root) if "Laravel" in stack["frameworks"] else empty_laravel
+    generic_points, generic_background = entry_points(root)
+    points = laravel["routes"] + laravel["commands"] + laravel["queue_jobs"] + laravel["listeners"] or generic_points
+    background = laravel["scheduled_processes"] + laravel["queue_jobs"] or generic_background
+    runtime = _runtime(points, background, stack["frameworks"])
+    inputs, outputs = _io(points, systems, stores)
+    flows = _flows(root, laravel, stores, systems) if laravel["routes"] else []
+    important = laravel["important_files"] or ([{"path": "README.md", "role": "Documentación", "reason": "README detectado"}] if (root / "README.md").exists() else [])
+    tests = [{"path": path, "reason": "Tests detectados"} for path in ("tests", "test", "phpunit.xml", "pytest.ini") if (root / path).exists()]
+    story = " ".join(item for item in (value["text"], runtime["description"], "La aplicación está contenerizada con Docker." if "Docker" in deploy["tools"] else None) if item)
+    system = {"purpose": value, "project_story": {"text": story or None, "status": "CONFIRMED" if story else "UNKNOWN"}, "runtime": runtime, "framework": laravel["framework"], "runtime_surfaces": laravel["runtime_surfaces"], "routes": laravel["routes"], "commands": laravel["commands"], "scheduled_processes": laravel["scheduled_processes"], "queue_jobs": laravel["queue_jobs"], "events": laravel["events"], "listeners": laravel["listeners"], "components": laravel["components"], "dependencies": laravel["dependencies"], "entry_points": points, "main_flows": flows, "system_interactions": _interactions(flows, systems, stores), "capabilities": _modules(_nodes(graph)), "inputs": inputs, "outputs": outputs, "external_systems": systems, "background_processes": background, "datastores": stores, "deployment": deploy, "observability": observability, "important_files": important, "start_here": _start(root, laravel, systems), "unknowns": [item for item, found in (("Propósito de negocio del proyecto", value["text"]), ("Plataforma de despliegue en producción", deploy["tools"])) if not found]}
+    technical = {"languages": stack["languages"], "frameworks": stack["frameworks"], "framework": laravel["framework"], "dependencies": laravel["dependencies"], "graph": {"nodes": len(_nodes(graph)), "edges": len(graph.get("edges", graph.get("graph", {}).get("edges", [])))}, "documents": [{"path": doc["path"]} for doc in docs], "tests": tests, "infrastructure": stack["infrastructure"]}
+    project = {"name": root.name, "type": stack["frameworks"][0] if stack["frameworks"] else None, "root": str(root.resolve()), "generated_at": datetime.now(timezone.utc).isoformat(), "git_commit": commit(root)}
+    return {"schema_version": "0.4", "project": project, "technical_model": technical, "system_model": system, "human_context": {"purpose": None, "users": None, "important_processes": [], "notes": []}, "stack": stack, "architecture": {"style": "MVC" if "Laravel" in stack["frameworks"] else None, "status": "INFERRED" if "Laravel" in stack["frameworks"] else "UNKNOWN", "confidence": None, "evidence": []}, "entry_points": points, "modules": system["capabilities"], "flows": flows, "api": laravel["routes"], "jobs": background, "datastores": stores, "external_systems": systems, "deployment": deploy, "observability": observability, "tests": tests, "evidence": [item.as_dict() for item in detector_evidence] + value["evidence"] + _analysis_evidence(laravel)}

klapcontext-0.1.3/src/klapcontext/evidence.py

@@ -0,0 +1,39 @@
+"""Small, serializable evidence records shared by every analyzer."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Evidence:
+    source_type: str
+    path: str
+    reason: str
+    status: str = "CONFIRMED"
+    confidence: float = 1.0
+    line: int | None = None
+    symbol: str | None = None
+    snippet: str | None = None
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def from_match(root: Path, path: Path, match_start: int, reason: str, *, symbol: str | None = None, status: str = "CONFIRMED", confidence: float | None = None) -> Evidence:
+    """Create evidence anchored to one source line; snippets never include env files."""
+    text = path.read_text(encoding="utf-8", errors="replace")
+    line = text.count("\n", 0, match_start) + 1
+    snippet = None
+    if not path.name.startswith(".env"):
+        snippet = text.splitlines()[line - 1].strip()[:240]
+    return Evidence(
+        "source",
+        str(path.relative_to(root)),
+        reason,
+        status,
+        confidence if confidence is not None else (1.0 if status == "CONFIRMED" else 0.7),
+        line,
+        symbol,
+        snippet,
+    )

klapcontext-0.1.3/src/klapcontext/frameworks/laravel.py

@@ -0,0 +1,138 @@
+"""Deterministic Laravel conventions analyzer; Graphify remains the code graph."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from ..evidence import Evidence, from_match
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _symbol(target: str) -> str | None:
+    match = re.search(r"(?:\[\s*)?([A-Za-z_]\w*(?:\\[A-Za-z_]\w*)*)::class\s*,\s*['\"](\w+)['\"]", target)
+    return f"{match.group(1).split('\\')[-1]}::{match.group(2)}" if match else None
+
+
+def _e(root: Path, path: Path, offset: int, reason: str, *, symbol: str | None = None, status: str = "CONFIRMED") -> list[dict]:
+    return [from_match(root, path, offset, reason, symbol=symbol, status=status).as_dict()]
+
+
+def _category(package: str) -> str:
+    package = package.lower()
+    if package == "laravel/framework": return "framework"
+    if any(token in package for token in ("mysql", "postgres", "mongodb", "redis", "doctrine/dbal")): return "database"
+    if any(token in package for token in ("queue", "horizon", "rabbit", "kafka")): return "queue"
+    if any(token in package for token in ("jwt", "sanctum", "passport", "auth")): return "authentication"
+    if any(token in package for token in ("guzzle", "http", "curl", "soap")): return "http"
+    if any(token in package for token in ("sentry", "telescope", "prometheus", "opentelemetry")): return "observability"
+    if any(token in package for token in ("phpunit", "pest", "faker")): return "testing"
+    if any(token in package for token in ("flysystem", "s3", "filesystem")): return "storage"
+    return "other"
+
+
+def _composer(root: Path) -> tuple[list[dict], dict]:
+    composer = root / "composer.json"
+    if not composer.exists():
+        return [], {"laravel": None, "php": None}
+    try:
+        data = json.loads(_read(composer))
+    except json.JSONDecodeError:
+        return [], {"laravel": None, "php": None}
+    dependencies = []
+    for scope, key in (("runtime", "require"), ("development", "require-dev")):
+        for package, version in data.get(key, {}).items():
+            evidence = Evidence("manifest", "composer.json", f"Dependencia Composer ({scope})", "CONFIRMED", 1.0, symbol=package).as_dict()
+            dependencies.append({"package": package, "version": version, "scope": scope, "category": _category(package), "status": "CONFIRMED", "evidence": [evidence]})
+    requirements = data.get("require", {})
+    return dependencies, {"laravel": requirements.get("laravel/framework"), "php": requirements.get("php")}
+
+
+def _routes(root: Path) -> tuple[list[dict], list[dict]]:
+    routes, scheduled = [], []
+    directory = root / "routes"
+    if not directory.is_dir():
+        return routes, scheduled
+    route_pattern = re.compile(r"Route::(get|post|put|patch|delete|options|any)\s*\(\s*['\"]([^'\"]+)['\"]\s*,\s*(.+?)\);", re.S | re.I)
+    resource_pattern = re.compile(r"Route::(?:api)?resource\s*\(\s*['\"]([^'\"]+)['\"]\s*,\s*([A-Za-z_]\w*(?:\\[A-Za-z_]\w*)*)::class", re.I)
+    schedule_pattern = re.compile(r"Schedule::(?:command|job)\s*\(\s*['\"]([^'\"]+)['\"]\s*\).*?->([A-Za-z]\w*)\s*\(", re.S)
+    for file in directory.glob("*.php"):
+        text = _read(file)
+        for match in route_pattern.finditer(text):
+            method, uri, target = match.groups()
+            handler = _symbol(target)
+            name = f"{method.upper()} /{uri.lstrip('/')}"
+            routes.append({"type": "http", "method": method.upper(), "uri": "/" + uri.lstrip("/"), "name": name, "path": str(file.relative_to(root)), "source": str(file.relative_to(root)), "line": text.count("\n", 0, match.start()) + 1, "target": handler, "handler": handler, "middleware": [], "status": "CONFIRMED", "evidence": _e(root, file, match.start(), "Declaración de ruta Laravel", symbol=name)})
+        for match in resource_pattern.finditer(text):
+            resource, controller = match.groups()
+            name = f"RESOURCE /{resource.lstrip('/')}"
+            routes.append({"type": "http", "method": "RESOURCE", "uri": "/" + resource.lstrip("/"), "name": name, "path": str(file.relative_to(root)), "source": str(file.relative_to(root)), "line": text.count("\n", 0, match.start()) + 1, "target": controller.split("\\")[-1], "handler": controller.split("\\")[-1], "middleware": [], "status": "INFERRED", "evidence": _e(root, file, match.start(), "Declaración resource de Laravel", symbol=name, status="INFERRED")})
+        if file.name == "console.php":
+            for match in schedule_pattern.finditer(text):
+                command, frequency = match.groups()
+                scheduled.append({"name": command, "type": "scheduled_command", "schedule": frequency, "path": str(file.relative_to(root)), "line": text.count("\n", 0, match.start()) + 1, "status": "CONFIRMED", "evidence": _e(root, file, match.start(), "Comando programado de Laravel", symbol=command)})
+    return routes, scheduled
+
+
+def _scheduled_kernel(root: Path) -> list[dict]:
+    kernel = root / "app" / "Console" / "Kernel.php"
+    if not kernel.exists():
+        return []
+    text = _read(kernel)
+    pattern = re.compile(r"\$schedule->(?:command|job)\s*\(\s*['\"]([^'\"]+)['\"]\s*\).*?->([A-Za-z]\w*)\s*\(", re.S)
+    return [{"name": match.group(1), "type": "scheduled_command", "schedule": match.group(2), "path": str(kernel.relative_to(root)), "line": text.count("\n", 0, match.start()) + 1, "status": "CONFIRMED", "evidence": _e(root, kernel, match.start(), "Scheduler de Laravel", symbol=match.group(1))} for match in pattern.finditer(text)]
+
+
+def _classes(root: Path, folder: str, kind: str, predicate=None) -> list[dict]:
+    directory = root / folder
+    if not directory.is_dir():
+        return []
+    result = []
+    for file in directory.rglob("*.php"):
+        text = _read(file)
+        if predicate and not predicate(text):
+            continue
+        name = file.stem
+        match = re.search(r"\bclass\s+(\w+)", text)
+        if match:
+            name = match.group(1)
+        result.append({"name": name, "type": kind, "path": str(file.relative_to(root)), "line": text.count("\n", 0, match.start()) + 1 if match else 1, "status": "CONFIRMED", "evidence": _e(root, file, match.start() if match else 0, f"Clase Laravel de tipo {kind}", symbol=name)})
+    return result
+
+
+def analyze(root: Path) -> dict:
+    routes, scheduled = _routes(root)
+    scheduled.extend(_scheduled_kernel(root))
+    dependencies, versions = _composer(root)
+    commands = _classes(root, "app/Console/Commands", "artisan_command")
+    for command in commands:
+        text = _read(root / command["path"])
+        signature = re.search(r"(?:protected|public)\s+\$signature\s*=\s*['\"]([^'\"]+)", text)
+        if signature:
+            command["name"] = signature.group(1)
+            command["evidence"] = _e(root, root / command["path"], signature.start(), "Firma de comando Artisan", symbol=command["name"])
+    jobs = _classes(root, "app/Jobs", "queue_job", lambda text: "ShouldQueue" in text)
+    for job in jobs:
+        text = _read(root / job["path"])
+        queue = re.search(r"(?:public|protected)\s+\$queue\s*=\s*['\"]([^'\"]+)", text)
+        job["queue"] = queue.group(1) if queue else None
+    events = _classes(root, "app/Events", "event")
+    listeners = _classes(root, "app/Listeners", "listener")
+    components = []
+    for folder, kind in (("app/Http/Controllers", "controller"), ("app/Http/Middleware", "middleware"), ("app/Services", "service"), ("app/Repositories", "repository"), ("app/Models", "model"), ("database/migrations", "migration"), ("database/seeders", "seeder")):
+        components.extend(_classes(root, folder, kind))
+    important = []
+    for path, role in (("routes/api.php", "Rutas HTTP API"), ("routes/web.php", "Rutas web"), ("routes/console.php", "Programación de comandos"), ("routes/channels.php", "Canales de broadcast"), ("app/Console/Kernel.php", "Scheduler Laravel"), ("config/database.php", "Configuración de datos"), ("config/services.php", "Configuración de integraciones"), (".env.example", "Variables de entorno documentadas"), ("composer.json", "Dependencias PHP")):
+        if (root / path).exists():
+            important.append({"path": path, "role": role, "reason": f"{role} detectado"})
+    surfaces = []
+    for kind, label, values in (("http", "HTTP", routes), ("cli", "CLI", commands), ("scheduler", "Scheduler", scheduled), ("queue", "Queue", jobs), ("event", "Eventos", events), ("listener", "Listeners", listeners)):
+        if values:
+            surfaces.append({"type": kind, "label": label, "count": len(values), "items": values})
+    return {"framework": {"name": "Laravel", "version": versions["laravel"], "php_version": versions["php"], "status": "CONFIRMED", "evidence": [Evidence("manifest", "composer.json", "laravel/framework declarado", "CONFIRMED", 1.0, symbol="laravel/framework").as_dict()]}, "routes": routes, "commands": commands, "scheduled_processes": scheduled, "queue_jobs": jobs, "events": events, "listeners": listeners, "components": components, "dependencies": dependencies, "runtime_surfaces": surfaces, "important_files": important}

{klapcontext-0.1.2 → klapcontext-0.1.3}/src/klapcontext/portal.py

@@ -69,10 +69,16 @@ def render(context: dict, agent_text: str, graphify_files: list[str]) -> str:
     evidence = context.get("evidence", [])
     surfaces = system.get("runtime_surfaces", [])
     unknowns = system.get("unknowns", [])
+    framework = system.get("framework") or {}
     purpose = system.get("purpose", {}).get("text") or "No pudimos determinar el propósito con suficiente confianza."
     story = system.get("project_story", {}).get("text") or system.get("runtime", {}).get("description") or "Todavía no hay una narrativa técnica verificable."
     state = "ACTUAL" if project.get("git_commit") else "SIN COMMIT"
-    tags = "".join(f"<span>{e(item)}</span>" for item in stack[:6]) or "<span>Stack no identificado</span>"
+    tags = "".join(f"<span>{e(item)}</span>" for item in stack[:6])
+    if framework.get("version"):
+        tags += f"<span>{e(framework.get('name', 'Framework'))} {e(framework['version'])}</span>"
+    if framework.get("php_version"):
+        tags += f"<span>PHP {e(framework['php_version'])}</span>"
+    tags = tags or "<span>Stack no identificado</span>"
     surface_cards = "".join(
         f"<article class='surface'><b>{e(item.get('count', 0))}</b><span>{e(item.get('label', 'superficies'))}</span></article>"
         for item in surfaces

klapcontext-0.1.3/src/klapcontext/providers/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in evidence providers. More engines can implement AnalysisProvider later."""
+from .graphify import GraphifyProvider
+
+
+def default_provider() -> GraphifyProvider:
+    return GraphifyProvider()

klapcontext-0.1.3/src/klapcontext/providers/base.py

@@ -0,0 +1,14 @@
+"""Contract for code-analysis engines feeding KlapContext evidence."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+
+class AnalysisProvider(Protocol):
+    name: str
+
+    def generate(self, root: Path, update: bool = False) -> Path: ...
+    def load_graph(self, graph: Path) -> dict: ...
+    def copy_outputs(self, root: Path, destination: Path) -> list[str]: ...
+    def version(self) -> str | None: ...

klapcontext-0.1.3/src/klapcontext/providers/graphify.py

@@ -0,0 +1,22 @@
+"""Graphify provider adapter. Keeps the engine separate from the system model."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .. import graphify
+
+
+class GraphifyProvider:
+    name = "graphify"
+
+    def generate(self, root: Path, update: bool = False) -> Path:
+        return graphify.generate(root, update)
+
+    def load_graph(self, graph: Path) -> dict:
+        return graphify.load_graph(graph)
+
+    def copy_outputs(self, root: Path, destination: Path) -> list[str]:
+        return graphify.copy_outputs(root, destination)
+
+    def version(self) -> str | None:
+        return graphify.version()

{klapcontext-0.1.2 → klapcontext-0.1.3}/src/klapcontext.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: klapcontext
-Version: 0.1.2
+Version: 0.1.3
 Summary: Make your repository understandable to humans and AI.
 Author: Willy Cordon
 License-Expression: Apache-2.0
@@ -29,7 +29,12 @@ Dynamic: license-file
 
 # KlapContext
 
-Make your repository understandable to humans and AI.
+**Understand an unfamiliar codebase before changing it.**
+
+KlapContext convierte evidencia de código en un modelo del sistema: puntos de
+entrada, flujos, automatizaciones, integraciones y sus incertidumbres.
+Graphify funciona como proveedor de análisis técnico; KlapContext es la capa
+que transforma esa evidencia en comprensión para personas y agentes de IA.
 
 KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
 portal estático para personas y un briefing compacto para agentes de IA. Usa

{klapcontext-0.1.2 → klapcontext-0.1.3}/src/klapcontext.egg-info/SOURCES.txt

@@ -19,4 +19,7 @@ src/klapcontext.egg-info/requires.txt
 src/klapcontext.egg-info/top_level.txt
 src/klapcontext/frameworks/__init__.py
 src/klapcontext/frameworks/laravel.py
+src/klapcontext/providers/__init__.py
+src/klapcontext/providers/base.py
+src/klapcontext/providers/graphify.py
 tests/test_klapcontext.py

{klapcontext-0.1.2 → klapcontext-0.1.3}/tests/test_klapcontext.py

@@ -66,3 +66,24 @@ def test_laravel_adapter_detects_flow_and_map(tmp_path):
     assert system["scheduled_processes"][0]["schedule"] == "hourly"
     assert system["queue_jobs"][0]["queue"] == "reports"
     assert system["main_flows"] and system["system_interactions"]["nodes"]
+
+
+def test_laravel_analysis_includes_versions_components_and_navigable_evidence(tmp_path):
+    root = fixture_repo(tmp_path)
+    (root / "composer.json").write_text(json.dumps({"require": {"php": "^8.2", "laravel/framework": "^11.0", "guzzlehttp/guzzle": "^7.0", "laravel/sanctum": "^4.0"}, "require-dev": {"pestphp/pest": "^3.0"}}))
+    (root / "routes" / "api.php").write_text("<?php\nRoute::post('/orders', [OrderController::class, 'store']);\n")
+    for folder, name in (("app/Http/Controllers", "OrderController"), ("app/Services", "OrderService"), ("app/Repositories", "OrderRepository"), ("app/Models", "Order"), ("app/Events", "OrderCreated"), ("app/Listeners", "SyncOrder")):
+        path = root / folder; path.mkdir(parents=True, exist_ok=True)
+        (path / f"{name}.php").write_text(f"<?php class {name} {{}}")
+    context = build(root, {"nodes": []})
+    system = context["system_model"]
+    assert system["framework"]["version"] == "^11.0"
+    assert system["framework"]["php_version"] == "^8.2"
+    assert {item["category"] for item in system["dependencies"]} >= {"framework", "http", "authentication", "testing"}
+    assert {item["type"] for item in system["components"]} >= {"controller", "service", "repository", "model"}
+    route = system["routes"][0]
+    assert route["line"] == 2 and route["evidence"][0]["line"] == 2
+    assert route["evidence"][0]["snippet"] == "Route::post('/orders', [OrderController::class, 'store']);"
+    assert len(system["events"]) == 1 and len(system["listeners"]) == 1
+    page = render_portal(context, render_agent(context), [])
+    assert "Laravel ^11.0" in page and "PHP ^8.2" in page

klapcontext-0.1.2/src/klapcontext/context_builder.py

@@ -1,72 +0,0 @@
-from __future__ import annotations
-from datetime import datetime, timezone
-from pathlib import Path
-from .detector import detect_project
-from .evidence import Evidence
-from .frameworks.laravel import analyze as analyze_laravel
-from .git import commit
-from .system import deployment, documents, entry_points, external_systems, purpose
-
-def _nodes(graph): return graph.get("nodes",[]) if isinstance(graph.get("nodes"),list) else graph.get("graph",{}).get("nodes",[])
-def _modules(nodes):
-    return [{"name":n.get("label") or n.get("name") or n.get("id"),"path":n.get("file") or n.get("path"),"kind":n.get("type","module"),"description":None,"status":"CONFIRMED","evidence":[]} for n in nodes if (n.get("label") or n.get("name") or n.get("id")) and (n.get("file") or n.get("path"))][:100]
-def _runtime(points, background, framework):
-    modes=[]; text=[]
-    if any(p["type"]=="http" for p in points): modes.append("http"); text.append("Las solicitudes HTTP ingresan por las rutas detectadas.")
-    if any(p["type"] in {"cli","artisan_command"} for p in points): modes.append("cli"); text.append("La aplicación expone comandos ejecutables.")
-    if background: modes.append("scheduler"); text.append("La aplicación declara procesamiento en segundo plano.")
-    return {"modes":modes,"layers":framework,"description":" ".join(text) or None,"status":"CONFIRMED" if text else "UNKNOWN"}
-def _io(points, systems, stores):
-    inputs=[]; outputs=[]
-    if any(p["type"]=="http" for p in points): inputs.append({"type":"http_request","description":"Solicitudes HTTP","status":"CONFIRMED"}); outputs.append({"type":"http_response","description":"Respuestas HTTP","status":"INFERRED"})
-    if any(p["type"] in {"cli","artisan_command"} for p in points): inputs.append({"type":"cli","description":"Invocación por línea de comandos","status":"CONFIRMED"})
-    if stores: inputs.append({"type":"datastore","description":"Base de datos","status":"INFERRED"}); outputs.append({"type":"datastore","description":"Escrituras de base de datos","status":"INFERRED"})
-    return inputs,outputs
-def _flows(root, laravel, stores, systems):
-    flows=[]
-    for route in laravel["routes"][:8]:
-        steps=[{"name":route["name"],"kind":"route","path":route["source"]}]
-        if route.get("target"):
-            steps.append({"name":route["target"],"kind":"controller","path":route["source"]})
-            ctrl=root/"app"/"Http"/"Controllers"/(route["target"].split("::")[0]+".php")
-            if ctrl.exists():
-                import re
-                names=re.findall(r"\b(\w*(?:Service|Repository))\b",ctrl.read_text(encoding="utf-8",errors="replace"))
-                if names: steps.append({"name":names[0],"kind":"service","path":None})
-        if stores: steps.append({"name":stores[0]["name"],"kind":"datastore","path":None})
-        elif systems: steps.append({"name":systems[0]["name"],"kind":"external_system","path":None})
-        if len(steps)>1: flows.append({"name":route["name"],"trigger":"http","entry_point":route["name"],"steps":steps,"status":"INFERRED","confidence":None,"evidence":route["evidence"],"inputs":[],"outputs":[],"external_systems":[],"datastores":[],"tests":[]})
-    for command in laravel["scheduled_processes"][:3]: flows.append({"name":command["name"],"trigger":"scheduler","entry_point":command["name"],"steps":[{"name":"Scheduler","kind":"scheduler","path":command["path"]},{"name":command["name"],"kind":"command","path":command["path"]}],"status":"CONFIRMED","confidence":None,"evidence":command["evidence"],"inputs":[],"outputs":[],"external_systems":[],"datastores":[],"tests":[]})
-    return flows[:10]
-def _interactions(flows, systems, stores):
-    nodes=[]; edges=[]
-    def n(name,kind):
-        if not any(x["name"]==name for x in nodes): nodes.append({"name":name,"type":kind})
-    for flow in flows:
-        previous=None
-        for step in flow["steps"]:
-            n(step["name"],step["kind"])
-            if previous: edges.append({"source":previous,"target":step["name"],"label":"uses" if step["kind"] in {"datastore","external_system"} else "calls"})
-            previous=step["name"]
-    for x in stores: n(x["name"],"datastore")
-    for x in systems: n(x["name"],"external_system")
-    return {"nodes":nodes[:30],"edges":edges[:45],"status":"INFERRED" if edges else "UNKNOWN"}
-def _start(root, laravel, systems):
-    result=[]
-    for path,intent in (("routes/api.php","Entender la API"),("routes/web.php","Entender las rutas web"),("routes/console.php","Entender procesamiento programado"),("composer.json","Entender dependencias"),("config/database.php","Entender acceso a datos")):
-        if (root/path).exists(): result.append({"intent":intent,"paths":[path],"reason":"Archivo Laravel relevante detectado"})
-    if systems: result.append({"intent":"Entender integraciones","paths":sorted({p for s in systems for p in s["configuration"]}),"reason":"Sistemas externos detectados"})
-    return result
-def build(root: Path, graph: dict) -> dict:
-    stack,evidence=detect_project(root); docs=documents(root); value=purpose(root,docs); systems,stores=external_systems(root); deploy,observability,_=deployment(root)
-    laravel=analyze_laravel(root) if "Laravel" in stack["frameworks"] else {"routes":[],"commands":[],"scheduled_processes":[],"queue_jobs":[],"dependencies":[],"runtime_surfaces":[],"important_files":[]}
-    generic_points,generic_background=entry_points(root)
-    points=laravel["routes"]+laravel["commands"] or generic_points; background=laravel["scheduled_processes"]+laravel["queue_jobs"] or generic_background
-    runtime=_runtime(points,background,stack["frameworks"]); inputs,outputs=_io(points,systems,stores); flows=_flows(root,laravel,stores,systems) if laravel["routes"] else []
-    important=laravel["important_files"] or [{"path":"README.md","role":"Documentación","reason":"README detectado"}] if (root/"README.md").exists() else []
-    tests=[{"path":x,"reason":"Tests detectados"} for x in ("tests","test","phpunit.xml","pytest.ini") if (root/x).exists()]
-    story=" ".join(x for x in [value["text"],runtime["description"],("La aplicación está contenerizada con Docker." if "Docker" in deploy["tools"] else None)] if x)
-    system={"purpose":value,"project_story":{"text":story or None,"status":"CONFIRMED" if story else "UNKNOWN"},"runtime":runtime,"runtime_surfaces":laravel["runtime_surfaces"],"routes":laravel["routes"],"commands":laravel["commands"],"scheduled_processes":laravel["scheduled_processes"],"queue_jobs":laravel["queue_jobs"],"dependencies":laravel["dependencies"],"entry_points":points,"main_flows":flows,"system_interactions":_interactions(flows,systems,stores),"capabilities":_modules(_nodes(graph)),"inputs":inputs,"outputs":outputs,"external_systems":systems,"background_processes":background,"datastores":stores,"deployment":deploy,"observability":observability,"important_files":important,"start_here":_start(root,laravel,systems),"unknowns":[x for x,ok in (("Propósito de negocio del proyecto",value["text"]),("Plataforma de despliegue en producción",deploy["tools"])) if not ok]}
-    technical={"languages":stack["languages"],"frameworks":stack["frameworks"],"dependencies":laravel["dependencies"],"graph":{"nodes":len(_nodes(graph)),"edges":len(graph.get("edges",graph.get("graph",{}).get("edges",[])))},"documents":[{"path":d["path"]} for d in docs],"tests":tests,"infrastructure":stack["infrastructure"]}
-    project={"name":root.name,"type":stack["frameworks"][0] if stack["frameworks"] else None,"root":str(root.resolve()),"generated_at":datetime.now(timezone.utc).isoformat(),"git_commit":commit(root)}
-    return {"schema_version":"0.3","project":project,"technical_model":technical,"system_model":system,"human_context":{"purpose":None,"users":None,"important_processes":[],"notes":[]},"stack":stack,"architecture":{"style":"MVC" if "Laravel" in stack["frameworks"] else None,"status":"INFERRED" if "Laravel" in stack["frameworks"] else "UNKNOWN","confidence":None,"evidence":[]},"entry_points":points,"modules":system["capabilities"],"flows":flows,"api":laravel["routes"],"jobs":background,"datastores":stores,"external_systems":systems,"deployment":deploy,"observability":observability,"tests":tests,"evidence":[x.as_dict() for x in evidence]+value["evidence"]}

klapcontext-0.1.2/src/klapcontext/evidence.py

@@ -1,11 +0,0 @@
-from __future__ import annotations
-from dataclasses import asdict, dataclass
-
-@dataclass(frozen=True)
-class Evidence:
-    source_type: str
-    path: str
-    reason: str
-    status: str = "CONFIRMED"
-    confidence: float = 1.0
-    def as_dict(self): return asdict(self)

klapcontext-0.1.2/src/klapcontext/frameworks/laravel.py

@@ -1,74 +0,0 @@
-"""Conservative Laravel conventions scanner; Graphify remains the code graph."""
-from __future__ import annotations
-
-import json
-import re
-from pathlib import Path
-
-from ..evidence import Evidence
-
-
-def _read(path: Path) -> str:
-    try: return path.read_text(encoding="utf-8", errors="replace")
-    except OSError: return ""
-
-
-def _e(path: str, reason: str, status: str="CONFIRMED") -> list[dict]:
-    return [Evidence("file", path, reason, status, 1.0 if status == "CONFIRMED" else .8).as_dict()]
-
-
-def _symbol(target: str) -> str | None:
-    target=target.strip()
-    match=re.search(r"(?:\[\s*)?([A-Za-z_][\w\\]+)::class\s*,\s*['\"](\w+)['\"]", target)
-    return f"{match.group(1).split('\\')[-1]}::{match.group(2)}" if match else None
-
-
-def analyze(root: Path) -> dict:
-    routes=[]; commands=[]; scheduled=[]; jobs=[]; dependencies=[]; important=[]
-    route_dir=root/"routes"
-    if route_dir.is_dir():
-        for file in route_dir.glob("*.php"):
-            text=_read(file); rel=str(file.relative_to(root))
-            for method, uri, target in re.findall(r"Route::(get|post|put|patch|delete|any)\s*\(\s*['\"]([^'\"]+)['\"]\s*,\s*(.+?)\);", text, re.S|re.I):
-                routes.append({"type":"http","method":method.upper(),"uri":"/"+uri.lstrip("/"),"name":f"{method.upper()} /{uri.lstrip('/')}","target":_symbol(target),"middleware":[],"source":rel,"status":"CONFIRMED","evidence":_e(rel,"Declaración de ruta Laravel")})
-            for resource, controller in re.findall(r"Route::(?:api)?resource\s*\(\s*['\"]([^'\"]+)['\"]\s*,\s*([A-Za-z_][\w\\]+)::class", text, re.I):
-                routes.append({"type":"http","method":"RESOURCE","uri":"/"+resource.lstrip("/"),"name":f"RESOURCE /{resource.lstrip('/')}","target":controller.split("\\")[-1],"middleware":[],"source":rel,"status":"INFERRED","evidence":_e(rel,"Declaración resource de Laravel","INFERRED")})
-            if file.name == "console.php":
-                for command, freq in re.findall(r"Schedule::command\s*\(\s*['\"]([^'\"]+)['\"]\s*\).*?->([A-Za-z]\w*)\s*\(", text, re.S):
-                    scheduled.append({"name":command,"type":"scheduled_command","schedule":freq,"path":rel,"status":"CONFIRMED","evidence":_e(rel,"Comando programado de Laravel")})
-    commands_dir=root/"app"/"Console"/"Commands"
-    if commands_dir.is_dir():
-        for file in commands_dir.glob("*.php"):
-            text=_read(file); signature=re.search(r"(?:protected|public)\s+\$signature\s*=\s*['\"]([^'\"]+)", text)
-            commands.append({"name":signature.group(1) if signature else file.stem,"type":"artisan_command","path":str(file.relative_to(root)),"status":"CONFIRMED","evidence":_e(str(file.relative_to(root)),"Clase de comando Artisan")})
-    jobs_dir=root/"app"/"Jobs"
-    if jobs_dir.is_dir():
-        for file in jobs_dir.glob("*.php"):
-            text=_read(file); rel=str(file.relative_to(root))
-            if "ShouldQueue" in text:
-                queue=re.search(r"(?:public|protected)\s+\$queue\s*=\s*['\"]([^'\"]+)", text)
-                jobs.append({"name":file.stem,"type":"queue_job","queue":queue.group(1) if queue else None,"path":rel,"status":"CONFIRMED","evidence":_e(rel,"Job Laravel que implementa ShouldQueue")})
-    composer=root/"composer.json"
-    if composer.exists():
-        try:
-            data=json.loads(_read(composer))
-            for scope,key in (("runtime","require"),("development","require-dev")):
-                for name, version in data.get(key,{}).items(): dependencies.append({"package":name,"version":version,"scope":scope,"category":_category(name),"status":"CONFIRMED","evidence":_e("composer.json",f"Dependencia Composer ({scope})")})
-        except json.JSONDecodeError: pass
-    for path,role in (("routes/api.php","Rutas HTTP API"),("routes/web.php","Rutas web"),("routes/console.php","Programación de comandos"),("app/Console/Kernel.php","Scheduler Laravel"),("config/database.php","Configuración de base de datos"),("bootstrap/app.php","Bootstrap de aplicación"),("composer.json","Dependencias PHP")):
-        if (root/path).exists(): important.append({"path":path,"role":role,"reason":f"{role} detectado"})
-    surfaces=[]
-    if routes: surfaces.append({"type":"http","label":"HTTP","count":len(routes),"items":routes})
-    if commands: surfaces.append({"type":"cli","label":"CLI","count":len(commands),"items":commands})
-    if scheduled: surfaces.append({"type":"scheduler","label":"Scheduler","count":len(scheduled),"items":scheduled})
-    if jobs: surfaces.append({"type":"queue","label":"Queue","count":len(jobs),"items":jobs})
-    return {"routes":routes,"commands":commands,"scheduled_processes":scheduled,"queue_jobs":jobs,"dependencies":dependencies,"runtime_surfaces":surfaces,"important_files":important}
-
-
-def _category(package: str) -> str:
-    if package == "laravel/framework": return "framework"
-    if "phpunit" in package or "pest" in package: return "testing"
-    if "sentry" in package: return "observability"
-    if "guzzle" in package: return "http"
-    if "jwt" in package or "sanctum" in package: return "authentication"
-    return "other"