sourcecode 2.3.0__tar.gz → 2.4.0__tar.gz

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

@@ -1,5 +1,58 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.3.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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.3.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.3.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.3.0"
+__version__ = "2.4.0"

{sourcecode-2.3.0 → sourcecode-2.4.0}/src/sourcecode/cli.py

@@ -5341,6 +5341,7 @@ def explain_cmd(
     from sourcecode.context_graph import ContextGraph
     from sourcecode.spring_model import SpringSemanticModel
     from sourcecode.explain import explain_class
+    from sourcecode import context_cache as _ctxcache
 
     if not class_name.strip():
         _emit_error_json(
@@ -5383,14 +5384,27 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
+    # AI Context Cache — operates at the *knowledge* level: it caches the
+    # reusable Canonical IR (the expensive Java parse), keyed only by knowledge
+    # state, not by command. explain then derives its answer cheaply from that
+    # shared CIR. The same cached CIR is reused for free by any other command.
+    # Provider-agnostic and best-effort: any fault degrades to a fresh build.
     _prog = Progress()
     _prog.start(f"explaining {class_name} ({len(file_list)} files)")
+    _cc_look = None
     try:
-        cir = ContextGraph.build(file_list, target).cir
+        try:
+            cir, _cc_look = _ctxcache.get_or_build_cir(
+                _resolve_repo_root(target), target, file_list
+            )
+        except Exception:
+            cir = ContextGraph.build(file_list, target).cir  # fallback: never break explain
         model = SpringSemanticModel.build(cir)
         explanation = explain_class(class_name, cir, model)
     finally:
         _prog.finish()
+    if _cc_look is not None:
+        typer.echo(_cc_look.render(), err=True)
 
     if format == "json":
         output = _json.dumps(explanation.to_dict(), indent=2, ensure_ascii=False)
@@ -7199,6 +7213,53 @@ def cache_freshness_cmd(
         typer.echo(f"RIS updated:  {result.get('ris_last_updated_at') or 'never'}")
 
 
+@cache_app.command("context-stats")
+def cache_context_stats_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show AI Context Cache statistics (structured-knowledge reuse metrics).
+
+    This is the provider-agnostic context cache — distinct from the snapshot
+    cache reported by `ask cache status`. It measures reuse of ASK's structured
+    context (entities/evidence/observations/summaries), never prompts or LLM output.
+    """
+    from sourcecode import context_cache as _ctxcache
+    target = _resolve_repo_root(Path(path))
+    stats = _ctxcache.stats_for_repo(target)
+    if json_output:
+        import json as _j
+        typer.echo(_j.dumps(stats, indent=2, ensure_ascii=False))
+    else:
+        typer.echo(f"Cache dir:     {stats['cache_dir']}")
+        typer.echo(f"Enabled:       {stats['enabled']}")
+        typer.echo(f"Contexts:      {stats['contexts']}")
+        typer.echo(f"Hits:          {stats['hits']}")
+        typer.echo(f"Misses:        {stats['misses']}")
+        typer.echo(f"Invalidations: {stats['invalidations']}")
+        typer.echo(f"Stores:        {stats['stores']}")
+        typer.echo(f"Hit ratio:     {stats['hit_ratio']}")
+        typer.echo(f"Avg lookup:    {stats['avg_lookup_ms']} ms")
+        typer.echo(f"Avg build:     {stats['avg_build_ms']} ms")
+        typer.echo(f"Bytes stored:  {stats['bytes_stored']}")
+        typer.echo(f"KL version:    {stats['kl_schema_version']}  producer={stats['producer_version']}")
+
+
+@cache_app.command("context-clear")
+def cache_context_clear_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Delete the AI Context Cache for a repository (structured context + stats)."""
+    from sourcecode import context_cache as _ctxcache
+    target = _resolve_repo_root(Path(path))
+    if not yes and sys.stdin.isatty():
+        import click as _click
+        _click.confirm(f"Delete AI context cache for {target}?", abort=True, err=True)
+    removed = _ctxcache.clear_for_repo(target)
+    typer.echo(f"Removed {removed} context file(s).", err=True)
+
+
 # ── Entry point ───────────────────────────────────────────────────────────────
 
 def _stderr_is_interactive() -> bool: