sourcecode 2.0.0__tar.gz → 2.1.0__tar.gz

{sourcecode-2.0.0 → sourcecode-2.1.0}/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## [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
+
+- **`migrate-check --compact` — bounded decision summary.** A new opt-in view of the
+  migration report that keeps every decision field (readiness scores, headline blocker,
+  blocking count, estimated effort, executive summary, Hibernate classification, aggregate
+  counts) and caps each large collection to its top items with a `+N more` count. On real
+  monoliths the report shrinks ~97% (BroadleafCommerce 1.2 MB → 32 KB, OpenMRS 908 KB →
+  23 KB) — an agent or reviewer gets the verdict without the leaf-level firehose. The full
+  report remains the default output.
+
+### Fixed
+
+- **`onboard` project summary no longer leaks raw README markup.** READMEs that open with
+  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.
+
+### 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;

sourcecode-2.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: sourcecode
+Version: 2.1.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
+
+> **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.1.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.1.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.1.0/README.md

@@ -0,0 +1,203 @@
+# ASK Engine
+
+> **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.1.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.1.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.0 → sourcecode-2.1.0}/pyproject.toml

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

{sourcecode-2.0.0 → sourcecode-2.1.0}/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__ = "2.0.0"
+__version__ = "2.1.0"

{sourcecode-2.0.0 → sourcecode-2.1.0}/src/sourcecode/cli.py

@@ -4496,7 +4496,18 @@ def validation_cmd(
     from sourcecode.context_graph import ContextGraph
     from sourcecode.validation_surface import build_validation_surface
     # Structural facts come from the ContextGraph — the single access layer.
-    data = build_validation_surface(target, graph=ContextGraph.build_from_root(target))
+    _graph = ContextGraph.build_from_root(target)
+    data = build_validation_surface(target, graph=_graph)
+
+    # P1-C: classify the request-body validation *pattern* so a repo with a
+    # validation framework on the classpath but no @Valid reads as
+    # "present-but-unused" instead of a silent sea of zeros (DESIGN §2/§5).
+    try:
+        from sourcecode.validation_inference import infer_validation_pattern
+
+        data["validation_pattern"] = infer_validation_pattern(_graph.cir).to_dict()
+    except Exception:
+        pass
 
     if path_prefix:
         data["endpoints"] = [
@@ -4836,6 +4847,16 @@ def migrate_check_cmd(
         help="Minimum severity to include: critical, high, medium, or low (default).",
         show_default=True,
     ),
+    compact: bool = typer.Option(
+        False,
+        "--compact",
+        help=(
+            "Bounded decision summary (JSON): readiness scores, headline blocker, "
+            "effort, executive summary, Hibernate classification and aggregate "
+            "counts, with large collections capped to their top items (+N more). "
+            "No new analysis — same report, projected. Full detail is the default."
+        ),
+    ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
         help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
@@ -4867,6 +4888,7 @@ def migrate_check_cmd(
     \b
     Examples:
       ask migrate-check .
+      ask migrate-check . --compact          bounded decision summary
       ask migrate-check /path/to/repo --format text
       ask migrate-check . --min-severity high
       ask migrate-check . --output migration.json
@@ -4905,7 +4927,11 @@ def migrate_check_cmd(
     if format == "text":
         output = report.to_text(min_severity=min_severity)
     else:
-        output = _serialize_dict(report.to_dict(), "json")
+        # --compact projects the SAME report into a bounded, decision-grade view
+        # (output-shaping only). Default (full) output is unchanged — it is the
+        # baseline-oracle form and must stay byte-identical.
+        payload = report.to_compact_dict() if compact else report.to_dict()
+        output = _serialize_dict(payload, "json")
 
     _total = report.summary.get("total_findings", 0)
     _emit_command_output(

{sourcecode-2.0.0 → sourcecode-2.1.0}/src/sourcecode/migrate_check.py

@@ -1308,6 +1308,33 @@ def _dimension_score(
     return max(0, 100 - deduction)
 
 
+# --- Compact projection (output-shaping only) --------------------------------
+# `--compact` renders a bounded, decision-grade view of the SAME report: it caps
+# each large leaf collection to its top-N items and reports total/omitted counts.
+# It performs NO new analysis — it is a pure projection over the dict `to_dict()`
+# already produces (Semantic IR / ContextGraph / semantic engines untouched).
+# The default (full) output is unchanged and remains the baseline-oracle form.
+# FUTURE (not this increment): invert the default — emit compact by default and
+# add `--full` for the complete report — once the oracle baseline is recaptured.
+_COMPACT_TOP_N = 5
+
+
+def _cap_collection(items: list, top_n: int, key=None) -> dict:
+    """Project a list into a bounded `{total, shown, omitted, items}` view. Items
+    are optionally reordered by `key` (stable) so the retained slice is the most
+    important; ordering falls back to the engine's own emission order. No values
+    are recomputed — only selected and counted."""
+    total = len(items)
+    ordered = sorted(items, key=key) if key is not None else items
+    shown = ordered[:top_n]
+    return {
+        "total": total,
+        "shown": len(shown),
+        "omitted": max(0, total - len(shown)),
+        "items": shown,
+    }
+
+
 @dataclass
 class MigrationReport:
     schema_version: str = "1.4"
@@ -1679,6 +1706,43 @@ class MigrationReport:
             "metadata": self.metadata,
         }
 
+    def to_compact_dict(self, top_n: int = _COMPACT_TOP_N) -> dict:
+        """Bounded, decision-grade projection of `to_dict()`.
+
+        Keeps every decision field verbatim (readiness_score, per-dimension
+        readiness, headline_blocker, blocking_count, estimated_effort_days,
+        effort_breakdown, summary, Hibernate classification, aggregate counts) and
+        caps only the large leaf collections — top-level `findings` and the
+        Hibernate `rewrite_targets` / `findings` / `critical_call_chains` /
+        `golden_sql_hotspots` — to their top-`top_n` items, each wrapped as
+        `{total, shown, omitted, items}`. It reuses the already-computed
+        `to_dict()` output and recomputes nothing (output-shaping only)."""
+        full = self.to_dict()
+        compact = dict(full)
+        compact["mode"] = "compact"
+        compact["compact_note"] = (
+            f"Bounded decision summary: large collections are capped to the top {top_n} "
+            "items (see each collection's total/omitted). Run without --compact (JSON "
+            "default) for the complete report. A future release will invert this — "
+            "compact by default with --full for the full detail."
+        )
+        # Top-level findings: retain the most severe first, then engine order.
+        compact["findings"] = _cap_collection(
+            full["findings"], top_n,
+            key=lambda f: SEVERITY_ORDER.get(f.get("severity"), 3),
+        )
+        hib = full.get("hibernate")
+        if isinstance(hib, dict):
+            h = dict(hib)
+            for _col in (
+                "rewrite_targets", "findings",
+                "critical_call_chains", "golden_sql_hotspots",
+            ):
+                if isinstance(h.get(_col), list):
+                    h[_col] = _cap_collection(h[_col], top_n)
+            compact["hibernate"] = h
+        return compact
+
     def to_text(self, min_severity: str = "low") -> str:
         min_order = SEVERITY_ORDER.get(min_severity, 3)
         visible = [f for f in self.findings if SEVERITY_ORDER.get(f.severity, 3) <= min_order]