Metadata-Version: 2.4
Name: sourcecode
Version: 3.2.1
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.

**What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
shared structural layers (L1/L2 + the Repository Intelligence Snapshot) and the **compact
view**. Pass `--agent` to warm the agent view as well. Deeper projections are separate view
keys and are *not* covered by either — `--full`, `--env-map` and a raised `--depth` recompute
on first use, as do most `prepare-context` tasks. Measured on a 3,342-file Spring monolith:
`cache warm` 103s → `--compact --git-context` 1s (hit), but `--agent --full --env-map
--depth 20` still 171s (miss). Budget the deep run explicitly in CI, or warm exactly the view
your pipeline consumes. Full model: [USER_GUIDE.md#caching](docs/USER_GUIDE.md#caching).

---

## 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

**Start with these four.** In three independent field evaluations they carried most of the
measured value, and `posture --diff` is the one no evaluator found an equivalent for —
commercial or open source.

```bash
# What does each profile set ACTUALLY wire — and what changes between them?
# Resolves conditional beans and the filter chain, then diffs effective endpoint access.
ask posture /path/to/repo --diff dev:prod

# Every REST endpoint with its effective path (context-path + servlet path resolved),
# its inferred security policy and a confidence per endpoint.
ask endpoints /path/to/repo

# Spring semantic audit: transactional anomalies (private @Transactional = silent
# CGLIB no-op), security surface, request-body validation.
ask spring-audit /path/to/repo

# Spring Boot 2→3 readiness: located blockers, per-dimension score, effort estimate.
ask migrate-check /path/to/repo --compact
```

Then the everyday loop:

```bash
# High-signal structural summary — warm cache ~0.3s, cold 2–10s
ask --compact

# Blast radius: what breaks if this class changes?  (target the INTERFACE, not the Impl)
ask impact OrderService /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

# CI gate on NEW violations only, instead of on pre-existing debt
ask verify /path/to/repo --capture-baseline   # accept today's debt, once
ask verify /path/to/repo                      # then: only new violations block
```

> **Adopting a gate on a real codebase.** A repository that starts declaring contracts already
> violates them somewhere; `ask verify` is **baseline-relative by default** (`--fail-on new`)
> so the gate survives contact with reality instead of being switched off on day one.
> `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
> time, for trend reporting rather than blocking.

Full command reference: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)** · posture in depth:
**[docs/posture.md](docs/posture.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, an effort estimate, and — with `--blast-radius` — the endpoints whose call path runs through each blocker, so the re-test plan is ordered by regression scope.
`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)

### 5b · Runtime Posture *(experimental — and the most differentiated thing here)*
What a profile set **actually wires**: which conditional beans register, which do not, and which conditions could not be decided at all — then the effective endpoint access that follows from the filter chain. `--diff` answers the question nobody else answers in one command: *what changes between `dev` and `prod`, across every endpoint at once.*
`ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
→ [posture.md](docs/posture.md)

Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
hole with the condition named, never folded into active or inactive. **A posture answer that
guesses is a confident security falsehood — the worst failure mode this tool has.**

### 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)

---

## Every command, in one table

*`ask --help` shows a short header; this is the full surface. If you only read one row, read
`posture`.*

| Command | Answers | Note |
|---|---|---|
| `posture` | which beans a profile set wires, and how effective endpoint access differs between two sets | **experimental**, most differentiated |
| `endpoints` | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
| `spring-audit` | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
| `migrate-check` | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
| `impact` / `impact-chain` | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
| `pr-impact` | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
| `verify` | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
| `verify-edit` | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
| `--compact` / `--agent` | bounded structural context for an agent | `--compact` is the token-cheap one |
| `onboard` / `explain` / `cold-start` | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
| `export` / `repo-ir` / `schema` | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
| `modernize` | coupling hubs, cycles, dead zones, refactor candidates | |
| `review-pr` / `fix-bug` / `prepare-context` | diff review, symptom triage, task-shaped context | |
| `plan` / `compare` / `delta` / `contract-diff` | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
| `validation` | request-body validation coverage and gaps | |
| `baseline capture\|diff\|trend` | versioned architectural metrics over time | trend reporting, not gating |
| `retrieve` | typed knowledge queries over the model | **experimental** |
| `archetype` | evidence-based architectural archetype | **experimental** |
| `rename-class` / `chunk-file` | word-boundary Java rename; split a large file for an agent | |
| `cache status\|warm\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | housekeeping | |

---

## 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.
>
> **What that means concretely.** `ask auth status` reports `"status": "unauthenticated"`
> together with `"pro": true`, `"pro_reason": "early-adoption unlock"` — that combination is
> expected, not a bug: you are unauthenticated *and* unlocked. When the unlock ends, gating
> returns **by repo size and automation, never by command**: `posture`, `endpoints`,
> `spring-audit` and `migrate-check` stay in the base tier at full output. Nothing you can run
> today becomes a paid-only command tomorrow.

**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`). It defaults to **off in CI**.

> **Auditing someone else's code — regulated, client-owned or public-sector?** Turn it off
> *before* the first run, not after: `SOURCECODE_TELEMETRY=0 ask …`, or `ask telemetry disable`
> once (remembered). The default is opt-out today; **moving it to opt-in is on the roadmap**
> (`docs/DEFECT-LEDGER.md` P-1) precisely because a default you must remember to disable is the
> wrong default for third-party code.

**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 |
| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml`, enforce them in the edit loop and in CI |
| [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — and what could not be decided (experimental) |
| [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 |
| [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |
