sourcecode 2.2.0__tar.gz → 2.4.0__tar.gz

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

@@ -1,5 +1,111 @@
 # Changelog
 
+## [2.4.0] — 2026-07-12
+
+**AI Context Cache — a provider-agnostic cache for ASK's reusable Knowledge
+Context.** This is *not* a prompt cache: it never stores prompts, generated text,
+or LLM responses. It caches the structured knowledge ASK derives from source —
+so expensive commands stop re-parsing the same repository on every run. The cache
+belongs entirely to ASK and is consumed identically by any AI provider (GPT,
+Claude, Gemini, local models) or none at all; the LLM never participates in
+producing or reading it.
+
+### Added
+
+- **`context_cache.py` — the AI Context Cache component.** Operates at the
+  *knowledge* level: it caches the reusable Canonical IR (the expensive Java
+  parse) keyed **only by knowledge state**, never by command or prompt. The key
+  is `worktree_signature + KL_SCHEMA_VERSION + PRODUCER_VERSION + scope`, where
+  `worktree_signature` is the committed HEAD folded with a hash of the working-tree
+  diff when dirty — so a new commit *or* an uncommitted edit deterministically
+  invalidates the entry rather than serving stale context. Invalidation is
+  state-based, never TTL-based for correctness (TTL and a max-entry cap exist only
+  as cleanup). Entries are gzip'd, inspectable envelopes (no opaque blobs);
+  persistence survives across executions under `~/.sourcecode/context-cache/`.
+- **`get_or_build_cir()` — the reusable-knowledge entry point.** Builds the
+  Canonical IR once and, on a hit, rebuilds the full CIR cheaply from the cached
+  raw IR via `ir_dict_to_canonical` — skipping the parse entirely, with the
+  `cir_hash` verified equal so the rebuilt CIR is provably faithful. Because the
+  key is command-agnostic, every command that needs a CIR shares one entry: once
+  wired, `impact` / `review-pr` / `modernize` reuse it for free.
+- **`CachedContext`** — an inspectable structured record (`metadata`, `entities`,
+  `evidence`, `observations`, `summaries`, `graph_metrics`, `payload`,
+  `timestamps`, `producer_version`). Advisory metrics are tracked from day one:
+  hits, misses, invalidations, stores, hit ratio, average lookup/build time, bytes
+  stored, contexts reused.
+- **`ask cache context-stats` / `ask cache context-clear`** — observability and
+  management for the context cache, kept distinct from the existing snapshot-cache
+  `cache status` / `cache clear` so neither clobbers the other.
+- **`ask explain` is the first consumer.** It fetches its CIR through
+  `get_or_build_cir` and derives the class explanation cheaply from the shared
+  knowledge; each run reports `Context cache: HIT/MISS` with timing. Output is
+  byte-identical whether served from cache or a fresh build.
+
+### Notes
+
+- **Only `explain` is wired** — a deliberate reference integration to validate the
+  design before connecting `impact` / `onboard` / `prepare-context` / `archetype` /
+  `review-pr` / `modernize`. The SourceMap-based commands (`onboard`,
+  `prepare-context`, `archetype`) will use a separate cache scope.
+- No AI-provider-specific logic, no embeddings, no RAG, no prompt/response caching.
+- Env vars: `SOURCECODE_CONTEXT_CACHE_{DIR,DISABLE,TTL_DAYS,MAX_ENTRIES}`.
+- Tests: `tests/test_context_cache.py` adds 23 tests (hit/miss, commit/dirty/version
+  invalidation, persistence, corruption recovery, concurrency, TTL GC, CIR
+  round-trip fidelity, cross-command reuse). No report or behaviour cutover.
+
+## [2.3.0] — 2026-07-12
+
+**Module graph promoted to a first-class Evidence Provider for architectural
+characterization (ADR-0003 step 2).** The experimental `archetype` model can now
+derive architectural style from the *directed structure* of the module
+dependency graph rather than from directory names — names become secondary
+evidence. This consolidates a new evidence source; the legacy report wording is
+unchanged (no cutover) pending cross-repo validation.
+
+### Added
+
+- **`graph_evidence.py` — a pure, archetype-agnostic Graph Evidence Provider.**
+  Transforms a `ModuleGraph` into reusable topological evidence
+  (`ModuleGraph → metrics → GraphEvidence`). It knows graphs, not archetypes: it
+  never classifies, emits no prose, and does not import the scorer. Seven
+  name-free metrics, each O(V+E)/O(V log V): `scc_mass` (non-trivial
+  strongly-connected-component node fraction, iterative Tarjan), `cyclic_density`
+  (intra-SCC back-edges), `hub_concentration`, `module_centralization` (Freeman),
+  `downward_edge_ratio` and `dependency_inversion_ratio` (both via Martin
+  instability `I = out/(in+out)`), and `fan_in_gini`. Graphs below 4 nodes / 3
+  edges report `available=False` and degrade cleanly.
+- **`archetype` consumes topological evidence via a declarative `_GRAPH_MAP`.**
+  The map (`metric → [(dimension, label, weight, polarity, lo, hi)]`) is the only
+  place that couples graphs to archetypes; the scorer reads `Evidence` objects and
+  never traverses the graph. Polarity `-1` *refutes* (a dense cyclic core refutes
+  `layered`/`microkernel`/`hexagonal`). Architectural style now emerges from
+  structure: `layered` from downward flow + acyclicity, `engine` from a woven
+  cyclic core, `microkernel` from a stable hub, `hexagonal` from dependency
+  inversion into a distributed core.
+- **`ask archetype` builds a bounded `ModuleGraph`** (`GraphAnalyzer`) and feeds it
+  to the classifier, best-effort with graceful degradation to the previous
+  name-mass-only behaviour on failure or oversized trees. Output gains top-level
+  `graph_metrics` and `graph_*` entries in candidate evidence traces.
+
+### Changed
+
+- **Confidence is now tied to topological support for the winning label.**
+  `graph_backed` is true only when the winning candidate carries positive
+  `graph_*` evidence — so "high" confidence requires real structure behind *that*
+  conclusion, not merely that a graph exists. (The prior gate keyed on
+  `module_graph_summary` was effectively dead, since the command never populated
+  it.) A new absolute-score floor (`_MIN_CONFIDENT_SCORE`) keeps a near-floor lone
+  winner at "low".
+
+### Notes
+
+- **No report cutover.** Legacy `project_type` / `architecture.pattern` and the
+  report's first two lines are unchanged; `archetype` remains parallel and
+  experimental while the new evidence is validated across repositories.
+- Tests: `tests/test_graph_evidence.py` adds 12 synthetic-graph tests (no real
+  repository) covering metric ranges for layered/engine/microkernel/hexagonal
+  topologies and the archetype integration. Full battery: 3220 passed.
+
 ## [2.2.0] — 2026-07-12
 
 **Field-validation hardening — narrative/reporting-layer correctness across the

{sourcecode-2.2.0 → sourcecode-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.2.0
+Version: 2.4.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
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-2.2.0-blue)
+![Version](https://img.shields.io/badge/version-2.3.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`**
@@ -84,7 +84,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 2.2.0
+ask version                    # ask 2.3.0
 ```
 
 > **Package vs. command.** The install package is named `sourcecode` this release

{sourcecode-2.2.0 → sourcecode-2.4.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-2.2.0-blue)
+![Version](https://img.shields.io/badge/version-2.3.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`**
@@ -46,7 +46,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 2.2.0
+ask version                    # ask 2.3.0
 ```
 
 > **Package vs. command.** The install package is named `sourcecode` this release

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

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

{sourcecode-2.2.0 → sourcecode-2.4.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.2.0"
+__version__ = "2.4.0"