contract-driven-delivery 2.1.3 → 2.2.0

package/assets/skills/contract-driven-delivery/scripts/validate_api_conformance.py

@@ -0,0 +1,543 @@
+#!/usr/bin/env python3
+"""Code-vs-contract API conformance check.
+
+The other API validator (validate_api_semantic.py) only checks that the
+contract *document* is internally well formed. It never looks at code, so
+frontend and backend can both drift away from the contract without anything
+failing. In a workflow where no human reviews the contract by hand, that
+markdown is only worth what a machine can enforce against real code.
+
+This validator closes that gap. It:
+  1. reads the authoritative endpoint table from contracts/api/api-contract.md
+  2. scans backend source for route declarations (Express/Koa/Fastify/NestJS,
+     Flask/FastAPI/Django, Spring, Go net/http & chi/gin, Laravel, Rails-ish)
+  3. scans frontend source for HTTP call sites (fetch/axios/ky/$http/api.*)
+  4. diffs both against the contract and reports drift
+
+It is intentionally heuristic and stack-agnostic (regex, no per-framework
+parser). To avoid false positives on the many repos that ship this kit, it is
+OFF unless `.cdd/conformance.json` exists with `"enabled": true`. When the
+config is absent it prints a one-line skip notice and exits 0.
+
+Exit codes:
+  0  conformance OK, or skipped (no/disabled config)
+  1  drift found (or, in strict mode, warnings escalated to errors)
+
+Config (.cdd/conformance.json), all keys optional:
+{
+  "enabled": true,
+  "apiPrefixes": ["/api"],          // only FE calls under these prefixes are checked
+  "sourceRoots": ["src", "app"],    // dirs to scan; default: common roots that exist
+  "backendGlobsExt": [".py", ".js", ".ts", ".go", ".java", ".php"],
+  "frontendGlobsExt": [".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte"],
+  "excludeDirs": ["node_modules", "dist", "build", ".git", "tests", "__tests__"],
+  "ignorePaths": ["/health", "/metrics"],  // contract+code paths to ignore (supports trailing *)
+  "checks": {
+    "backendRouteNotInContract": "error",
+    "contractEndpointNotImplemented": "warning",
+    "frontendCallNotInContract": "error"
+  },
+  "strict": false                   // escalate all warnings to errors
+}
+"""
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+CONTRACT_PATH = Path('contracts/api/api-contract.md')
+CONFIG_PATH = Path('.cdd/conformance.json')
+
+VALID_METHODS = {'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'}
+
+DEFAULT_CONFIG = {
+    'enabled': False,
+    'apiPrefixes': ['/api'],
+    'sourceRoots': [],  # auto-detected when empty
+    # No '.rb' by default: Rails routing is a stateful DSL (routes.rb draw block)
+    # that a regex heuristic cannot parse honestly, so it is not claimed here.
+    'backendGlobsExt': ['.py', '.js', '.ts', '.mjs', '.cjs', '.go', '.java', '.php'],
+    'frontendGlobsExt': ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.vue', '.svelte'],
+    'excludeDirs': ['node_modules', 'dist', 'build', '.git', '.cdd', 'coverage',
+                    'vendor', '__pycache__', '.next', '.nuxt'],
+    'ignorePaths': [],
+    'checks': {
+        'backendRouteNotInContract': 'error',
+        'contractEndpointNotImplemented': 'warning',
+        'frontendCallNotInContract': 'error',
+    },
+    'strict': False,
+}
+
+AUTO_ROOTS = ['src', 'app', 'lib', 'server', 'backend', 'frontend', 'web', 'api', 'pages', 'packages']
+
+
+# ── contract parsing (mirrors validate_api_semantic.py table logic) ───────────
+
+def strip_frontmatter(text: str) -> str:
+    if text.startswith('---'):
+        end = text.find('\n---', 3)
+        if end != -1:
+            return text[end + 4:].lstrip('\n')
+    return text
+
+
+def parse_table_row(line: str) -> list:
+    return [cell.strip() for cell in line.strip().strip('|').split('|')]
+
+
+def is_separator_row(cells: list) -> bool:
+    return all(re.match(r'^:?-+:?$', c) for c in cells if c)
+
+
+def find_contract_endpoints(lines: list) -> set:
+    """Return a set of (METHOD, normalized_path) from all '| method |' tables."""
+    in_table = False
+    sep_seen = False
+    endpoints = set()
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or not stripped.startswith('|'):
+            continue
+        cells = parse_table_row(stripped)
+        if not cells:
+            continue
+        if cells[0].lower() == 'method':
+            in_table = True
+            sep_seen = False
+            continue
+        if not in_table:
+            continue
+        if not sep_seen and is_separator_row(cells):
+            sep_seen = True
+            continue
+        if len(cells) < 2 or not any(cells):
+            continue
+        method = cells[0].upper()
+        path = cells[1]
+        if method not in VALID_METHODS or not path.startswith('/'):
+            continue
+        endpoints.add((method, normalize_path(path)))
+    return endpoints
+
+
+# ── path normalization ────────────────────────────────────────────────────────
+
+PARAM_PATTERNS = [
+    re.compile(r'\$\{[^}/]*\}'),             # ${id}          (js template literal) — before {id}
+    re.compile(r':[A-Za-z_][\w]*'),          # :id            (express/rails)
+    re.compile(r'\{[^}/]*\}'),               # {id}           (flask/fastapi/spring)
+    re.compile(r'<[^>/]*>'),                 # <int:id>       (django/flask)
+    re.compile(r'\*\*?'),                    # wildcard segments
+]
+
+
+def normalize_path(path: str) -> str:
+    """Collapse route params and template interpolations to a single token so
+    `/users/:id`, `/users/{id}`, and `/users/${x}` all compare equal."""
+    # strip query string / hash
+    path = path.split('?', 1)[0].split('#', 1)[0]
+    for pat in PARAM_PATTERNS:
+        path = pat.sub('{}', path)
+    # template literal leftovers like /users/`+id+`  -> treat remainder as param
+    path = re.sub(r'`.*$', '{}', path)
+    if not path.startswith('/'):
+        path = '/' + path
+    if len(path) > 1:
+        path = path.rstrip('/')
+    # collapse duplicate slashes
+    path = re.sub(r'/{2,}', '/', path)
+    return path
+
+
+def matches_ignore(path: str, ignore_list: list) -> bool:
+    for ig in ignore_list:
+        ig_norm = normalize_path(ig.rstrip('*'))
+        if ig.endswith('*'):
+            if path == ig_norm or path.startswith(ig_norm.rstrip('/') + '/') or path.startswith(ig_norm):
+                return True
+        elif path == normalize_path(ig):
+            return True
+    return False
+
+
+def under_api_prefix(path: str, prefixes: list) -> bool:
+    if not prefixes:
+        return True
+    for p in prefixes:
+        pn = normalize_path(p)
+        if path == pn or path.startswith(pn.rstrip('/') + '/'):
+            return True
+    return False
+
+
+# ── source scanning ────────────────────────────────────────────────────────────
+
+# Backend route patterns grouped by language. Only the patterns for a file's
+# extension are applied to it, so a Python Flask/Django pattern can never match a
+# PHP or JS file (cross-language false matches were polluting results, e.g. the
+# Flask route regex firing on a Laravel `Route::match` line).
+_JS_BACKEND = [
+    # Express / Koa / Fastify: app.get('/x'), router.post("/x").
+    # Client idioms (api/http/client/request/...) are intentionally excluded —
+    # those are frontend calls, not server routes; counting them as backend
+    # would silently satisfy `contractEndpointNotImplemented`.
+    (re.compile(r'\b(?:app|router|server|fastify|route|routes)\.(get|post|put|delete|patch|options|head|all)\s*\(\s*[\'"`]([^\'"`]+)[\'"`]', re.I), 'verb_first'),
+]
+
+# NestJS: @Controller('users') class prefix + @Get(':id') method decorators.
+# Handled by a dedicated two-pass scanner (scan_nestjs) since the route path is
+# the join of the controller prefix and the per-method decorator argument.
+NEST_CONTROLLER_RE = re.compile(r'@Controller\s*\(\s*[\'"`]?([^\'"`)]*)[\'"`]?\s*\)', re.I)
+NEST_METHOD_RE = re.compile(r'@(Get|Post|Put|Delete|Patch|Options|Head|All)\s*\(\s*[\'"`]?([^\'"`)]*)[\'"`]?\s*\)', re.I)
+_PY_BACKEND = [
+    # FastAPI / APIRouter decorators: @app.get("/x"), @router.post('/x')
+    (re.compile(r'@(?:app|router|\w+)\.(get|post|put|delete|patch|options|head)\s*\(\s*[\'"]([^\'"]+)[\'"]', re.I), 'verb_first'),
+    # Flask: @app.route("/x", methods=["POST"])  (methods captured separately below)
+    (re.compile(r'@(?:app|bp|blueprint|\w+)\.route\s*\(\s*[\'"]([^\'"]+)[\'"]([^)]*)', re.I), 'flask_route'),
+    # Django urls: path("x/", ...)  re_path(r"^x/$", ...)
+    (re.compile(r'\b(?:path|re_path|url)\s*\(\s*r?[\'"]([^\'"]+)[\'"]', re.I), 'path_only'),
+]
+_JAVA_BACKEND = [
+    # Spring: @GetMapping("/x")
+    (re.compile(r'@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?[\'"]([^\'"]+)[\'"]', re.I), 'verb_first'),
+    # Spring: @RequestMapping(value="/x", method=RequestMethod.POST) — method (if
+    # present) is parsed from the call tail so method drift is not wildcarded.
+    (re.compile(r'@RequestMapping\s*\(\s*(?:value\s*=\s*)?[\'"]([^\'"]+)[\'"]([^)]*)', re.I), 'spring_request_mapping'),
+]
+_GO_BACKEND = [
+    # chi/gin/echo/mux: r.Get("/x", ...) router.POST("/x", ...) mux.HandleFunc("/x", ...)
+    (re.compile(r'\b\w+\.(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s*\(\s*"([^"]+)"', re.I), 'verb_first'),
+    (re.compile(r'\b\w+\.HandleFunc\s*\(\s*"([^"]+)"', re.I), 'path_only'),
+]
+_PHP_BACKEND = [
+    # Laravel verb form: Route::get('/x', ...)
+    (re.compile(r'\bRoute::(get|post|put|delete|patch|options|any)\s*\(\s*[\'"]([^\'"]+)[\'"]', re.I), 'verb_first'),
+    # Laravel array form: Route::match(['get','post'], '/x', ...)
+    (re.compile(r'\bRoute::match\s*\(\s*\[([^\]]*)\]\s*,\s*[\'"]([^\'"]+)[\'"]', re.I), 'laravel_match'),
+]
+
+BACKEND_PATTERNS_BY_EXT = {
+    '.js': _JS_BACKEND, '.jsx': _JS_BACKEND, '.mjs': _JS_BACKEND, '.cjs': _JS_BACKEND,
+    '.ts': _JS_BACKEND, '.tsx': _JS_BACKEND,
+    '.py': _PY_BACKEND,
+    '.java': _JAVA_BACKEND,
+    '.go': _GO_BACKEND,
+    '.php': _PHP_BACKEND,
+}
+
+FLASK_METHODS_RE = re.compile(r'methods\s*=\s*\[([^\]]*)\]', re.I)
+SPRING_METHOD_RE = re.compile(r'method\s*=\s*\{?([^)}]*)', re.I)
+
+# Frontend HTTP calls -> list of (method_or_None, raw_path). Only scanned in
+# files with a frontend extension. The path capture allows ${...} template
+# params (normalize_path collapses them) but stops at the closing quote/backtick,
+# a paren, or whitespace.
+_FE_PATH = r"([^`'\")\s]+)"
+_FE_EXTS = {'.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.vue', '.svelte'}
+FRONTEND_PATTERNS = [
+    # axios.get('/x'), ky.post(`/x`), http.put("/x"), $http.delete('/x'), client.patch('/x')
+    (re.compile(r'\b(?:axios|ky|http|\$http|api|client|request|httpClient|fetcher)\.(get|post|put|delete|patch|head|options)\s*\(\s*[`\'"]' + _FE_PATH, re.I), 'verb_first'),
+    # fetch('/x', { method: 'POST' })  — method parsed from the options object below
+    (re.compile(r'\bfetch\s*\(\s*[`\'"]' + _FE_PATH, re.I), 'fetch'),
+    # axios({ url: '/x', method: 'post' }) — method parsed from a nearby window so
+    # config-object method drift is caught instead of wildcarded.
+    (re.compile(r'\burl\s*:\s*[`\'"]' + _FE_PATH, re.I), 'config_object'),
+    # useFetch('/x') / useSWR('/x') — no method on the call site; method-agnostic.
+    (re.compile(r'\b(?:useFetch|useSWR|useQuery)\s*\(\s*[`\'"]' + _FE_PATH, re.I), 'path_only'),
+]
+
+# Look a short window on EITHER side of a config-object `url:` for `method:`
+# (the key order in axios({ method, url }) is not fixed).
+OBJECT_METHOD_RE = re.compile(r'method\s*:\s*[`\'"](\w+)[`\'"]', re.I)
+OBJECT_METHOD_WINDOW = 200
+
+
+def iter_source_files(roots, exts, exclude_dirs):
+    seen = set()
+    excl = set(exclude_dirs)
+    for root in roots:
+        if not os.path.isdir(root):
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in excl and not d.startswith('.')]
+            for fn in filenames:
+                ext = os.path.splitext(fn)[1]
+                if ext not in exts:
+                    continue
+                full = os.path.join(dirpath, fn)
+                if full in seen:
+                    continue
+                seen.add(full)
+                yield full
+
+
+def looks_like_test(path: str) -> bool:
+    base = os.path.basename(path).lower()
+    return ('.test.' in base or '.spec.' in base or base.startswith('test_')
+            or '/tests/' in path.replace('\\', '/') or '/__tests__/' in path.replace('\\', '/'))
+
+
+def _join_route(prefix: str, suffix: str) -> str:
+    parts = [p.strip('/') for p in (prefix, suffix) if p and p.strip('/')]
+    return normalize_path('/' + '/'.join(parts)) if parts else normalize_path('/')
+
+
+def scan_nestjs(text: str):
+    """Yield (METHOD, normalized_path) for NestJS controllers in one file.
+
+    Each method decorator's path is joined with the nearest preceding
+    @Controller(prefix). This is the documented NestJS shape; it deliberately
+    does not try to resolve dynamic prefixes or RouterModule registrations."""
+    controllers = [(m.start(), m.group(1) or '') for m in NEST_CONTROLLER_RE.finditer(text)]
+    if not controllers:
+        return
+    for mm in NEST_METHOD_RE.finditer(text):
+        prefix = ''
+        for pos, pfx in controllers:
+            if pos < mm.start():
+                prefix = pfx
+            else:
+                break
+        method = mm.group(1).upper()
+        method = 'ANY' if method == 'ALL' else method
+        yield (method, _join_route(prefix, mm.group(2) or ''))
+
+
+def scan_backend(roots, exts, exclude_dirs):
+    """Return set of (METHOD, normalized_path). METHOD may be 'ANY'."""
+    routes = set()
+    for path in iter_source_files(roots, exts, exclude_dirs):
+        if looks_like_test(path):
+            continue
+        ext = os.path.splitext(path)[1].lower()
+        patterns = BACKEND_PATTERNS_BY_EXT.get(ext)
+        if not patterns:
+            continue
+        try:
+            text = Path(path).read_text(encoding='utf-8', errors='ignore')
+        except OSError:
+            continue
+        if ext in ('.ts', '.tsx', '.js', '.mjs', '.cjs'):
+            routes.update(scan_nestjs(text))
+        for pat, kind in patterns:
+            for m in pat.finditer(text):
+                if kind == 'verb_first':
+                    method = m.group(1).upper()
+                    raw = m.group(2)
+                    method = 'ANY' if method == 'ALL' else method
+                    routes.add((method, normalize_path(raw)))
+                elif kind == 'flask_route':
+                    raw = m.group(1)
+                    tail = m.group(2) or ''
+                    mm = FLASK_METHODS_RE.search(tail)
+                    if mm:
+                        for meth in re.findall(r'[A-Za-z]+', mm.group(1)):
+                            if meth.upper() in VALID_METHODS:
+                                routes.add((meth.upper(), normalize_path(raw)))
+                    else:
+                        routes.add(('GET', normalize_path(raw)))
+                elif kind == 'path_only':
+                    routes.add(('ANY', normalize_path(m.group(1))))
+                elif kind == 'laravel_match':
+                    methods_raw = m.group(1)
+                    raw = m.group(2)
+                    found = [meth.upper() for meth in re.findall(r'[A-Za-z]+', methods_raw)
+                             if meth.upper() in VALID_METHODS]
+                    for meth in (found or ['ANY']):
+                        routes.add((meth, normalize_path(raw)))
+                elif kind == 'spring_request_mapping':
+                    raw = m.group(1)
+                    tail = m.group(2) or ''
+                    mm = SPRING_METHOD_RE.search(tail)
+                    methods = []
+                    if mm:
+                        # method=RequestMethod.POST  or  method={RequestMethod.GET, RequestMethod.POST}
+                        methods = [tok.upper() for tok in re.findall(r'[A-Za-z]+', mm.group(1))
+                                   if tok.upper() in VALID_METHODS]
+                    for meth in (methods or ['ANY']):
+                        routes.add((meth, normalize_path(raw)))
+    return routes
+
+
+def scan_frontend(roots, exts, exclude_dirs):
+    calls = set()
+    for path in iter_source_files(roots, exts, exclude_dirs):
+        if looks_like_test(path):
+            continue
+        if os.path.splitext(path)[1].lower() not in _FE_EXTS:
+            continue
+        try:
+            text = Path(path).read_text(encoding='utf-8', errors='ignore')
+        except OSError:
+            continue
+        for pat, kind in FRONTEND_PATTERNS:
+            for m in pat.finditer(text):
+                if kind == 'verb_first':
+                    method = m.group(1).upper()
+                    raw = m.group(2)
+                elif kind == 'fetch':
+                    raw = m.group(1)
+                    # Per the fetch spec the default method is GET; look a short
+                    # window past the URL for an explicit `method:` so method
+                    # drift (e.g. DELETE on a GET-only endpoint) is caught.
+                    window = text[m.end():m.end() + OBJECT_METHOD_WINDOW]
+                    mm = OBJECT_METHOD_RE.search(window)
+                    method = mm.group(1).upper() if mm else 'GET'
+                elif kind == 'config_object':
+                    raw = m.group(1)
+                    # axios({ url, method }) — key order is not fixed, so scan a
+                    # window on both sides of the url: token for method:.
+                    lo = max(0, m.start() - OBJECT_METHOD_WINDOW)
+                    window = text[lo:m.end() + OBJECT_METHOD_WINDOW]
+                    mm = OBJECT_METHOD_RE.search(window)
+                    method = mm.group(1).upper() if mm else 'ANY'
+                else:  # path_only
+                    method = 'ANY'
+                    raw = m.group(1)
+                if not raw.startswith('/'):
+                    continue  # skip absolute URLs / relative non-rooted strings
+                calls.add((method, normalize_path(raw)))
+    return calls
+
+
+# ── contract matching ──────────────────────────────────────────────────────────
+
+def contract_has(method: str, path: str, contract: set) -> bool:
+    """A code endpoint conforms if some entry matches the path and the method
+    matches OR *either* side is method-agnostic ('ANY'). Path-only declarations
+    (Go HandleFunc, Django path(), Spring @RequestMapping) register as 'ANY' and
+    must therefore satisfy a concrete contract method, and vice versa."""
+    for c_method, c_path in contract:
+        if c_path != path:
+            continue
+        if method == 'ANY' or c_method == 'ANY' or c_method == method:
+            return True
+    return False
+
+
+def load_config():
+    cfg = dict(DEFAULT_CONFIG)
+    if not CONFIG_PATH.exists():
+        return cfg, False
+    try:
+        user = json.loads(CONFIG_PATH.read_text(encoding='utf-8'))
+    except (OSError, ValueError) as e:
+        print(f'API conformance: .cdd/conformance.json is not valid JSON: {e}')
+        sys.exit(1)
+    cfg.update({k: v for k, v in user.items() if k != 'checks'})
+    if isinstance(user.get('checks'), dict):
+        merged = dict(DEFAULT_CONFIG['checks'])
+        merged.update(user['checks'])
+        cfg['checks'] = merged
+    return cfg, True
+
+
+def resolve_roots(cfg):
+    roots = cfg.get('sourceRoots') or []
+    if roots:
+        return [r for r in roots if os.path.isdir(r)]
+    return [r for r in AUTO_ROOTS if os.path.isdir(r)]
+
+
+def severity(check_name, cfg):
+    sev = cfg['checks'].get(check_name, 'error')
+    if cfg.get('strict') and sev == 'warning':
+        return 'error'
+    return sev
+
+
+def main() -> None:
+    cfg, present = load_config()
+
+    if not present:
+        print('API conformance: skipped (no .cdd/conformance.json; '
+              'add one with "enabled": true to enforce code-vs-contract checks).')
+        sys.exit(0)
+    if not cfg.get('enabled'):
+        print('API conformance: skipped (.cdd/conformance.json has "enabled": false).')
+        sys.exit(0)
+
+    if not CONTRACT_PATH.exists():
+        print(f'API conformance: contract not found: {CONTRACT_PATH}')
+        sys.exit(1)
+
+    body = strip_frontmatter(CONTRACT_PATH.read_text(encoding='utf-8', errors='ignore'))
+    contract = find_contract_endpoints(body.splitlines())
+    if not contract:
+        print('API conformance: no endpoint table found in contract; nothing to check.')
+        sys.exit(0)
+
+    roots = resolve_roots(cfg)
+    if not roots:
+        # Enabled but nothing to scan almost always means a mistyped/missing
+        # sourceRoots. Failing (not exit 0) prevents a config mistake from
+        # silently disabling the drift net while the gate stays green.
+        print('API conformance validation failed:')
+        print('  conformance is enabled but no source roots were found to scan; '
+              'set "sourceRoots" in .cdd/conformance.json to existing directories.')
+        sys.exit(1)
+
+    exclude = cfg['excludeDirs']
+    ignore = cfg['ignorePaths']
+    prefixes = cfg['apiPrefixes']
+
+    backend = scan_backend(roots, set(cfg['backendGlobsExt']), exclude)
+    frontend = scan_frontend(roots, set(cfg['frontendGlobsExt']), exclude)
+
+    errors = []
+    warnings = []
+
+    def emit(check_name, message):
+        (errors if severity(check_name, cfg) == 'error' else warnings).append(message)
+
+    # 1. Backend routes that are not documented in the contract.
+    for method, path in sorted(backend):
+        if matches_ignore(path, ignore):
+            continue
+        if not under_api_prefix(path, prefixes):
+            continue
+        if not contract_has(method, path, contract):
+            emit('backendRouteNotInContract',
+                 f'backend route {method} {path} is not in the API contract')
+
+    # 2. Contract endpoints with no backend implementation found.
+    for method, path in sorted(contract):
+        if matches_ignore(path, ignore):
+            continue
+        if not contract_has(method, path, backend):
+            emit('contractEndpointNotImplemented',
+                 f'contract endpoint {method} {path} has no backend route in scanned source')
+
+    # 3. Frontend calls to paths not in the contract (the FE/BE drift case).
+    for method, path in sorted(frontend):
+        if matches_ignore(path, ignore):
+            continue
+        if not under_api_prefix(path, prefixes):
+            continue
+        if not contract_has(method, path, contract):
+            label = path if method == 'ANY' else f'{method} {path}'
+            emit('frontendCallNotInContract',
+                 f'frontend calls {label} which is not in the API contract')
+
+    print(f'API conformance: contract={len(contract)} endpoint(s), '
+          f'backend={len(backend)} route(s), frontend={len(frontend)} call(s) '
+          f'across roots: {", ".join(roots)}')
+
+    if warnings:
+        print('API conformance warnings:')
+        for w in warnings:
+            print(f'  {w}')
+
+    if errors:
+        print('API conformance validation failed:')
+        for e in errors:
+            print(f'  {e}')
+        sys.exit(1)
+
+    print('API conformance validation passed.')
+
+
+if __name__ == '__main__':
+    main()

package/assets/skills/contract-driven-delivery/scripts/validate_api_semantic.py

@@ -45,6 +45,8 @@ def find_endpoint_table(lines: list[str]) -> list[tuple[int, str]]:
     Find all data rows across ALL '| method |' tables in the document.
     Blank lines and prose between rows do not end collection, making this
     robust to files where content is appended after the original table block.
+    A new markdown heading does end the active table so ADR 0002 schema field
+    tables under `## Schemas` are not misread as endpoint rows.
     """
     in_table = False
     sep_seen = False
@@ -53,6 +55,11 @@ def find_endpoint_table(lines: list[str]) -> list[tuple[int, str]]:
     for i, line in enumerate(lines):
         stripped = line.strip()
 
+        if re.match(r'^#{2,}\s+', stripped):
+            in_table = False
+            sep_seen = False
+            continue
+
         if not stripped:
             continue  # blank lines never end table mode
 
@@ -66,7 +73,7 @@ def find_endpoint_table(lines: list[str]) -> list[tuple[int, str]]:
             continue
 
         # A header row for an endpoint table
-        if cells[0].lower() == 'method':
+        if cells[0].lower() == 'method' and len(cells) > 1 and cells[1].lower() == 'path':
             in_table = True
             sep_seen = False
             continue  # skip header row

package/assets/skills/contract-driven-delivery/scripts/validate_contract_versions.py

@@ -132,6 +132,8 @@ def git_available(root: Path) -> bool:
             ['git', 'rev-parse', '--git-dir'],
             capture_output=True,
             text=True,
+            encoding='utf-8',
+            errors='replace',
             cwd=str(root),
         )
         return r.returncode == 0
@@ -150,6 +152,8 @@ def git_show_head(root: Path, rel_path: str) -> str | None:
             ['git', 'show', f'HEAD:{rel_path}'],
             capture_output=True,
             text=True,
+            encoding='utf-8',
+            errors='replace',
             cwd=str(root),
         )
         if r.returncode == 0: