sourcecode 5.9.32__tar.gz → 5.9.33__tar.gz

{sourcecode-5.9.32 → sourcecode-5.9.33}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [5.9.33] — 2026-09-15
+
+*Patch release keeping `ask --help` responsive on large repositories.*
+
+### Fixed
+
+- Bare `ask --help` no longer scans the current directory while building
+  contextual suggestions. Repository-aware help remains available with
+  `ask <repo> --help`.
+- Informational `--help` and `--version` exits no longer fail because an
+  unrelated `--output` path was not created.
+
 ## [5.9.32] — 2026-09-15
 
 *Patch release adding safe, explicit PyPI update notifications and installation.*

{sourcecode-5.9.32 → sourcecode-5.9.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.9.32
+Version: 5.9.33
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.32-blue)
+![Version](https://img.shields.io/badge/version-5.9.33-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -290,7 +290,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.32 — and, on a build that has aged,
+ask version                    # ask 5.9.33 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.9.32 → sourcecode-5.9.33}/README.md

@@ -10,7 +10,7 @@
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.32-blue)
+![Version](https://img.shields.io/badge/version-5.9.33-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -241,7 +241,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.32 — and, on a build that has aged,
+ask version                    # ask 5.9.33 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.9.32 → sourcecode-5.9.33}/docs/USER_GUIDE.md

@@ -279,7 +279,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.9.32
+# ask 5.9.33
 ```
 
 Requires Python 3.9+.

sourcecode-5.9.33/docs/investigations/2026-09-15-core-audit.md

@@ -0,0 +1,107 @@
+# Auditoría intensiva del camino crítico de ASK (2026-09-15)
+
+## Repositorios y ground truth
+
+| Repo | SHA auditado | Características |
+|---|---|---|
+| `testing/fullstack-app/spring-boot-server` | `de63350a76b0ad272b43a17d6aa071e5585b904c` | 6 Java, Spring Boot 3.1, Maven, REST/JPA; checkout padre Git |
+| `spring-projects/spring-petclinic` | `818c4136ea971c21674525f9053de0d9c7ad8cfe` | 50 Java, Spring Boot 4.1, Maven/Gradle, MVC/Thymeleaf/JPA |
+| `apache/kafka` | `3eb0b8c1b27d10084a6fee3b787616ddc06bcedc` | 6,188 Java, Gradle, multimódulo, Scala, JAX-RS/Trogdor |
+| `micronaut-projects/micronaut-core` | `09c62d0ed1a51703dab798867218a9a116192ca7` | 5,378 Java, Gradle, JVM/Micronaut, Java/Kotlin/Groovy |
+
+Los tres últimos fueron clones shallow de GitHub sin modificar sus fuentes; Kafka y
+Micronaut se usaron para estresar tamaño y arquitectura. El checkout local contiene
+archivos no versionados del entorno (`.ade`, `memory-bank`, `testdb.mv.db`), que ASK
+reporta honestamente como estado Git sucio.
+
+## Alcance y matriz ejecutada
+
+Se inspeccionaron CLI, `prepare-context`, parser/IR, serializadores `compact` y
+`agent`, Git, caché, MCP, contratos de salida y tests. Para cada repo se ejecutaron
+las salidas compacta y agent, endpoints cuando aplicaba, tres análisis repetidos,
+frío/cálido, y un ciclo modificar → analizar → revertir → analizar. También se
+probaron repositorio vacío, POM roto, Java inválido, Unicode y symlink.
+
+Ground truth independiente: conteo `find`, lectura directa de controladores,
+`ripgrep` de anotaciones, `git log/diff/status`, manifests y SHAs. En el servidor
+local ASK encontró exactamente los 7 mappings REST reales. En Petclinic encontró
+17 rutas; la inspección de controladores confirma 17 mappings literales. Kafka
+expone 44 rutas JAX-RS en Trogdor, que ASK enumera como 44.
+
+## Rendimiento observado
+
+Medianas aproximadas de cuatro ejecuciones de `ask <repo> --compact --format json`
+(primera fría, tres posteriores cálidas; macOS/Python 3.14, caché local):
+
+| Repo | Java | Frío | Cálido (mediana) | Compact bytes | Agent bytes |
+|---|---:|---:|---:|---:|---:|
+| server local | 6 | 0.57 s | 0.40 s | 8,603 | 12,288 |
+| Petclinic | 50 | 0.67 s | 0.40 s | 11,661 | 26,778 |
+| Kafka | 6,188 | 6.02 s | 0.46 s | 14,332 | 39,329 |
+| Micronaut | 5,378 | 4.13 s | 0.56 s | 15,096 | 25,120 |
+
+No es una baseline de memoria ni de otras plataformas. El principal coste frío es
+el escaneo/parsing inicial; la caché reduce el coste posterior de forma material.
+
+## Findings
+
+| ID / severidad / estado | Reproducción y evidencia | Impacto / decisión |
+|---|---|---|
+| CORE-001 / HIGH / CONFIRMED | `ask analyze --since HEAD` no es una invocación válida; `--since` existe en `prepare-context delta`. | La documentación de la tarea usa un nombre conceptual distinto al contrato CLI real. No se cambia retrospectivamente: usar `ask prepare-context delta <repo> --since REF`; añadir alias sería una decisión de API separada. |
+| CORE-002 / MEDIUM / CONFIRMED | `prepare-context delta --since HEAD` publica `git diff --name-only HEAD HEAD` e `includes_uncommitted=false`; una modificación sin commit produce `no_changes`. | Correcto para comparación de refs, peligroso si el agente cree que incluye working tree. El payload lo declara; el bucle de cambios locales debe usar la ruta de análisis con `--git-context`/changed-only. |
+| CORE-003 / MEDIUM / CONFIRMED LIMITATION | Micronaut: 87 controladores aparecen en el inventario, pero `endpoints` devuelve 0 y `coverage.gaps` declara `micronaut: 87 controllers`. | No es un falso cero oculto: la limitación está explícita. ASK no debe usarse como inventario HTTP Micronaut hasta añadir extractor específico. |
+| CORE-004 / LOW / CONFIRMED LIMITATION | Arquitectura de Kafka/Micronaut infiere capas por directorios y emite limitaciones de baja confianza/refutación. | El resultado no presenta la inferencia como certeza y conserva `confidence`/`limitations`. No corregir con heurísticas por repo. |
+| CORE-005 / LOW / CONFIRMED | En el checkout local, archivos no versionados del entorno entran en `uncommitted_files` y hotspots no distinguen intención humana. | Es fiel a Git y no altera la semántica; consumidores deben leer `tree_state` y `scope`. |
+| CORE-006 / LOW / NOT-REPRODUCED | Tres ejecuciones idénticas de Petclinic producen el mismo hash semántico tras quitar clocks/cache metadata. | No hay defecto de determinismo en la muestra. |
+
+No se encontraron defectos CRITICAL/HIGH de corrección en las rutas ejecutadas
+fuera de la incompatibilidad de nombre `analyze --since`. No se modificó código de
+análisis porque las limitaciones observadas ya se publican de manera inequívoca.
+
+## CLI, MCP, compact y agent
+
+`get_agent_context` MCP y `ask <repo> --agent` devolvieron el mismo proyecto,
+frameworks, entry points y señales para Petclinic. MCP añade la envoltura
+`success/data/error`, conservando el contrato interno. Las llamadas consecutivas
+comparten la misma caché y el mismo scope; los errores se estructuran sin traceback.
+
+`--compact` cambia la forma y elimina detalle, pero conserva identidad de proyecto,
+entry points, dependencias, confianza y gaps. No se observaron cifras materiales
+contradictorias respecto a `--agent`; los bytes muestran una reducción clara en
+repos pequeños y grandes. La salida agent puede ser 1.7–2.7× mayor que compacta,
+porque incorpora señales y razones útiles para decisiones del modelo.
+
+## Caché e incrementalidad
+
+La clave incorpora SHA, estado dirty y fingerprint del analizador. En Petclinic:
+
+```text
+cold      served_from_cache=false, fresh
+repetido  served_from_cache=true,  L2_view
+modificar served_from_cache=false, fresh, tree=<sha>+dirty:<hash>
+revertir  served_from_cache=true,  L2_view
+```
+
+No se observó stale-cache, símbolo fantasma ni duplicación en este ciclo. `--since`
+debe interpretarse como comparación de commits/ref; no sustituye la detección de
+cambios no committeados.
+
+## Robustez y seguridad
+
+Repos vacío, POM roto, Java sintácticamente inválido, Unicode y symlink terminaron
+con JSON válido y `rc=0` con gaps/confianza, sin traceback. No se escribieron los
+repositorios auditados. Los límites de salida publican `answer_bounds`; las
+superficies no soportadas se enumeran en `non_coverage`/`coverage.gaps`.
+
+## Veredicto
+
+1. `ask <repo> --agent` es suficientemente fiable para comprensión continua de repos Java/Spring muestreados, siempre leyendo confianza y gaps.
+2. `prepare-context delta --since REF` es fiable para deltas entre refs; no debe tratarse como working-tree delta cuando REF es `HEAD`.
+3. `--compact` conserva hechos centrales y reduce materialmente el output.
+4. `--agent` es claro y estable para un LLM, con límites explícitos.
+5. CLI y MCP son semánticamente equivalentes en la muestra; MCP añade envoltura y límites propios.
+6. No se confirmó stale-cache; la invalidación por estado dirty funcionó.
+7. El cuello de botella principal es el primer escaneo/parsing frío de repos grandes.
+8. El principal riesgo de corrección es interpretar como completa una superficie que ASK declara fuera de cobertura (Micronaut HTTP, servlets y DSLs no soportados).
+9. La siguiente inversión base debería ser un contrato incremental unificado que nombre explícitamente `ref delta` frente a `working-tree delta`, seguido de extractor Micronaut si ese stack es prioritario.
+10. Confiaría en ASK para estructura, dependencias, mappings soportados, cambios Git entre refs y contexto agent; no lo usaría como única fuente de verdad para reflexión, proxies runtime o endpoints de frameworks declarados en `coverage.gaps`.

{sourcecode-5.9.32 → sourcecode-5.9.33}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "5.9.32"
+version = "5.9.33"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-5.9.32 → sourcecode-5.9.33}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.9.32"
+__version__ = "5.9.33"

{sourcecode-5.9.32 → sourcecode-5.9.33}/src/sourcecode/cli.py

@@ -782,13 +782,24 @@ def _help_scope() -> "Optional[Any]":
     # carries this block.
     if any(not arg.startswith("-") and arg in _SUBCOMMANDS for arg in argv):
         return None
+    # Bare ``ask --help`` is an informational command.  Do not infer the
+    # current working directory as its repository: on a large checkout that
+    # turns help generation into an unbounded recursive scan before Click can
+    # print a single line.  Scope-aware help remains available when the caller
+    # explicitly supplies a repository path (``ask <repo> --help``).
+    explicit_roots = [
+        Path(arg) for arg in argv
+        if not arg.startswith("-") and arg not in _SUBCOMMANDS
+    ]
+    if not explicit_roots:
+        return None
     try:
         from sourcecode.execution_plan import measure_scope
 
         # The path token is lifted out of argv by `_preprocess_args` before Click
         # sees it, so `ask <repo> --help` is read from the same thread-local every
         # command reads, not from argv.
-        target = Path(_get_detected_path() or ".")
+        target = Path(_get_detected_path() or explicit_roots[0])
         if not target.is_dir():
             target = Path.cwd()
         return measure_scope(target)
@@ -3214,6 +3225,13 @@ def _record_output_promise(argv: "list[str]") -> None:
     _OUTPUT_PROMISED = None
     _OUTPUT_DELIVERED = False
     _ANSWER_REQUIRED_BY = None
+    # Informational exits are handled by Click before any command callback or
+    # output seam runs.  An output option may still be present (for example
+    # ``ask --help --output help.txt``), but help/version are not answers that
+    # promise the requested analysis file.  Arming the delivery guard here
+    # would turn a successful informational command into a false failure.
+    if any(token in ("--help", "-h", "--version") for token in argv):
+        return
     for i, token in enumerate(argv):
         value: "Optional[str]" = None
         if token in ("--output", "-o"):