sourcecode 2.0.1__tar.gz → 2.2.0__tar.gz

{sourcecode-2.0.1 → sourcecode-2.2.0}/CHANGELOG.md

@@ -1,5 +1,133 @@
 # Changelog
 
+## [2.2.0] — 2026-07-12
+
+**Field-validation hardening — narrative/reporting-layer correctness across the
+audit corpus.** A refute-first pass over ten real repositories fixed a batch of
+mislabeling and miscount bugs where the headline framing contradicted the
+structured output the engine had already produced. No Semantic IR change — every
+fix is in the reporting/narrative layer and reuses facts already extracted.
+
+### Fixed
+
+- **`endpoints` — modeled JAX-RS no longer double-reported as un-modeled surface
+  (A2).** `_build_route_surface` fully models JAX-RS, but `extract_java_endpoints`
+  also counted every `@Path` file into `non_spring_rest_surface{modeled:false}` and
+  warned "count covers Spring-MVC-annotated endpoints only" — contradicting the
+  JAX-RS routes just emitted (18 on eureka, 689 on keycloak). Modeled routes now
+  carry framework provenance (`jax_rs`/`spring_mvc`); when JAX-RS routes were
+  modeled, `jax_rs` is dropped from the un-modeled surface. Genuinely un-modeled
+  surfaces (WebScripts/Servlets, or JAX-RS that produced no route) still surface and
+  still warn.
+- **`spring-audit` — overloaded `@Transactional` methods counted separately (A1).**
+  `TransactionBoundaryIndex.by_symbol` is keyed by signature-less FQN, so overloaded
+  methods (`findAll()` / `findAll(Pageable)`) collapsed to one entry and `stats()`
+  undercounted. A new `all_declared` list (one entry per site) drives the count
+  (petclinic 1→2, matching source); FQN-keyed lookups are unchanged.
+- **`spring-audit` — per-site TX overloads no longer hidden by `by_symbol` collapse
+  (A1-RESIDUAL).** TX-001 (proxy-bypass) and TX-005 (exception-swallow) are per-site
+  checks but iterated the collapsed FQN map; a non-risky overload could overwrite a
+  risky one sharing an FQN, silently dropping the finding. Both now iterate
+  `all_declared` with a dedupe guard. Corpus TX counts unchanged (the residual was
+  latent).
+- **`compact` — Spring Boot version surfaced from pom property (A3).** `--compact`
+  deployment omitted the Boot version when it lived in a `<spring.boot.version>`
+  property rather than the starter-parent, while `migrate-check` resolved it. The
+  serializer now falls back to the property-resolving detector (single source of
+  truth), gated on Boot presence so non-Boot repos gain no phantom version
+  (Broadleaf 3.5.14, consistent).
+- **`endpoints` — `Map.put("/", literal)` no longer treated as a router-DSL route
+  (B1).** The router-DSL detector matched an HTTP-verb name + `"/"` first arg; a
+  plain map write (`swapChars.put("/", "slash")`) was reported as a `PUT /`
+  endpoint. A negative lookahead now rejects a literal second argument — a handler
+  is never a bare literal (openmrs 3→2, jobrunr 12/12 kept).
+- **`endpoints` — test-suite module controllers excluded from entry points (B2).**
+  A scaffolding `@Controller` in openmrs' `test-suite` module (sources under
+  `src/main`) surfaced as a production entry point. Entry-point collection now uses
+  the broader `is_test_or_fixture_path`, and `test-suite`/`test-suites` are
+  recognized test-module segments (openmrs 19→18; petclinic/eureka/keycloak
+  unchanged).
+- **`stack` — JAX-RS API surfaced in the headline stack from source annotations
+  (C1).** Eureka reported `project_type=library` with an empty stack despite 18
+  JAX-RS routes, because the manifest scan has no Jersey/Guice/jsr311 vocabulary and
+  (for gradle) reads only the root build file. When the `.java` scan found JAX-RS
+  entry points and no Jakarta EE framework was inferred, the stack now surfaces
+  `Jakarta EE` from the `@Path`/`@GET` evidence (eureka → `Java rest api using
+  Jakarta EE`). Manifest-only jsr311 still infers nothing (honesty preserved).
+
+### Changed
+
+- **`modernize` — cyclic tangles distinguished from one-way deps in
+  `cross_module_tangles` (TANGLE-1).** A directional dependency is normal layering,
+  not a tangle. Each entry now carries `coupling_type` (`cyclic` when mutual, else
+  `directional`); the note and recommendation state only cyclic entries are real
+  tangles. The key is retained (mcp/USER_GUIDE/tests reference it); cyclic entries
+  still sort first.
+- **CLI — consistent progress spinner across all long-running commands (UX-1).** The
+  TTY-gated progress spinner ran on only 5 code paths; the slowest commands
+  (`spring-audit`, `validation`, `migrate-check`, `endpoints`, `export`,
+  `impact-chain`, `pr-impact`, `explain`) ran silent. All 9 now show the same
+  stderr-only, TTY/CI-gated indicator (never pollutes stdout JSON, zero cost in CI).
+
+### Notes
+
+- No breaking changes. All fixes are reporting/narrative-layer; the Semantic IR and
+  default JSON schemas are unchanged (`cross_module_tangles` gains an additive
+  `coupling_type` field). 3193 tests passing.
+
+## [2.1.0] — 2026-07-10
+
+**Robustness & Security Inference — vendor-agnostic security & validation posture.**
+Two new Knowledge-Layer projections let the engine reason about a repo's security
+and validation *model* without prior knowledge of the framework or any per-client
+configuration. Detection is structural (coverage, specificity, correlation,
+request-interception topology); a config file may only raise confidence, never
+drive detection. No IR change — both projections reuse facts the engine already
+extracts.
+
+### Added
+
+- **`spring-audit` — `security_posture` block (custom authorization inference).**
+  The engine now infers custom endpoint security models on a repo it has never
+  seen. It auto-detects a candidate custom-authorization annotation purely by
+  structure — an annotation outside the published open-standard baseline that
+  covers a systematic share of controller handlers, tracks the endpoint surface
+  (specificity), and correlates with a request-interception pipeline. The
+  concrete annotation name appears only as *evidence*, never in detection logic.
+  Every conclusion carries an Evidence-Confidence envelope
+  (`Verified | Likely | Unknown | RequiresManualReview`): detection fires at
+  `Likely` with no config present, and a `sourcecode.config.json` entry naming
+  the annotation upgrades it to `Verified`. Emits per-endpoint 4-way verdicts
+  (`protected_standard` / `protected_custom` / `coverage_unknown` /
+  `probably_exposed`) plus a request-interception ("authentication pipeline
+  inferred") conclusion. This kills the recurring false "N endpoints without
+  security" alarm on repos guarded by a bespoke gate — when a custom mechanism is
+  inferred, uncovered endpoints degrade to `coverage_unknown`, never a categorical
+  "unsecured". The related `SEC-001` finding is suppressed on any endpoint carrying
+  an auto-detected gate.
+
+- **`validation` — `validation_pattern` block (present-but-unused inference).**
+  Instead of reporting silent zeros when a repo has no `@Valid`, the engine now
+  classifies the request-body validation *pattern*: `bean_validation_active`
+  (Verified), `bean_validation_available_unused` (Likely — a validation framework
+  is on the classpath and body endpoints exist but none validate), or
+  `no_validation_detected` (Unknown). The middle class is the real finding on
+  repos with many `@RequestBody` handlers and zero `@Valid`: "framework present
+  but unused", with a prioritized recommendation — not an empty report.
+
+### Notes
+
+- Both projections are vendor-agnostic: inference predicates key only on published
+  open standards (`org.springframework.security`, `jakarta`/`javax.validation`,
+  JAX-RS), loaded as a declarative baseline table used to subtract the known
+  vocabulary. No proprietary annotation, framework, or naming convention appears
+  in any inference predicate (enforced by test).
+- Manual (throw-on-bad-parameter) validation detection is intentionally deferred:
+  guard-clause atoms do not yet cover endpoint-kind handler bodies. See
+  `docs/architecture/DESIGN-robustness-security-inference.md` §2.
+- No breaking changes. Default command outputs are unchanged except for the added
+  blocks above.
+
 ## [2.0.1] — 2026-07-10
 
 ### Added
@@ -18,14 +146,56 @@
   a logo block (`<img>` / `<p>` HTML) or use inline markdown links (`[label](url)`) had
   produced summaries like `API: <img src="…"/>`. The summary is now rendered to clean prose
   — HTML/badge blocks are skipped and inline links are unwrapped to their label.
-- **More complete blast radius in `impact` and `review-pr`.** Change-impact analysis now
-  surfaces every affected entry point for a changed repository/service, reducing missed
-  callers on interface- and DI-wired code.
 
 ### Notes
 
 - No breaking changes. Default command outputs are unchanged except where explicitly noted.
 
+## [2.0.0] — 2026-07-06
+
+**ASK Engine 2.0** — the product identity is now final. The engine is unchanged;
+this major marks the CLI/product rename and is fully backward compatible.
+
+### Changed — canonical command is now `ask`
+
+- **`ask` is the canonical CLI command.** `ask impact`, `ask migrate-check`,
+  `ask review-pr`, `ask mcp init`, `ask activate …` — one short verb that matches
+  the product name (ASK Engine).
+- **`sourcecode` becomes a deprecated compatibility alias.** It keeps working
+  (same single implementation, `prog_name` pinned to `ask`), prints a one-line
+  deprecation notice **only on an interactive terminal**, and forwards to `ask`.
+  Pipes and agents that still call `sourcecode` get byte-identical stdout **and**
+  clean (JSON-only) stderr — the machine contract is unchanged. The alias will be
+  removed in a future major.
+- **New welcome wordmark**: a large `ASK` block with an `E N G I N E` label
+  replaces the old `SOURCE`/`CODE` banner. Help and banners read `CLI: ask`.
+- **Config home moved to `~/.ask`** (canonical writes); the legacy `~/.sourcecode`
+  is still read as a fallback, so **no existing user loses their license or config**.
+  Cache dir (`.sourcecode-cache/`) and `SOURCECODE_*` env vars are unchanged.
+- **MCP**: `ask mcp init` registers the client entry under `ask`; a pre-existing
+  `sourcecode` entry is recognized and migrated (and both are removed on
+  `mcp remove`).
+- **Docs**: README, user guide, manual, tiers, demo and onboarding now say
+  **ASK Engine** and use `ask …` in every example. Package/install/config and
+  compatibility references are preserved and the compatibility strategy is
+  documented in `docs/PRODUCT_IDENTITY.md` (normative).
+
+### Compatibility
+
+- **PyPI/Homebrew distribution stays `sourcecode` this release**; installing it
+  provides both the `ask` and `sourcecode` commands. Renaming the distribution to
+  `ask-engine` is a separate, explicitly-breaking future change.
+- Python package/import name (`sourcecode`), MCP protocol identity, cache format,
+  and all serialized/JSON outputs are unchanged.
+
+### Also in this line (identity + precision, pre-2.0 increments)
+
+- **Impact/`review-pr`**: a changed repository/service now surfaces **every**
+  affected entry point (controller) instead of collapsing an N-controller blast
+  radius to one — bounded by `max_impacts`, no new semantic fact, hash-neutral.
+- **Product identity consolidation**: audited every `sourcecode` occurrence and
+  established `docs/PRODUCT_IDENTITY.md` as the normative product↔CLI mapping.
+
 ## [1.73.0] — 2026-07-01
 
 ### Fixed — audit reliability on a large non-Boot Spring monolith (Alfresco Community Repo field test)

{sourcecode-2.0.1 → sourcecode-2.2.0}/CONTRIBUTING.md

@@ -30,8 +30,8 @@ This installs `sourcecode` in editable mode with all development dependencies (`
 ### Run the CLI locally
 
 ```bash
-sourcecode . --agent
-sourcecode . prepare-context explain
+ask . --agent
+ask . prepare-context explain
 ```
 
 ### Run tests
@@ -150,7 +150,7 @@ Keep commits atomic. One logical change per commit.
 ## Reporting bugs
 
 Open an issue with:
-- `sourcecode --version` output
+- `ask --version` output
 - Command you ran
 - Expected behavior
 - Actual behavior / error output

sourcecode-2.2.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: sourcecode
+Version: 2.2.0
+Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
+License-File: LICENSE
+Keywords: agents,ai,codebase,context,developer-tools,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pathspec>=1.0
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.24
+Provides-Extra: ast
+Requires-Dist: tree-sitter-javascript>=0.21; extra == 'ast'
+Requires-Dist: tree-sitter-typescript>=0.21; extra == 'ast'
+Requires-Dist: tree-sitter>=0.21; extra == 'ast'
+Provides-Extra: dev
+Requires-Dist: mcp>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# ASK Engine
+
+> **ASK — Actionable Software Knowledge.** Persistent structural intelligence for AI coding agents.
+
+**Context · Impact · Migration · Architecture · Review — everything from one structural model.**
+
+![Version](https://img.shields.io/badge/version-2.2.0-blue)
+![Python](https://img.shields.io/badge/python-3.9%2B-green)
+
+> **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
+> command still works as a deprecated alias (it prints a one-line notice and forwards to
+> `ask`) and remains the Python/PyPI package name for now. The authoritative version is
+> whatever `ask version` reports. See [docs/PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md).
+
+---
+
+## The problem
+
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. For a large Java or TypeScript monolith, that means 5–15 seconds per invocation. Multiply by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+
+ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, every subsequent invocation returns pre-built context in milliseconds. The repo doesn't change? The cache doesn't expire.
+
+**The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
+
+---
+
+## Proof — measured on real repos
+
+| Repo | Size | Cold scan | Cache hit | Speedup |
+|------|------|-----------|-----------|---------|
+| Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
+| BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
+
+Cache keyed on content hashes — invalidated only when source changes. On repeated agent sessions against the same codebase, nearly every invocation is a cache hit.
+
+At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
+
+---
+
+## Install
+
+```bash
+# Homebrew (macOS / Linux)
+brew tap haroundominique/sourcecode && brew install sourcecode
+
+# pip / pipx
+pipx install sourcecode        # or: pip install sourcecode
+
+ask version                    # ask 2.2.0
+```
+
+> **Package vs. command.** The install package is named `sourcecode` this release
+> (renaming the distribution is a separate, breaking change). Installing it gives you the
+> canonical **`ask`** command plus the deprecated **`sourcecode`** alias.
+
+---
+
+## Quickstart
+
+```bash
+# High-signal structural summary — warm cache ~0.3s, cold 2–10s
+ask --compact
+
+# Blast radius: what breaks if this class changes?
+ask impact OrderService /path/to/repo
+
+# Spring Boot 2→3 migration readiness (bounded decision summary)
+ask migrate-check /path/to/repo --compact
+
+# Spring semantic audit: TX anomalies + security surface
+ask spring-audit /path/to/repo
+
+# Onboard to an unfamiliar codebase
+ask onboard /path/to/repo
+
+# PR review: risk, test gaps, changed modules
+ask review-pr /path/to/repo --since main
+```
+
+Full command reference: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)**.
+
+---
+
+## Capabilities
+
+Everything is computed from one cached structural model. Seven groups:
+
+### 1 · Structural Context
+Bounded, noise-free repo context designed to drop straight into an agent's context window.
+`ask --compact` · `ask --agent` · `ask onboard` · `ask cold-start`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 2 · Impact Analysis
+Blast radius from a class or interface — reverse dependencies, through Spring DI, to the HTTP endpoints a change reaches.
+`ask impact` · `ask impact-chain` (TX/SEC-enriched) · `ask pr-impact`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 3 · Architecture Intelligence
+The system map: module graph, dependency views, REST surface, per-class summaries, and a symbol-level IR for downstream tooling.
+`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 4 · Migration & Modernization
+Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, and an effort estimate.
+`ask migrate-check` · `ask modernize`
+→ [migrate-check reference](docs/migrate-check.md) · [MODERNIZATION.md](docs/MODERNIZATION.md)
+
+### 5 · Spring Analysis
+Deterministic Spring semantics: transactional anomalies (e.g. `@Transactional` on a private method = silent CGLIB no-op), security surface, request-body validation.
+`ask spring-audit` · `ask validation`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 6 · Developer Workflows
+The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
+`ask review-pr` · `ask fix-bug` · `ask prepare-context`
+→ [reference](docs/USER_GUIDE.md#typical-workflows)
+
+### 7 · Utilities
+`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / clear / freshness)
+→ [reference](docs/USER_GUIDE.md)
+
+---
+
+## What it does — and doesn't
+
+**ASK Engine reduces exploration cost.** It accelerates context acquisition and computes
+blast radius; it does not replace reading code — it reduces how often an agent needs to.
+All signals are **static and deterministic** (annotations, import graph, file structure) —
+no runtime analysis, no LLM guessing.
+
+Honest limits worth knowing before you rely on it:
+
+- `impact` on an **implementation** class (`OrderServiceImpl`) returns 0 callers in Spring Boot — callers inject the interface. **Always target the interface.**
+- `no_security_signal` on an endpoint means *no recognized method-level annotation*, **not** "unsecured" — Spring Security filter chains and custom authorization annotations show as `no_security_signal` unless taught via config (below).
+- `spring-audit` / `impact-chain` are **Java/Spring only**; non-Java repos return `spring_detected: false`.
+- Event topology (`--type events`) resolves Spring `ApplicationEvent` / `@EventListener` chains only — **not** Kafka/RabbitMQ/Redis routes.
+- Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
+- Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
+
+---
+
+## Pricing
+
+> **🎉 Early-adoption: Pro is currently unlocked for everyone.** Every install runs with
+> full Pro entitlements — no size gate, no key. The tiers below describe the model the
+> paywall will return to later.
+
+**Gating is by repo size and automation — never by command.** Every command runs at full
+power on Free for small and mid-size repos; you upgrade when the work gets bigger or automated.
+
+| | **Free** — €0 | **Pro** — €19/mo · €190/yr per dev |
+|---|---|---|
+| Repo size | ≤ 500 Java source files | **> 500 Java files** (enterprise monoliths) |
+| Commands | All of them, full output | Same commands, unlocked at scale |
+| `impact` / `fix-bug` / `review-pr` / `modernize` | ✅ full on small repos | ✅ full on large repos (Free gets a capped preview) |
+| `prepare-context delta` | 30 free runs/repo | unlimited — CI/CD automation |
+| MCP local server, offline, no data egress | ✅ | ✅ |
+
+**Non-Java repos are free at any size** — the size limit counts Java source files only.
+ASK Engine monetises enterprise Java monoliths. Activate with `ask activate <key>`.
+Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
+
+---
+
+## Configuration & privacy
+
+```bash
+ask config              # version, config file path, telemetry status
+ask telemetry disable   # anonymous telemetry is on by default (opt-out)
+```
+
+Telemetry collects version, OS, commands, flags, duration, repo-size range, and errors —
+**no source code, paths, secrets, or output**. Disable any time with
+`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`).
+
+**Custom security annotations.** Teach `endpoints`, `spring-audit`, and `explain` about
+project-specific authorization annotations via an optional `sourcecode.config.json` at the
+repo root (otherwise they report `policy: "none_detected"`):
+
+```json
+{
+  "customSecurityAnnotations": [
+    { "fullyQualifiedName": "com.example.security.M3FiltroSeguridad", "shortName": "M3FiltroSeguridad" }
+  ]
+}
+```
+
+Matching endpoints report `policy: "custom"` and drop out of the `no_security_signal` count.
+
+---
+
+## Documentation
+
+| Doc | What it covers |
+|-----|----------------|
+| [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
+| [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
+| [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |
+| [PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md) | Free vs Pro, pricing model |
+| [DEMO-5MIN.md](docs/DEMO-5MIN.md) | A reproducible 5-minute demo |
+| [MANUAL-USUARIO.md](docs/MANUAL-USUARIO.md) | Guía de usuario en español |
+| [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
+| [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |

sourcecode-2.2.0/README.md

@@ -0,0 +1,203 @@
+# ASK Engine
+
+> **ASK — Actionable Software Knowledge.** Persistent structural intelligence for AI coding agents.
+
+**Context · Impact · Migration · Architecture · Review — everything from one structural model.**
+
+![Version](https://img.shields.io/badge/version-2.2.0-blue)
+![Python](https://img.shields.io/badge/python-3.9%2B-green)
+
+> **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
+> command still works as a deprecated alias (it prints a one-line notice and forwards to
+> `ask`) and remains the Python/PyPI package name for now. The authoritative version is
+> whatever `ask version` reports. See [docs/PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md).
+
+---
+
+## The problem
+
+Every time an AI coding agent starts a new session, it has to re-parse the repository from scratch. For a large Java or TypeScript monolith, that means 5–15 seconds per invocation. Multiply by dozens of agent turns per hour, and repo context acquisition becomes a real bottleneck — not just latency, but tokens, compute, and iteration velocity.
+
+ASK Engine solves this with a persistent structural cache keyed on file content hashes. After the first scan, every subsequent invocation returns pre-built context in milliseconds. The repo doesn't change? The cache doesn't expire.
+
+**The cache is not a performance optimization. It is what makes ASK Engine usable as infrastructure rather than a one-off tool.**
+
+---
+
+## Proof — measured on real repos
+
+| Repo | Size | Cold scan | Cache hit | Speedup |
+|------|------|-----------|-----------|---------|
+| Keycloak | 7,885 Java files | 10.5s | 0.6s | **~17x** |
+| BroadleafCommerce | 2,985 Java files | 2.7s | 0.3s | **~9x** |
+
+Cache keyed on content hashes — invalidated only when source changes. On repeated agent sessions against the same codebase, nearly every invocation is a cache hit.
+
+At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
+
+---
+
+## Install
+
+```bash
+# Homebrew (macOS / Linux)
+brew tap haroundominique/sourcecode && brew install sourcecode
+
+# pip / pipx
+pipx install sourcecode        # or: pip install sourcecode
+
+ask version                    # ask 2.2.0
+```
+
+> **Package vs. command.** The install package is named `sourcecode` this release
+> (renaming the distribution is a separate, breaking change). Installing it gives you the
+> canonical **`ask`** command plus the deprecated **`sourcecode`** alias.
+
+---
+
+## Quickstart
+
+```bash
+# High-signal structural summary — warm cache ~0.3s, cold 2–10s
+ask --compact
+
+# Blast radius: what breaks if this class changes?
+ask impact OrderService /path/to/repo
+
+# Spring Boot 2→3 migration readiness (bounded decision summary)
+ask migrate-check /path/to/repo --compact
+
+# Spring semantic audit: TX anomalies + security surface
+ask spring-audit /path/to/repo
+
+# Onboard to an unfamiliar codebase
+ask onboard /path/to/repo
+
+# PR review: risk, test gaps, changed modules
+ask review-pr /path/to/repo --since main
+```
+
+Full command reference: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)**.
+
+---
+
+## Capabilities
+
+Everything is computed from one cached structural model. Seven groups:
+
+### 1 · Structural Context
+Bounded, noise-free repo context designed to drop straight into an agent's context window.
+`ask --compact` · `ask --agent` · `ask onboard` · `ask cold-start`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 2 · Impact Analysis
+Blast radius from a class or interface — reverse dependencies, through Spring DI, to the HTTP endpoints a change reaches.
+`ask impact` · `ask impact-chain` (TX/SEC-enriched) · `ask pr-impact`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 3 · Architecture Intelligence
+The system map: module graph, dependency views, REST surface, per-class summaries, and a symbol-level IR for downstream tooling.
+`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 4 · Migration & Modernization
+Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, and an effort estimate.
+`ask migrate-check` · `ask modernize`
+→ [migrate-check reference](docs/migrate-check.md) · [MODERNIZATION.md](docs/MODERNIZATION.md)
+
+### 5 · Spring Analysis
+Deterministic Spring semantics: transactional anomalies (e.g. `@Transactional` on a private method = silent CGLIB no-op), security surface, request-body validation.
+`ask spring-audit` · `ask validation`
+→ [reference](docs/USER_GUIDE.md#core-commands)
+
+### 6 · Developer Workflows
+The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
+`ask review-pr` · `ask fix-bug` · `ask prepare-context`
+→ [reference](docs/USER_GUIDE.md#typical-workflows)
+
+### 7 · Utilities
+`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / clear / freshness)
+→ [reference](docs/USER_GUIDE.md)
+
+---
+
+## What it does — and doesn't
+
+**ASK Engine reduces exploration cost.** It accelerates context acquisition and computes
+blast radius; it does not replace reading code — it reduces how often an agent needs to.
+All signals are **static and deterministic** (annotations, import graph, file structure) —
+no runtime analysis, no LLM guessing.
+
+Honest limits worth knowing before you rely on it:
+
+- `impact` on an **implementation** class (`OrderServiceImpl`) returns 0 callers in Spring Boot — callers inject the interface. **Always target the interface.**
+- `no_security_signal` on an endpoint means *no recognized method-level annotation*, **not** "unsecured" — Spring Security filter chains and custom authorization annotations show as `no_security_signal` unless taught via config (below).
+- `spring-audit` / `impact-chain` are **Java/Spring only**; non-Java repos return `spring_detected: false`.
+- Event topology (`--type events`) resolves Spring `ApplicationEvent` / `@EventListener` chains only — **not** Kafka/RabbitMQ/Redis routes.
+- Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
+- Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
+
+---
+
+## Pricing
+
+> **🎉 Early-adoption: Pro is currently unlocked for everyone.** Every install runs with
+> full Pro entitlements — no size gate, no key. The tiers below describe the model the
+> paywall will return to later.
+
+**Gating is by repo size and automation — never by command.** Every command runs at full
+power on Free for small and mid-size repos; you upgrade when the work gets bigger or automated.
+
+| | **Free** — €0 | **Pro** — €19/mo · €190/yr per dev |
+|---|---|---|
+| Repo size | ≤ 500 Java source files | **> 500 Java files** (enterprise monoliths) |
+| Commands | All of them, full output | Same commands, unlocked at scale |
+| `impact` / `fix-bug` / `review-pr` / `modernize` | ✅ full on small repos | ✅ full on large repos (Free gets a capped preview) |
+| `prepare-context delta` | 30 free runs/repo | unlimited — CI/CD automation |
+| MCP local server, offline, no data egress | ✅ | ✅ |
+
+**Non-Java repos are free at any size** — the size limit counts Java source files only.
+ASK Engine monetises enterprise Java monoliths. Activate with `ask activate <key>`.
+Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
+
+---
+
+## Configuration & privacy
+
+```bash
+ask config              # version, config file path, telemetry status
+ask telemetry disable   # anonymous telemetry is on by default (opt-out)
+```
+
+Telemetry collects version, OS, commands, flags, duration, repo-size range, and errors —
+**no source code, paths, secrets, or output**. Disable any time with
+`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`).
+
+**Custom security annotations.** Teach `endpoints`, `spring-audit`, and `explain` about
+project-specific authorization annotations via an optional `sourcecode.config.json` at the
+repo root (otherwise they report `policy: "none_detected"`):
+
+```json
+{
+  "customSecurityAnnotations": [
+    { "fullyQualifiedName": "com.example.security.M3FiltroSeguridad", "shortName": "M3FiltroSeguridad" }
+  ]
+}
+```
+
+Matching endpoints report `policy: "custom"` and drop out of the `no_security_signal` count.
+
+---
+
+## Documentation
+
+| Doc | What it covers |
+|-----|----------------|
+| [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
+| [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
+| [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |
+| [PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md) | Free vs Pro, pricing model |
+| [DEMO-5MIN.md](docs/DEMO-5MIN.md) | A reproducible 5-minute demo |
+| [MANUAL-USUARIO.md](docs/MANUAL-USUARIO.md) | Guía de usuario en español |
+| [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
+| [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |

{sourcecode-2.0.1 → sourcecode-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.0.1"
+version = "2.2.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -35,7 +35,8 @@ dependencies = [
 ]
 
 [project.scripts]
-sourcecode = "sourcecode.cli:main_entry"
+ask = "sourcecode.cli:main_entry"
+sourcecode = "sourcecode.cli:main_entry"  # deprecated compat alias — removed in a future major
 
 [project.optional-dependencies]
 dev = [