phy-api-version-audit#

API versioning health auditor — finds unversioned routes, deprecated endpoints missing Sunset headers, hardcoded version strings, mixed versioning strategies, and version gaps before they cause breaking-change incidents.

Companion to phy-api-changelog-gen (spec diff) — this tool scans source code, that tool diffs OpenAPI specs.

What It Detects#

CheckIDSeverityRoute defined without /v{N}/ or /api/v{N}/ prefixUV001MEDIUM@deprecated / DEPRECATED handler with no Sunset: header emissionSU001HIGHClient code with hardcoded /v{N}/ URL string (brittle coupling)HC001LOWMixed versioning strategies in the same codebase (URL + header + query)MX001MEDIUMVersion gap — v1 and v3 registered but no v2VG001LOWDeprecation: header present but no Sunset: header (RFC 8594)SU002MEDIUMVersion in Accept header not validated (any value accepted)AV001MEDIUMRoutes using numeric /v0/ (pre-production leaking to prod)V0001HIGHOpenAPI info.version not matching any route version prefixOA001LOW

How to Use#

Paste this skill into Claude Code and describe your project:

text

/phy-api-version-audit
Scan my Express API in src/routes/ for versioning issues

text

/phy-api-version-audit
Check my FastAPI project at ~/projects/myapi for deprecated endpoints without Sunset headers

text

/phy-api-version-audit
Audit the entire monorepo at ~/work/platform for versioning strategy consistency

The agent will:

1. Detect the tech stack automatically (Express, FastAPI, Django, Spring, Gin, Rails, Laravel)
2. Walk all route definition files
3. Scan for all 9 check patterns
4. Group findings by severity (HIGH → MEDIUM → LOW)
5. Output per-framework fix snippets for every finding
6. Print a CI fail-gate command

---

Implementation#

When invoked, execute the following Python analysis. Ask the user for --root (default .) and optional flags.

python

#!/usr/bin/env python3
"""
phy-api-version-audit — REST API versioning health scanner
Checks for UV001, SU001, HC001, MX001, VG001, SU002, AV001, V0001, OA001
"""
import os
import re
import json
import sys
from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional
from collections import defaultdict

# ─────────────────────────────────────────────────────
# Configuration
# ─────────────────────────────────────────────────────

VERSION_PREFIX_RE = re.compile(
    r'/(?:api/)?v\d+/',
    re.IGNORECASE
)

SKIP_DIRS = {
    '__pycache__', '.git', 'node_modules', 'vendor', '.venv', 'venv',
    'dist', 'build', '.next', 'coverage', 'test', 'tests', 'spec',
    '__tests__', 'e2e', 'fixtures', 'mocks', 'migrations', 'seeds',
}

SKIP_EXTENSIONS = {'.min.js', '.map', '.lock', '.sum', '.mod', '.generated.ts'}

MIN_SEVERITY = os.environ.get('API_AUDIT_MIN_SEVERITY', 'LOW')
CI_MODE = '--ci' in sys.argv
MIN_COUNT = int(next((sys.argv[sys.argv.index('--min-count') + 1]
                      for _ in ['x'] if '--min-count' in sys.argv), 1))

SEVERITY_ORDER = {'HIGH': 0, 'MEDIUM': 1, 'LOW': 2}

# ─────────────────────────────────────────────────────
# Data models
# ─────────────────────────────────────────────────────

@dataclass
class Finding:
    check_id: str
    file: str
    line: int
    matched_text: str
    severity: str       # HIGH / MEDIUM / LOW
    description: str
    fix: str
    framework: str = ''

@dataclass
class VersionStrategyReport:
    url_versioned_files: list = field(default_factory=list)
    header_versioned_files: list = field(default_factory=list)
    query_versioned_files: list = field(default_factory=list)

# ─────────────────────────────────────────────────────
# Framework-specific route patterns
# ─────────────────────────────────────────────────────

# Each entry: (framework_name, route_definition_regex, file_extensions)
ROUTE_DEFINITION_PATTERNS = [
    # Express/Fastify — app.get('/path', ...) or router.post('/path')
    (
        'express',
        re.compile(
            r"""(?:app|router|fastify)\s*\.\s*(?:get|post|put|patch|delete|head|options)\s*\(\s*['"]([^'"]+)['"]""",
            re.IGNORECASE
        ),
        {'.js', '.ts', '.mjs', '.cjs'}
    ),
    # Express app.use('/prefix', router)
    (
        'express-use',
        re.compile(
            r"""(?:app|router)\s*\.\s*use\s*\(\s*['"]([^'"]+)['"]""",
            re.IGNORECASE
        ),
        {'.js', '.ts', '.mjs', '.cjs'}
    ),
    # FastAPI — @app.get('/path') or @router.post('/path')
    (
        'fastapi',
        re.compile(
            r"""@(?:app|router|APIRouter\(\))\s*\.\s*(?:get|post|put|patch|delete|head|options)\s*\(\s*['"]([^'"]+)['"]""",
            re.IGNORECASE
        ),
        {'.py'}
    ),
    # Flask — @app.route('/path') or @bp.route('/path')
    (
        'flask',
        re.compile(
            r"""@(?:\w+)\.route\s*\(\s*['"]([^'"]+)['"]""",
            re.IGNORECASE
        ),
        {'.py'}
    ),
    # Django urls.py — path('endpoint/', view)
    (
        'django',
        re.compile(
            r"""(?:path|re_path|url)\s*\(\s*['"]([^'"]+)['"]""",
            re.IGNORECASE
        ),
        {'.py'}
    ),
    # Spring Boot — @GetMapping, @PostMapping, @RequestMapping
    (
        'spring',
        re.compile(
            r"""@(?:Get|Post|Put|Patch|Delete|Request)Mapping\s*(?:\(\s*(?:value\s*=\s*)?['"]([^'"]+)['"]|\(\s*\{?['"]([^'"]+)['"])""",
            re.IGNORECASE
        ),
        {'.java', '.kt'}
    ),
    # Gin (Go) — r.GET("/path") or group.POST("/path")
    (
        'gin',
        re.compile(
            r"""\.(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(\s*"([^"]+)"""
        ),
        {'.go'}
    ),
    # Echo (Go) — e.GET("/path") or g.POST("/path")
    (
        'echo',
        re.compile(
            r"""(?:e|g|group|api)\s*\.\s*(?:GET|POST|PUT|PATCH|DELETE)\s*\(\s*"([^"]+)"""
        ),
        {'.go'}
    ),
    # Go net/http — http.HandleFunc("/path", ...)
    (
        'net/http',
        re.compile(
            r"""http\.HandleFunc\s*\(\s*"([^"]+)"""
        ),
        {'.go'}
    ),
    # Rails routes.rb — get 'path', post 'path', resources :name
    (
        'rails',
        re.compile(
            r"""^\s*(?:get|post|put|patch|delete|resources|resource|namespace|scope)\s+['"]([^'"]+)['"]""",
            re.MULTILINE
        ),
        {'.rb'}
    ),
    # Laravel — Route::get('/path', ...) or Route::resource('/path', ...)
    (
        'laravel',
        re.compile(
            r"""Route\s*::\s*(?:get|post|put|patch|delete|resource|apiResource)\s*\(\s*['"]([^'"]+)['"]""",
            re.IGNORECASE
        ),
        {'.php'}
    ),
]

# Routes that are intentionally unversioned (health checks, auth, static)
UNVERSIONED_WHITELIST = re.compile(
    r'^/?(?:health|ping|ready|live|status|metrics|favicon|robots\.txt|'
    r'static|public|assets|auth|oauth|login|logout|signup|register|'
    r'webhook|webhooks|ws|wss|\.|_).*',
    re.IGNORECASE
)

# ─────────────────────────────────────────────────────
# Sunset / Deprecation header patterns
# ─────────────────────────────────────────────────────

DEPRECATED_MARKER_RE = re.compile(
    r'(?:@deprecated|DEPRECATED|deprecated\s*[:=]|is_deprecated|mark.*deprecated|'
    r'deprecat.*route|deprecat.*endpoint)',
    re.IGNORECASE
)

SUNSET_HEADER_RE = re.compile(
    r"""['"]Sunset['"]|res\.(?:set|header|setHeader)\s*\(\s*['"]Sunset['"]|"""
    r"""add_header\s+Sunset|response\.headers\[['"]sunset|X-Sunset""",
    re.IGNORECASE
)

DEPRECATION_HEADER_RE = re.compile(
    r"""['"]Deprecation['"]|Deprecation.*header|res\.(?:set|header|setHeader)\s*\(\s*['"]Deprecation""",
    re.IGNORECASE
)

# ─────────────────────────────────────────────────────
# Hardcoded version string patterns (client code)
# ─────────────────────────────────────────────────────

HARDCODED_VERSION_RE = re.compile(
    r"""(?:fetch|axios|requests\.(?:get|post|put|patch|delete)|http\.(?:get|post)|"""
    r"""urllib|httpx|RestTemplate|WebClient|Net::HTTP|curl|wget)\s*[(\[]?\s*['"`]"""
    r"""([^'"`]*?/v\d+/[^'"`]*?)['"`]""",
    re.IGNORECASE
)

HARDCODED_VERSION_CONST_RE = re.compile(
    r"""(?:const|let|var|BASE_URL|API_URL|API_BASE|baseUrl|apiUrl)\s*[=:]\s*['"`]"""
    r"""([^'"`]*?/v\d+/?)['"`]""",
    re.IGNORECASE
)

# ─────────────────────────────────────────────────────
# Versioning strategy detection
# ─────────────────────────────────────────────────────

HEADER_VERSION_RE = re.compile(
    r"""[xX]-[aA][pP][iI]-[vV]ersion|api-version|Accept.*version=\d|"""
    r"""vnd\.\w+\.v\d+\+|content-type.*version|x-version""",
    re.IGNORECASE
)

QUERY_VERSION_RE = re.compile(
    r"""[?&]version=\d|req\.query\.version|request\.GET\[.version|"""
    r"""params\[:version\]|request\.query_params\[.version""",
    re.IGNORECASE
)

V0_ROUTE_RE = re.compile(r'/v0/', re.IGNORECASE)

# ─────────────────────────────────────────────────────
# OpenAPI spec parsing
# ─────────────────────────────────────────────────────

def find_openapi_version(root: Path) -> Optional[str]:
    """Find version string from openapi.json or openapi.yaml."""
    for name in ['openapi.json', 'openapi.yaml', 'openapi.yml',
                 'swagger.json', 'swagger.yaml', 'swagger.yml']:
        spec_path = root / name
        if not spec_path.exists():
            # Search recursively up to 3 levels deep
            for p in root.rglob(name):
                spec_path = p
                break
        if spec_path.exists():
            try:
                content = spec_path.read_text(errors='ignore')
                m = re.search(r"""['""]version['""]:\s*['""]([^'""]+)['""]""", content)
                if m:
                    return m.group(1)
                m = re.search(r"""^version:\s*['""]?([^\s'""\n]+)""", content, re.MULTILINE)
                if m:
                    return m.group(1)
            except Exception:
                pass
    return None

# ─────────────────────────────────────────────────────
# File walker
# ─────────────────────────────────────────────────────

def walk_files(root: Path, extensions: set[str]):
    """Yield (path, content) for all relevant source files."""
    for dirpath, dirnames, filenames in os.walk(root):
        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith('.')]
        for fname in filenames:
            fpath = Path(dirpath) / fname
            ext = fpath.suffix.lower()
            if ext not in extensions:
                continue
            if any(fpath.name.endswith(s) for s in SKIP_EXTENSIONS):
                continue
            # Skip files under test/spec directories
            parts = fpath.parts
            if any(p in {'test', 'tests', 'spec', '__tests__', 'e2e', 'fixtures'} for p in parts):
                continue
            try:
                content = fpath.read_text(errors='ignore')
                yield fpath, content
            except Exception:
                continue

# ─────────────────────────────────────────────────────
# Check: UV001 — Unversioned routes
# ─────────────────────────────────────────────────────

def check_unversioned_routes(root: Path) -> list[Finding]:
    findings = []
    all_exts = set()
    for _, _, exts in ROUTE_DEFINITION_PATTERNS:
        all_exts |= exts

    for fpath, content in walk_files(root, all_exts):
        ext = fpath.suffix.lower()
        lines = content.split('\n')
        for fw_name, pattern, fw_exts in ROUTE_DEFINITION_PATTERNS:
            if ext not in fw_exts:
                continue
            for m in pattern.finditer(content):
                route = m.group(1) or (m.group(2) if m.lastindex >= 2 else '')
                if not route:
                    continue
                # Skip whitelisted paths
                if UNVERSIONED_WHITELIST.match(route):
                    continue
                # Skip if already versioned
                if VERSION_PREFIX_RE.search(route):
                    continue
                # Skip pure wildcards, parameters-only, and root /
                if route in ('/', '*', '') or route.startswith('/:') or route.startswith('{'):
                    continue
                # Skip Rails resource names (no slash = resource name, not path)
                if fw_name == 'rails' and '/' not in route:
                    continue
                line_no = content[:m.start()].count('\n') + 1
                findings.append(Finding(
                    check_id='UV001',
                    file=str(fpath),
                    line=line_no,
                    matched_text=f'{fw_name}: {route!r}',
                    severity='MEDIUM',
                    description=f'Route "{route}" has no version prefix (/v1/, /api/v1/)',
                    fix=_uv001_fix(fw_name, route),
                    framework=fw_name,
                ))
    return findings

def _uv001_fix(framework: str, route: str) -> str:
    versioned = f'/v1{route}' if route.startswith('/') else f'/v1/{route}'
    fixes = {
        'express': f'Change route to "{versioned}" or register under a versioned router:\n  const v1 = express.Router();\n  app.use("/v1", v1);\n  v1.get("{route}", handler);',
        'express-use': f'app.use("/v1", router); // prefix all routes in this sub-router',
        'fastapi': f'Change to @router.get("{versioned}") or use APIRouter(prefix="/v1")',
        'flask': f'Use Blueprint with url_prefix="/v1" or change to @bp.route("{versioned}")',
        'django': f'Wrap in path("v1/", include("your_app.urls")) in root urls.py',
        'spring': f'Change to @RequestMapping("/v1{route}") or @GetMapping("/v1{route}")',
        'gin': f'v1 := r.Group("/v1")\nv1.GET("{route}", handler)',
        'echo': f'v1 := e.Group("/v1")\nv1.GET("{route}", handler)',
        'net/http': f'http.HandleFunc("/v1{route}", handler)',
        'rails': f'namespace :v1 do\n  get "{route}", to: "controller#action"\nend',
        'laravel': f'Route::prefix("v1")->group(function () {{\n  Route::get("{route}", handler);\n}});',
    }
    return fixes.get(framework, f'Add version prefix: {versioned}')

# ─────────────────────────────────────────────────────
# Check: SU001 — Deprecated without Sunset header
# ─────────────────────────────────────────────────────

def check_deprecated_without_sunset(root: Path) -> list[Finding]:
    findings = []
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php'}

    for fpath, content in walk_files(root, all_exts):
        lines = content.split('\n')
        for i, line in enumerate(lines):
            if not DEPRECATED_MARKER_RE.search(line):
                continue
            # Check ±30 lines for Sunset header
            window_start = max(0, i - 5)
            window_end = min(len(lines), i + 30)
            window = '\n'.join(lines[window_start:window_end])
            if SUNSET_HEADER_RE.search(window):
                continue  # Sunset found nearby, skip
            findings.append(Finding(
                check_id='SU001',
                file=str(fpath),
                line=i + 1,
                matched_text=line.strip()[:120],
                severity='HIGH',
                description='Deprecated endpoint has no Sunset header (RFC 8594). Clients cannot plan migration.',
                fix=_su001_fix(fpath.suffix),
                framework=_detect_framework_from_ext(fpath.suffix),
            ))
    return findings

def _su001_fix(ext: str) -> str:
    fixes = {
        '.js': 'res.set("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT");\nres.set("Deprecation", "true");\nres.set("Link", "</v2/resource>; rel=\\"successor-version\\"");',
        '.ts': 'res.setHeader("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT");\nres.setHeader("Deprecation", "true");',
        '.py': 'response.headers["Sunset"] = "Sat, 31 Dec 2026 23:59:59 GMT"\nresponse.headers["Deprecation"] = "true"',
        '.java': 'return ResponseEntity.ok(body)\n  .header("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT")\n  .header("Deprecation", "true")\n  .build();',
        '.kt': 'return ResponseEntity.ok(body)\n  .header("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT")\n  .build()',
        '.go': 'w.Header().Set("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT")\nw.Header().Set("Deprecation", "true")',
        '.rb': 'response.headers["Sunset"] = "Sat, 31 Dec 2026 23:59:59 GMT"\nresponse.headers["Deprecation"] = "true"',
        '.php': 'header("Sunset: Sat, 31 Dec 2026 23:59:59 GMT");\nheader("Deprecation: true");',
    }
    return fixes.get(ext, 'Add Sunset: <RFC 5322 date> response header (RFC 8594)')

# ─────────────────────────────────────────────────────
# Check: SU002 — Deprecation header without Sunset
# ─────────────────────────────────────────────────────

def check_deprecation_without_sunset(root: Path) -> list[Finding]:
    findings = []
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php'}

    for fpath, content in walk_files(root, all_exts):
        lines = content.split('\n')
        for i, line in enumerate(lines):
            if not DEPRECATION_HEADER_RE.search(line):
                continue
            window_start = max(0, i - 3)
            window_end = min(len(lines), i + 10)
            window = '\n'.join(lines[window_start:window_end])
            if SUNSET_HEADER_RE.search(window):
                continue
            findings.append(Finding(
                check_id='SU002',
                file=str(fpath),
                line=i + 1,
                matched_text=line.strip()[:120],
                severity='MEDIUM',
                description='`Deprecation` header set without accompanying `Sunset` date. RFC 8594 §4 requires both.',
                fix='Add: Sunset: Sat, 31 Dec 2026 23:59:59 GMT',
                framework=_detect_framework_from_ext(fpath.suffix),
            ))
    return findings

# ─────────────────────────────────────────────────────
# Check: HC001 — Hardcoded version strings
# ─────────────────────────────────────────────────────

def check_hardcoded_versions(root: Path) -> list[Finding]:
    findings = []
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php',
                '.mjs', '.cjs', '.jsx', '.tsx'}

    for fpath, content in walk_files(root, all_exts):
        # Skip server-side route files for this check (they SHOULD define versions)
        fname_lower = fpath.name.lower()
        if any(x in fname_lower for x in ('route', 'router', 'urls', 'endpoint', 'controller')):
            continue
        lines = content.split('\n')
        for pattern in (HARDCODED_VERSION_RE, HARDCODED_VERSION_CONST_RE):
            for m in pattern.finditer(content):
                url = m.group(1)
                line_no = content[:m.start()].count('\n') + 1
                line_text = lines[line_no - 1].strip()
                # Skip tests
                if 'test' in line_text.lower() or 'expect(' in line_text or 'assert' in line_text:
                    continue
                findings.append(Finding(
                    check_id='HC001',
                    file=str(fpath),
                    line=line_no,
                    matched_text=line_text[:120],
                    severity='LOW',
                    description=f'Hardcoded version string in URL: "{url}" — version bumps require source edits',
                    fix='Extract to a constant: const API_BASE = process.env.API_BASE_URL || "https://api.example.com/v1"\nOr use a versioned SDK client.',
                    framework='client',
                ))
    return findings

# ─────────────────────────────────────────────────────
# Check: MX001 — Mixed versioning strategies
# ─────────────────────────────────────────────────────

def check_mixed_strategies(root: Path) -> list[Finding]:
    findings = []
    url_files, header_files, query_files = [], [], []
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php'}

    for fpath, content in walk_files(root, all_exts):
        if VERSION_PREFIX_RE.search(content):
            url_files.append(str(fpath))
        if HEADER_VERSION_RE.search(content):
            header_files.append(str(fpath))
        if QUERY_VERSION_RE.search(content):
            query_files.append(str(fpath))

    strategies_used = sum([
        bool(url_files),
        bool(header_files),
        bool(query_files),
    ])

    if strategies_used >= 2:
        strategy_desc = []
        if url_files:
            strategy_desc.append(f'URL versioning in {len(url_files)} files')
        if header_files:
            strategy_desc.append(f'header versioning (X-API-Version / Accept) in {len(header_files)} files')
        if query_files:
            strategy_desc.append(f'query-param versioning in {len(query_files)} files')

        findings.append(Finding(
            check_id='MX001',
            file='<codebase-wide>',
            line=0,
            matched_text='; '.join(strategy_desc),
            severity='MEDIUM',
            description='Multiple API versioning strategies detected in the same codebase. Clients cannot reliably discover the correct strategy.',
            fix='Pick one strategy and apply consistently:\n'
                '  • URL versioning (/v1/): simplest, most widely supported, recommended for public APIs\n'
                '  • Header versioning (X-API-Version: 1): cleaner URLs, but harder to test in browser\n'
                '  • Content negotiation (Accept: application/vnd.api+json;version=1): REST-purist, complex\n'
                'Document the chosen strategy in your OpenAPI spec info.description.',
            framework='architecture',
        ))
    return findings

# ─────────────────────────────────────────────────────
# Check: VG001 — Version gaps
# ─────────────────────────────────────────────────────

def check_version_gaps(root: Path) -> list[Finding]:
    """Find registered versions and report gaps (e.g. v1 and v3 but no v2)."""
    findings = []
    registered_versions: set[int] = set()
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php',
                '.mjs', '.cjs'}
    version_re = re.compile(r'/v(\d+)/', re.IGNORECASE)

    for fpath, content in walk_files(root, all_exts):
        for m in version_re.finditer(content):
            v = int(m.group(1))
            if 1 <= v <= 20:   # sanity bound
                registered_versions.add(v)

    if len(registered_versions) >= 2:
        sorted_versions = sorted(registered_versions)
        expected = set(range(sorted_versions[0], sorted_versions[-1] + 1))
        gaps = expected - registered_versions
        if gaps:
            findings.append(Finding(
                check_id='VG001',
                file='<codebase-wide>',
                line=0,
                matched_text=f'Registered: {sorted(registered_versions)}, Missing: {sorted(gaps)}',
                severity='LOW',
                description=f'Version gap detected — versions {sorted(gaps)} are missing between v{sorted_versions[0]} and v{sorted_versions[-1]}.',
                fix='Either add stubs for missing versions that redirect to the latest compatible version, or document the intentional skip in your API changelog.',
                framework='architecture',
            ))
    return findings

# ─────────────────────────────────────────────────────
# Check: AV001 — Accept header version not validated
# ─────────────────────────────────────────────────────

def check_accept_version_validation(root: Path) -> list[Finding]:
    """Detect when code reads Accept header for versioning but has no validation."""
    findings = []
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php'}
    accept_read_re = re.compile(
        r"""req\.(?:get|header|headers)\s*\(\s*['"]accept['"]|"""
        r"""request\.headers\.get\s*\(\s*['"]accept['"]|"""
        r"""request\.META\[.HTTP_ACCEPT|"""
        r"""r\.Header\.Get\s*\(\s*"Accept"""",
        re.IGNORECASE
    )
    validation_re = re.compile(
        r"""vnd\.|version\s*==|version\s*in\s*\[|SUPPORTED_VERSIONS|allowed_versions|"""
        r"""version_map|switch.*version|if.*version.*==\s*['"]?\d""",
        re.IGNORECASE
    )

    for fpath, content in walk_files(root, all_exts):
        if not HEADER_VERSION_RE.search(content):
            continue
        lines = content.split('\n')
        for i, line in enumerate(lines):
            if not accept_read_re.search(line):
                continue
            window = '\n'.join(lines[max(0, i-2):min(len(lines), i+15)])
            if validation_re.search(window):
                continue
            findings.append(Finding(
                check_id='AV001',
                file=str(fpath),
                line=i + 1,
                matched_text=line.strip()[:120],
                severity='MEDIUM',
                description='Accept header read for version negotiation but no version validation found. Any value will be accepted silently.',
                fix='Add explicit version validation:\n'
                    'const SUPPORTED = ["application/vnd.api.v1+json", "application/vnd.api.v2+json"];\n'
                    'if (!SUPPORTED.includes(req.get("Accept"))) {\n'
                    '  return res.status(406).json({error: "Unsupported API version"});\n'
                    '}',
                framework=_detect_framework_from_ext(fpath.suffix),
            ))
    return findings

# ─────────────────────────────────────────────────────
# Check: V0001 — /v0/ routes in production code
# ─────────────────────────────────────────────────────

def check_v0_routes(root: Path) -> list[Finding]:
    findings = []
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php',
                '.mjs', '.cjs'}

    for fpath, content in walk_files(root, all_exts):
        lines = content.split('\n')
        for i, line in enumerate(lines):
            if V0_ROUTE_RE.search(line):
                findings.append(Finding(
                    check_id='V0001',
                    file=str(fpath),
                    line=i + 1,
                    matched_text=line.strip()[:120],
                    severity='HIGH',
                    description='/v0/ route found in production code. v0 conventionally signals unstable/pre-release and should never be exposed publicly.',
                    fix='Rename /v0/ to /v1/ before production deployment. If this is intentionally internal, add a middleware that rejects requests from external IPs.',
                    framework=_detect_framework_from_ext(fpath.suffix),
                ))
    return findings

# ─────────────────────────────────────────────────────
# Check: OA001 — OpenAPI version mismatch
# ─────────────────────────────────────────────────────

def check_openapi_version_mismatch(root: Path, registered_versions: set[int]) -> list[Finding]:
    findings = []
    spec_version = find_openapi_version(root)
    if not spec_version or not registered_versions:
        return []
    # Extract major version number from semver like "1.3.2" → 1
    m = re.match(r'v?(\d+)', spec_version)
    if not m:
        return []
    spec_major = int(m.group(1))
    max_route_version = max(registered_versions)
    if spec_major != max_route_version:
        findings.append(Finding(
            check_id='OA001',
            file='openapi.yaml (or similar)',
            line=0,
            matched_text=f'OpenAPI info.version: {spec_version}, highest route version: v{max_route_version}',
            severity='LOW',
            description='OpenAPI spec version does not match highest route version prefix. Clients relying on spec metadata may target the wrong version.',
            fix=f'Update info.version in openapi.yaml to "{max_route_version}.0.0" to match the latest route version.',
            framework='openapi',
        ))
    return findings

# ─────────────────────────────────────────────────────
# Helpers
# ─────────────────────────────────────────────────────

def _detect_framework_from_ext(ext: str) -> str:
    return {'.js': 'express', '.ts': 'express/nestjs', '.py': 'fastapi/flask/django',
            '.java': 'spring', '.kt': 'spring-kotlin', '.go': 'gin/echo',
            '.rb': 'rails', '.php': 'laravel'}.get(ext.lower(), 'unknown')

def deduplicate(findings: list[Finding]) -> list[Finding]:
    seen: set[tuple] = set()
    result = []
    for f in findings:
        key = (f.check_id, f.file, f.line)
        if key not in seen:
            seen.add(key)
            result.append(f)
    return result

# ─────────────────────────────────────────────────────
# Main runner
# ─────────────────────────────────────────────────────

def run_audit(root: Path) -> int:
    print(f"\n🔍  phy-api-version-audit — scanning {root}\n{'─'*60}")

    all_findings: list[Finding] = []

    # Collect registered versions for VG001 / OA001
    registered_versions: set[int] = set()
    version_re = re.compile(r'/v(\d+)/', re.IGNORECASE)
    all_exts = {'.js', '.ts', '.py', '.java', '.kt', '.go', '.rb', '.php', '.mjs', '.cjs'}
    for _, content in walk_files(root, all_exts):
        for m in version_re.finditer(content):
            v = int(m.group(1))
            if 1 <= v <= 20:
                registered_versions.add(v)

    checks = [
        ('UV001 — Unversioned routes', check_unversioned_routes(root)),
        ('SU001 — Deprecated without Sunset', check_deprecated_without_sunset(root)),
        ('SU002 — Deprecation without Sunset date', check_deprecation_without_sunset(root)),
        ('HC001 — Hardcoded version strings', check_hardcoded_versions(root)),
        ('MX001 — Mixed versioning strategies', check_mixed_strategies(root)),
        ('VG001 — Version gaps', check_version_gaps(root)),
        ('AV001 — Accept version not validated', check_accept_version_validation(root)),
        ('V0001 — v0 routes in production', check_v0_routes(root)),
        ('OA001 — OpenAPI version mismatch', check_openapi_version_mismatch(root, registered_versions)),
    ]

    for label, findings in checks:
        findings = deduplicate(findings)
        if findings:
            all_findings.extend(findings)

    # Filter by minimum severity
    severity_threshold = SEVERITY_ORDER.get(MIN_SEVERITY, 2)
    all_findings = [f for f in all_findings
                    if SEVERITY_ORDER.get(f.severity, 2) <= severity_threshold]

    # Sort: HIGH first, then by file/line
    all_findings.sort(key=lambda f: (SEVERITY_ORDER.get(f.severity, 2), f.file, f.line))

    # ── Output ──────────────────────────────────────────────
    if not all_findings:
        print("✅  No versioning issues found.")
        return 0

    high_count = sum(1 for f in all_findings if f.severity == 'HIGH')
    med_count = sum(1 for f in all_findings if f.severity == 'MEDIUM')
    low_count = sum(1 for f in all_findings if f.severity == 'LOW')

    print(f"Found {len(all_findings)} issue(s): "
          f"🔴 HIGH={high_count}  🟡 MEDIUM={med_count}  🔵 LOW={low_count}\n")

    current_severity = None
    for f in all_findings:
        if f.severity != current_severity:
            current_severity = f.severity
            emoji = {'HIGH': '🔴', 'MEDIUM': '🟡', 'LOW': '🔵'}.get(f.severity, '⚪')
            print(f"\n{emoji} {f.severity} ISSUES\n{'─'*50}")

        loc = f'{f.file}:{f.line}' if f.line else f.file
        print(f"\n[{f.check_id}] {loc}")
        print(f"  {f.description}")
        print(f"  Matched: {f.matched_text}")
        print(f"  Fix:")
        for fix_line in f.fix.split('\n'):
            print(f"    {fix_line}")

    # CI summary
    print(f"\n{'═'*60}")
    print(f"SUMMARY: {high_count} HIGH, {med_count} MEDIUM, {low_count} LOW")
    print(f"\nCI fail-gate (fails on any HIGH or MEDIUM finding):")
    print(f"  python api_version_audit.py --root . --ci --min-severity MEDIUM")
    if CI_MODE and high_count + med_count > 0:
        print("\n[CI] Exiting with code 1 — HIGH/MEDIUM findings present.")
        return 1
    return 0

if __name__ == '__main__':
    import argparse
    parser = argparse.ArgumentParser(description='API versioning health auditor')
    parser.add_argument('--root', default='.', help='Root directory to scan')
    parser.add_argument('--ci', action='store_true', help='CI mode: exit 1 on HIGH/MEDIUM')
    parser.add_argument('--min-severity', choices=['HIGH', 'MEDIUM', 'LOW'],
                        default='LOW', help='Minimum severity to report')
    parser.add_argument('--json', action='store_true', help='Output JSON instead of text')
    args = parser.parse_args()

    CI_MODE = args.ci
    MIN_SEVERITY = args.min_severity

    exit_code = run_audit(Path(args.root))
    sys.exit(exit_code)

---

Example Output#

text

🔍  phy-api-version-audit — scanning /home/user/myapi
────────────────────────────────────────────────────────────

Found 7 issue(s): 🔴 HIGH=2  🟡 MEDIUM=3  🔵 LOW=2

🔴 HIGH ISSUES
──────────────────────────────────────────────────────

[SU001] src/routes/users.js:47
  Deprecated endpoint has no Sunset header (RFC 8594). Clients cannot plan migration.
  Matched: // @deprecated — use /v2/users instead
  Fix:
    res.set("Sunset", "Sat, 31 Dec 2026 23:59:59 GMT");
    res.set("Deprecation", "true");
    res.set("Link", "</v2/users>; rel="successor-version"");

[V0001] src/routes/internal.ts:12
  /v0/ route found in production code.
  Matched: router.get('/v0/internal/config', adminHandler)
  Fix:
    Rename /v0/ to /v1/ before production deployment.

🟡 MEDIUM ISSUES
──────────────────────────────────────────────────────

[UV001] src/routes/payments.js:23
  Route "/checkout" has no version prefix (/v1/, /api/v1/)
  Matched: express: '/checkout'
  Fix:
    Change route to "/v1/checkout" or register under a versioned router:
      const v1 = express.Router();
      app.use("/v1", v1);
      v1.get("/checkout", handler);

[UV001] src/routes/webhooks.js:8
  Route "/stripe/webhook" has no version prefix
  [skipped — matches UNVERSIONED_WHITELIST for 'webhook']

[MX001] <codebase-wide>:0
  Multiple API versioning strategies detected.
  Matched: URL versioning in 12 files; header versioning (X-API-Version) in 3 files
  Fix:
    Pick one strategy. Recommended: URL versioning (/v1/) for public APIs.

🔵 LOW ISSUES
──────────────────────────────────────────────────────

[HC001] src/client/apiClient.ts:34
  Hardcoded version string: "https://api.example.com/v1/users"
  Fix:
    const API_BASE = process.env.API_BASE_URL || "https://api.example.com/v1";

[VG001] <codebase-wide>:0
  Version gap: versions [2] missing between v1 and v3
  Fix:
    Add /v2/ stub routes that redirect to /v3/ or document intentional skip.

════════════════════════════════════════════════════════════
SUMMARY: 2 HIGH, 3 MEDIUM, 2 LOW

CI fail-gate (fails on any HIGH or MEDIUM finding):
  python api_version_audit.py --root . --ci --min-severity MEDIUM

---

Whitelisted Paths (Never Flagged for UV001)#

These paths are intentionally unversioned and are excluded from UV001:

text

/health, /ping, /ready, /live, /status, /metrics
/favicon, /robots.txt, /static, /public, /assets
/auth, /oauth, /login, /logout, /signup, /register
/webhook, /webhooks, /ws, /wss

Add custom exemptions by setting:

bash

export API_AUDIT_WHITELIST="^/internal,^/admin"

---

Relationship to Other phy- Skills#

SkillWhen to Usephy-api-version-audit (this)Source code has versioning issues — pre-deploymentphy-api-changelog-genYou have two OpenAPI spec files and need a semantic diffphy-openapi-mock-serverYou want a mock server from a spec filephy-security-headersYou want to audit runtime HTTP response headers

---

Supported Frameworks#

LanguageFrameworksNode.js / TypeScriptExpress, Fastify, Koa, NestJSPythonFastAPI, Flask, DjangoJava / KotlinSpring Boot, JAX-RSGoGin, Echo, net/http, ChiRubyRails, SinatraPHPLaravel, Slim

Detection is automatic — no configuration needed.

---

Author#

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041