sourcecode 3.6.0__py3-none-any.whl → 3.7.0__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.6.0"
+__version__ = "3.7.0"

sourcecode/change_plan.py

@@ -88,7 +88,11 @@ def build_change_plan(
     resolution = blast.get("resolution", "not_found")
 
     # Unresolvable target → return a plan-shaped resolution notice (never crash).
-    if resolution in ("not_found", "ambiguous_path") or not blast.get("matched_fqns"):
+    # The set of resolutions that means "never found it" is one fact, and the CLI
+    # reads the same one to decide the exit code (C3-29).
+    from sourcecode.target_admission import is_unresolved
+
+    if is_unresolved(resolution) or not blast.get("matched_fqns"):
         return {
             "schema": CHANGE_PLAN_SCHEMA,
             "target": target,

sourcecode/cli.py

@@ -238,6 +238,64 @@ def _tier_help_block() -> str:
     return "\n".join(lines)
 
 
+#: Command groups whose subcommands `--help` names one by one. A group that is
+#: not listed here still appears — as its exact subcommand count and a pointer to
+#: its own `--help` — so nothing can go missing; `retrieve` publishes 29 parked
+#: intents, and naming them here would bury the blocks a reader acts on.
+_GROUPS_LISTED_IN_HELP = ("cache", "auth", "mcp", "telemetry", "baseline")
+
+
+def _subcommand_summary(entry: Any) -> str:
+    """The one-line description a subcommand publishes about itself."""
+    text = str(getattr(entry, "short_help", None) or getattr(entry, "help", None) or "")
+    if not text:
+        callback = getattr(entry, "callback", None)
+        text = str(getattr(callback, "__doc__", "") or "")
+    line = text.strip().splitlines()[0].strip() if text.strip() else ""
+    line = line.rstrip(".")
+    # Kept short so the block still fits an 80-column terminal, where a clipped
+    # line would hide the very fact this block exists to publish.
+    return line if len(line) <= 46 else line[:45].rstrip() + "…"
+
+
+def _group_help_block() -> str:
+    """The command groups as `--help` prints them — generated from the registered
+    groups, never typed out.
+
+    C4-1 and C4-2 replaced the hand-written catalogue at the *root*, and the same
+    omission survived one level down (C4-7): `cache model` — the per-layer answer
+    to "what does a warm buy this command" — was in no help text at all, because
+    the Cache block was three lines somebody wrote by hand and never revisited.
+    A group's subcommands are therefore read from the registry: a new one appears
+    in `--help` the moment it is registered, or the group states its own count.
+    """
+    registered = globals().get("app")
+    groups = list(getattr(registered, "registered_groups", ()) or ())
+    if not groups:
+        # Import-time call, before any group is registered. The real `--help`
+        # render refreshes this text (see `_get_command_with_preprocessing`).
+        return ""
+
+    lines = ["[bold]Command groups:[/bold]"]
+    for group in groups:
+        name = str(getattr(group, "name", "") or "")
+        subcommands = list(
+            getattr(getattr(group, "typer_instance", None), "registered_commands", ()) or ()
+        )
+        if name in _GROUPS_LISTED_IN_HELP:
+            for sub in subcommands:
+                label = f"{name} {sub.name}"
+                lines.append(f"  {label:<29}[dim]# {_subcommand_summary(sub)}[/dim]")
+        else:
+            tier = command_tier(name)
+            _tier_note = f", {tier}" if tier in ("experimental", "parked") else ""
+            lines.append(
+                f"  {name + ' <subcommand>':<29}"
+                f"[dim]# {len(subcommands)} subcommands{_tier_note} — ask {name} --help[/dim]"
+            )
+    return "\n".join(lines)
+
+
 def _build_help_text() -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -284,16 +342,7 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
 
 {_tier_help_block()}
 
-[bold]Auth commands:[/bold]
-  auth status                  [dim]# show current plan and auth state[/dim]
-  auth logout                  [dim]# remove local credentials[/dim]
-
-[bold]Cache commands:[/bold]
-  cache status                 [dim]# cache size, hit keys, last-warmed timestamp[/dim]
-  cache warm                   [dim]# pre-build structural layers + compact view
-                               #   (--agent warms the agent view too; --full,
-                               #   --env-map and raised --depth are NOT warmed)[/dim]
-  cache clear                  [dim]# clear all cached results for this repo[/dim]
+{_group_help_block()}
 
 [bold]Examples:[/bold]
   ask posture . --diff default:prod -o posture.json
@@ -305,12 +354,6 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
 
 [bold]Subcommands:[/bold]
   prepare-context TASK [PATH]  [dim]# task-specific context (onboard, delta, fix-bug, ...)[/dim]
-  mcp init                     [dim]# setup MCP integration (Claude Desktop, Cursor)[/dim]
-  mcp status                   [dim]# show MCP integration status[/dim]
-  mcp remove                   [dim]# remove MCP integration safely[/dim]
-  mcp serve                    [dim]# start MCP server for AI agent integration[/dim]
-  telemetry status|enable|disable
-  version
 """
 
     if not _is_pro:
@@ -674,6 +717,53 @@ def _notice(message: str) -> None:
         typer.echo(message, err=True)
 
 
+def _apply_budget(
+    data: dict,
+    budget_bytes: int,
+    *,
+    label: str,
+    output_path: "Optional[Path]",
+) -> dict:
+    """Apply the payload budget — the one seam every command goes through.
+
+    The budget exists because an agent's context window is finite, so it is a
+    constraint on **stdout** and on nothing else. When `--output FILE` is given
+    the payload does not pass through a context window at all, and cutting it
+    there breaks the contract twice over: the answer is silently sampled, and
+    the note explaining the cut advises `--output` — the flag already in use
+    (C3-17). Two of the six call sites had the rule and four did not, which is
+    the shape this seam removes: one place decides, every command inherits it.
+    """
+    from sourcecode.output_budget import trim_to_budget as _trim
+
+    to_file = output_path is not None
+    return _trim(
+        data, budget_bytes, label=label, skip=to_file, warn_stderr=not to_file
+    )
+
+
+def _prepare_context_budget(task: str) -> int:
+    """The stdout budget for a `prepare-context` task — one table, two readers.
+
+    The fresh path and the cache-hit path both budget the payload, and a second
+    copy of this mapping beside the first is exactly how the two drift apart.
+    """
+    from sourcecode.output_budget import (
+        BUDGET_DELTA, BUDGET_EXPLAIN, BUDGET_FIX_BUG,
+        BUDGET_ONBOARD, BUDGET_REFACTOR, BUDGET_REVIEW_PR,
+    )
+
+    return {
+        "fix-bug":         BUDGET_FIX_BUG,
+        "review-pr":       BUDGET_REVIEW_PR,
+        "onboard":         BUDGET_ONBOARD,
+        "explain":         BUDGET_EXPLAIN,
+        "refactor":        BUDGET_REFACTOR,
+        "delta":           BUDGET_DELTA,
+        "generate-tests":  BUDGET_EXPLAIN,
+    }.get(task, BUDGET_EXPLAIN)
+
+
 def _admit_path(
     raw: "Path | str",
     *,
@@ -713,6 +803,21 @@ def _admit_path(
     raise typer.Exit(code=exit_code)
 
 
+def _exit_on_unresolved_target(resolution: "Optional[str]") -> None:
+    """Close the run on a target the analysis never resolved — one exit code.
+
+    The payload has already been emitted and it is truthful: it names the
+    resolution and lists nothing. What was inconsistent is the code a pipeline
+    reads — `impact` said 1, `plan` said 0 over the same fact (C3-29) — so the
+    decision belongs to `target_admission`, not to each command.
+    """
+    from sourcecode.target_admission import exit_code_for
+
+    code = exit_code_for(resolution)
+    if code:
+        raise typer.Exit(code=code)
+
+
 def _misread_path_note(symbol: str, analysed_root: "Path", usage: str) -> "Optional[str]":
     """State the repository actually analysed when the symbol argument holds a path.
 
@@ -1518,7 +1623,11 @@ def main(
     full: bool = typer.Option(
         False,
         "--full",
-        help="Remove truncation limits on transactional_boundaries, mybatis.dto_mappers, and other capped lists.",
+        help=(
+            "Raise the display caps: transactional_boundaries and mybatis.dto_mappers "
+            "are listed in full, file_relevance rises to 40 entries. Other caps stay, "
+            "and each says what it cut; --output FILE skips the payload budget entirely."
+        ),
     ),
     trace_pipeline: bool = typer.Option(
         False,
@@ -2146,17 +2255,15 @@ def main(
                                 _rebuilt = _red_l1(_rebuilt)
                             # Apply output budget
                             if agent:
-                                from sourcecode.output_budget import (
-                                    trim_to_budget as _trim_l1,
-                                    BUDGET_AGENT,
+                                from sourcecode.output_budget import BUDGET_AGENT
+                                _rebuilt = _apply_budget(
+                                    _rebuilt, BUDGET_AGENT, label="agent", output_path=output
                                 )
-                                _rebuilt = _trim_l1(_rebuilt, BUDGET_AGENT, label="agent")
                             elif compact:
-                                from sourcecode.output_budget import (
-                                    trim_to_budget as _trim_l1c,
-                                    BUDGET_COMPACT,
+                                from sourcecode.output_budget import BUDGET_COMPACT
+                                _rebuilt = _apply_budget(
+                                    _rebuilt, BUDGET_COMPACT, label="compact", output_path=output
                                 )
-                                _rebuilt = _trim_l1c(_rebuilt, BUDGET_COMPACT, label="compact")
                             # Serialize
                             _cache_hit_content = _serialize_dict(_rebuilt, format)
                             # Cache rebuilt view in L2 (skip for --changed-only: stale diff)
@@ -2315,11 +2422,12 @@ def main(
         # IMP-2: warn if the exclude value looks like it was swallowed as a path
         # (BUG-2 symptom in older versions: --exclude value consumed as repo path).
         if len(_extra_excludes) == 1 and Path(list(_extra_excludes)[0]).is_dir():
-            sys.stderr.write(
+            # C3-34: same rule as every other advisory — the run succeeds, so
+            # this speaks to a person at a terminal and never to a pipe.
+            _notice(
                 f"[sourcecode] Warning: --exclude value '{list(_extra_excludes)[0]}' is a directory path. "
-                "If this was meant as a pattern, use --exclude=pattern or --exclude pattern (both are supported).\n"
+                "If this was meant as a pattern, use --exclude=pattern or --exclude pattern (both are supported)."
             )
-            sys.stderr.flush()
 
     _progress = Progress()
     _progress.start("scanning files")
@@ -3065,8 +3173,8 @@ def main(
             data = redact_dict(data)
         # P0-1: Apply output budget — safety net for large repos.
         # Skip budget when writing to a file (no size constraint); warn on stdout.
-        from sourcecode.output_budget import trim_to_budget as _trim, BUDGET_AGENT
-        data = _trim(data, BUDGET_AGENT, label="agent", skip=(output is not None), warn_stderr=(output is None))
+        from sourcecode.output_budget import BUDGET_AGENT
+        data = _apply_budget(data, BUDGET_AGENT, label="agent", output_path=output)
         # FIX-P0-2: agent mode must honour --format yaml (previously always emitted JSON).
         content = _serialize_dict(data, format)
     elif compact:
@@ -3087,8 +3195,8 @@ def main(
             data = redact_dict(data)
         # P0-1: Apply output budget — safety net for large repos.
         # Skip budget when writing to a file (no size constraint); warn on stdout.
-        from sourcecode.output_budget import trim_to_budget as _trim_c, BUDGET_COMPACT
-        data = _trim_c(data, BUDGET_COMPACT, label="compact", skip=(output is not None), warn_stderr=(output is None))
+        from sourcecode.output_budget import BUDGET_COMPACT
+        data = _apply_budget(data, BUDGET_COMPACT, label="compact", output_path=output)
         content = _serialize_dict(data, format)
     else:
         raw_dict = standard_view(sm, include_tree=tree and not no_tree)
@@ -3605,6 +3713,22 @@ def prepare_context_cmd(
             _pctx_cache_key = f"pctx-{task}-{_pctx_git_sha}-{_sym_h}-{format or 'json'}"
             _cached_pctx = _pctx_cache.read(target, _pctx_cache_key)
             if _cached_pctx is not None:
+                # Cached documents are stored pre-budget: a hit that reused the
+                # previous run's trimming would send a stdout-sized answer to a
+                # file, which is the defect the budget seam exists to stop (C3-17).
+                try:
+                    _cached_pctx = json.dumps(
+                        _apply_budget(
+                            json.loads(_cached_pctx),
+                            _prepare_context_budget(task),
+                            label=task,
+                            output_path=output_path,
+                        ),
+                        indent=2,
+                        ensure_ascii=False,
+                    )
+                except Exception:
+                    pass  # not JSON (or unreadable) → serve exactly what was stored
                 _emit_command_output(_cached_pctx, output_path, copy)
                 try:
                     from sourcecode import telemetry as _tel
@@ -3958,22 +4082,7 @@ def prepare_context_cmd(
         out["skipped_analyzers"] = _skipped
 
     # P0-1: Apply output budget per task — safety net for large repos.
-    from sourcecode.output_budget import (
-        trim_to_budget as _pc_trim,
-        BUDGET_FIX_BUG, BUDGET_REVIEW_PR, BUDGET_ONBOARD,
-        BUDGET_EXPLAIN, BUDGET_REFACTOR, BUDGET_DELTA,
-    )
-    _pc_budgets: dict[str, int] = {
-        "fix-bug":         BUDGET_FIX_BUG,
-        "review-pr":       BUDGET_REVIEW_PR,
-        "onboard":         BUDGET_ONBOARD,
-        "explain":         BUDGET_EXPLAIN,
-        "refactor":        BUDGET_REFACTOR,
-        "delta":           BUDGET_DELTA,
-        "generate-tests":  BUDGET_EXPLAIN,
-    }
-    _pc_budget = _pc_budgets.get(task, BUDGET_EXPLAIN)
-    out = _pc_trim(out, _pc_budget, label=task)
+    _pc_budget = _prepare_context_budget(task)
 
     # Size-gated preview: on enterprise-scale monoliths free users get a capped
     # preview (top-5 / lightweight) + upgrade note. Small/mid repos get the full
@@ -4002,6 +4111,13 @@ def prepare_context_cmd(
                     "complete execution paths, and CI-grade risk scoring."
                 )
 
+    # The cache stores the analysis, never the rendering. The budget depends on
+    # where this particular run sends its payload (C3-17), so caching the trimmed
+    # document would serve a stdout-sized answer to the next `--output FILE` run —
+    # the defect surviving one layer down. Written pre-budget, budgeted per run.
+    _pc_cacheable_content = json.dumps(out, indent=2, ensure_ascii=False)
+    out = _apply_budget(out, _pc_budget, label=task, output_path=output_path)
+
     if format == "github-comment" and task == "review-pr":
         from sourcecode.pr_comment_renderer import render_github_comment
         _pc_content = render_github_comment(out)
@@ -4010,7 +4126,7 @@ def prepare_context_cmd(
 
     if _pctx_cacheable and _pctx_cache_key and format != "github-comment":
         try:
-            _pctx_cache.write(target, _pctx_cache_key, _pc_content)
+            _pctx_cache.write(target, _pctx_cache_key, _pc_cacheable_content)
         except Exception:
             pass
 
@@ -4330,17 +4446,17 @@ def repo_ir_cmd(
             )
             raise typer.Exit(1)
         if _ir_tokens_est > 10_000:
-            if summary_only:
-                sys.stderr.write(
-                    f"[repo-ir] ~{_ir_tokens_est // 1000}K tokens — "
-                    "use --max-nodes N --max-edges N or --output FILE for smaller output.\n"
-                )
-            else:
-                sys.stderr.write(
-                    f"[repo-ir] ~{_ir_tokens_est // 1000}K tokens — "
-                    "use --summary-only or --output FILE for smaller output.\n"
-                )
-            sys.stderr.flush()
+            # C3-34: the run succeeded and the IR is on stdout, so this advisory
+            # is a note to a person — on a pipe it is noise, and on PowerShell
+            # 5.1 it turns a successful `ask repo-ir --force > ir.json` into a
+            # NativeCommandError. Terminal-gated like every other notice.
+            _smaller = (
+                "--max-nodes N --max-edges N" if summary_only else "--summary-only"
+            )
+            _notice(
+                f"[repo-ir] ~{_ir_tokens_est // 1000}K tokens — "
+                f"use {_smaller} or --output FILE for smaller output."
+            )
         _emit_command_output(output, None, copy)
 
 
@@ -4428,7 +4544,7 @@ def impact_cmd(
     from sourcecode.repository_ir import (
         build_repo_ir, find_java_files, compute_blast_radius,
     )
-    from sourcecode.output_budget import trim_to_budget as _trim, BUDGET_IMPACT
+    from sourcecode.output_budget import BUDGET_IMPACT
 
     # Legacy-compat: old syntax was `impact <path> <target>`.
     # Detect: target resolves to an existing directory (not a class name), and
@@ -4495,7 +4611,7 @@ def impact_cmd(
     result = compute_blast_radius(
         ir, target, max_depth=depth, list_limit=0 if _to_file else None
     )
-    result = _trim(result, BUDGET_IMPACT, label="impact", skip=_to_file)
+    result = _apply_budget(result, BUDGET_IMPACT, label="impact", output_path=output_path)
     if _misread and result.get("resolution") == "not_found":
         result["analysis_warnings"] = [*(result.get("analysis_warnings") or []), _misread]
 
@@ -4503,8 +4619,7 @@ def impact_cmd(
     _emit_command_output(output, output_path, copy,
                          success_msg=f"Impact analysis written to {output_path}")
 
-    if result.get("resolution") == "not_found":
-        raise typer.Exit(code=1)
+    _exit_on_unresolved_target(result.get("resolution"))
 
     from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
     _nudge()
@@ -5545,9 +5660,6 @@ def plan_cmd(
     data = build_change_plan(_cir, target, max_depth=depth)
     _prog.finish()
 
-    if data.get("resolution") in ("not_found", "ambiguous_path"):
-        typer.echo(f"Note: {data.get('message', 'target not resolved')}", err=True)
-
     output = _serialize_dict(data, format)
     _emit_command_output(
         output, output_path, copy,
@@ -5559,6 +5671,12 @@ def plan_cmd(
         ),
     )
 
+    # C3-29: the payload already names the resolution and lists nothing; the
+    # `Note:` on stderr that used to stand here said the same thing a second
+    # time on a run that exited 0, so a gate reading the exit code was told the
+    # plan succeeded. The exit code now carries it, and stderr stays clean.
+    _exit_on_unresolved_target(data.get("resolution"))
+
 
 # ── D4 Candidate Comparison ───────────────────────────────────────────────────
 
@@ -6069,6 +6187,15 @@ def spring_audit_cmd(
         "--ci/--no-ci",
         help="Exit with code 1 if any findings at or above --min-severity are found. For CI/CD gates.",
     ),
+    compact: bool = typer.Option(
+        False,
+        "--compact",
+        help=(
+            "Bounded summary: caps `findings` and the per-endpoint security projection "
+            "to their top 5, most-severe first. Every count is still measured over the "
+            "whole population. The full report can exceed 1 MB on a monolith."
+        ),
+    ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
         help=_NO_CACHE_SUBCOMMAND_HELP,
@@ -6104,6 +6231,7 @@ def spring_audit_cmd(
       ask spring-audit /path/to/repo
       ask spring-audit . --scope security
       ask spring-audit . --min-severity high
+      ask spring-audit . --compact
       ask spring-audit . --output audit.json
     """
     import json as _json
@@ -6182,7 +6310,7 @@ def spring_audit_cmd(
     except Exception:
         pass
 
-    data = combined.to_dict()
+    data = combined.to_compact_dict() if compact else combined.to_dict()
 
     # Non-fatal RIS side-effect — persist summary only (not full findings).
     try:
@@ -7100,8 +7228,7 @@ def impact_chain_cmd(
         ),
     )
 
-    if result.resolution == "not_found":
-        raise typer.Exit(code=1)
+    _exit_on_unresolved_target(result.resolution)
 
 
 # ── PR Impact Report ──────────────────────────────────────────────────────────
@@ -7418,8 +7545,11 @@ def explain_cmd(
     _emit_command_output(output, output_path, copy,
                          success_msg=f"Explanation written to {output_path}")
 
-    if not explanation.found:
-        raise typer.Exit(code=1)
+    # `explain` reports a flag where the others report a resolution; it maps onto
+    # the same vocabulary rather than deriving its own code beside the authority.
+    from sourcecode.target_admission import resolution_for_found_flag
+
+    _exit_on_unresolved_target(resolution_for_found_flag(explanation.found))
 
 
 # ── Enterprise Workflow Commands ──────────────────────────────────────────────
@@ -7722,7 +7852,7 @@ def modernize_cmd(
     """
     import json as _json
     from sourcecode.repository_ir import build_repo_ir, find_java_files, apply_ir_size_limits
-    from sourcecode.output_budget import trim_to_budget, BUDGET_ONBOARD
+    from sourcecode.output_budget import BUDGET_ONBOARD
     from sourcecode.license import is_pro as _mod_is_pro, is_large_repo as _mod_large
 
     root = _admit_path(path)
@@ -8027,7 +8157,7 @@ def modernize_cmd(
             ),
         }
 
-    result = trim_to_budget(result, BUDGET_ONBOARD, label="modernize")
+    result = _apply_budget(result, BUDGET_ONBOARD, label="modernize", output_path=output_path)
     output = _json.dumps(result, indent=2, ensure_ascii=False)
 
     if output_path:
@@ -9570,7 +9700,7 @@ def _warm_shared_cir(target: Path):
         return None
 
 
-@cache_app.command("warm")
+@cache_app.command("warm", short_help="Pre-build the cache: structural layers + compact view")
 def cache_warm_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path to warm (default: current directory)"),
     compact: bool = typer.Option(True, "--compact/--no-compact", help="Warm compact view (default: on)."),
@@ -9662,7 +9792,7 @@ def cache_warm_cmd(
     )
 
 
-@cache_app.command("model")
+@cache_app.command("model", short_help="What a warm buys each command, per cache layer")
 def cache_model_cmd(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
     markdown: bool = typer.Option(False, "--markdown", help="Output the tables published in the user guide."),
@@ -9690,7 +9820,7 @@ def cache_model_cmd(
         typer.echo(_cmodel.render_text())
 
 
-@cache_app.command("freshness")
+@cache_app.command("freshness", short_help="RIS freshness relative to the current git HEAD")
 def cache_freshness_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
     json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
@@ -9772,7 +9902,7 @@ def cache_freshness_cmd(
         typer.echo(f"RIS updated:  {result.get('ris_last_updated_at') or 'never'}")
 
 
-@cache_app.command("context-stats")
+@cache_app.command("context-stats", short_help="AI context cache: size and reuse metrics")
 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."),
@@ -9804,7 +9934,7 @@ def cache_context_stats_cmd(
         typer.echo(f"KL version:    {stats['kl_schema_version']}  producer={stats['producer_version']}")
 
 
-@cache_app.command("context-clear")
+@cache_app.command("context-clear", short_help="Delete the AI context cache for a repository")
 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."),
@@ -9929,6 +10059,11 @@ def main_entry() -> None:
     routing for tokens like 'version' or 'config').
     """
     _force_utf8_streams()
+    # A reader that stops reading is not a failed run (C3-28). Installed after
+    # the UTF-8 reconfiguration so the wrapper keeps that stream, and before any
+    # command writes a byte.
+    from sourcecode.pipe_contract import install as _install_pipe_contract
+    _install_pipe_contract()
     # Deprecation notice when invoked through the legacy `sourcecode` alias.
     # One line, and only on an interactive terminal — pipes/agents that still call
     # `sourcecode` keep clean stderr (error envelopes are JSON on stderr), so the

sourcecode/compare.py

@@ -34,9 +34,11 @@ if TYPE_CHECKING:
 COMPARE_SCHEMA: str = "candidate-comparison-v1"
 
 # Resolutions on which D3's build_change_plan returns a bare resolution notice
-# (no affected set). Mirror that exact bail condition so "resolved" here means
-# "build_change_plan actually produced a plan for this target".
-_UNRESOLVED: frozenset[str] = frozenset({"not_found", "ambiguous_path"})
+# (no affected set), so "resolved" here means "build_change_plan actually
+# produced a plan for this target". Read from the authority rather than
+# restated: this set had been written out three times, and the copy in the CLI
+# is what let `plan` and `impact` disagree about the same fact (C3-29).
+from sourcecode.target_admission import UNRESOLVED_RESOLUTIONS as _UNRESOLVED
 
 
 def _measured_count(blast: dict, stat_key: str, list_key: str) -> tuple[int, bool]:

sourcecode/explain.py

@@ -206,7 +206,18 @@ def _resolve_fqn(class_name: str, cir: "CanonicalRepositoryIR") -> tuple[str, li
 
     Returns (best_fqn, all_matches).
     best_fqn is empty string when no match found.
+
+    A target that names a *file* is resolved by that file first (C3-35): the
+    path is the more specific input, and this resolver used to answer
+    `not_found` for it because no CIR symbol is ever spelled as a path.
     """
+    from sourcecode.target_admission import fqns_declared_in_file, is_path_like
+
+    if is_path_like(class_name):
+        by_file = sorted(fqns_declared_in_file(class_name, _get_raw_nodes(cir)))
+        if by_file:
+            return by_file[0], by_file
+
     suffix_dot = f".{class_name}"
     suffix_hash = f"{class_name}#"
     matches: list[str] = []

sourcecode/output_budget.py

@@ -253,8 +253,13 @@ def trim_to_budget(
             )
             if label:
                 _warn_line = f"[{label}] {_warn_line}"
-            sys.stderr.write(_warn_line)
-            sys.stderr.flush()
+            # C3-26/C3-34: the run succeeded and the payload is on stdout, so
+            # this line speaks to a person at a terminal. On a pipe it is noise
+            # that PowerShell 5.1 turns into a NativeCommandError — and the fact
+            # itself is already in the payload, under `_truncation_summary`.
+            if sys.stderr.isatty():
+                sys.stderr.write(_warn_line)
+                sys.stderr.flush()
 
     return result