66 lines
2.7 KiB
JavaScript
66 lines
2.7 KiB
JavaScript
#!/usr/bin/env node
|
|
|
|
// Contract-coverage gate (docs/adr/ADR-029-v2-r5-final-hardening.md, brief Phase 1):
|
|
// fails when a route actually registered by an ASP.NET Minimal API endpoint file under
|
|
// src/backend/ItWorx.KnowledgeHub.Api/Endpoints does not appear in
|
|
// docs/api/openapi.yaml. This is what makes "the API must be reliably usable by a
|
|
// future separate MCP server" (CLAUDE.md) an enforced property, not an aspiration —
|
|
// a route can no longer silently ship undocumented.
|
|
//
|
|
// Deliberately a source-scan, not a live-server introspection: it runs with no
|
|
// database, no built application and no network, so it is cheap enough to run on every
|
|
// `node scripts/verify.mjs` (fast and full), not only the release gate.
|
|
|
|
import fs from "node:fs";
|
|
import path from "node:path";
|
|
import process from "node:process";
|
|
import yaml from "js-yaml";
|
|
import { extractRoutesFromSource } from "./lib/openapi-routes.mjs";
|
|
|
|
const endpointsDir = "src/backend/ItWorx.KnowledgeHub.Api/Endpoints";
|
|
const openApiPath = "docs/api/openapi.yaml";
|
|
|
|
// Routes intentionally excluded from OpenAPI coverage: not `/api/v1/*` REST endpoints
|
|
// at all (health probes, the raw attachment byte stream already documented once under
|
|
// its real path, etc.) — see docs/09-api-contract.md "Base path: /api/v1".
|
|
const EXCLUDED_ROUTE_PREFIXES = ["/health"];
|
|
|
|
function listEndpointFiles(dir) {
|
|
return fs
|
|
.readdirSync(dir)
|
|
.filter((file) => file.endsWith(".cs"))
|
|
.map((file) => path.join(dir, file));
|
|
}
|
|
|
|
function extractRoutesFromFile(filePath) {
|
|
return extractRoutesFromSource(fs.readFileSync(filePath, "utf8"), filePath);
|
|
}
|
|
|
|
function isExcluded(routePath) {
|
|
return EXCLUDED_ROUTE_PREFIXES.some((prefix) => routePath.startsWith(prefix));
|
|
}
|
|
|
|
const registeredRoutes = listEndpointFiles(endpointsDir).flatMap(extractRoutesFromFile).filter((route) => !isExcluded(route.path));
|
|
|
|
const document = yaml.load(fs.readFileSync(openApiPath, "utf8"));
|
|
const documentedPaths = document?.paths ?? {};
|
|
|
|
const missing = [];
|
|
for (const route of registeredRoutes) {
|
|
const pathEntry = documentedPaths[route.path];
|
|
const documentedMethods = pathEntry ? Object.keys(pathEntry).map((key) => key.toUpperCase()) : [];
|
|
if (!documentedMethods.includes(route.method)) {
|
|
missing.push(route);
|
|
}
|
|
}
|
|
|
|
if (missing.length > 0) {
|
|
console.error(`OpenAPI coverage gate failed: ${missing.length} registered route(s) not documented in ${openApiPath}:`);
|
|
for (const route of missing.sort((a, b) => a.path.localeCompare(b.path))) {
|
|
console.error(`- ${route.method} /api/v1${route.path === "/" ? "" : route.path} (${route.file})`);
|
|
}
|
|
process.exit(1);
|
|
}
|
|
|
|
console.log(`OpenAPI coverage gate passed: all ${registeredRoutes.length} registered /api/v1 routes are documented.`);
|