sourcecode 1.36.5__tar.gz → 1.39.0__tar.gz

{sourcecode-1.36.5 → sourcecode-1.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.36.5
+Version: 1.39.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.36.5-blue)
+![Version](https://img.shields.io/badge/version-1.39.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 ---
@@ -114,7 +114,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.36.5
+# sourcecode 1.39.0
 ```
 
 ---
@@ -149,6 +149,9 @@ sourcecode impact-chain OrderPlacedEvent /path/to/repo --type events
 # REST endpoint surface
 sourcecode endpoints /path/to/repo
 
+# Request-body validation per endpoint: constraints + custom validators (free)
+sourcecode validation /path/to/repo
+
 # Onboard to an unfamiliar codebase
 sourcecode onboard /path/to/repo
 

{sourcecode-1.36.5 → sourcecode-1.39.0}/README.md

@@ -2,7 +2,7 @@
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.36.5-blue)
+![Version](https://img.shields.io/badge/version-1.39.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 ---
@@ -76,7 +76,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.36.5
+# sourcecode 1.39.0
 ```
 
 ---
@@ -111,6 +111,9 @@ sourcecode impact-chain OrderPlacedEvent /path/to/repo --type events
 # REST endpoint surface
 sourcecode endpoints /path/to/repo
 
+# Request-body validation per endpoint: constraints + custom validators (free)
+sourcecode validation /path/to/repo
+
 # Onboard to an unfamiliar codebase
 sourcecode onboard /path/to/repo
 

{sourcecode-1.36.5 → sourcecode-1.39.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.36.5"
+version = "1.39.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.36.5 → sourcecode-1.39.0}/src/sourcecode/__init__.py

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

{sourcecode-1.36.5 → sourcecode-1.39.0}/src/sourcecode/cli.py

@@ -230,6 +230,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "cold-start",
         # Spring semantic audit
         "spring-audit",
+        # Request-body validation surface
+        "validation",
         # Spring impact chain
         "impact-chain",
         # PR blast-radius report
@@ -401,6 +403,28 @@ def _emit_error_json(error: str, message: str, **context: object) -> None:
     sys.stderr.flush()
 
 
+def _enforce_format(command: str, fmt: str) -> None:
+    """Validate ``--format`` for ``command`` against the central contract.
+
+    Single validation path for every command's ``--format`` option (see
+    ``sourcecode.format_contract``). On an invalid value it emits the
+    homogeneous JSON error envelope to stderr and exits with code 2
+    (argument-validation convention). Valid values are a no-op.
+    """
+    from sourcecode.format_contract import (
+        FORMAT_ERROR_EXIT_CODE,
+        format_error_context,
+        is_valid_format,
+    )
+
+    if is_valid_format(command, fmt):
+        return
+    ctx = format_error_context(command, fmt)
+    message = str(ctx.pop("message"))
+    _emit_error_json(INVALID_INPUT_CODE, message, **ctx)
+    raise typer.Exit(code=FORMAT_ERROR_EXIT_CODE)
+
+
 def _safe_write_file(path: "Path", content: str) -> None:
     """Write content to path, emitting a clean JSON error on I/O failure."""
     try:
@@ -631,7 +655,8 @@ def _active_flags(
     if fmt != "json": flags.append("--format")
     return flags
 
-FORMAT_CHOICES = ["json", "yaml"]
+# Per-command output-format contracts now live in sourcecode.format_contract
+# (validated via _enforce_format). No module-level FORMAT_CHOICES here.
 GRAPH_DETAIL_CHOICES = ["high", "medium", "full"]
 GRAPH_EDGE_CHOICES = {"imports", "calls", "contains", "extends"}
 DOCS_DEPTH_CHOICES = ["module", "symbols", "full"]
@@ -1138,17 +1163,7 @@ def main(
         )
 
     # Validate format choices
-    if format not in FORMAT_CHOICES:
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid value '{format}' for --format. Valid values: {', '.join(FORMAT_CHOICES)}.",
-            flag="--format",
-            value=format,
-            valid_values=list(FORMAT_CHOICES),
-            hint="Choose one of the supported --format values.",
-            expected=f"One of: {', '.join(FORMAT_CHOICES)}",
-        )
-        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
+    _enforce_format("main", format)
     if graph_detail not in GRAPH_DETAIL_CHOICES:
         _emit_error_json(
             INVALID_INPUT_CODE,
@@ -2834,19 +2849,9 @@ def prepare_context_cmd(
     # Validate --format: only "json" and "github-comment" are valid for prepare-context.
     # "yaml" is intentionally NOT supported here (use main command for yaml output).
     # Invalid values must error loudly — silently falling through to JSON is a lie.
-    _PC_FORMAT_CHOICES = ("json", "github-comment")
-    if format is not None and format not in _PC_FORMAT_CHOICES:
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"invalid value '{format}' for --format. "
-            f"Valid options: {', '.join(_PC_FORMAT_CHOICES)}.",
-            flag="--format",
-            value=format,
-            valid_values=list(_PC_FORMAT_CHOICES),
-            hint="Choose one of the supported prepare-context output formats.",
-            expected=f"One of: {', '.join(_PC_FORMAT_CHOICES)}",
-        )
-        raise typer.Exit(code=2)
+    # None means "use default" (json); a concrete value is validated against the contract.
+    if format is not None:
+        _enforce_format("prepare-context", format)
     # github-comment only renders for review-pr; warn and normalize for other tasks.
     if format == "github-comment" and task != "review-pr":
         typer.echo(
@@ -3479,14 +3484,7 @@ def repo_ir_cmd(
 
     from sourcecode.repository_ir import apply_ir_size_limits, build_repo_ir, find_java_files
 
-    if format not in ("json", "yaml"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="Valid values: json, yaml.",
-            expected="json | yaml",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("repo-ir", format)
 
     root = path.resolve()
     if not root.is_dir():
@@ -3712,14 +3710,7 @@ def impact_cmd(
     from sourcecode.license import require_repo_or_pro as _require_repo_or_pro
     _require_repo_or_pro(str(path.resolve()), "impact")
 
-    if format not in ("json", "yaml"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="format must be: json or yaml.",
-            expected="json | yaml",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("impact", format)
 
     from sourcecode.repository_ir import (
         build_repo_ir, find_java_files, compute_blast_radius,
@@ -3875,14 +3866,7 @@ def endpoints_cmd(
       sourcecode endpoints . --controller LiquidacionJornada
       sourcecode endpoints . --limit 10
     """
-    if format not in ("json", "yaml"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="format must be: json or yaml.",
-            expected="json | yaml",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("endpoints", format)
 
     target = path.resolve()
     if not target.exists() or not target.is_dir():
@@ -3933,6 +3917,105 @@ def endpoints_cmd(
     _nudge()
 
 
+@app.command("validation")
+def validation_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path to scan for request-body validation (default: current directory)",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json",
+        "--format",
+        "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False,
+        "--copy",
+        "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+    path_prefix: Optional[str] = typer.Option(
+        None, "--path-prefix", "-p",
+        help="Filter endpoints whose URL path starts with this prefix.",
+    ),
+    gaps_only: bool = typer.Option(
+        False, "--gaps-only",
+        help="Report only endpoints/fields with no declared validation (the gaps section).",
+    ),
+) -> None:
+    """Map request-body validation per endpoint (constraints + custom validators).
+
+    \b
+    Aggregates two sources of bean-validation truth so an agent knows exactly
+    what a request body must satisfy before touching it:
+      * declarative constraints on the DTOs (@Pattern/@Size/@NotNull, min/max,
+        enum), recovered from the OpenAPI spec even when the DTOs are generated
+        under target/generated-sources (not scanned);
+      * hand-written custom validators (@Constraint + ConstraintValidator, e.g.
+        PetAgeValidator), linked to fields via x-field-extra-annotation.
+
+    \b
+    Output (JSON): per-endpoint validatedFields with their rules + custom
+    validators, the discovered custom-validator catalog, and the set of body
+    endpoints with no declared validation (gaps).
+
+    \b
+    Examples:
+      sourcecode validation .
+      sourcecode validation . --gaps-only
+      sourcecode validation . --path-prefix /owners
+      sourcecode validation . --format yaml
+    """
+    _enforce_format("validation", format)
+
+    target = path.resolve()
+    if not target.exists() or not target.is_dir():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+            hint="Pass an existing repository directory.",
+            expected="A directory path.",
+        )
+        raise typer.Exit(code=1)
+
+    from sourcecode.validation_surface import build_validation_surface
+    data = build_validation_surface(target)
+
+    if path_prefix:
+        data["endpoints"] = [
+            e for e in data.get("endpoints", [])
+            if str(e.get("path", "")).startswith(path_prefix)
+        ]
+        data["gaps"] = [
+            g for g in data.get("gaps", [])
+            if str(g.get("path", "")).startswith(path_prefix)
+        ]
+    if gaps_only:
+        data = {
+            "gaps": data.get("gaps", []),
+            "summary": data.get("summary", {}),
+        }
+
+    output = _serialize_dict(data, format)
+    _summary = data.get("summary", {})
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=f"Validation surface written to {output_path} "
+        f"({_summary.get('endpoints_with_body', 0)} body endpoints, "
+        f"{_summary.get('gaps', 0)} gaps)",
+    )
+
+    from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
+    _nudge()
+
+
 # ── Spring Semantic Audit ─────────────────────────────────────────────────────
 
 
@@ -4116,14 +4199,7 @@ def spring_audit_cmd(
         )
         raise typer.Exit(code=1)
 
-    if format not in ("json", "yaml", "github-comment"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="format must be one of: json, yaml, github-comment.",
-            expected="json | yaml | github-comment",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("spring-audit", format)
 
     _file_limitations: list[str] = []
     file_list = find_java_files(target, limitations=_file_limitations)
@@ -4274,14 +4350,7 @@ def migrate_check_cmd(
         )
         raise typer.Exit(code=1)
 
-    if format not in ("json", "text"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="format must be one of: json, text.",
-            expected="json | text",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("migrate-check", format)
 
     if min_severity not in ("critical", "high", "medium", "low"):
         _emit_error_json(
@@ -4426,14 +4495,7 @@ def impact_chain_cmd(
         )
         raise typer.Exit(code=1)
 
-    if format not in ("json", "yaml"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="format must be: json or yaml.",
-            expected="json | yaml",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("impact-chain", format)
 
     file_list = find_java_files(target)
     if not file_list:
@@ -4567,14 +4629,7 @@ def pr_impact_cmd(
         )
         raise typer.Exit(code=1)
 
-    if format not in ("text", "json"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="format must be: text or json.",
-            expected="text | json",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("pr-impact", format)
 
     # Read changed-files list
     changed_files = [
@@ -4699,14 +4754,7 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
-    if format not in ("text", "json"):
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"Invalid format '{format}'.",
-            hint="format must be: text or json.",
-            expected="text | json",
-        )
-        raise typer.Exit(code=1)
+    _enforce_format("explain", format)
 
     file_list = find_java_files(target)
     if not file_list:

sourcecode-1.39.0/src/sourcecode/format_contract.py

@@ -0,0 +1,87 @@
+"""Single source of truth for per-command output-format contracts.
+
+Every CLI command that emits machine-consumable output validates its
+``--format`` option through this registry so that:
+
+  * the set of allowed formats for each command lives in exactly one place,
+  * ``-f json`` is a strict contract on every command (pure JSON to stdout),
+  * invalid-format errors share an identical envelope shape and exit code.
+
+The registry value is an *ordered* tuple; element ``0`` is the command's
+default and matches its Typer option default. Defaults are intentionally NOT
+changed when centralizing — ``explain`` and ``pr-impact`` keep their
+human-facing ``text`` default — to avoid breaking existing scripts. The strict
+guarantee is on ``-f json``, which every command supports.
+
+Exit-code policy: an invalid ``--format`` is an argument-validation error and
+exits with code ``2`` for every command (matching the documented
+``arg validation -> exit 2`` convention used by the root command).
+"""
+
+from __future__ import annotations
+
+# Command name (as registered with ``@app.command``, or "main" for the root
+# command) -> ordered tuple of allowed formats. Element 0 is the default.
+FORMAT_REGISTRY: "dict[str, tuple[str, ...]]" = {
+    "main": ("json", "yaml"),
+    "repo-ir": ("json", "yaml"),
+    "impact": ("json", "yaml"),
+    "endpoints": ("json", "yaml"),
+    "validation": ("json", "yaml"),
+    "impact-chain": ("json", "yaml"),
+    "pr-impact": ("text", "json"),
+    "migrate-check": ("json", "text"),
+    "spring-audit": ("json", "yaml", "github-comment"),
+    "explain": ("text", "json"),
+    "prepare-context": ("json", "github-comment"),
+}
+
+# Invalid --format is an argument-validation error.
+FORMAT_ERROR_EXIT_CODE = 2
+
+# The strict machine-readable format every command must support.
+STRICT_FORMAT = "json"
+
+
+def allowed_formats(command: str) -> "tuple[str, ...]":
+    """Return the ordered tuple of allowed formats for ``command``.
+
+    Raises ``KeyError`` if the command has no registered contract — a
+    programming error, surfaced loudly rather than silently allowing anything.
+    """
+    try:
+        return FORMAT_REGISTRY[command]
+    except KeyError as exc:
+        raise KeyError(
+            f"No format contract registered for command '{command}'. "
+            f"Add it to FORMAT_REGISTRY in sourcecode/format_contract.py."
+        ) from exc
+
+
+def default_format(command: str) -> str:
+    """Return the default format for ``command`` (registry element 0)."""
+    return allowed_formats(command)[0]
+
+
+def is_valid_format(command: str, fmt: str) -> bool:
+    """True iff ``fmt`` is allowed for ``command``."""
+    return fmt in FORMAT_REGISTRY.get(command, ())
+
+
+def format_error_context(command: str, fmt: str) -> "dict[str, object]":
+    """Build the homogeneous error-envelope fields for an invalid ``--format``.
+
+    Returns a dict whose ``message`` key is the human message and whose
+    remaining keys are passed verbatim as the error-envelope context, so every
+    command produces an identically shaped ``--format`` error.
+    """
+    allowed = list(allowed_formats(command))
+    joined = ", ".join(allowed)
+    return {
+        "message": f"Invalid value '{fmt}' for --format. Valid values: {joined}.",
+        "flag": "--format",
+        "value": fmt,
+        "valid_values": allowed,
+        "hint": "Choose one of the supported --format values.",
+        "expected": f"One of: {joined}",
+    }

{sourcecode-1.36.5 → sourcecode-1.39.0}/src/sourcecode/mcp/registry.py

@@ -864,6 +864,31 @@ Returns: endpoints list with method, path, controller, handler fields;
          "unknown" (no security signals detected).
 Supports Spring MVC (@GetMapping etc.) and JAX-RS (@GET/@POST etc.).
 repo_path: absolute path to the Java repository (default: current working directory).
+"""
+
+    _GET_VALIDATION_DOC = """\
+Request-body validation surface per endpoint. JAVA/SPRING ONLY.
+
+Do NOT call this on non-Java repositories — it will return empty results.
+
+Combines two sources of bean-validation truth so you know what a request body
+must satisfy before generating a payload, a test, or reasoning about a 400:
+  * declarative constraints on the DTOs (@Pattern/@Size/@NotNull, minimum/maximum,
+    enum) — recovered from the OpenAPI spec even when DTOs are generated under
+    target/generated-sources (not scanned);
+  * hand-written custom validators (@Constraint + ConstraintValidator, e.g.
+    PetAgeValidator), linked to fields via x-field-extra-annotation.
+
+Maps to: sourcecode validation <repo_path>
+Returns: endpoints[] (method, path, controller, handler, schema, validatedFields[
+  {name, rules[{kind,value}], customValidators[{annotation,validators,message,resolved}]}]),
+  custom_validators[] (catalog: annotation, validators, message, validatedTypes, targets),
+  gaps[] (POST/PUT/PATCH endpoints with no declared validation),
+  summary, openapi_spec.
+An unresolved custom annotation (referenced in the spec, no validator in source)
+is reported with resolved=false.
+repo_path: absolute path to the Java repository (default: current working directory).
+gaps_only: when true, return only the gaps section (endpoints lacking validation).
 """
 
     _CACHE_STATUS_DOC = """\
@@ -1083,6 +1108,27 @@ repo_path: absolute path to the repository (default: current working directory).
             docstring_override=_GET_ENDPOINTS_DOC,
         ),
 
+        # --- get_validation: clean alias replacing raw canonical (6 CLI params) ---
+        _alias_spec(
+            "get_validation",
+            "Request-body validation surface per endpoint (constraints + custom validators). JAVA/SPRING ONLY.",
+            ("validation",),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+                ToolParamSpec("gaps_only", "option", bool, required=False, default=False,
+                              option_names=("--gaps-only",), is_flag=True,
+                              help="Return only endpoints/fields lacking validation."),
+            ),
+            lambda inputs: (
+                ["validation", str(inputs.get("repo_path", "."))]
+                + (["--gaps-only"] if bool(inputs.get("gaps_only")) else [])
+            ),
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_GET_VALIDATION_DOC,
+        ),
+
         # --- cache management: curated aliases stripping CLI noise params ---
         _alias_spec(
             "cache_status",
@@ -1214,6 +1260,7 @@ _MCP_HIDDEN_CANONICAL_TOOLS: frozenset[str] = frozenset({
     "modernize",          # duplicate of modernize_context
     # Raw CLI tools with output-format/noise params — clean alias with only repo_path exists
     "endpoints",          # 7 CLI params (output_path/format/copy/etc.); use get_endpoints
+    "validation",         # 6 CLI params (output_path/format/copy/path_prefix/gaps_only); use get_validation
     "cache_status",       # path + json_output flag; curated alias strips json_output, renames path→repo_path
     "cache_warm",         # path + compact/agent output flags; curated alias keeps only repo_path
     "cache_clear",        # path + yes/all_ destructive flags; curated alias keeps repo_path + include_ris only