sourcecode 3.2.0__py3-none-any.whl → 3.2.2__py3-none-any.whl

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__ = "3.2.0"
+__version__ = "3.2.2"

sourcecode/cache.py

@@ -178,6 +178,110 @@ def _get_git_head(repo_root: Path) -> str:
     return ""
 
 
+#: Directories never read as source, so their contents cannot change an answer.
+#: Used only by the non-git fingerprint below (git ignores them by .gitignore).
+_SIG_SKIP_DIRS: frozenset[str] = frozenset({
+    ".git", ".hg", ".svn", "target", "build", "out", "dist", "bin",
+    "node_modules", ".gradle", ".idea", ".vscode", "__pycache__", ".venv",
+    "venv", ".sourcecode-cache", ".mypy_cache", ".pytest_cache",
+})
+
+
+def _untracked_tree_fingerprint(target: Path) -> str:
+    """Fingerprint of a tree git cannot describe (no repository, or no commit).
+
+    Hashes ``(relative path, size, mtime_ns)`` of every non-ignored file. It is a
+    fingerprint of the tree, not of a commit — which is the point: without it the
+    key for a non-git tree is constant, and the cache answers forever with the
+    first analysis it ever ran.
+    """
+    h = hashlib.sha256()
+    try:
+        root = Path(target).resolve()
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = sorted(d for d in dirnames if d not in _SIG_SKIP_DIRS)
+            for name in sorted(filenames):
+                p = Path(dirpath) / name
+                try:
+                    st = p.stat()
+                except OSError:
+                    continue
+                h.update(str(p.relative_to(root)).encode("utf-8", "replace"))
+                h.update(f"\x00{st.st_size}\x00{st.st_mtime_ns}\x00".encode())
+    except Exception:
+        return ""
+    return f"ff{h.hexdigest()[:14]}"
+
+
+def worktree_signature(repo_root: Path, scope: Optional[Path] = None) -> str:
+    """Hex fingerprint of the **exact tree state an analysis would read**.
+
+    This is the single authority for cache freshness (ADR-0008): every layer that
+    stores an answer about the tree keys on this, so one rule describes them all —
+    *any change to the analysed files invalidates, committed or not*. Keying on the
+    committed HEAD alone made the root command serve an answer for a tree it had
+    not read: a dependency added to an uncommitted ``pom.xml`` stayed invisible
+    while the payload reported ``is_stale: false``.
+
+    Clean tree → the HEAD sha, so repeated runs hit. Dirty tree → HEAD plus a hash
+    of the porcelain status, the diff against HEAD, and the size/mtime of untracked
+    files (whose bytes the diff does not carry). *scope* restricts the status and
+    the diff to a subdirectory, so an edit in a sibling module does not invalidate
+    the module actually analysed.
+
+    Returns hex only — cache file names embed it and the GC parses them. Empty
+    string when the tree cannot be described at all; callers then skip the cache.
+    """
+    root = Path(repo_root)
+    head = _get_git_head(root)
+    if not head:
+        return _untracked_tree_fingerprint(scope if scope is not None else root)
+
+    pathspec: list[str] = []
+    try:
+        if scope is not None and Path(scope).resolve() != root.resolve():
+            pathspec = ["--", str(Path(scope).resolve())]
+    except Exception:
+        pathspec = []
+
+    try:
+        st = subprocess.run(
+            ["git", "-C", str(root), "status", "--porcelain", *pathspec],
+            capture_output=True, text=True, timeout=10,
+        )
+        porcelain = st.stdout if st.returncode == 0 else ""
+    except Exception:
+        porcelain = ""
+    if not porcelain.strip():
+        return head  # clean — HEAD fully describes the tree
+
+    try:
+        df = subprocess.run(
+            ["git", "-C", str(root), "diff", "HEAD", *pathspec],
+            capture_output=True, text=True, timeout=20,
+        )
+        diff_txt = df.stdout if df.returncode == 0 else ""
+    except Exception:
+        diff_txt = ""
+
+    h = hashlib.sha256()
+    h.update(porcelain.encode("utf-8", "replace"))
+    h.update(b"\x00")
+    h.update(diff_txt.encode("utf-8", "replace"))
+    # Untracked files appear in the porcelain by name only; their bytes are in no
+    # diff, so an edit to one would be invisible without their stat.
+    for line in porcelain.splitlines():
+        if not line.startswith("?? "):
+            continue
+        try:
+            p = root / line[3:].strip().strip('"')
+            st_u = p.stat()
+            h.update(f"\x00{line[3:]}\x00{st_u.st_size}\x00{st_u.st_mtime_ns}".encode("utf-8", "replace"))
+        except OSError:
+            continue
+    return f"{head}d{h.hexdigest()[:12]}"
+
+
 # ---------------------------------------------------------------------------
 # Public API — location helpers
 # ---------------------------------------------------------------------------

sourcecode/cache_model.py

@@ -0,0 +1,295 @@
+"""What each cache layer stores, what invalidates it, and which commands a warm helps.
+
+Field evaluation #3 could not predict the cache: `cache warm` took 103 s and made
+`--compact` return in 1 s, then `--agent --full --env-map --depth 20` missed anyway
+and took 171 s, and most of `prepare-context` was unaffected. The verdict was
+*"el warm no es un warm general — el modelo de invalidación no está documentado y
+no es predecible"* (defect C4-3), and the cold cost was nowhere a user meets it
+(C4-5).
+
+This module is the answer, and it is the only place the answer lives: `ask cache
+model` renders it, the user guide embeds the same rendering, and the battery fails
+if a registered command is missing from it or if the guide has drifted from it. A
+curated list beside a generated one is how `endpoints` went missing from `--help`
+(C4-1); the same mistake is not repeated here.
+
+The rows are **measured, not asserted**. Which layers a command reads was derived by
+wrapping the entry points of each layer and running every command; what a warm is
+worth was then timed per command **in isolation** — caches cleared, `cache warm`,
+then the command. Measuring them in sequence instead reports a benefit the user
+will not get, because one command warms the next: run in a batch, `impact-chain`
+looked unaffected by a warm; run in isolation it goes from 9.9 s to 1.7 s.
+
+Two results are worth stating because they contradict the natural assumption: a
+warm buys `endpoints` and `migrate-check` **nothing**, and on a small diff it makes
+`review-pr` slower than no cache at all.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Layer:
+    """One cache layer: what it holds, where, and what makes it invalid."""
+
+    id: str
+    stores: str
+    location: str
+    invalidated_by: str
+    warmed: str  # what `ask cache warm` does to this layer
+
+
+@dataclass(frozen=True)
+class CommandCache:
+    """What caching does for one command."""
+
+    command: str
+    reads: tuple[str, ...]
+    warm: str  # "answer" | "shared" | "none"
+    repeat: bool  # does a second identical run serve a stored answer?
+    note: str
+    #: Wall time on the reference repository, or "" where it was not timed.
+    #: Every figure below was taken in isolation — caches cleared, then `cache warm`,
+    #: then the command — because measuring them in sequence lets one command warm the
+    #: next and reports a benefit the user will not get.
+    measured: str = ""
+
+
+#: Where every `measured` figure comes from.
+REFERENCE_REPOSITORY = (
+    "BroadleafCommerce (2 000+ Java files, dirty tree), warm machine, 3.2.2"
+)
+
+
+#: Every layer keys on `cache.worktree_signature` — the exact tree state (C1-9).
+#: One sentence covers all of them: **any change to the analysed files invalidates,
+#: committed or not.** The rows below say what *else* invalidates each layer.
+LAYERS: tuple[Layer, ...] = (
+    Layer(
+        id="snapshot",
+        stores="the rendered answer of the root command (L1 core analysis + L2 view)",
+        location="~/.sourcecode/cache/<repo>/core-*.json.gz, view-*.json.gz",
+        invalidated_by=(
+            "tree state · analyzer fingerprint · analysis flags "
+            "(--env-map, --depth, --docs, --exclude, …) for the core; "
+            "presentation flags (--compact, --agent, --full, --format, …) for the view"
+        ),
+        warmed="built for the compact view (`--agent` also builds the agent view)",
+    ),
+    Layer(
+        id="ris",
+        stores="the Repository Intelligence Snapshot — structural index, endpoint index, summaries",
+        location="~/.sourcecode/cache/<repo>/ris.json.gz",
+        invalidated_by="tree state (the snapshot records the tree it describes)",
+        warmed="rebuilt on every warm",
+    ),
+    Layer(
+        id="cir",
+        stores="the shared Canonical IR — the Java parse every knowledge command reuses",
+        location="~/.sourcecode/ctx-*.json.gz (context cache)",
+        invalidated_by="tree state · analyzer fingerprint · schema version",
+        warmed="built",
+    ),
+    Layer(
+        id="task",
+        stores="one `prepare-context` task answer, per task and per option set",
+        location="~/.sourcecode/cache/<repo>/snapshot-pctx-*.json.gz",
+        invalidated_by="tree state · task · --symptom / --all / --include-config / --format",
+        warmed="never — a warm does not run any task",
+    ),
+    Layer(
+        id="parse",
+        stores="the symbol extraction of one file, keyed by its bytes",
+        location="~/.sourcecode/parse-cache-v1/",
+        invalidated_by=(
+            "the file's own bytes and the extractor's source — content-addressed, "
+            "so it is never stale and never needs invalidating"
+        ),
+        warmed="filled for every Java file the warm parses",
+    ),
+)
+
+#: What a warm does for each command.
+#:
+#: ``answer`` — a warm stores the answer this command returns; it comes back in
+#: about a second.
+#: ``shared`` — a warm removes the expensive shared work (the Java parse, the CIR);
+#: the command still computes its own answer.
+#: ``none`` — a warm does nothing for it. Some of these still hit on a *repeat*
+#: run because they cache their own answer (`repeat`), which a warm cannot do for
+#: them because it never runs them.
+COMMANDS: tuple[CommandCache, ...] = (
+    CommandCache("ask (root)", ("snapshot", "ris", "parse"), "answer", True,
+                 "`--compact` is what a warm stores by default; `--agent` needs `cache warm --agent`. "
+                 "`--env-map`, `--depth N` and `--exclude` change the *analysis*, so they miss the "
+                 "warmed core and rescan — this is the 171 s the field measured after a 103 s warm.",
+                 "--compact 17.7 s → 0.3 s; --agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)"),
+    CommandCache("posture", ("parse",), "shared", False,
+                 "Resolves the conditional bean graph on every run; a warm saves it the Java parse, "
+                 "which is the smaller half of its work.",
+                 "24.5 s → 19.3 s"),
+    CommandCache("endpoints", ("ris", "parse"), "none", False,
+                 "Recomputes the endpoint surface on every run and refreshes the RIS endpoint index. "
+                 "Measured: a warm buys it nothing.",
+                 "2.8 s → 2.9 s"),
+    CommandCache("spring-audit", ("ris", "parse"), "shared", False,
+                 "Recomputes every run, but over a parse a warm has already paid for.",
+                 "8.8 s → 3.7 s"),
+    CommandCache("migrate-check", ("cir",), "none", False,
+                 "Computes its own inventory and shares nothing a warm builds. Only `--blast-radius` "
+                 "reuses the shared CIR.",
+                 "4.8 s → 4.8 s"),
+    CommandCache("impact-chain", ("cir", "parse"), "shared", False,
+                 "The CIR is the expensive half — this is where a warm pays most.",
+                 "9.9 s → 1.7 s"),
+    CommandCache("impact", ("parse",), "shared", False, "", "4.9 s → 2.8 s"),
+    CommandCache("pr-impact", ("parse",), "shared", False,
+                 "Diff-dependent: the answer itself is never stored."),
+    CommandCache("verify", (), "none", False, "Runs the contracts against a fresh reading."),
+    CommandCache("verify-edit", ("parse",), "shared", True,
+                 "Built for the edit loop: the parse cache is what keeps an unchanged file out of the "
+                 "next run. Its own second run is faster again.",
+                 "14.6 s → 9.6 s → 5.6 s on repeat"),
+    CommandCache("review-pr", ("cir",), "none", False,
+                 "Diff-dependent, and it reuses the CIR only if one exists. On a small diff, loading "
+                 "the warmed CIR costs more than the work it saves.",
+                 "1.1 s → 2.3 s (slower)"),
+    CommandCache("plan", ("parse",), "shared", False, "", "9.3 s → 3.8 s"),
+    CommandCache("compare", ("parse",), "shared", False, ""),
+    CommandCache("delta", (), "none", False, "Analyses two checkouts; neither is the tree the cache describes."),
+    CommandCache("contract-diff", (), "none", False, "Analyses two checkouts."),
+    CommandCache("fix-bug", ("task",), "none", True,
+                 "Shorthand for `prepare-context fix-bug`; caches its own answer, which a warm never runs."),
+    CommandCache("rename-class", (), "none", False, ""),
+    CommandCache("prepare-context", ("task", "ris", "cir", "parse"), "answer", True,
+                 "Per task: `onboard` and `explain` are served from the RIS a warm rebuilds; "
+                 "`refactor`, `fix-bug` and `generate-tests` cache their own answer, but a warm does "
+                 "not run them, so their first call pays full price; `delta` and `review-pr` are "
+                 "diff-dependent and never cached.",
+                 "onboard 6.5 s → 0.3 s · refactor 7.7 s → 7.7 s (0.3 s on repeat) · "
+                 "generate-tests 12.4 s → 11.0 s (0.3 s on repeat)"),
+    CommandCache("onboard", ("task", "ris"), "answer", True, "Shorthand for `prepare-context onboard`.",
+                 "6.5 s → 0.3 s"),
+    CommandCache("explain", ("cir",), "shared", False, "Serves from the shared CIR a warm builds.",
+                 "9.8 s → 1.6 s"),
+    CommandCache("export", ("parse",), "shared", False, "", "8.8 s → 3.7 s"),
+    CommandCache("repo-ir", ("parse",), "shared", False, "", "5.1 s → 2.9 s"),
+    CommandCache("validation", ("parse",), "shared", False, "", "11.6 s → 6.4 s"),
+    CommandCache("modernize", ("parse",), "shared", False, "", "5.2 s → 3.0 s"),
+    CommandCache("chunk-file", (), "none", False, "Reads one file; nothing to cache."),
+    CommandCache("cold-start", ("ris",), "answer", True,
+                 "Reads the RIS a warm rebuilds — that is all it does. Without one it answers "
+                 "`no_ris` instead of a snapshot.",
+                 "0.2 s either way"),
+    CommandCache("baseline", ("parse",), "shared", False, "`capture`/`diff`/`trend` over architectural metrics.",
+                 "capture 8.7 s → 3.6 s"),
+    CommandCache("retrieve", ("cir", "parse"), "shared", False,
+                 "Every query builds or reuses the shared CIR a warm builds."),
+    CommandCache("archetype", ("parse",), "shared", False, "", "9.3 s → 5.6 s"),
+    CommandCache("activate", (), "none", False, "Not an analysis."),
+    CommandCache("auth", (), "none", False, "Not an analysis."),
+    CommandCache("cache", (), "none", False, "Operates on the caches themselves."),
+    CommandCache("config", (), "none", False, "Not an analysis."),
+    CommandCache("mcp", ("snapshot", "ris", "cir", "parse"), "shared", True,
+                 "Serves the same commands over MCP, with the same layers."),
+    CommandCache("schema", (), "none", False, "Prints registries; reads no repository."),
+    CommandCache("telemetry", (), "none", False, "Not an analysis."),
+    CommandCache("version", (), "none", False, "Not an analysis."),
+)
+
+_WARM_LABEL = {
+    "answer": "the answer",
+    "shared": "the shared work",
+    "none": "nothing",
+}
+
+
+def layer(layer_id: str) -> Layer:
+    for entry in LAYERS:
+        if entry.id == layer_id:
+            return entry
+    raise KeyError(layer_id)
+
+
+def as_dict() -> dict:
+    """The whole model as data — what `ask cache model --json` emits."""
+    return {
+        "invalidation": (
+            "Every layer keys on the exact tree state: any change to the analysed files "
+            "invalidates it, committed or not. A clean tree keys on the commit, so a repeat "
+            "run hits."
+        ),
+        "layers": [
+            {
+                "id": lyr.id,
+                "stores": lyr.stores,
+                "location": lyr.location,
+                "invalidated_by": lyr.invalidated_by,
+                "warmed_by_cache_warm": lyr.warmed,
+            }
+            for lyr in LAYERS
+        ],
+        "reference_repository": REFERENCE_REPOSITORY,
+        "commands": [
+            {
+                "command": cmd.command,
+                "reads": list(cmd.reads),
+                "warm_provides": cmd.warm,
+                "repeat_run_is_cached": cmd.repeat,
+                "note": cmd.note,
+                "measured": cmd.measured or None,
+            }
+            for cmd in COMMANDS
+        ],
+    }
+
+
+def render_markdown() -> str:
+    """The model as the tables published in the user guide."""
+    out: list[str] = []
+    out.append("| Layer | What it stores | What invalidates it | `cache warm` |")
+    out.append("|---|---|---|---|")
+    for lyr in LAYERS:
+        out.append(f"| `{lyr.id}` | {lyr.stores} | {lyr.invalidated_by} | {lyr.warmed} |")
+    out.append("")
+    out.append(f"Measured on {REFERENCE_REPOSITORY}, each command in isolation.")
+    out.append("")
+    out.append("| Command | A warm gives it | Measured (nothing cached → after a warm) | Repeat run cached | Layers | Notes |")
+    out.append("|---|---|---|---|---|---|")
+    for cmd in COMMANDS:
+        layers = ", ".join(f"`{name}`" for name in cmd.reads) or "—"
+        out.append(
+            f"| `{cmd.command}` | {_WARM_LABEL[cmd.warm]} | {cmd.measured or 'not timed'} | "
+            f"{'yes' if cmd.repeat else 'no'} | {layers} | {cmd.note or '—'} |"
+        )
+    return "\n".join(out)
+
+
+def render_text() -> str:
+    """The model as `ask cache model` prints it."""
+    lines: list[str] = []
+    lines.append("Invalidation — one rule for every layer")
+    lines.append("  Every layer keys on the exact tree state. Any change to the analysed files")
+    lines.append("  invalidates it, committed or not, tracked or not. A clean tree keys on the")
+    lines.append("  commit, so a repeat run with no edits hits.")
+    lines.append("")
+    lines.append("Layers")
+    for lyr in LAYERS:
+        lines.append(f"  {lyr.id}")
+        lines.append(f"    stores        {lyr.stores}")
+        lines.append(f"    location      {lyr.location}")
+        lines.append(f"    invalidated   {lyr.invalidated_by}")
+        lines.append(f"    cache warm    {lyr.warmed}")
+    lines.append("")
+    lines.append("What a warm gives each command")
+    lines.append(f"  Timings: {REFERENCE_REPOSITORY}, each command measured in isolation.")
+    width = max(len(c.command) for c in COMMANDS)
+    for cmd in COMMANDS:
+        repeat = "repeat cached" if cmd.repeat else "recomputes"
+        lines.append(f"  {cmd.command.ljust(width)}  {_WARM_LABEL[cmd.warm]:<16} ({repeat})")
+        if cmd.measured:
+            lines.append(f"  {' ' * width}    measured: {cmd.measured}")
+        if cmd.note:
+            lines.append(f"  {' ' * width}    {cmd.note}")
+    return "\n".join(lines)

sourcecode/chain_rules.py

@@ -274,16 +274,57 @@ def rule_matches(rule: AccessRule, method: str, path: str) -> bool:
     return any(ant_matches(pattern, path) for pattern in rule.patterns)
 
 
-def first_matching_rule(
-    rules: "list[AccessRule]", method: str, path: str
-) -> "Optional[AccessRule]":
-    """The rule Spring would apply: the first declared one that matches."""
+#: Matchers that see the DispatcherServlet path. An ant matcher matches the URL
+#: the filter chain receives — servlet path included, servlet CONTEXT path never,
+#: because the container has already stripped it. An mvc matcher matches the path
+#: relative to the servlet mapping, so the servlet path is not part of it.
+#: `requestMatchers` is either one depending on the Spring Security version and
+#: what is on the classpath — undecidable from source, so both readings are tried
+#: and the pattern is honoured if it covers the request under either.
+_SERVLET_PATH_MATCHERS = ("antMatchers", "regexMatchers", "requestMatchers")
+_SERVLET_RELATIVE_MATCHERS = ("mvcMatchers", "requestMatchers")
+
+
+def candidate_paths(rule: AccessRule, path: str, servlet_prefix: str = "") -> "tuple[str, ...]":
+    """The path(s) `rule`'s matcher compares against a mapping-relative `path`.
+
+    Without a declared servlet path the two readings coincide and this is just
+    `(path,)` — which is every repository that never set `spring.mvc.servlet.path`.
+    """
+    if not servlet_prefix or rule.is_any_request:
+        return (path,)
+    prefixed = f"{servlet_prefix.rstrip('/')}/{path.lstrip('/')}".rstrip("/") or "/"
+    out: list[str] = []
+    if rule.matcher in _SERVLET_PATH_MATCHERS:
+        out.append(prefixed)
+    if rule.matcher in _SERVLET_RELATIVE_MATCHERS or not out:
+        out.append(path)
+    return tuple(dict.fromkeys(out))
+
+
+def first_match(
+    rules: "list[AccessRule]", method: str, path: str, servlet_prefix: str = ""
+) -> "tuple[Optional[AccessRule], str]":
+    """`(rule Spring would apply, the path it matched)` — first declared wins.
+
+    The matched path is returned because with a servlet path declared it is not
+    the mapping-relative path the endpoint is keyed by, and a reader checking the
+    claim against the source line needs to see the URL the rule actually covers.
+    """
     for rule in rules:
         if rule.paths_unknown:
             # A rule whose paths could not be read may cover this request, and
             # everything after it is only reachable if it does not. Stopping here
             # is what keeps a later `permitAll` from being reported as the answer.
-            return rule
-        if rule_matches(rule, method, path):
-            return rule
-    return None
+            return rule, path
+        for candidate in candidate_paths(rule, path, servlet_prefix):
+            if rule_matches(rule, method, candidate):
+                return rule, candidate
+    return None, path
+
+
+def first_matching_rule(
+    rules: "list[AccessRule]", method: str, path: str, servlet_prefix: str = ""
+) -> "Optional[AccessRule]":
+    """The rule Spring would apply: the first declared one that matches."""
+    return first_match(rules, method, path, servlet_prefix)[0]