sourcecode 1.7.0__tar.gz → 1.9.0__tar.gz

{sourcecode-1.7.0 → sourcecode-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.7.0
+Version: 1.9.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004

{sourcecode-1.7.0 → sourcecode-1.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.7.0"
+version = "1.9.0"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.7.0 → sourcecode-1.9.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.7.0"
+__version__ = "1.9.0"

{sourcecode-1.7.0 → sourcecode-1.9.0}/src/sourcecode/cli.py

@@ -354,32 +354,29 @@ def main(
         "json",
         "--format",
         "-f",
-        help="Output format: json (default) or yaml. Both carry identical data — yaml is more human-readable, json is preferred for agent pipelines.",
+        help="Output format: json (default) or yaml.",
         show_default=True,
     ),
     output: Optional[Path] = typer.Option(
         None,
         "--output",
         "-o",
-        help="Write output to a file instead of stdout. Useful for storing analysis snapshots or piping to downstream tools.",
+        help="Write output to a file instead of stdout.",
     ),
     compact: bool = typer.Option(
         False,
         "--compact",
         help=(
-            "Compact output (~600–800 tokens): project type, stacks, production entry points, "
-            "dependency summary, confidence summary, and analysis gaps. "
-            "Omits file tree, raw dependency lists, docs, and module graph. "
-            "Designed for agent context windows. Automatically enables --dependencies, --env-map, and --code-notes."
+            "High-signal summary (~600–800 tokens): stacks, entry points, "
+            "dependency summary, confidence, and gaps. "
+            "Optimized for agent context windows."
         ),
     ),
     dependencies: bool = typer.Option(
         False,
         "--dependencies",
-        help=(
-            "Analyze direct and transitive dependencies. Reads manifests (pyproject.toml, package.json, go.mod, etc.) "
-            "and lockfiles when available. Adds dependency_summary and key_dependencies to output."
-        ),
+        hidden=True,
+        help="Analyze direct dependencies from manifests and lockfiles.",
     ),
     graph_modules: bool = typer.Option(
         False,
@@ -422,10 +419,7 @@ def main(
     no_redact: bool = typer.Option(
         False,
         "--no-redact",
-        help=(
-            "Disable automatic secret redaction. By default, potential secrets (API keys, tokens, passwords) "
-            "are replaced with [REDACTED]. Use with caution — output may contain sensitive values."
-        ),
+        help="Disable secret redaction. Use with caution — output may contain sensitive values.",
     ),
     version: Optional[bool] = typer.Option(
         None,
@@ -438,10 +432,7 @@ def main(
     depth: int = typer.Option(
         4,
         "--depth",
-        help=(
-            "Maximum depth for file tree traversal (default: 4, range: 1–20). "
-            "Increase for deeply nested projects — Maven/Java requires at least 8 (src/main/java/...)."
-        ),
+        help="File tree traversal depth (default: 4). Java/Maven projects auto-adjust to 12.",
         min=1,
         max=20,
     ),
@@ -480,72 +471,58 @@ def main(
         False,
         "--git-context",
         "-g",
-        help="Include git activity: recent commits, change hotspots (most frequently modified files), pending uncommitted changes, and contributors. Adds git_context to output.",
+        help="Include git activity: recent commits, change hotspots, and uncommitted changes.",
     ),
     git_depth: int = typer.Option(
         20,
         "--git-depth",
-        help="Number of recent commits to include with --git-context (default: 20, max: 100).",
+        hidden=True,
+        help="Number of recent commits to include with --git-context (default: 20).",
         min=1,
         max=100,
     ),
     git_days: int = typer.Option(
         90,
         "--git-days",
-        help="Time window in days for detecting change hotspots with --git-context (default: 90). Hotspots are files with the most commits in this window.",
+        hidden=True,
+        help="Time window in days for change hotspot detection (default: 90).",
         min=1,
         max=3650,
     ),
     env_map: bool = typer.Option(
         False,
         "--env-map",
-        help="Map environment variables: keys, types (string/int/bool/url/path), categories (database/auth/service/...), and which files reference them. Adds env_map and env_summary.",
+        hidden=True,
+        help="Map environment variables referenced across the codebase.",
     ),
     code_notes: bool = typer.Option(
         False,
         "--code-notes",
-        help=(
-            "Extract inline annotations: TODO, FIXME, HACK, NOTE, DEPRECATED, WARNING, BUG, XXX, OPTIMIZE — "
-            "with file location and enclosing symbol. "
-            "Also detects Architecture Decision Records (ADRs) in docs/decisions/, docs/adr/, and similar paths."
-        ),
+        hidden=True,
+        help="Extract inline annotations: TODO, FIXME, HACK, DEPRECATED, ADRs.",
     ),
     agent: bool = typer.Option(
         False,
         "--agent",
-        help=(
-            "Agent-optimized output: structured, noise-free JSON for AI consumption. "
-            "Automatically enables --dependencies, --env-map, and --code-notes. Suppresses file tree. "
-            "Output includes: identity, entry points, architecture, runtime dependencies, "
-            "operational signals, confidence summary, and analysis gaps. No empty sections."
-        ),
+        help="Structured noise-free JSON for AI agents: identity, entry points, dependencies, confidence, gaps.",
     ),
     trace_pipeline: bool = typer.Option(
         False,
         "--trace-pipeline",
-        help=(
-            "Diagnostic mode: include pipeline_trace in output showing every candidate, filter decision, "
-            "and data origin across all pipeline stages. "
-            "Use to diagnose unexpected or contaminated results. Not intended for normal agent use."
-        ),
+        hidden=True,
+        help="Diagnostic: include full pipeline trace in output.",
     ),
     mode: str = typer.Option(
         "contract",
         "--mode",
-        help=(
-            "Output mode: contract (default) | standard | raw. "
-            "contract: minimal per-file contracts — exports, signatures, deps. "
-            "Smallest output, recommended for AI agents. "
-            "minimal is accepted as an alias for contract. "
-            "standard: full per-file detail with imports, relevance scores, extraction method. "
-            "raw: project-level analysis only (stacks, entry points, dependency summary). "
-            "No per-file contracts."
-        ),
+        hidden=True,
+        help="Output mode: contract (default) | standard | raw.",
     ),
     max_symbols: Optional[int] = typer.Option(
         None,
         "--max-symbols",
-        help="Limit total exported semantic nodes across all file contracts. Trims lowest-ranked files first.",
+        hidden=True,
+        help="Limit total exported semantic nodes across all file contracts.",
         min=1,
     ),
     dependency_depth: int = typer.Option(
@@ -559,22 +536,25 @@ def main(
     entrypoints_only: bool = typer.Option(
         False,
         "--entrypoints-only",
-        help="Contract mode: include only files that are runtime entrypoints or have exported symbols (public API surface). Note: 'entrypoints' here includes all files with exports, not strictly detected runtime entry points.",
+        hidden=True,
+        help="Include only files with exported symbols or runtime entrypoints.",
     ),
     changed_only: bool = typer.Option(
         False,
         "--changed-only",
-        help="Contract mode: include only git-modified files (staged, unstaged, untracked).",
+        help="Limit output to git-modified files (staged, unstaged, untracked).",
     ),
     rank_by: str = typer.Option(
         "relevance",
         "--rank-by",
+        hidden=True,
         help="Contract ranking strategy: relevance (default) | centrality | git-churn.",
     ),
     emit_graph: bool = typer.Option(
         False,
         "--emit-graph",
-        help="Contract mode: include a compact dependency graph (nodes + edges) in output.",
+        hidden=True,
+        help="Include a compact dependency graph in contract output.",
     ),
     compress_types: bool = typer.Option(
         False,
@@ -585,16 +565,13 @@ def main(
     symbol: Optional[str] = typer.Option(
         None,
         "--symbol",
-        help="Contract mode: extract localized context for a specific symbol name. Returns defining file + all importers.",
+        help="Extract context for a specific symbol: defining file + all importers.",
     ),
     max_importers: int = typer.Option(
         50,
         "--max-importers",
-        help=(
-            "Maximum importer files returned by --symbol (default: 50). "
-            "Popular symbols can have hundreds of importers — this prevents output explosion. "
-            "Defining files are never truncated. Override: --symbol Foo --max-importers 200."
-        ),
+        hidden=True,
+        help="Maximum importer files returned by --symbol (default: 50).",
         min=1,
         max=10000,
     ),
@@ -789,22 +766,9 @@ def main(
         env_map = True
         code_notes = True
         no_tree = True  # agents never need the raw file tree
-        typer.echo("[agent] dependencies env-map code-notes (no-tree)", err=True)
-        # Warn about flags that are computed but excluded from agent_view output
-        _agent_suppressed: list[str] = []
-        if full_metrics:
-            _agent_suppressed.append("--full-metrics")
-        if graph_modules:
-            _agent_suppressed.append("--graph-modules")
-        if docs:
-            _agent_suppressed.append("--docs")
-        if _agent_suppressed:
-            typer.echo(
-                f"[agent] warning: {', '.join(_agent_suppressed)} computed but excluded "
-                "from --agent output — agent_view does not include these sections. "
-                "Remove these flags to skip unnecessary computation.",
-                err=True,
-            )
+
+    _progress = Progress()
+    _progress.start("scanning files")
 
     scanner = AdaptiveScanner(target, topology=_topology, base_depth=effective_depth)
     raw_tree = scanner.scan_tree()
@@ -842,6 +806,7 @@ def main(
                 node = child
         return pruned
 
+    _progress.update("parsing manifests")
     file_tree = filter_sensitive_files(raw_tree)
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
@@ -1310,6 +1275,7 @@ def main(
 
     # Git Context (--git-context flag)
     if git_context:
+        _progress.update("git analysis")
         from sourcecode.git_analyzer import GitAnalyzer
         sm.git_context = GitAnalyzer().analyze(target, depth=git_depth, days=git_days)
 
@@ -1417,6 +1383,7 @@ def main(
             changed_only = False
 
     # Contract pipeline — runs for mode=contract|standard|deep|hybrid (skip for raw)
+    _progress.update("extracting contracts")
     _is_contract_mode = mode in ("contract", "standard")
     _pipeline_error = False
     if _is_contract_mode:
@@ -1487,6 +1454,7 @@ def main(
                 )
 
     # 4. Serialize
+    _progress.update("serializing output")
     if _is_contract_mode and not agent:
         from sourcecode.serializer import contract_view as _contract_view
         _depth = _CONTRACT_DEPTH.get(mode, "minimal")
@@ -1517,7 +1485,17 @@ def main(
         if _is_contract_mode and sm.file_contracts:
             from sourcecode.serializer import _serialize_contract_minimal
             data.pop("file_relevance", None)
-            data["contracts"] = [_serialize_contract_minimal(c) for c in sm.file_contracts]
+            _MAX_AGENT_CONTRACTS = 10
+            _all_contracts = sm.file_contracts
+            _sorted = sorted(_all_contracts, key=lambda c: getattr(c, "relevance_score", 0.0), reverse=True)
+            _sampled = _sorted[:_MAX_AGENT_CONTRACTS]
+            _total_contracts = len(_all_contracts)
+            data["contracts"] = [_serialize_contract_minimal(c) for c in _sampled]
+            data["contracts_meta"] = {
+                "total": _total_contracts,
+                "shown": len(_sampled),
+                "truncated": _total_contracts > _MAX_AGENT_CONTRACTS,
+            }
             if sm.contract_summary is not None:
                 cs = sm.contract_summary
                 data["contract_summary"] = {
@@ -1578,6 +1556,7 @@ def main(
         pass
 
     # 6. Write output (CLI-04)
+    _progress.finish()
     write_output(content, output=output)
 
     if _pipeline_error:

{sourcecode-1.7.0 → sourcecode-1.9.0}/src/sourcecode/serializer.py

@@ -958,7 +958,13 @@ def agent_view(sm: SourceMap) -> dict[str, Any]:
             "sections": _section_confidence(sm),
         }
         if cs.hard_signals:
-            conf["hard_signals"] = cs.hard_signals
+            _MAX_HARD_SIGNALS = 20
+            _hs = cs.hard_signals
+            _hs_total = len(_hs)
+            conf["hard_signals"] = _hs[:_MAX_HARD_SIGNALS]
+            if _hs_total > _MAX_HARD_SIGNALS:
+                conf["hard_signals_truncated"] = True
+                conf["hard_signals_total"] = _hs_total
         if cs.soft_signals:
             conf["soft_signals"] = cs.soft_signals
         if cs.ignored_signals:

{sourcecode-1.7.0 → sourcecode-1.9.0}/tests/test_cli.py

@@ -42,18 +42,23 @@ def test_telemetry_status():
     assert "Telemetry" in result.output
 
 
-def test_help_contains_all_flags():
+def test_help_contains_core_flags():
     result = invoke(["--help"])
     assert result.exit_code == 0
+    # Core visible flags
     assert "--format" in result.output
     assert "--output" in result.output
     assert "--compact" in result.output
-    assert "--dependencies" in result.output
-    assert "--graph-modules" in result.output
-    assert "--graph-detail" in result.output
-    assert "--max-nodes" in result.output
-    assert "--graph-edges" in result.output
+    assert "--git-context" in result.output
+    assert "--agent" in result.output
+    assert "--changed-only" in result.output
+    assert "--symbol" in result.output
     assert "--no-redact" in result.output
+    # Hidden flags must not appear in default help
+    assert "--dependencies" not in result.output
+    assert "--graph-modules" not in result.output
+    assert "--semantics" not in result.output
+    assert "--architecture" not in result.output
 
 
 def test_no_args_runs_without_exception(tmp_project: Path):