Metadata-Version: 2.4
Name: sourcecode
Version: 2.5.2
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.5.1-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.5.1
```

> **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.CustomSecurityAnnotation", "shortName": "CustomSecurityAnnotation" }
  ]
}
```

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 |
