inventory_app_client_schemas.py

#!/usr/bin/env python3
"""Inventory Flutter REST schemas and backend OpenAPI coverage.

This is a progress tool for the schema single-source migration. It intentionally
uses static source scanning so it can run before the backend import harness or
Flutter toolchain is available.
"""

from __future__ import annotations

import argparse
import json
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Any

ROOT_DIR = Path(__file__).resolve().parents[2]
APP_SCHEMA_DIR = ROOT_DIR / 'app' / 'lib' / 'backend' / 'schema'
APP_API_DIR = ROOT_DIR / 'app' / 'lib' / 'backend' / 'http' / 'api'
APP_MODELS_DIR = ROOT_DIR / 'app' / 'lib' / 'models'
APP_CLIENT_SPEC_PATH = ROOT_DIR / 'docs' / 'api-reference' / 'app-client-openapi.json'
MODEL_REST_DTO_FILES = (
    APP_MODELS_DIR / 'announcement.dart',
    APP_MODELS_DIR / 'subscription.dart',
    APP_MODELS_DIR / 'user_usage.dart',
)
LOCAL_NON_REST_SCHEMA_FILES = frozenset(
    {
        APP_SCHEMA_DIR / 'bt_device' / 'bt_device.dart',
        APP_SCHEMA_DIR / 'message_event.dart',  # local SSE/WS event schema, not a REST DTO
    }
)

# These helpers parse an SSE transport frame, not an OpenAPI REST response.
# Keep this allowlist exact: adding an entry requires a behavioral parser test
# and must not be used to exempt normal HTTP response DTO decoding.
STREAM_PROTOCOL_DECODER_FUNCTIONS = frozenset(
    {
        (APP_API_DIR / 'messages.dart', 'parseVoiceMessageStreamChunk'),
    }
)

# These helpers inspect a bounded error envelope to choose an application
# control path; they do not decode an OpenAPI response DTO. Keep the allowlist
# exact so normal REST response decoding remains covered by the migration gate.
NON_REST_RESPONSE_DECODER_FUNCTIONS = frozenset(
    {
        (APP_API_DIR / 'conversations.dart', 'isSyncRecoveryWindowExceededResponse'),
    }
)
NON_REST_DECODE_CONTEXTS = frozenset({'stream_protocol', 'error_discriminator'})

CLASS_RE = re.compile(r'^\s*class\s+([A-Za-z_][A-Za-z0-9_]*)\b', re.MULTILINE)
ENUM_RE = re.compile(r'^\s*enum\s+([A-Za-z_][A-Za-z0-9_]*)\b', re.MULTILINE)
FROM_JSON_RE = re.compile(r'\b(?:factory|static)?\s*([A-Za-z_][A-Za-z0-9_]*)?\.?fromJson\s*\(')
TO_JSON_RE = re.compile(r'\btoJson\s*\(')
INTERPOLATION_RE = re.compile(r'\$\{[^}]+\}|\$[A-Za-z_][A-Za-z0-9_]*')
OPENAPI_PARAM_RE = re.compile(r'\{[^}]+\}')
GENERATED_WIRE_RE = re.compile(r"""package:omi/backend/schema/gen/[^'"]+_wire\.g\.dart|wire\.Generated""")
GENERATED_MARKERS = (
    'Generated by',
    'JsonSerializableGenerator',
    'DO NOT EDIT',
)
RAW_DECODE_RE = re.compile(
    r'\bjsonDecode\s*\(|\bjson\.decode\s*\(|\bas\s+(?:Map|List)<[^>]+>|\b[A-Za-z_][A-Za-z0-9_]*\.fromJson\s*\(|\[[\'"][A-Za-z_][A-Za-z0-9_]*[\'"]\]'
)
WIRE_DECODE_RE = re.compile(r'wire\.Generated[A-Za-z0-9_]+\.fromJson|\.fromGenerated\s*\(|fromGeneratedWireJson')


def repo_relative_path(path: Path) -> str:
    """Return a stable repository path for JSON reports and diagnostics."""
    return path.relative_to(ROOT_DIR).as_posix()


def _collect_wire_backed_type_names() -> list[str]:
    """Collect Dart type names whose fromJson delegates to wire.Generated* parsers.

    Covers two patterns:
    - typedefs: ``typedef DevApiKey = wire.GeneratedDevApiKey;``
    - adapter classes with ``factory X.fromGenerated(...)`` or ``static X fromGeneratedWireJson(...)``

    Decode sites that call ``TypeName.fromJson`` for these names are generated-backed
    even though the call-site text doesn't contain ``wire.Generated``.
    """
    names: set[str] = set()
    typedef_re = re.compile(r'^\s*typedef\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*wire\.Generated', re.MULTILINE)
    adapter_re = re.compile(
        r'(?:factory|static)\s+([A-Za-z_][A-Za-z0-9_]*)\.(?:fromGenerated|fromGeneratedWireJson)\s*\('
    )
    for path in sorted(APP_SCHEMA_DIR.rglob('*.dart')):
        if path.name.endswith('.g.dart') or path.name.endswith('.gen.dart'):
            continue
        text = path.read_text(encoding='utf-8')
        names.update(typedef_re.findall(text))
        names.update(adapter_re.findall(text))
    return sorted(names, key=len, reverse=True)  # longest first for alternation


_WIRE_BACKED_NAMES = _collect_wire_backed_type_names()
_WIRE_BACKED_DECODE_RE = (
    re.compile(r'\b(?:' + '|'.join(re.escape(n) for n in _WIRE_BACKED_NAMES) + r')\.(?:fromJson|fromResponseJson)\s*\(')
    if _WIRE_BACKED_NAMES
    else re.compile(r'(?!)')  # never matches
)


@dataclass(frozen=True)
class DartSchemaFile:
    path: Path
    classes: list[str]
    enums: list[str]
    from_json_count: int
    to_json_count: int
    generated: bool
    generated_backed: bool

    def to_report(self) -> dict[str, Any]:
        return {
            'path': repo_relative_path(self.path),
            'classes': self.classes,
            'enums': self.enums,
            'fromJson': self.from_json_count,
            'toJson': self.to_json_count,
            'generated': self.generated,
            'generated_backed': self.generated_backed,
        }


@dataclass(frozen=True)
class AppRoute:
    path: Path
    route: str
    normalized_route: str
    line: int
    function_name: str | None
    function_start_line: int | None
    function_end_line: int | None
    http_method: str | None
    called_function_ranges: tuple[tuple[str, int, int], ...]

    def to_report(self) -> dict[str, Any]:
        return {
            'path': repo_relative_path(self.path),
            'route': self.route,
            'normalized_route': self.normalized_route,
            'line': self.line,
            'function_name': self.function_name,
            'function_start_line': self.function_start_line,
            'function_end_line': self.function_end_line,
            'http_method': self.http_method,
            'called_function_ranges': [
                {'function_name': name, 'function_start_line': start, 'function_end_line': end}
                for name, start, end in self.called_function_ranges
            ],
        }


@dataclass(frozen=True)
class OpenApiOperation:
    path: str
    normalized_path: str
    method: str
    operation_id: str
    unmodeled_success_response: bool
    response_schema: str
    request_schema: str | None

    def to_report(self) -> dict[str, Any]:
        return {
            'path': self.path,
            'normalized_path': self.normalized_path,
            'method': self.method,
            'operation_id': self.operation_id,
            'unmodeled_success_response': self.unmodeled_success_response,
            'response_schema': self.response_schema,
            'request_schema': self.request_schema,
        }


@dataclass(frozen=True)
class DartDecodeSite:
    path: Path
    line: int
    kind: str
    snippet: str
    generated_backed: bool
    context: str

    def to_report(self) -> dict[str, Any]:
        return {
            'path': repo_relative_path(self.path),
            'line': self.line,
            'kind': self.kind,
            'snippet': self.snippet,
            'generated_backed': self.generated_backed,
            'context': self.context,
        }


@dataclass(frozen=True)
class AppOperationManifestItem:
    path: Path
    route: str
    normalized_route: str
    line: int
    function_name: str | None
    function_start_line: int | None
    function_end_line: int | None
    http_method: str | None
    called_function_ranges: tuple[tuple[str, int, int], ...]
    operations: list[OpenApiOperation]
    decode_sites: list[DartDecodeSite]
    raw_decode_scope: str

    def to_report(self) -> dict[str, Any]:
        stream_protocol_sites = [site for site in self.decode_sites if site.context == 'stream_protocol']
        raw_sites = [
            site
            for site in self.decode_sites
            if not site.generated_backed and site.context not in NON_REST_DECODE_CONTEXTS
        ]
        raw_response_sites = [site for site in raw_sites if site.context == 'response_decode']
        raw_request_sites = [site for site in raw_sites if site.context == 'request_encode']
        generated_backed_sites = [site for site in self.decode_sites if site.generated_backed]
        return {
            'path': repo_relative_path(self.path),
            'route': self.route,
            'normalized_route': self.normalized_route,
            'line': self.line,
            'function_name': self.function_name,
            'function_start_line': self.function_start_line,
            'function_end_line': self.function_end_line,
            'http_method': self.http_method,
            'called_function_ranges': [
                {'function_name': name, 'function_start_line': start, 'function_end_line': end}
                for name, start, end in self.called_function_ranges
            ],
            'operations': [operation.to_report() for operation in self.operations],
            'raw_decode_scope': self.raw_decode_scope,
            'decode_site_count': len(self.decode_sites),
            'decode_sites': [site.to_report() for site in self.decode_sites],
            'stream_protocol_decode_site_count': len(stream_protocol_sites),
            'stream_protocol_decode_sites': [site.to_report() for site in stream_protocol_sites],
            'generated_backed_decode_site_count': len(generated_backed_sites),
            'generated_backed_decode_sites': [site.to_report() for site in generated_backed_sites],
            'raw_decode_site_count': len(raw_sites),
            'raw_decode_sites': [site.to_report() for site in raw_sites],
            'raw_response_decode_site_count': len(raw_response_sites),
            'raw_response_decode_sites': [site.to_report() for site in raw_response_sites],
            'raw_request_encode_site_count': len(raw_request_sites),
            'raw_request_encode_sites': [site.to_report() for site in raw_request_sites],
        }


def scan_dart_schema_file(path: Path) -> DartSchemaFile:
    text = path.read_text(encoding='utf-8')
    return DartSchemaFile(
        path=path,
        classes=CLASS_RE.findall(text),
        enums=ENUM_RE.findall(text),
        from_json_count=len(FROM_JSON_RE.findall(text)),
        to_json_count=len(TO_JSON_RE.findall(text)),
        generated=any(marker in text[:500] for marker in GENERATED_MARKERS) or path.name.endswith('.g.dart'),
        generated_backed=bool(
            GENERATED_WIRE_RE.search(text) or WIRE_DECODE_RE.search(text) or _WIRE_BACKED_DECODE_RE.search(text)
        ),
    )


def scan_dart_schemas() -> list[DartSchemaFile]:
    return [
        scan_dart_schema_file(path)
        for path in sorted(APP_SCHEMA_DIR.rglob('*.dart'))
        if not path.name.endswith('.gen.dart')
    ]


def scan_rest_dto_files() -> list[DartSchemaFile]:
    paths = [*sorted(APP_SCHEMA_DIR.rglob('*.dart')), *sorted(APP_API_DIR.glob('*.dart'))]
    paths.extend(path for path in MODEL_REST_DTO_FILES if path.exists())
    return [
        scan_dart_schema_file(path)
        for path in paths
        if not path.name.endswith('.gen.dart')
        and not path.name.endswith('.g.dart')
        and path not in LOCAL_NON_REST_SCHEMA_FILES
    ]


def scan_local_non_rest_schema_files() -> list[DartSchemaFile]:
    return [scan_dart_schema_file(path) for path in sorted(LOCAL_NON_REST_SCHEMA_FILES) if path.exists()]


def decode_site_kind(line: str) -> str:
    if 'jsonDecode' in line or 'json.decode' in line:
        return 'jsonDecode'
    if '.fromJson' in line:
        return 'fromJson'
    if ' as Map<' in line or ' as List<' in line:
        return 'cast'
    return 'field_access'


def decode_site_context(line: str) -> str:
    stripped = line.strip()
    if re.search(r'\b(?:requestBody|request|payload|body|fields)\s*\[', stripped):
        return 'request_encode'
    if re.search(r'\b(?:jsonDecode|json\.decode|response\.body|response\.bodyBytes|decoded|data)\b', stripped):
        return 'response_decode'
    if '.fromJson' in stripped or ' as Map<' in stripped or ' as List<' in stripped:
        return 'response_decode'
    return 'unknown'


def scan_dart_decode_sites() -> list[DartDecodeSite]:
    paths = [*sorted(APP_SCHEMA_DIR.rglob('*.dart')), *sorted(APP_API_DIR.glob('*.dart'))]
    paths.extend(path for path in MODEL_REST_DTO_FILES if path.exists())
    sites: list[DartDecodeSite] = []
    for path in paths:
        if path.name.endswith('.gen.dart') or path.name.endswith('.g.dart') or path in LOCAL_NON_REST_SCHEMA_FILES:
            continue
        lines = path.read_text(encoding='utf-8').splitlines()
        functions = _function_ranges(path.read_text(encoding='utf-8'))
        for index, line in enumerate(lines, start=1):
            stripped = line.strip()
            if not stripped or stripped.startswith('//') or not RAW_DECODE_RE.search(line):
                continue
            window = '\n'.join(lines[max(0, index - 3) : min(len(lines), index + 3)])
            enclosing_function = _enclosing_function(functions, index)
            is_stream_protocol = (
                enclosing_function is not None and (path, enclosing_function.name) in STREAM_PROTOCOL_DECODER_FUNCTIONS
            )
            is_error_discriminator = (
                enclosing_function is not None
                and (path, enclosing_function.name) in NON_REST_RESPONSE_DECODER_FUNCTIONS
            )
            sites.append(
                DartDecodeSite(
                    path=path,
                    line=index,
                    kind=decode_site_kind(line),
                    snippet=stripped[:220],
                    generated_backed=bool(WIRE_DECODE_RE.search(window) or _WIRE_BACKED_DECODE_RE.search(window)),
                    context=(
                        'stream_protocol'
                        if is_stream_protocol
                        else 'error_discriminator' if is_error_discriminator else decode_site_context(line)
                    ),
                )
            )
    return sites


def normalize_app_route(route: str) -> str:
    route = INTERPOLATION_RE.sub('{param}', route)
    route = re.sub(r'(?<=[A-Za-z0-9_-])\{param\}$', '', route)
    route = route.split('?', 1)[0]
    route = re.sub(r'/+', '/', route)
    return '/' + route.lstrip('/')


def normalize_openapi_path(path: str) -> str:
    return OPENAPI_PARAM_RE.sub('{param}', path)


def route_prefix(route: str) -> str:
    parts = route.strip('/').split('/')
    if len(parts) >= 2:
        return '/' + '/'.join(parts[:2])
    if parts and parts[0]:
        return '/' + parts[0]
    return '/'


def _outer_quote_before(text: str, marker_start: int) -> str | None:
    for index in range(marker_start - 1, -1, -1):
        char = text[index]
        if char not in ("'", '"'):
            continue
        backslashes = 0
        cursor = index - 1
        while cursor >= 0 and text[cursor] == '\\':
            backslashes += 1
            cursor -= 1
        if backslashes % 2 == 0:
            return char
    return None


def _dart_string_tail_after_marker(text: str, marker_start: int, marker: str) -> str | None:
    quote = _outer_quote_before(text, marker_start)
    if quote is None:
        return None

    tail: list[str] = []
    cursor = marker_start + len(marker)
    if cursor < len(text) and text[cursor] == '}':
        cursor += 1
    interpolation_depth = 0
    while cursor < len(text):
        char = text[cursor]
        if interpolation_depth == 0 and char == quote:
            return ''.join(tail)
        if char == '$' and cursor + 1 < len(text) and text[cursor + 1] == '{':
            interpolation_depth += 1
            tail.append('${')
            cursor += 2
            continue
        if interpolation_depth > 0 and char in ("'", '"'):
            string_quote = char
            tail.append(char)
            cursor += 1
            while cursor < len(text):
                nested_char = text[cursor]
                tail.append(nested_char)
                cursor += 1
                if nested_char == '\\' and cursor < len(text):
                    tail.append(text[cursor])
                    cursor += 1
                    continue
                if nested_char == string_quote:
                    break
            continue
        if interpolation_depth > 0 and char == '{':
            interpolation_depth += 1
        elif interpolation_depth > 0 and char == '}':
            interpolation_depth -= 1
        tail.append(char)
        cursor += 1
    return None


@dataclass(frozen=True)
class RouteOccurrence:
    route: str
    line: int


@dataclass(frozen=True)
class FunctionRange:
    name: str
    start_line: int
    end_line: int
    text: str


def _scan_marker_route_occurrences(
    text: str, marker: str, *, must_start_with: str | None = None
) -> list[RouteOccurrence]:
    routes: list[RouteOccurrence] = []
    for match in re.finditer(re.escape(marker), text):
        route = _dart_string_tail_after_marker(text, match.start(), marker)
        if route is None:
            continue
        if must_start_with is not None and not route.startswith(must_start_with):
            continue
        routes.append(RouteOccurrence(route=route, line=text.count('\n', 0, match.start()) + 1))
    return routes


def _scan_marker_routes(text: str, marker: str, *, must_start_with: str | None = None) -> list[str]:
    return [
        occurrence.route for occurrence in _scan_marker_route_occurrences(text, marker, must_start_with=must_start_with)
    ]


def _line_start_offsets(text: str) -> list[int]:
    offsets = [0]
    offsets.extend(index + 1 for index, char in enumerate(text) if char == '\n')
    return offsets


def _line_for_offset(line_offsets: list[int], offset: int) -> int:
    line = 1
    for index, start in enumerate(line_offsets, start=1):
        if start > offset:
            break
        line = index
    return line


def _matching_brace_offset(text: str, open_brace: int) -> int | None:
    depth = 0
    in_string: str | None = None
    in_line_comment = False
    in_block_comment = False
    cursor = open_brace
    while cursor < len(text):
        char = text[cursor]
        next_char = text[cursor + 1] if cursor + 1 < len(text) else ''

        if in_line_comment:
            if char == '\n':
                in_line_comment = False
            cursor += 1
            continue
        if in_block_comment:
            if char == '*' and next_char == '/':
                cursor += 2
                in_block_comment = False
            else:
                cursor += 1
            continue
        if in_string:
            if char == '\\':
                cursor += 2
                continue
            if char == in_string:
                in_string = None
            cursor += 1
            continue
        if char in ("'", '"'):
            in_string = char
            cursor += 1
            continue
        if char == '/' and next_char == '/':
            cursor += 2
            in_line_comment = True
            continue
        if char == '/' and next_char == '*':
            cursor += 2
            in_block_comment = True
            continue

        if char == '{':
            depth += 1
        elif char == '}':
            depth -= 1
            if depth == 0:
                return cursor
        cursor += 1
    return None


FUNCTION_START_RE = re.compile(
    r'(?m)^(?P<indent>[ \t]*)(?!class\b|enum\b|typedef\b|mixin\b|extension\b)(?:[A-Za-z_][^\n;=]*[ \t]+)?(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\('
)
HTTP_METHOD_RE = re.compile(r"""\bmethod\s*:\s*['"]([A-Z]+)['"]""")
CONTROL_STATEMENT_NAMES = frozenset({'if', 'for', 'while', 'switch', 'catch'})
METHOD_DECLARATION_PREFIXES = (
    'static ',
    'Future',
    'Stream',
    'void ',
    'bool ',
    'int ',
    'double ',
    'String ',
    'Map<',
    'List<',
)


def _previous_nonempty_line(text: str, offset: int) -> str:
    prefix = text[:offset].splitlines()
    for line in reversed(prefix):
        if line.strip():
            return line
    return ''


def _matching_delimiter_offset(text: str, open_offset: int, open_char: str, close_char: str) -> int | None:
    depth = 0
    cursor = open_offset
    in_string: str | None = None
    in_line_comment = False
    in_block_comment = False

    while cursor < len(text):
        char = text[cursor]
        next_char = text[cursor + 1] if cursor + 1 < len(text) else ''

        if in_line_comment:
            if char == '\n':
                in_line_comment = False
            cursor += 1
            continue
        if in_block_comment:
            if char == '*' and next_char == '/':
                cursor += 2
                in_block_comment = False
            else:
                cursor += 1
            continue
        if in_string:
            if char == '\\':
                cursor += 2
                continue
            if char == in_string:
                in_string = None
            cursor += 1
            continue
        if char in ("'", '"'):
            in_string = char
            cursor += 1
            continue
        if char == '/' and next_char == '/':
            cursor += 2
            in_line_comment = True
            continue
        if char == '/' and next_char == '*':
            cursor += 2
            in_block_comment = True
            continue

        if char == open_char:
            depth += 1
        elif char == close_char:
            depth -= 1
            if depth == 0:
                return cursor
        cursor += 1
    return None


def _function_ranges(text: str) -> list[FunctionRange]:
    line_offsets = _line_start_offsets(text)
    ranges: list[FunctionRange] = []
    for match in FUNCTION_START_RE.finditer(text):
        name = match.group('name')
        if name in CONTROL_STATEMENT_NAMES:
            continue
        if match.group('indent'):
            previous = _previous_nonempty_line(text, match.start())
            stripped_line = text[
                match.start() : text.find('\n', match.start()) if '\n' in text[match.start() :] else len(text)
            ].strip()
            if not stripped_line.startswith(METHOD_DECLARATION_PREFIXES) and (
                previous[:1].isspace() or previous.rstrip().endswith(('{', '}', ';'))
            ):
                continue
        close_paren = _matching_delimiter_offset(text, match.end() - 1, '(', ')')
        if close_paren is None:
            continue
        body_match = re.match(r'\s*(?:async\*?|sync\*?)?\s*\{', text[close_paren + 1 :])
        if body_match is None:
            continue
        open_brace = close_paren + body_match.end()
        close_brace = _matching_brace_offset(text, open_brace)
        if close_brace is None:
            continue
        ranges.append(
            FunctionRange(
                name=name,
                start_line=_line_for_offset(line_offsets, match.start()),
                end_line=_line_for_offset(line_offsets, close_brace),
                text=text[match.start() : close_brace + 1],
            )
        )
    return ranges


def _enclosing_function(functions: list[FunctionRange], line: int) -> FunctionRange | None:
    for function in functions:
        if function.start_line <= line <= function.end_line:
            return function
    return None


def _infer_http_method(function: FunctionRange | None) -> str | None:
    if function is None:
        return None
    method_match = HTTP_METHOD_RE.search(function.text)
    if method_match:
        return method_match.group(1)
    if 'makeStreamingApiCall' in function.text or 'makeMultipart' in function.text:
        return 'POST'
    return None


def _called_function_ranges(
    function: FunctionRange | None, functions: list[FunctionRange]
) -> tuple[tuple[str, int, int], ...]:
    if function is None:
        return ()
    called: list[tuple[str, int, int]] = []
    for candidate in functions:
        if candidate.name == function.name:
            continue
        if re.search(rf'\b{re.escape(candidate.name)}\s*\(', function.text):
            called.append((candidate.name, candidate.start_line, candidate.end_line))
    return tuple(called)


def _mask_dart_comments(text: str) -> str:
    chars = list(text)
    cursor = 0
    in_string: str | None = None
    in_line_comment = False
    in_block_comment = False

    while cursor < len(chars):
        char = chars[cursor]
        next_char = chars[cursor + 1] if cursor + 1 < len(chars) else ''

        if in_line_comment:
            if char == '\n':
                in_line_comment = False
            else:
                chars[cursor] = ' '
            cursor += 1
            continue

        if in_block_comment:
            if char == '*' and next_char == '/':
                chars[cursor] = ' '
                chars[cursor + 1] = ' '
                cursor += 2
                in_block_comment = False
            else:
                if char != '\n':
                    chars[cursor] = ' '
                cursor += 1
            continue

        if in_string:
            if char == '\\' and cursor + 1 < len(chars):
                cursor += 2
                continue
            if char == in_string:
                in_string = None
            cursor += 1
            continue

        if char in ("'", '"'):
            in_string = char
            cursor += 1
            continue

        if char == '/' and next_char == '/':
            chars[cursor] = ' '
            chars[cursor + 1] = ' '
            cursor += 2
            in_line_comment = True
            continue

        if char == '/' and next_char == '*':
            chars[cursor] = ' '
            chars[cursor + 1] = ' '
            cursor += 2
            in_block_comment = True
            continue

        cursor += 1

    return ''.join(chars)


def scan_app_routes() -> list[AppRoute]:
    routes: list[AppRoute] = []
    for path in sorted(APP_API_DIR.glob('*.dart')):
        original_text = path.read_text(encoding='utf-8')
        text = _mask_dart_comments(original_text)
        functions = _function_ranges(original_text)
        env_routes = _scan_marker_route_occurrences(text, 'Env.apiBaseUrl', must_start_with='v')
        base_routes = [
            occurrence
            for occurrence in env_routes
            if _enclosing_function(functions, occurrence.line) is None
            and re.search(rf"""_baseUrl\s*=\s*['"]\$\{{Env\.apiBaseUrl\}}{re.escape(occurrence.route)}['"]""", text)
        ]
        for occurrence in env_routes:
            function = _enclosing_function(functions, occurrence.line)
            if function is None:
                continue
            routes.append(
                AppRoute(
                    path=path,
                    route='/' + occurrence.route.lstrip('/'),
                    normalized_route=normalize_app_route(occurrence.route),
                    line=occurrence.line,
                    function_name=function.name if function else None,
                    function_start_line=function.start_line if function else None,
                    function_end_line=function.end_line if function else None,
                    http_method=_infer_http_method(function),
                    called_function_ranges=_called_function_ranges(function, functions),
                )
            )
        for base_route in base_routes:
            for local_route in _scan_marker_route_occurrences(text, '_baseUrl', must_start_with='/'):
                route = base_route.route.rstrip('/') + local_route.route
                function = _enclosing_function(functions, local_route.line)
                routes.append(
                    AppRoute(
                        path=path,
                        route='/' + route.lstrip('/'),
                        normalized_route=normalize_app_route(route),
                        line=local_route.line,
                        function_name=function.name if function else None,
                        function_start_line=function.start_line if function else None,
                        function_end_line=function.end_line if function else None,
                        http_method=_infer_http_method(function),
                        called_function_ranges=_called_function_ranges(function, functions),
                    )
                )

    unique: dict[tuple[Path, str, str], AppRoute] = {}
    for route in routes:
        unique[(route.path, route.normalized_route, route.http_method or '')] = route
    return sorted(unique.values(), key=lambda item: (str(item.path), item.normalized_route))


def load_openapi_schema_names(path: Path) -> list[str]:
    if not path.exists():
        return []
    spec = json.loads(path.read_text(encoding='utf-8'))
    return sorted(spec.get('components', {}).get('schemas', {}).keys())


def load_openapi_paths(path: Path) -> list[str]:
    if not path.exists():
        return []
    spec = json.loads(path.read_text(encoding='utf-8'))
    return sorted(spec.get('paths', {}).keys())


def is_unmodeled_success_schema(schema: dict[str, Any]) -> bool:
    if schema == {}:
        return True
    return (
        schema.get('type') == 'object'
        and not schema.get('properties')
        and schema.get('additionalProperties')
        in (
            None,
            True,
        )
    )


def operation_has_unmodeled_success_response(operation: dict[str, Any]) -> bool:
    for status_code, response in operation.get('responses', {}).items():
        if not status_code.startswith('2'):
            continue
        content = response.get('content') or {}
        json_content = content.get('application/json')
        if not json_content:
            continue
        schema = json_content.get('schema')
        if isinstance(schema, dict) and is_unmodeled_success_schema(schema):
            return True
    return False


def schema_ref_name(schema: Any) -> str:
    if not isinstance(schema, dict):
        return ''
    ref = schema.get('$ref')
    if isinstance(ref, str):
        return ref.rsplit('/', 1)[-1]
    if 'items' in schema:
        item_name = schema_ref_name(schema['items'])
        return f'array[{item_name}]' if item_name else 'array'
    if schema.get('type'):
        return str(schema['type'])
    if 'anyOf' in schema:
        names = [schema_ref_name(item) for item in schema['anyOf']]
        return ' | '.join(name for name in names if name)
    return ''


def operation_response_schema_name(operation: dict[str, Any]) -> str:
    for status_code, response in operation.get('responses', {}).items():
        if not status_code.startswith('2'):
            continue
        schema = ((response.get('content') or {}).get('application/json') or {}).get('schema')
        name = schema_ref_name(schema)
        if name:
            return name
    return ''


def operation_request_schema_name(operation: dict[str, Any]) -> str | None:
    content = (operation.get('requestBody') or {}).get('content') or {}
    schema = (content.get('application/json') or {}).get('schema')
    name = schema_ref_name(schema)
    return name or None


def load_openapi_operations(path: Path) -> list[OpenApiOperation]:
    if not path.exists():
        return []
    spec = json.loads(path.read_text(encoding='utf-8'))
    operations = []
    for route, methods in spec.get('paths', {}).items():
        for method, operation in methods.items():
            if not isinstance(operation, dict):
                continue
            operations.append(
                OpenApiOperation(
                    path=route,
                    normalized_path=normalize_openapi_path(route),
                    method=method.upper(),
                    operation_id=operation.get('operationId', ''),
                    unmodeled_success_response=operation_has_unmodeled_success_response(operation),
                    response_schema=operation_response_schema_name(operation),
                    request_schema=operation_request_schema_name(operation),
                )
            )
    return sorted(operations, key=lambda item: (item.path, item.method))


def build_operation_manifest(
    app_routes: list[AppRoute],
    openapi_operations: list[OpenApiOperation],
    decode_sites: list[DartDecodeSite],
) -> list[AppOperationManifestItem]:
    operations_by_route: dict[str, list[OpenApiOperation]] = {}
    for operation in openapi_operations:
        operations_by_route.setdefault(operation.normalized_path, []).append(operation)
    decode_sites_by_file: dict[Path, list[DartDecodeSite]] = {}
    for site in decode_sites:
        decode_sites_by_file.setdefault(site.path, []).append(site)

    manifest: list[AppOperationManifestItem] = []
    for route in app_routes:
        operations = operations_by_route.get(route.normalized_route, [])
        if route.http_method:
            operations = [operation for operation in operations if operation.method == route.http_method]
        if not operations:
            continue
        file_decode_sites = decode_sites_by_file.get(route.path, [])
        if route.function_start_line is not None and route.function_end_line is not None:
            route_decode_sites = [
                site for site in file_decode_sites if route.function_start_line <= site.line <= route.function_end_line
            ]
            helper_decode_sites = [
                site
                for site in file_decode_sites
                for _, start_line, end_line in route.called_function_ranges
                if start_line <= site.line <= end_line
            ]
            route_decode_sites = sorted(
                {*route_decode_sites, *helper_decode_sites}, key=lambda site: (site.path, site.line, site.kind)
            )
            scope = 'enclosing_function_and_called_helpers'
        else:
            route_decode_sites = file_decode_sites
            scope = 'dart_api_file'
        manifest.append(
            AppOperationManifestItem(
                path=route.path,
                route=route.route,
                normalized_route=route.normalized_route,
                line=route.line,
                function_name=route.function_name,
                function_start_line=route.function_start_line,
                function_end_line=route.function_end_line,
                http_method=route.http_method,
                called_function_ranges=route.called_function_ranges,
                operations=operations,
                decode_sites=route_decode_sites,
                raw_decode_scope=scope,
            )
        )
    return sorted(manifest, key=lambda item: (str(item.path), item.normalized_route))


def build_report(spec_path: Path) -> dict[str, Any]:
    dart_files = scan_rest_dto_files()
    local_non_rest_files = scan_local_non_rest_schema_files()
    manual_files = [
        item for item in dart_files if not item.generated and (item.from_json_count > 0 or item.to_json_count > 0)
    ]
    generated_backed_files = [item for item in manual_files if item.generated_backed]
    remaining_manual_files = [item for item in manual_files if not item.generated_backed]
    app_routes = scan_app_routes()
    decode_sites = scan_dart_decode_sites()
    raw_decode_sites = [site for site in decode_sites if not site.generated_backed]
    openapi_paths = load_openapi_paths(spec_path)
    openapi_operations = load_openapi_operations(spec_path)
    operation_manifest = build_operation_manifest(app_routes, openapi_operations, decode_sites)
    openapi_prefixes = sorted({route_prefix(path) for path in openapi_paths})
    app_route_prefixes = sorted({route_prefix(route.normalized_route) for route in app_routes})
    uncovered_prefixes = sorted(set(app_route_prefixes) - set(openapi_prefixes))
    app_route_keys = {(route.normalized_route, route.http_method) for route in app_routes if route.http_method}
    app_route_paths_without_method = {route.normalized_route for route in app_routes if not route.http_method}
    app_used_unmodeled_operations = [
        operation
        for operation in openapi_operations
        if operation.unmodeled_success_response
        and (
            (operation.normalized_path, operation.method) in app_route_keys
            or operation.normalized_path in app_route_paths_without_method
        )
    ]
    unmodeled_operations = [operation for operation in openapi_operations if operation.unmodeled_success_response]
    return {
        'dart_schema_dirs': [
            repo_relative_path(APP_SCHEMA_DIR),
            repo_relative_path(APP_API_DIR),
            *(repo_relative_path(path) for path in MODEL_REST_DTO_FILES if path.exists()),
        ],
        'app_client_openapi': repo_relative_path(spec_path),
        'openapi_schema_count': len(load_openapi_schema_names(spec_path)),
        'openapi_schemas': load_openapi_schema_names(spec_path),
        'openapi_path_count': len(openapi_paths),
        'openapi_paths': openapi_paths,
        'openapi_operations': [operation.to_report() for operation in openapi_operations],
        'app_operation_manifest_count': len(operation_manifest),
        'app_operation_manifest': [item.to_report() for item in operation_manifest],
        'unmodeled_success_response_count': len(unmodeled_operations),
        'unmodeled_success_responses': [operation.to_report() for operation in unmodeled_operations],
        'app_used_unmodeled_success_response_count': len(app_used_unmodeled_operations),
        'app_used_unmodeled_success_responses': [operation.to_report() for operation in app_used_unmodeled_operations],
        'app_route_count': len(app_routes),
        'app_routes': [route.to_report() for route in app_routes],
        'dart_decode_site_count': len(decode_sites),
        'dart_decode_sites': [site.to_report() for site in decode_sites],
        'raw_dart_decode_site_count': len(raw_decode_sites),
        'raw_dart_decode_sites': [site.to_report() for site in raw_decode_sites],
        'app_route_prefixes': app_route_prefixes,
        'openapi_prefixes': openapi_prefixes,
        'uncovered_app_route_prefixes': uncovered_prefixes,
        'rest_dto_file_count': len(dart_files),
        'manual_dart_json_schema_file_count': len(manual_files),
        'manual_dart_json_schema_files': [item.to_report() for item in manual_files],
        'generated_backed_adapter_file_count': len(generated_backed_files),
        'generated_backed_adapter_files': [item.to_report() for item in generated_backed_files],
        'remaining_manual_dart_json_schema_file_count': len(remaining_manual_files),
        'remaining_manual_dart_json_schema_files': [item.to_report() for item in remaining_manual_files],
        'local_non_rest_schema_file_count': len(local_non_rest_files),
        'local_non_rest_schema_files': [item.to_report() for item in local_non_rest_files],
    }


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description='Inventory app-client schema migration coverage.')
    parser.add_argument(
        '--spec',
        default=str(APP_CLIENT_SPEC_PATH),
        help='app-client OpenAPI spec path; defaults to docs/api-reference/app-client-openapi.json',
    )
    parser.add_argument('--json', action='store_true', help='emit machine-readable JSON')
    parser.add_argument(
        '--fail-on-uncovered-prefixes',
        action='store_true',
        help='fail when Flutter REST route prefixes are missing from app-client OpenAPI',
    )
    parser.add_argument(
        '--fail-on-manual-rest-dtos',
        action='store_true',
        help='fail when raw hand-written REST DTO JSON parsing remains',
    )
    parser.add_argument(
        '--fail-on-unmodeled-openapi-object-response',
        action='store_true',
        help='fail when app-used OpenAPI operations expose untyped object/empty JSON success responses',
    )
    parser.add_argument(
        '--fail-on-any-unmodeled-openapi-object-response',
        action='store_true',
        help='fail when any app-client OpenAPI operation exposes an untyped object/empty JSON success response',
    )
    parser.add_argument(
        '--fail-on-raw-dart-decode-sites',
        action='store_true',
        help='fail when Dart app-client files contain raw JSON decode/cast/access sites not backed by generated wire parsing',
    )
    parser.add_argument(
        '--fail-on-raw-json-decode-for-openapi-routes',
        action='store_true',
        help='fail when a matched OpenAPI route function still contains raw JSON decode/cast/access sites',
    )
    parser.add_argument(
        '--operation-id',
        action='append',
        default=[],
        help='limit operation-level raw decode checks to this OpenAPI operationId; may be repeated',
    )
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    report = build_report(Path(args.spec))
    if args.fail_on_uncovered_prefixes and report['uncovered_app_route_prefixes']:
        print(
            'Uncovered Flutter REST route prefixes: ' + ', '.join(report['uncovered_app_route_prefixes']),
            flush=True,
        )
        return 1
    if args.fail_on_manual_rest_dtos and report['remaining_manual_dart_json_schema_files']:
        paths = [item['path'] for item in report['remaining_manual_dart_json_schema_files']]
        print('Remaining raw manual Dart JSON schema files: ' + ', '.join(paths), flush=True)
        return 1
    if args.fail_on_unmodeled_openapi_object_response and report['app_used_unmodeled_success_responses']:
        operations = [
            f"{item['method']} {item['path']} ({item['operation_id']})"
            for item in report['app_used_unmodeled_success_responses']
        ]
        print('App-used unmodeled OpenAPI success responses: ' + ', '.join(operations), flush=True)
        return 1
    if args.fail_on_any_unmodeled_openapi_object_response and report['unmodeled_success_responses']:
        operations = [
            f"{item['method']} {item['path']} ({item['operation_id']})"
            for item in report['unmodeled_success_responses']
        ]
        print('Unmodeled OpenAPI success responses: ' + ', '.join(operations), flush=True)
        return 1
    if args.fail_on_raw_dart_decode_sites and report['raw_dart_decode_sites']:
        sites = [f"{item['path']}:{item['line']} ({item['kind']})" for item in report['raw_dart_decode_sites'][:50]]
        print('Raw Dart decode sites: ' + ', '.join(sites), flush=True)
        return 1
    if args.fail_on_raw_json_decode_for_openapi_routes:
        selected_operation_ids = set(args.operation_id)
        items = [
            item
            for item in report['app_operation_manifest']
            if item['raw_decode_site_count']
            and (
                not selected_operation_ids
                or any(operation['operation_id'] in selected_operation_ids for operation in item['operations'])
            )
        ]
        if items:
            routes = [
                f"{item['path']} {item['http_method'] or '*'} {item['normalized_route']} "
                f"{item['function_name'] or '(unknown function)'} "
                f"({item['raw_decode_site_count']} raw decode sites)"
                for item in items[:50]
            ]
            print('OpenAPI route functions with raw Dart decode sites: ' + ', '.join(routes), flush=True)
            return 1
    if args.json:
        print(json.dumps(report, indent=2, sort_keys=True))
        return 0

    print(f"REST DTO candidate files: {report['rest_dto_file_count']}")
    print(f"Manual Dart JSON schema files: {report['manual_dart_json_schema_file_count']}")
    print(f"Generated-backed adapter files: {report['generated_backed_adapter_file_count']}")
    print(f"Remaining raw manual Dart JSON schema files: {report['remaining_manual_dart_json_schema_file_count']}")
    print(f"Local non-REST schema files: {report['local_non_rest_schema_file_count']}")
    print(f"OpenAPI schemas in app-client spec: {report['openapi_schema_count']}")
    print(f"OpenAPI paths in app-client spec: {report['openapi_path_count']}")
    print(f"Unmodeled OpenAPI success responses: {report['unmodeled_success_response_count']}")
    print(f"App-used unmodeled OpenAPI success responses: {report['app_used_unmodeled_success_response_count']}")
    print(f"Flutter REST routes found: {report['app_route_count']}")
    print(f"OpenAPI route manifest entries: {report['app_operation_manifest_count']}")
    print(f"Dart decode sites found: {report['dart_decode_site_count']}")
    print(f"Raw Dart decode sites: {report['raw_dart_decode_site_count']}")
    if report['uncovered_app_route_prefixes']:
        print('Uncovered Flutter REST route prefixes: ' + ', '.join(report['uncovered_app_route_prefixes']))
    for item in report['unmodeled_success_responses']:
        print(f"- unmodeled {item['method']} {item['path']} ({item['operation_id']})")
    for item in report['remaining_manual_dart_json_schema_files']:
        classes = ', '.join(item['classes']) or '(no classes found)'
        print(f"- {item['path']}: {classes} (fromJson={item['fromJson']}, toJson={item['toJson']})")
    for item in report['local_non_rest_schema_files']:
        classes = ', '.join(item['classes']) or '(no classes found)'
        print(f"- local {item['path']}: {classes} (fromJson={item['fromJson']}, toJson={item['toJson']})")
    for item in report['raw_dart_decode_sites'][:50]:
        print(f"- raw {item['path']}:{item['line']} {item['kind']}: {item['snippet']}")
    for item in report['app_operation_manifest'][:50]:
        if item['raw_decode_site_count']:
            operations = ', '.join(
                f"{operation['method']} {operation['operation_id']}" for operation in item['operations']
            )
            print(
                f"- route {item['path']} {item['normalized_route']}: "
                f"{item['raw_decode_site_count']} raw decode sites; {operations}"
            )
    return 0


if __name__ == '__main__':
    raise SystemExit(main())