sourcecode 3.2.1

Persistent structural context and ultra-fast repeated analysis for AI coding agents

ASK Engine

ASK — Actionable Software Knowledge. Persistent structural intelligence for AI coding agents.

Context · Impact · Migration · Architecture · Review — everything from one structural model.

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.

---

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.

---

Install

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

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

# 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 · posture in depth: 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

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

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

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

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

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

7 · Utilities

ask rename-class (word-boundary Java rename) · ask chunk-file (split large files for agents) · ask cache (status / warm / clear / freshness) → reference

---

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.

---

Configuration & privacy

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"):

{
  "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	Full command reference, flags, output schema, workflows
contracts.md	Declare invariants in .ask/contracts.yml, enforce them in the edit loop and in CI
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	Migration rule catalogue (MIG-001..043) + Hibernate stratification
MODERNIZATION.md	The modernization product: assess → understand → plan → execute
PRODUCT_TIERS.md	Free vs Pro, pricing model
DEMO-5MIN.md	A reproducible 5-minute demo
MANUAL-USUARIO.md	Guía de usuario en español
PRODUCT_IDENTITY.md	ask (command) vs sourcecode (package/alias)
privacy.md	Telemetry and data-handling policy
DEFECT-LEDGER.md	Every defect found in the field, its class, and which release closed it — published on purpose