This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/scripts/validate-openapi-routes.ts
2026-06-22 17:45:56 +03:00

424 lines
13 KiB
JavaScript

#!/usr/bin/env node
/**
* OpenAPI Route Coverage Validator
*
* Parses Express route registrations from source code, compares them against
* the OpenAPI spec, and reports coverage gaps.
*
* Usage:
* npx tsx scripts/validate-openapi-routes.ts
*
* Exit codes:
* 0 - All routes covered
* 1 - Undocumented routes found
*/
import * as fs from "fs";
import * as path from "path";
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
interface RouteInfo {
method: string;
path: string;
file: string;
}
interface SpecRoute {
method: string;
path: string;
}
interface ProductConfig {
name: string;
routeDir: string;
entryFile: string;
specFile: string;
basePrefix: string;
}
// ---------------------------------------------------------------------------
// Route extraction from source code
// ---------------------------------------------------------------------------
/**
* Extract route registrations from an Express router file.
* Matches patterns like: router.get("/path", ...) or router.post("/path", ...)
*/
function extractRoutesFromFile(filePath: string): Array<{ method: string; subPath: string }> {
const routes: Array<{ method: string; subPath: string }> = [];
if (!fs.existsSync(filePath)) {
return routes;
}
const content = fs.readFileSync(filePath, "utf-8");
// Match router.METHOD("path" or router.METHOD( followed by newline + "path"
const routeRegex = /router\.(get|post|put|patch|delete)\(\s*["'`]([^"'`]+)["'`]/gi;
let match: RegExpExecArray | null;
while ((match = routeRegex.exec(content)) !== null) {
const method = match[1].toUpperCase();
const subPath = match[2];
routes.push({ method, subPath });
}
// Also match multiline patterns like router.get(\n "/path",
const multilineRegex = /router\.(get|post|put|patch|delete)\(\s*\n\s*["'`]([^"'`]+)["'`]/gi;
while ((match = multilineRegex.exec(content)) !== null) {
const method = match[1].toUpperCase();
const subPath = match[2];
// Avoid duplicates
if (!routes.some((r) => r.method === method && r.subPath === subPath)) {
routes.push({ method, subPath });
}
}
return routes;
}
/**
* Parse the entry file (index.ts) to find route mount points.
* Matches patterns like: app.use("/v1/sync", syncRoutes);
*/
function extractMountPoints(entryFile: string): Map<string, string> {
const mounts = new Map<string, string>();
if (!fs.existsSync(entryFile)) {
return mounts;
}
const content = fs.readFileSync(entryFile, "utf-8");
// Match import statements to map variable names to file names
const importMap = new Map<string, string>();
const importRegex = /import\s+(\w+)\s+from\s+["'`]\.\/routes\/([^"'`]+)["'`]/g;
let match: RegExpExecArray | null;
while ((match = importRegex.exec(content)) !== null) {
importMap.set(match[1], match[2].replace(/\.js$/, ""));
}
// Also handle CommonJS requires
const requireRegex = /(?:const|let|var)\s+(\w+)\s*=\s*require\(\s*["'`]\.\/routes\/([^"'`]+)["'`]\s*\)/g;
while ((match = requireRegex.exec(content)) !== null) {
importMap.set(match[1], match[2].replace(/\.js$/, ""));
}
// Match app.use("/path", variableName)
const useRegex = /app\.use\(\s*["'`]([^"'`]+)["'`]\s*,\s*(?:[^,)]*,\s*)*(\w+Routes?)\s*\)/g;
while ((match = useRegex.exec(content)) !== null) {
const mountPath = match[1];
const varName = match[2];
const routeFile = importMap.get(varName);
if (routeFile) {
// Use the first mount point for each route file (prefer v1 routes)
if (!mounts.has(routeFile) || mountPath.startsWith("/v1") || mountPath.startsWith("/api/v1")) {
mounts.set(routeFile, mountPath);
}
}
}
return mounts;
}
/**
* Build the full list of implemented routes for a product.
*/
function getImplementedRoutes(config: ProductConfig): RouteInfo[] {
const routes: RouteInfo[] = [];
const mounts = extractMountPoints(config.entryFile);
// Also handle inline routes defined directly in the entry file
const entryContent = fs.existsSync(config.entryFile)
? fs.readFileSync(config.entryFile, "utf-8")
: "";
// Match app.get/post directly in entry file
const inlineRegex = /app\.(get|post|put|patch|delete)\(\s*["'`]([^"'`]+)["'`]/gi;
let inlineMatch: RegExpExecArray | null;
while ((inlineMatch = inlineRegex.exec(entryContent)) !== null) {
const method = inlineMatch[1].toUpperCase();
const fullPath = inlineMatch[2];
routes.push({ method, path: fullPath, file: path.basename(config.entryFile) });
}
// Get route files
if (!fs.existsSync(config.routeDir)) {
console.error(`Route directory not found: ${config.routeDir}`);
return routes;
}
const routeFiles = fs.readdirSync(config.routeDir).filter((f) => f.endsWith(".ts"));
for (const file of routeFiles) {
const filePath = path.join(config.routeDir, file);
const routeName = file.replace(/\.ts$/, "");
const mountPath = mounts.get(routeName);
if (!mountPath) {
// Try to find mount via various naming conventions
continue;
}
const fileRoutes = extractRoutesFromFile(filePath);
for (const { method, subPath } of fileRoutes) {
// Build full path
let fullPath = mountPath;
if (subPath === "/") {
// Root of the mount
} else {
fullPath = mountPath + subPath;
}
// Normalize: remove trailing slash, collapse double slashes
fullPath = fullPath.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
routes.push({ method, path: fullPath, file });
}
}
return routes;
}
// ---------------------------------------------------------------------------
// OpenAPI spec parsing
// ---------------------------------------------------------------------------
/**
* Parse OpenAPI YAML spec to extract paths.
* Simple YAML parser for our specific use case (no external deps).
*/
function parseOpenAPIRoutes(specFile: string): SpecRoute[] {
if (!fs.existsSync(specFile)) {
console.error(`OpenAPI spec not found: ${specFile}`);
return [];
}
const content = fs.readFileSync(specFile, "utf-8");
const routes: SpecRoute[] = [];
const lines = content.split("\n");
let currentPath = "";
let inPaths = false;
let pathIndent = -1;
let methodIndent = -1;
for (const line of lines) {
const trimmed = line.trimEnd();
// Detect paths: section
if (/^paths:\s*$/.test(trimmed)) {
inPaths = true;
pathIndent = -1;
continue;
}
if (!inPaths) continue;
// If we hit a top-level key that's not a path, end paths section
if (/^\S/.test(line) && !line.startsWith(" ") && !line.startsWith("#")) {
inPaths = false;
continue;
}
// Match path entries (indented with spaces)
const pathMatch = trimmed.match(/^(\s+)(\/[^:]*)\s*:\s*$/);
if (pathMatch) {
const indent = pathMatch[1].length;
if (pathIndent === -1 || indent <= pathIndent) {
pathIndent = indent;
currentPath = pathMatch[2].trim();
methodIndent = -1;
continue;
}
}
// Match HTTP methods under a path
if (currentPath) {
const methodMatch = trimmed.match(/^(\s+)(get|post|put|patch|delete)\s*:\s*$/);
if (methodMatch) {
const indent = methodMatch[1].length;
if (indent > pathIndent) {
routes.push({
method: methodMatch[2].toUpperCase(),
path: currentPath,
});
}
}
}
}
return routes;
}
// ---------------------------------------------------------------------------
// Normalization and comparison
// ---------------------------------------------------------------------------
/**
* Normalize a route path for comparison.
* Express :param becomes {param}, wildcards are handled, etc.
*/
function normalizePath(routePath: string): string {
return routePath
.replace(/:(\w+)/g, "{$1}") // :param -> {param}
.replace(/\/\*/g, "/{path}") // wildcard
.replace(/\/+/g, "/") // collapse slashes
.replace(/\/$/, "") // remove trailing slash
.toLowerCase();
}
/**
* Create a route key for comparison (METHOD:normalizedPath)
*/
function routeKey(method: string, routePath: string): string {
return `${method}:${normalizePath(routePath)}`;
}
// ---------------------------------------------------------------------------
// Report generation
// ---------------------------------------------------------------------------
function printTable(title: string, rows: Array<{ method: string; path: string; detail?: string }>) {
if (rows.length === 0) return;
console.log(`\n${"=".repeat(80)}`);
console.log(` ${title}`);
console.log(`${"=".repeat(80)}`);
console.log(` ${"Method".padEnd(10)} ${"Path".padEnd(55)} ${rows[0].detail ? "Detail" : ""}`);
console.log(` ${"-".repeat(10)} ${"-".repeat(55)} ${rows[0].detail ? "-".repeat(10) : ""}`);
for (const row of rows) {
console.log(` ${row.method.padEnd(10)} ${row.path.padEnd(55)} ${row.detail || ""}`);
}
}
// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------
function validateProduct(config: ProductConfig): { undocumented: number; stale: number; covered: number } {
console.log(`\n${"#".repeat(80)}`);
console.log(` Validating: ${config.name}`);
console.log(`${"#".repeat(80)}`);
// Get implemented routes
const implemented = getImplementedRoutes(config);
console.log(` Found ${implemented.length} implemented routes`);
// Get spec routes
const specRoutes = parseOpenAPIRoutes(config.specFile);
console.log(` Found ${specRoutes.length} routes in OpenAPI spec`);
// Build lookup sets
const implKeys = new Set(implemented.map((r) => routeKey(r.method, r.path)));
const specKeys = new Set(specRoutes.map((r) => routeKey(r.method, r.path)));
// Find undocumented routes (in code but not spec)
const undocumented = implemented.filter((r) => !specKeys.has(routeKey(r.method, r.path)));
// Find stale routes (in spec but not code)
const stale = specRoutes.filter((r) => !implKeys.has(routeKey(r.method, r.path)));
// Find covered routes (in both)
const covered = implemented.filter((r) => specKeys.has(routeKey(r.method, r.path)));
// Print results
const total = new Set([...implKeys, ...specKeys]).size;
const coveragePercent = total > 0 ? ((covered.length / total) * 100).toFixed(1) : "0";
console.log(`\n Coverage: ${covered.length}/${total} routes (${coveragePercent}%)`);
if (undocumented.length > 0) {
printTable(
`UNDOCUMENTED (${undocumented.length}) - Routes in code but NOT in spec`,
undocumented.map((r) => ({ method: r.method, path: r.path, detail: r.file }))
);
} else {
console.log(`\n All implemented routes are documented in the OpenAPI spec.`);
}
if (stale.length > 0) {
printTable(
`STALE (${stale.length}) - Routes in spec but NOT in code`,
stale.map((r) => ({ method: r.method, path: r.path }))
);
}
if (covered.length > 0) {
printTable(
`COVERED (${covered.length}) - Routes in both code and spec`,
covered.map((r) => ({ method: r.method, path: r.path }))
);
}
return {
undocumented: undocumented.length,
stale: stale.length,
covered: covered.length,
};
}
// ---------------------------------------------------------------------------
// Product configurations
// ---------------------------------------------------------------------------
const rootDir = path.resolve(__dirname, "..");
const products: ProductConfig[] = [
{
name: "AITimeMachine API",
routeDir: path.join(rootDir, "aitimemachine/api-server/src/routes"),
entryFile: path.join(rootDir, "aitimemachine/api-server/src/index.ts"),
specFile: path.join(rootDir, "aitimemachine/api-server/docs/openapi.yaml"),
basePrefix: "/v1",
},
{
name: "Gitgram Backend",
routeDir: path.join(rootDir, "gitgram/backend/src/routes"),
entryFile: path.join(rootDir, "gitgram/backend/src/index.ts"),
specFile: path.join(rootDir, "gitgram/backend/docs/openapi.yaml"),
basePrefix: "/api/v1",
},
];
// Run validation
let hasFailures = false;
const results: Array<{ name: string; undocumented: number; stale: number; covered: number }> = [];
for (const product of products) {
const result = validateProduct(product);
results.push({ name: product.name, ...result });
if (result.undocumented > 0) {
hasFailures = true;
}
}
// Print summary
console.log(`\n${"=".repeat(80)}`);
console.log(" SUMMARY");
console.log(`${"=".repeat(80)}`);
console.log(` ${"Product".padEnd(30)} ${"Covered".padEnd(12)} ${"Undocumented".padEnd(15)} ${"Stale".padEnd(10)}`);
console.log(` ${"-".repeat(30)} ${"-".repeat(12)} ${"-".repeat(15)} ${"-".repeat(10)}`);
for (const r of results) {
const total = r.covered + r.undocumented;
const pct = total > 0 ? `(${((r.covered / total) * 100).toFixed(0)}%)` : "";
console.log(
` ${r.name.padEnd(30)} ${(r.covered + " " + pct).padEnd(12)} ${String(r.undocumented).padEnd(15)} ${String(r.stale).padEnd(10)}`
);
}
if (hasFailures) {
console.log(`\n FAIL: Undocumented routes found. Update OpenAPI specs to achieve full coverage.\n`);
process.exit(1);
} else {
console.log(`\n PASS: All implemented routes are documented.\n`);
process.exit(0);
}