sourcecode 1.36.5__py3-none-any.whl → 1.38.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/cli.py

@@ -401,6 +401,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 +653,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 +1161,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 +2847,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 +3482,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 +3708,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 +3864,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():
@@ -4116,14 +4098,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 +4249,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 +4394,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 +4528,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 +4653,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/format_contract.py

@@ -0,0 +1,86 @@
+"""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"),
+    "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/openapi_surface.py

@@ -0,0 +1,431 @@
+"""OpenAPI spec surface extraction (Phase 18, wave 18-01).
+
+Many enterprise Spring repos generate their HTTP surface, DTOs and validation
+constraints from an OpenAPI spec via openapi-generator: controllers
+``implements XxxApi`` where the mapping annotations and DTO classes live under
+``target/generated-sources`` (excluded from the source scan). The structural
+scanner therefore sees no routes and no constraints for those controllers.
+
+The spec itself, however, ships in the repo source (commonly
+``src/main/resources/openapi.yml``): always present, deterministic, no build
+required. This module discovers and parses that spec into a normalized surface
+— operations (method/path/operationId/tags/requestBody) and schemas (fields
+with validation constraints) — so downstream code can recover the endpoint and
+constraint surface without touching generated sources.
+
+Design notes:
+  * Pure extraction, not validation: we never assert spec conformance.
+  * Defensive: a malformed or partial spec yields a partial surface, never an
+    exception. Unresolvable ``$ref``/``allOf`` are skipped, not fatal.
+  * Bounded: discovery is limited to well-known locations + a capped content
+    sniff so it never walks an entire large tree.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+_HTTP_METHODS = ("get", "put", "post", "delete", "patch", "options", "head", "trace")
+
+# Filenames that are almost certainly an API spec.
+_SPEC_NAME_HINTS = ("openapi", "swagger", "api-docs")
+
+# Directories worth searching first (relative to repo root).
+_SPEC_DIRS = (
+    "src/main/resources",
+    "src/main/resources/openapi",
+    "api",
+    "apis",
+    "openapi",
+    "spec",
+    "specs",
+    "docs",
+    "contracts",
+    ".",
+)
+
+# Cap on how many candidate files we content-sniff, to stay fast on big repos.
+_SNIFF_CAP = 400
+# Cap on $ref / allOf resolution depth, to stay safe on cyclic specs.
+_RESOLVE_DEPTH = 8
+
+
+@dataclass
+class FieldConstraint:
+    """A single schema property and its validation constraints."""
+
+    name: str
+    type: Optional[str] = None
+    required: bool = False
+    pattern: Optional[str] = None
+    min_length: Optional[int] = None
+    max_length: Optional[int] = None
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+    fmt: Optional[str] = None
+    enum: Optional[list[Any]] = None
+    ref: Optional[str] = None  # schema name when the field is an object/array ref
+
+    def to_dict(self) -> "dict[str, Any]":
+        out: "dict[str, Any]" = {"name": self.name, "required": self.required}
+        for key, val in (
+            ("type", self.type),
+            ("pattern", self.pattern),
+            ("minLength", self.min_length),
+            ("maxLength", self.max_length),
+            ("minimum", self.minimum),
+            ("maximum", self.maximum),
+            ("format", self.fmt),
+            ("enum", self.enum),
+            ("ref", self.ref),
+        ):
+            if val is not None:
+                out[key] = val
+        return out
+
+
+@dataclass
+class OpenApiSchema:
+    name: str
+    fields: "list[FieldConstraint]" = field(default_factory=list)
+
+    def to_dict(self) -> "dict[str, Any]":
+        return {"name": self.name, "fields": [f.to_dict() for f in self.fields]}
+
+
+@dataclass
+class OpenApiOperation:
+    method: str
+    path: str
+    operation_id: Optional[str] = None
+    tags: "list[str]" = field(default_factory=list)
+    request_body_schema: Optional[str] = None  # schema name (ref) of the body
+    has_security: bool = False
+
+    def to_dict(self) -> "dict[str, Any]":
+        out: "dict[str, Any]" = {"method": self.method, "path": self.path}
+        if self.operation_id:
+            out["operationId"] = self.operation_id
+        if self.tags:
+            out["tags"] = self.tags
+        if self.request_body_schema:
+            out["requestBodySchema"] = self.request_body_schema
+        out["hasSecurity"] = self.has_security
+        return out
+
+
+@dataclass
+class OpenApiSurface:
+    spec_path: str
+    operations: "list[OpenApiOperation]" = field(default_factory=list)
+    schemas: "dict[str, OpenApiSchema]" = field(default_factory=dict)
+
+    def to_dict(self) -> "dict[str, Any]":
+        return {
+            "spec_path": self.spec_path,
+            "operations": [op.to_dict() for op in self.operations],
+            "schemas": {name: s.to_dict() for name, s in self.schemas.items()},
+        }
+
+
+def tag_to_interface(tag: str) -> str:
+    """Map an OpenAPI tag to the openapi-generator interface name.
+
+    openapi-generator with ``useTags: true`` derives one ``{PascalCaseTag}Api``
+    interface per tag, splitting on ``-``/``_``/space. E.g. ``owners`` ->
+    ``OwnersApi``, ``owner-v2`` -> ``OwnerV2Api``, ``vet_v2`` -> ``VetV2Api``.
+    """
+    import re as _re
+
+    words = [w for w in _re.split(r"[-_\s]+", tag) if w]
+    return "".join(w[:1].upper() + w[1:] for w in words) + "Api"
+
+
+# ── Discovery ──────────────────────────────────────────────────────────────
+
+
+def _looks_like_spec(data: Any) -> bool:
+    return isinstance(data, dict) and ("openapi" in data or "swagger" in data)
+
+
+def _load_yaml_or_json(path: Path) -> Optional[Any]:
+    """Load a YAML or JSON document, returning None on any failure."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    suffix = path.suffix.lower()
+    try:
+        if suffix == ".json":
+            return json.loads(text)
+        # .yml/.yaml (and unknown) -> YAML, which is a JSON superset.
+        from ruamel.yaml import YAML
+
+        yaml = YAML(typ="safe")
+        return yaml.load(text)
+    except Exception:
+        # Last resort: a .json-less file that is actually JSON.
+        try:
+            return json.loads(text)
+        except Exception:
+            return None
+
+
+def find_openapi_specs(root: Path) -> "list[Path]":
+    """Discover OpenAPI/Swagger spec files under ``root``.
+
+    Strategy: collect candidates by filename hint within well-known dirs, then
+    content-sniff a bounded set of ``.yml/.yaml/.json`` files to confirm. Result
+    is sorted for determinism. Never raises.
+    """
+    root = Path(root)
+    candidates: "list[Path]" = []
+    seen: "set[Path]" = set()
+
+    def _consider(p: Path) -> None:
+        try:
+            rp = p.resolve()
+        except OSError:
+            return
+        if rp in seen or not p.is_file():
+            return
+        seen.add(rp)
+        candidates.append(p)
+
+    # Pass 1: filename-hinted files in well-known dirs.
+    for rel in _SPEC_DIRS:
+        d = root / rel
+        if not d.is_dir():
+            continue
+        try:
+            entries = sorted(d.iterdir())
+        except OSError:
+            continue
+        for p in entries:
+            if not p.is_file():
+                continue
+            stem = p.stem.lower()
+            if p.suffix.lower() in (".yml", ".yaml", ".json") and any(
+                h in stem for h in _SPEC_NAME_HINTS
+            ):
+                _consider(p)
+
+    # Confirm pass-1 candidates by content; keep only real specs.
+    confirmed: "list[Path]" = []
+    for p in candidates:
+        data = _load_yaml_or_json(p)
+        if _looks_like_spec(data):
+            confirmed.append(p)
+
+    if confirmed:
+        return sorted(confirmed, key=lambda p: str(p))
+
+    # Pass 2 (fallback): bounded content sniff of resource-y yaml/json files.
+    sniffed = 0
+    for rel in ("src/main/resources", "."):
+        d = root / rel
+        if not d.is_dir():
+            continue
+        for p in sorted(d.rglob("*")):
+            if sniffed >= _SNIFF_CAP:
+                break
+            if not p.is_file() or p.suffix.lower() not in (".yml", ".yaml", ".json"):
+                continue
+            # Skip obvious build output.
+            parts = {seg.lower() for seg in p.parts}
+            if "target" in parts or "node_modules" in parts or "build" in parts:
+                continue
+            sniffed += 1
+            data = _load_yaml_or_json(p)
+            if _looks_like_spec(data):
+                _consider(p)
+    return sorted({p.resolve(): p for p in candidates}.values(), key=lambda p: str(p))
+
+
+# ── Parsing ────────────────────────────────────────────────────────────────
+
+
+def _ref_name(ref: Any) -> Optional[str]:
+    """Return the trailing name of a ``#/components/schemas/Xxx`` ref."""
+    if isinstance(ref, str) and ref.startswith("#/"):
+        return ref.rsplit("/", 1)[-1]
+    return None
+
+
+def _field_from_property(name: str, prop: Any, required: bool) -> FieldConstraint:
+    fc = FieldConstraint(name=name, required=required)
+    if not isinstance(prop, dict):
+        return fc
+    ref = _ref_name(prop.get("$ref"))
+    if ref:
+        fc.ref = ref
+    fc.type = prop.get("type")
+    fc.pattern = prop.get("pattern")
+    fc.fmt = prop.get("format")
+    for src, dst in (("minLength", "min_length"), ("maxLength", "max_length")):
+        v = prop.get(src)
+        if isinstance(v, int):
+            setattr(fc, dst, v)
+    for src, dst in (("minimum", "minimum"), ("maximum", "maximum")):
+        v = prop.get(src)
+        if isinstance(v, (int, float)):
+            setattr(fc, dst, float(v))
+    enum = prop.get("enum")
+    if isinstance(enum, list):
+        fc.enum = list(enum)
+    if fc.type is None and prop.get("type") == "array":
+        items = prop.get("items")
+        if isinstance(items, dict):
+            fc.ref = fc.ref or _ref_name(items.get("$ref"))
+    return fc
+
+
+def _resolve_schema_fields(
+    node: Any,
+    all_schemas: "dict[str, Any]",
+    depth: int = 0,
+    _seen: "Optional[set[str]]" = None,
+) -> "tuple[dict[str, FieldConstraint], set[str]]":
+    """Recursively flatten a schema node (handling allOf + $ref) into fields.
+
+    Returns (ordered field map by name, required-name set). Bounded by depth.
+    """
+    fields: "dict[str, FieldConstraint]" = {}
+    required: "set[str]" = set()
+    if depth > _RESOLVE_DEPTH or not isinstance(node, dict):
+        return fields, required
+    seen = _seen or set()
+
+    # $ref -> resolve the referenced schema.
+    ref = _ref_name(node.get("$ref"))
+    if ref:
+        if ref in seen:
+            return fields, required
+        target = all_schemas.get(ref)
+        if isinstance(target, dict):
+            return _resolve_schema_fields(target, all_schemas, depth + 1, seen | {ref})
+        return fields, required
+
+    # allOf -> merge each sub-schema.
+    for sub in node.get("allOf", []) or []:
+        sub_fields, sub_req = _resolve_schema_fields(
+            sub, all_schemas, depth + 1, seen
+        )
+        fields.update(sub_fields)
+        required |= sub_req
+
+    # required list at this level.
+    for r in node.get("required", []) or []:
+        if isinstance(r, str):
+            required.add(r)
+
+    # direct properties.
+    props = node.get("properties")
+    if isinstance(props, dict):
+        for pname, prop in props.items():
+            fields[pname] = _field_from_property(pname, prop, required=False)
+
+    # apply required flags now that we know the union.
+    for rname in required:
+        if rname in fields:
+            fields[rname].required = True
+    return fields, required
+
+
+def _parse_schemas(components: Any) -> "dict[str, OpenApiSchema]":
+    schemas_raw = {}
+    if isinstance(components, dict):
+        schemas_raw = components.get("schemas") or {}
+    if not isinstance(schemas_raw, dict):
+        return {}
+    out: "dict[str, OpenApiSchema]" = {}
+    for name, node in schemas_raw.items():
+        fields_map, _ = _resolve_schema_fields(node, schemas_raw)
+        out[name] = OpenApiSchema(name=name, fields=list(fields_map.values()))
+    return out
+
+
+def _request_body_schema(operation: Any) -> Optional[str]:
+    if not isinstance(operation, dict):
+        return None
+    body = operation.get("requestBody")
+    if not isinstance(body, dict):
+        return None
+    content = body.get("content")
+    if not isinstance(content, dict):
+        return None
+    # Prefer application/json, else first media type with a schema.
+    media_types = [content.get("application/json")] + [
+        v for k, v in content.items() if k != "application/json"
+    ]
+    for media in media_types:
+        if not isinstance(media, dict):
+            continue
+        schema = media.get("schema")
+        if isinstance(schema, dict):
+            name = _ref_name(schema.get("$ref"))
+            if name:
+                return name
+            # array of refs
+            if schema.get("type") == "array":
+                items = schema.get("items")
+                if isinstance(items, dict):
+                    return _ref_name(items.get("$ref"))
+    return None
+
+
+def _parse_operations(paths: Any) -> "list[OpenApiOperation]":
+    if not isinstance(paths, dict):
+        return []
+    ops: "list[OpenApiOperation]" = []
+    for path, methods in paths.items():
+        if not isinstance(methods, dict):
+            continue
+        for method in _HTTP_METHODS:
+            op = methods.get(method)
+            if not isinstance(op, dict):
+                continue
+            tags = op.get("tags")
+            ops.append(
+                OpenApiOperation(
+                    method=method.upper(),
+                    path=str(path),
+                    operation_id=op.get("operationId"),
+                    tags=[str(t) for t in tags] if isinstance(tags, list) else [],
+                    request_body_schema=_request_body_schema(op),
+                    has_security="security" in op,
+                )
+            )
+    return ops
+
+
+def parse_openapi_spec(path: Path) -> Optional[OpenApiSurface]:
+    """Parse a single spec file into an OpenApiSurface, or None if unparseable."""
+    data = _load_yaml_or_json(Path(path))
+    if not _looks_like_spec(data):
+        return None
+    surface = OpenApiSurface(spec_path=str(path))
+    try:
+        surface.operations = _parse_operations(data.get("paths"))
+        surface.schemas = _parse_schemas(data.get("components"))
+    except Exception:
+        # Partial surface beats a crash; return whatever resolved.
+        pass
+    return surface
+
+
+def build_openapi_surface(root: Path) -> Optional[OpenApiSurface]:
+    """Discover and parse the primary OpenAPI spec under ``root``.
+
+    Returns the surface of the first discovered spec (deterministic ordering),
+    or None when no spec is present.
+    """
+    specs = find_openapi_specs(Path(root))
+    for spec in specs:
+        surface = parse_openapi_spec(spec)
+        if surface is not None and (surface.operations or surface.schemas):
+            return surface
+    return None

sourcecode/repository_ir.py

@@ -3557,8 +3557,9 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     _CONTROLLER_ANNS = {"@RestController", "@Controller"}
     _IMPLEMENTS_RE = _re.compile(r'\bimplements\s+(.+)$')
     _routed_fqns = {route.get("effective_class") for route in routes}
-    interface_defined_controllers: list[str] = []
-    endpoint_warnings: list[str] = []
+    # Collect (controller_fqn, [implemented *Api interfaces]) pairs; resolution
+    # against the OpenAPI spec happens below.
+    _iface_controllers: list[tuple[str, list[str]]] = []
     for sym in all_symbols:
         if sym.type != "class":
             continue
@@ -3573,13 +3574,66 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
         api_ifaces = [i for i in ifaces if i.endswith("Api")]
         if not api_ifaces:
             continue
-        interface_defined_controllers.append(sym.symbol)
-        endpoint_warnings.append(
-            f"{sym.symbol.split('.')[-1]} implements {', '.join(api_ifaces)}: HTTP "
-            "mappings are declared on the implemented interface (commonly generated by "
-            "openapi-generator under target/generated-sources, which is not scanned). "
-            "Endpoint surface for this controller is NOT captured."
-        )
+        _iface_controllers.append((sym.symbol, api_ifaces))
+
+    # Recover the surface of interface-defined controllers from an OpenAPI spec
+    # shipped in the repo (src/main/resources/openapi.yml & co.). The spec is
+    # always present and deterministic — unlike target/generated-sources — so it
+    # lets us populate routes + request-body constraints without a build. A
+    # controller is "resolved" when its implemented *Api interface maps (via tag)
+    # to spec operations; otherwise it keeps the explicit "not captured" warning.
+    _spec_endpoints: list[dict] = []
+    resolved_from_openapi_spec: list[str] = []
+    interface_defined_controllers: list[str] = []
+    endpoint_warnings: list[str] = []
+    _openapi_spec_path: "str | None" = None
+    _iface_to_ops: dict[str, list] = {}
+    if _iface_controllers:
+        from sourcecode.openapi_surface import build_openapi_surface, tag_to_interface
+        _surface = build_openapi_surface(root)
+        if _surface is not None:
+            _openapi_spec_path = _surface.spec_path
+            for _op in _surface.operations:
+                for _tag in _op.tags:
+                    _iface_to_ops.setdefault(tag_to_interface(_tag), []).append(_op)
+        for _fqn, _api_ifaces in _iface_controllers:
+            _matched = [op for i in _api_ifaces for op in _iface_to_ops.get(i, [])]
+            if not _matched:
+                interface_defined_controllers.append(_fqn)
+                endpoint_warnings.append(
+                    f"{_fqn.split('.')[-1]} implements {', '.join(_api_ifaces)}: HTTP "
+                    "mappings are declared on the implemented interface (commonly "
+                    "generated by openapi-generator under target/generated-sources, "
+                    "which is not scanned) and no matching OpenAPI spec operation was "
+                    "found. Endpoint surface for this controller is NOT captured."
+                )
+                continue
+            resolved_from_openapi_spec.append(_fqn)
+            _ctrl_simple = _fqn.split(".")[-1]
+            for _op in _matched:
+                _entry: dict = {
+                    "method": _op.method,
+                    "path": _op.path,
+                    "controller": _ctrl_simple,
+                    "handler": _op.operation_id or "(operation)",
+                    "source": "openapi-spec",
+                    # Security for generated controllers is declared in the spec /
+                    # enforced by the filter chain, not by per-endpoint annotations.
+                    "security": {
+                        "policy": "openapi_spec"
+                        if _op.has_security
+                        else "openapi_spec_unspecified"
+                    },
+                }
+                if _op.request_body_schema and _surface is not None:
+                    _schema = _surface.schemas.get(_op.request_body_schema)
+                    if _schema is not None:
+                        _entry["request_body"] = {
+                            "schema": _op.request_body_schema,
+                            "constraints": [f.to_dict() for f in _schema.fields],
+                            "source": "openapi-spec",
+                        }
+                _spec_endpoints.append(_entry)
 
     endpoints: list[dict] = []
     for route in routes:
@@ -3707,6 +3761,11 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
             if e.get("security", {}).get("policy") == "none_detected"
         )
 
+    # Append spec-recovered endpoints AFTER the security-model heuristics (which
+    # are about annotation/filter/XML coverage of scanned source) so spec-sourced
+    # entries don't skew those signals. They carry their own source provenance.
+    endpoints = endpoints + _spec_endpoints
+
     result: dict[str, Any] = {
         "endpoints": endpoints,
         "total": len(endpoints),
@@ -3720,6 +3779,13 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     if endpoint_warnings:
         result["warnings"] = endpoint_warnings
         result["interface_defined_controllers"] = interface_defined_controllers
+    # Surface what was recovered from the OpenAPI spec, so a consumer knows the
+    # surface is complete (not the legacy "1 of N" blind spot) and where it came from.
+    if resolved_from_openapi_spec:
+        result["resolved_from_openapi_spec"] = resolved_from_openapi_spec
+        result["spec_sourced_endpoints"] = len(_spec_endpoints)
+        if _openapi_spec_path:
+            result["openapi_spec"] = _openapi_spec_path
     return result
 
 

{sourcecode-1.36.5.dist-info → sourcecode-1.38.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.36.5
+Version: 1.38.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.38.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.38.0
 ```
 
 ---

{sourcecode-1.36.5.dist-info → sourcecode-1.38.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=o9c3MUAMMI3cMbNxDQQBYbcvFPS_juLXH25a0Wy8jC0,103
+sourcecode/__init__.py,sha256=Wc32jhD7HMnKWYhdxikcnv_UXHFA2NT--SSeAopG1cA,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=liCwQmLgb5vplohy8arjYxs_HOIv5C9MjLh_gY6bc5Q,44115
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
@@ -7,7 +7,7 @@ sourcecode/cache.py,sha256=1V3vsaODAa2UBJAC0xpvxpmRdriCezQx5Q8JCcfgziE,31892
 sourcecode/canonical_ir.py,sha256=DEwucOPJguLsVtg5cV8mWXNi112l5jmBhv73KGGebVk,24849
 sourcecode/cir_graphs.py,sha256=rZi8JV4ZrAa2WSCeyNa4JIEKQ_yZzDZTsrvVz2KfuKA,8919
 sourcecode/classifier.py,sha256=hKzg-nQ47htqqIUzSGvYxv15cXrA3KgICTwJmdqal0o,8095
-sourcecode/cli.py,sha256=-E7iKh47hQyZGbhy1lM1bxCPUa21XW6zLHurByc7KGc,253149
+sourcecode/cli.py,sha256=b2dzPS2camrLgsBeDmsTKin9skqE0l_xttLvyTXEVgI,251296
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -24,6 +24,7 @@ sourcecode/explain.py,sha256=dVG35YBlpRmbtOXSmspEhoIwDMVApPmLISBy3iigUSc,16913
 sourcecode/file_chunker.py,sha256=3vkM3mDQ5eE_yTPvUgjyjpGFBIjkW6_mrBmIbrylnA8,16444
 sourcecode/file_classifier.py,sha256=A0fEABqtfVu1MfoaxnPAvGpZgneGgVXlJDhT74NYXxE,15314
 sourcecode/flow_analyzer.py,sha256=dSiuY4w49k29jW_EPXUOND9B5uVbuCA7kjnuHi-pIWA,28781
+sourcecode/format_contract.py,sha256=W_V-dWhJyjdMi3gNcQOHjdm2V3ufc262Kp7vdcM9-ZM,3398
 sourcecode/fqn_utils.py,sha256=XLU7zDkNBXz_RZkIUNfpPmp1nekWtqP-fxV92tDV1vg,2158
 sourcecode/git_analyzer.py,sha256=JStxTQXNjBWi_wLdwhsZs9mT-v50cSJIz4Agzn6Kh9I,13362
 sourcecode/graph_analyzer.py,sha256=DHR8fY69oU_Pi4SYaWboX6EoEFrctQKB9dsjpqwGMzw,62403
@@ -31,6 +32,7 @@ sourcecode/license.py,sha256=i_X1bYdobL_z9OVuLiycnWEFSaaNhcKKuTd6G55U3_k,20747
 sourcecode/mcp_nudge.py,sha256=5ELU_ixzh6uA83NXLOZT8h00OhL53okfQdji3jyKOjg,2917
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
 sourcecode/migrate_check.py,sha256=vowVIAxVaHU8vhZUEt-HrWrWM38m6a5INHJQGjEg5E0,55390
+sourcecode/openapi_surface.py,sha256=GgHPC_CUyTLPt2N9eLAWoPmnD1IvIrZzstJrLkvOZwo,14870
 sourcecode/output_budget.py,sha256=Js9yUlfQtPhqBl9R6wn_9UHVjjJc3GtLcqyfjf5t50Q,9869
 sourcecode/path_filters.py,sha256=EN1RGZRvLq5EcPgpjYV_IyCKVlAQQn2bbpEisQ5LpGg,3780
 sourcecode/pr_comment_renderer.py,sha256=smHslxiG14lrytCkq5nFrFu-qTHgA-t-LFYfdrfjz2o,14423
@@ -42,7 +44,7 @@ sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
-sourcecode/repository_ir.py,sha256=JuB0Dl1OMbQN-bd8smuVIIKwesLJJga5rCQyUSRm5xA,191971
+sourcecode/repository_ir.py,sha256=2Gr919ylJnY9Z7fxNOZ0UK0GtJ-YN1UqreUs6mP-NHg,195611
 sourcecode/ris.py,sha256=RcqLVwC-doFcKKViYDkCjZLBqf_wzLES7-F6vHEeWzE,20419
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
@@ -98,8 +100,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
 sourcecode/telemetry/filters.py,sha256=NHa5T-6DaZduQPFuC34jOqHWQgSizM-Ygq8aZ4j19ng,5834
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-1.36.5.dist-info/METADATA,sha256=ogbSzTG2t7MK6U6P2szIf9nfK99AVOFb9OLXoAm2KMw,32243
-sourcecode-1.36.5.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.36.5.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.36.5.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.36.5.dist-info/RECORD,,
+sourcecode-1.38.0.dist-info/METADATA,sha256=fSyrH1y9J5HEZuJc_HjNivpUIyKEnkF2cyJBKsQ-XMI,32243
+sourcecode-1.38.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.38.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.38.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.38.0.dist-info/RECORD,,