sourcecode 0.36.0__tar.gz → 0.37.0__tar.gz

{sourcecode-0.36.0 → sourcecode-0.37.0}/PKG-INFO

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

{sourcecode-0.36.0 → sourcecode-0.37.0}/pyproject.toml

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

{sourcecode-0.36.0 → sourcecode-0.37.0}/src/sourcecode/__init__.py

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

{sourcecode-0.36.0 → sourcecode-0.37.0}/src/sourcecode/cli.py

@@ -384,7 +384,8 @@ def main(
     no_tree: bool = typer.Option(
         False,
         "--no-tree",
-        help="(Deprecated) Previously suppressed file_tree. The file tree is excluded by default — this flag is now a no-op. Use --tree to include the file tree.",
+        hidden=True,
+        help="(Removed) No-op. File tree is excluded by default. Use --tree to include it.",
     ),
     tree: bool = typer.Option(
         False,
@@ -516,13 +517,13 @@ def main(
         "contract",
         "--mode",
         help=(
-            "Output mode: contract|minimal (default) | standard | deep | hybrid | raw. "
-            "contract/minimal: minimal per-file contracts — exports, signatures, deps. Smallest output. "
+            "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. "
-            "deep: standard + optional analysis sections (deps, env, git). "
-            "hybrid: contracts + compact bodies for top-ranked files. "
-            "raw: legacy project-level analysis (stacks, entry points, dependencies). "
-            "contract/minimal is the recommended default for AI coding agents."
+            "raw: project-level analysis only (stacks, entry points, dependency summary). "
+            "No per-file contracts."
         ),
     ),
     max_symbols: Optional[int] = typer.Option(
@@ -534,7 +535,8 @@ def main(
     dependency_depth: int = typer.Option(
         0,
         "--dependency-depth",
-        help="Transitive import traversal depth for contract mode (0 = direct only, N = follow N levels).",
+        hidden=True,
+        help="(Removed) Transitive resolution is not implemented. Pass 0 or omit.",
         min=0,
         max=5,
     ),
@@ -561,7 +563,8 @@ def main(
     compress_types: bool = typer.Option(
         False,
         "--compress-types",
-        help="Contract mode: abbreviate verbose type signatures (React.FC → FC, Promise<X> stays).",
+        hidden=True,
+        help="(Removed) No observable effect when type signatures are not extracted. Omit.",
     ),
     symbol: Optional[str] = typer.Option(
         None,
@@ -589,8 +592,20 @@ def main(
     _t0 = time.monotonic()
 
     # Validate new flag choices
-    _MODE_CHOICES = ("contract", "minimal", "standard", "deep", "hybrid", "raw")
-    if mode not in _MODE_CHOICES:
+    _MODE_CHOICES = ("contract", "minimal", "standard", "raw")
+    _DEPRECATED_MODES: dict[str, str] = {
+        "hybrid": "contract",
+        "deep": "standard",
+    }
+    if mode in _DEPRECATED_MODES:
+        fallback = _DEPRECATED_MODES[mode]
+        typer.echo(
+            f"[deprecated] --mode {mode} is removed: produced identical output to --mode {fallback}. "
+            f"Using --mode {fallback}.",
+            err=True,
+        )
+        mode = fallback
+    elif mode not in _MODE_CHOICES:
         typer.echo(
             f"Error: invalid value '{mode}' for --mode. Valid options: {', '.join(_MODE_CHOICES)}",
             err=True,
@@ -604,6 +619,22 @@ def main(
         )
         raise typer.Exit(code=1)
 
+    if dependency_depth > 0:
+        typer.echo(
+            f"[warning] --dependency-depth {dependency_depth} has no effect: "
+            "transitive import resolution is not implemented for npm/yarn/pip projects. "
+            "Using depth=0 (direct dependencies only).",
+            err=True,
+        )
+        dependency_depth = 0
+
+    if compress_types:
+        typer.echo(
+            "[deprecated] --compress-types is removed: type signatures are rarely extracted "
+            "at default depth. Flag ignored.",
+            err=True,
+        )
+
     # Validate format choices
     if format not in FORMAT_CHOICES:
         typer.echo(
@@ -634,9 +665,9 @@ def main(
         raise typer.Exit(code=1)
 
     # Normalize mode aliases
-    _CONTRACT_MODES = frozenset({"contract", "minimal", "standard", "deep", "hybrid"})
+    _CONTRACT_MODES = frozenset({"contract", "minimal", "standard"})
     if mode == "minimal":
-        mode = "contract"   # minimal is the canonical default contract rendering
+        mode = "contract"   # minimal is a documented alias for contract
     elif mode not in _CONTRACT_MODES and mode != "raw":
         mode = "contract"   # unknown → safe default
 
@@ -648,15 +679,13 @@ def main(
         compact or agent or tree or format == "yaml" or trace_pipeline
         or docs or semantics or graph_modules or full_metrics or architecture
     )
-    if mode in ("contract", "standard", "deep") and _legacy_flags_active:
+    if mode in ("contract", "standard") and _legacy_flags_active:
         mode = "raw"
 
     # Map mode to contract_view depth
     _CONTRACT_DEPTH = {
         "contract": "minimal",
         "standard": "standard",
-        "deep": "deep",
-        "hybrid": "minimal",  # hybrid adds bodies via pipeline, minimal header
     }
 
     # --- Import analysis modules ---
@@ -746,6 +775,19 @@ def main(
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
 
+    # Warn when scanning a monorepo at default depth — typical package sources
+    # (packages/*/src/) live at depth 5+, so default depth=4 silently misses them.
+    # Only emit to TTY to avoid contaminating piped/CI output; agents read analysis_gaps.
+    import sys as _sys
+    if workspace_analysis.is_monorepo and depth <= 4 and effective_depth <= 4:
+        if _sys.stderr.isatty():
+            typer.echo(
+                f"[warning] monorepo detected with --depth {depth}. "
+                "Source files in packages/*/src/ (depth 5+) may be invisible. "
+                "Use --depth 6 or higher for full coverage.",
+                err=True,
+            )
+
     # --compact implicitly enables lightweight analysis passes so that
     # dependency_summary, env_summary and code_notes_summary are never null.
     if compact:
@@ -1244,7 +1286,7 @@ def main(
         sm = _replace(sm, pipeline_trace=_trace.build_trace())
 
     # Contract pipeline — runs for mode=contract|standard|deep|hybrid (skip for raw)
-    _is_contract_mode = mode in ("contract", "standard", "deep", "hybrid")
+    _is_contract_mode = mode in ("contract", "standard")
     if _is_contract_mode:
         from sourcecode.contract_pipeline import ContractPipeline
         _cp = ContractPipeline()
@@ -1263,6 +1305,13 @@ def main(
             compress_types=compress_types,
         )
         sm = _replace(sm, file_contracts=_contracts, contract_summary=_contract_summary)
+        if symbol is not None and len(_contracts) == 0:
+            typer.echo(
+                f"[warning] --symbol '{symbol}' matched 0 files. "
+                "The symbol may not exist at the current --depth, or the name may differ in case. "
+                "Try --depth 8 or verify the symbol name.",
+                err=True,
+            )
         if agent:
             typer.echo(f"[contract] {len(_contracts)} files extracted ({_contract_summary.method_breakdown})", err=True)
 

{sourcecode-0.36.0 → sourcecode-0.37.0}/src/sourcecode/git_analyzer.py

@@ -198,6 +198,13 @@ def _is_hotspot_admin(path: str) -> bool:
     for suffix in _HOTSPOT_ADMIN_SUFFIXES:
         if filename.endswith(suffix):
             return True
+    # Localized changelogs: CHANGELOG.zh-CN.md, CHANGES.en-US.md, etc.
+    _lower = filename.lower()
+    if _lower.startswith("changelog.") or _lower.startswith("changes."):
+        return True
+    # lerna.json and root-level package.json are modified by version bumps, not dev work
+    if filename in ("lerna.json",):
+        return True
     return False
 
 

{sourcecode-0.36.0 → sourcecode-0.37.0}/src/sourcecode/metrics_analyzer.py

@@ -219,6 +219,16 @@ class MetricsAnalyzer:
             if fm.language != "unknown":
                 languages.add(fm.language)
 
+        # Emit explicit limitation when JS/TS files are present but complexity is unavailable.
+        # This prevents agents from assuming null complexity means "no functions found".
+        _js_ts_count = sum(1 for r in records if r.language in ("javascript", "typescript") and r.complexity_availability == "unavailable")
+        if _js_ts_count > 0:
+            limitations.append(
+                f"cyclomatic_complexity_unavailable: {_js_ts_count} JS/TS file(s) — "
+                "complexity requires tree-sitter (pip install 'sourcecode[ast]'). "
+                "null complexity fields are expected, not an error."
+            )
+
         summary = MetricsSummary(
             requested=True,
             file_count=len(records),

{sourcecode-0.36.0 → sourcecode-0.37.0}/src/sourcecode/serializer.py

@@ -923,7 +923,7 @@ def _contract_view_minimal(
 
     result: dict[str, Any] = {
         "schema_version": sm.metadata.schema_version,
-        "mode": "minimal",
+        "mode": "contract",
         "project": project,
     }
 
@@ -949,9 +949,28 @@ def _contract_view_minimal(
 
     if sm.env_summary is not None and sm.env_summary.requested:
         result["env_summary"] = asdict(sm.env_summary)
+        if sm.env_map:
+            # Include top-20 env entries sorted by required first, then name.
+            # Agents read the summary count but need the actual keys to act on them.
+            _sorted_env = sorted(sm.env_map, key=lambda e: (not getattr(e, "required", False), getattr(e, "name", "")))
+            result["env_map"] = [
+                {k: v for k, v in asdict(e).items() if v is not None and v != ""}
+                for e in _sorted_env[:20]
+            ]
 
     if sm.code_notes_summary is not None and sm.code_notes_summary.requested:
         result["code_notes_summary"] = asdict(sm.code_notes_summary)
+        if sm.code_notes:
+            # Include top-20 notes by severity: BUG > FIXME > DEPRECATED > TODO > others.
+            _SEVERITY_ORDER = {"BUG": 0, "FIXME": 1, "DEPRECATED": 2, "TODO": 3, "HACK": 4, "WARNING": 5}
+            _sorted_notes = sorted(
+                sm.code_notes,
+                key=lambda n: (_SEVERITY_ORDER.get(getattr(n, "kind", "").upper(), 9), getattr(n, "path", "")),
+            )
+            result["code_notes"] = [
+                {k: v for k, v in asdict(n).items() if v is not None and v != ""}
+                for n in _sorted_notes[:20]
+            ]
 
     if sm.git_context is not None and sm.git_context.requested:
         result["git_context"] = asdict(sm.git_context)

{sourcecode-0.36.0 → sourcecode-0.37.0}/tests/test_contract_pipeline.py

@@ -160,7 +160,7 @@ def test_cli_contract_mode_default(tmp_path: Path) -> None:
     assert result.exit_code == 0, result.output
     data = json.loads(result.output)
     # Default contract mode renders as minimal
-    assert data["mode"] == "minimal"
+    assert data["mode"] == "contract"
     assert "contracts" in data
     assert "project" in data
     assert "schema_version" in data
@@ -174,7 +174,7 @@ def test_cli_contract_mode_explicit(tmp_path: Path) -> None:
     assert result.exit_code == 0, result.output
     data = json.loads(result.output)
     # --mode contract is an alias for minimal
-    assert data["mode"] == "minimal"
+    assert data["mode"] == "contract"
     assert isinstance(data["contracts"], list)
 
 

{sourcecode-0.36.0 → sourcecode-0.37.0}/tests/test_integration.py

@@ -31,7 +31,7 @@ def test_full_json_output(tmp_project: Path):
     data = json.loads(result.output)
     # Default mode is minimal contract — compact header + per-file contracts
     assert data["schema_version"] == "1.0"
-    assert data["mode"] == "minimal"
+    assert data["mode"] == "contract"
     assert "file_tree" not in data
     assert data["project"]["type"] == "cli"
     assert "contracts" in data