sourcecode 0.36.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

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/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/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/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/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.dist-info → sourcecode-0.37.0.dist-info}/METADATA

@@ -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.dist-info → sourcecode-0.37.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
-sourcecode/__init__.py,sha256=X_JznUsRmn3yELdS1V1zFgnDITiz-h3a451D5eLoTnY,103
+sourcecode/__init__.py,sha256=Xha8jq1XWD5Ze_B5mEne-d5fOfBVVwnX-Ieg7spvalk,103
 sourcecode/architecture_analyzer.py,sha256=H6noGgVArUJ25z1qC0fFA0KvJJeHZYyhKvKSkOyWHUk,23096
 sourcecode/architecture_summary.py,sha256=rSY5MRiaz4N1YdG0pqDTDuFjSN7PO_Zplx-dtNzv2Yo,19985
 sourcecode/ast_extractor.py,sha256=0OHQwTUBBc9lmqPLryVeB1z8dGIC6NhLlar800CD9oI,41129
 sourcecode/classifier.py,sha256=GKTMN8qKZX7ponSwDJfN08RrasI4CVpq1_gFBgEopps,7093
-sourcecode/cli.py,sha256=O1ObfcxvhMYMXjd6otx6G0fE9ethIAX4qDUpUUjOxgY,63167
+sourcecode/cli.py,sha256=LSGytpRlyMFdmHugrP3USDhPb0hiigHn0PL9Ppac3R4,64852
 sourcecode/code_notes_analyzer.py,sha256=rRd8bFYV0krjlxxQV0wenwE9K7pVpUQSR7KvSvUQKw4,9226
 sourcecode/confidence_analyzer.py,sha256=HxJMPLI5ulqtkncnv98W4iVO6yMbpQo87VuxiuNbDmY,12167
 sourcecode/context_summarizer.py,sha256=CiQrfBEzun949bWvmLabWoj2HhPn6Lw62ofqnsy0FlQ,6503
@@ -15,9 +15,9 @@ sourcecode/doc_analyzer.py,sha256=Ec3orx6vBKsh5cNM3-F4y2Got2KuKx8w3dErwtdtM-A,19
 sourcecode/entrypoint_classifier.py,sha256=a69dMGyxCTd_LOm3oqj-EXWpRmbmeujN7T1mr2eJ1as,3877
 sourcecode/env_analyzer.py,sha256=slvq-eT24RVMNczLNDlZbe0hU8JXIIPxybqubvrrnSQ,14409
 sourcecode/file_classifier.py,sha256=_KfFIIolharaIxbSTrCkaWauQIqNHCyor_n47RGyDh8,8577
-sourcecode/git_analyzer.py,sha256=saI5wtHBEOXBhdk7SrVR7ArSM6MFkyGgukvGRuD9WRc,9638
+sourcecode/git_analyzer.py,sha256=s7tJTd_GAczhrH7j9JhBNp7ozhkW3lzBN0TMNwFqJwE,9977
 sourcecode/graph_analyzer.py,sha256=hMOsLLz9B0UnQ4xwbHdgr3bFvqpw0bQ8kN-xmEn3Krk,64156
-sourcecode/metrics_analyzer.py,sha256=4uh11v-Q0gdrN87BOxuFWUym3N3AOkOuy21K5N8peB8,20126
+sourcecode/metrics_analyzer.py,sha256=e2cFwB9XubFq_dIVsP2PLjpr4wX0N6ulb3ol3sGDUeo,20777
 sourcecode/prepare_context.py,sha256=vxEzr8czS3MFbdTx4hBJQlJLrl9cuvbHdL3ZokxFkvo,31384
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
 sourcecode/relevance_scorer.py,sha256=ea7_7AHVgahVEWK3ebKOpG67agzG_pGICu5f2KgzrIA,8133
@@ -25,7 +25,7 @@ sourcecode/runtime_classifier.py,sha256=zWX3r3HCKHc-qtIobErOa8aKMmaoPYREtJKvPcBG
 sourcecode/scanner.py,sha256=aM3h9-DCQ3xKpeHpHYdo2vX6T5P95HA_YwZbkAVNwmo,8288
 sourcecode/schema.py,sha256=AShu_bcP30TYaw4Dl1nYy8aFnBCKxrUli3LhU3MZTjs,20739
 sourcecode/semantic_analyzer.py,sha256=asQfJf-EhzYaOTA-iMuZsrVXtbW7SV2WEKCxgsxa88Y,79413
-sourcecode/serializer.py,sha256=8ONhYuJ25AjMfZImwveYjVSHjIFDCuBRjCKNjs94bEA,50057
+sourcecode/serializer.py,sha256=uQGcytdaaM3qzxXcZ2NMjXYvzdvT9PP45960t-Thgqk,51128
 sourcecode/summarizer.py,sha256=ZuzIdm3t8A-d5MuQL0TSNLrd-L0IQIuguIxeNXMNJf8,16070
 sourcecode/tree_utils.py,sha256=Fj9OIuUksBvgibNd3feog0sMDjVypJzPexp5lvMoYWI,1424
 sourcecode/workspace.py,sha256=fQlVoNx8S-fSHpKoJ0JBvEHCFkxszH0KZVJed1i3TRk,6845
@@ -56,8 +56,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=oEvvulfsv5GIDWG2174gSS6tNB95w38AIYiYeifGKlE,2294
 sourcecode/telemetry/filters.py,sha256=Asa71oRl7q3Wt_FMwuufIZJFzSYdgRNKS8LHCIyFeYE,4805
 sourcecode/telemetry/transport.py,sha256=KJeIPCPWMdmbCP3ySGs2iUlia34U6vWne2dZsUezesw,1560
-sourcecode-0.36.0.dist-info/METADATA,sha256=vQc2-46U5UyDGNaaVWbr5Jb7_eBOgJAYIPpYAD_aiwA,25209
-sourcecode-0.36.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.36.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-0.36.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-0.36.0.dist-info/RECORD,,
+sourcecode-0.37.0.dist-info/METADATA,sha256=75XE0yybH_O7U8rxcP6ZY2MdvibRaxALg4io5V9RsU4,25209
+sourcecode-0.37.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.37.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-0.37.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-0.37.0.dist-info/RECORD,,