npm - spring-api-scanner - Versions diffs - 0.1.0 - Mend

spring-api-scanner 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/PLAN.md +142 -0
package/README.md +60 -0
package/dist/args.d.ts +9 -0
package/dist/args.js +57 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +67 -0
package/dist/openapi.d.ts +67 -0
package/dist/openapi.js +94 -0
package/dist/output.d.ts +6 -0
package/dist/output.js +25 -0
package/dist/resolver.d.ts +17 -0
package/dist/resolver.js +206 -0
package/dist/scanner.d.ts +22 -0
package/dist/scanner.js +321 -0
package/dist/ui.d.ts +36 -0
package/dist/ui.js +407 -0
package/docs/plans/2026-02-07-complete-remaining-tasks.md +61 -0
package/package.json +23 -0
package/spring-api-scanner-0.1.0.tgz +0 -0
package/src/args.ts +76 -0
package/src/index.ts +81 -0
package/src/openapi.ts +191 -0
package/src/output.ts +36 -0
package/src/resolver.ts +274 -0
package/src/scanner.ts +409 -0
package/src/ui.ts +454 -0
package/tests/args.test.d.ts +1 -0
package/tests/args.test.ts +45 -0
package/tests/fixtures/sample-service/src/main/kotlin/demo/UserController.kt +34 -0
package/tests/fixtures/sample-service/src/main/kotlin/demo/UserDtos.kt +22 -0
package/tests/golden/openapi.sample-service.json +164 -0
package/tests/integration.test.ts +98 -0
package/tests/openapi.test.d.ts +1 -0
package/tests/openapi.test.ts +127 -0
package/tests/output.test.ts +55 -0
package/tests/resolver.test.ts +98 -0
package/tests/scanner.test.ts +138 -0
package/tests/ui.test.ts +85 -0
package/tsconfig.json +15 -0

package/dist/ui.js ADDED Viewed

@@ -0,0 +1,407 @@
+export function buildUiModel(input) {
+    const endpoints = input.endpoints.map((endpoint) => {
+        const operation = input.openapi.paths[endpoint.fullPath]?.[endpoint.httpMethod.toLowerCase()];
+        const requestSchema = deref(operation?.requestBody?.content?.["application/json"]?.schema, input.openapi);
+        const responseSchema = pickResponseSchema(operation?.responses, input.openapi);
+        return {
+            id: `${endpoint.httpMethod}:${endpoint.fullPath}:${endpoint.operationName}`,
+            operationName: endpoint.operationName,
+            method: endpoint.httpMethod,
+            path: endpoint.fullPath,
+            controller: operation?.tags?.[0] ?? guessController(endpoint.sourceFile),
+            pathVariables: endpoint.pathVariables.map((v) => ({
+                name: v.name,
+                type: v.type,
+                required: v.required ?? true
+            })),
+            queryParams: endpoint.queryParams.map((v) => ({
+                name: v.name,
+                type: v.type,
+                required: v.required ?? false
+            })),
+            headers: endpoint.headers.map((v) => ({
+                name: v.name,
+                type: v.type,
+                required: v.required ?? false
+            })),
+            requestSchema,
+            responseSchema,
+            curl: buildCurl(endpoint)
+        };
+    });
+    return {
+        generatedAt: new Date().toISOString(),
+        endpoints
+    };
+}
+export function renderUiHtml(title, embeddedModel) {
+    const embedded = embeddedModel ? escapeJsonForScriptTag(embeddedModel) : "";
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <style>
+    @import url('https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700&family=Manrope:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap');
+    :root {
+      --bg:#f7efe2;
+      --bg-soft:#fbf6ee;
+      --card:#fffdfa;
+      --ink:#2b2118;
+      --muted:#74685a;
+      --line:#e6d6bf;
+      --line-strong:#d8c1a1;
+      --accent:#a14b10;
+      --accent-soft:#f4e5d4;
+      --radius:16px;
+      --shadow:0 16px 38px rgba(94, 60, 21, .13);
+      --get:#0f766e;
+      --post:#14532d;
+      --put:#92400e;
+      --patch:#6d28d9;
+      --delete:#991b1b;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin:0;
+      font-family:"Manrope","Segoe UI",sans-serif;
+      color:var(--ink);
+      background:
+        radial-gradient(circle at 12% 8%, rgba(235, 200, 156, .28), transparent 34%),
+        radial-gradient(circle at 84% 0%, rgba(210, 152, 96, .2), transparent 30%),
+        linear-gradient(160deg,#f0dfc6 0%,var(--bg) 28%,var(--bg-soft) 100%);
+      min-height:100vh;
+    }
+    .wrap { max-width:1120px; margin:0 auto; padding:28px 24px 40px; }
+    h1 {
+      margin:0 0 8px;
+      font-family:"Fraunces","Georgia",serif;
+      font-size:clamp(1.8rem, 4vw, 2.5rem);
+      letter-spacing:.01em;
+    }
+    .sub { margin:0 0 16px; color:var(--muted); max-width:900px; }
+    .toolbar {
+      position:sticky;
+      top:10px;
+      z-index:3;
+      display:grid;
+      grid-template-columns:1.5fr 1fr 1fr auto;
+      gap:10px;
+      margin:18px 0 18px;
+      padding:12px;
+      border:1px solid var(--line);
+      border-radius:14px;
+      background:rgba(255,252,247,.82);
+      backdrop-filter: blur(4px);
+      box-shadow:0 8px 20px rgba(90,57,20,.07);
+    }
+    input,select,button {
+      border:1px solid var(--line);
+      border-radius:11px;
+      padding:10px 12px;
+      font:inherit;
+      background:#fff;
+      color:var(--ink);
+    }
+    input:focus, select:focus, button:focus {
+      outline:none;
+      border-color:var(--line-strong);
+      box-shadow:0 0 0 3px rgba(161,75,16,.12);
+    }
+    button { cursor:pointer; }
+    .btn-primary {
+      background:linear-gradient(180deg,#b35a1d 0%, var(--accent) 100%);
+      color:#fff;
+      border:0;
+      font-weight:700;
+      letter-spacing:.01em;
+      padding-inline:15px;
+    }
+    .cards { display:grid; gap:12px; }
+    .card {
+      border:1px solid var(--line);
+      border-radius:var(--radius);
+      background:var(--card);
+      overflow:hidden;
+      box-shadow:var(--shadow);
+      animation:lift .35s ease both;
+      transform-origin:top;
+    }
+    .head {
+      display:grid;
+      grid-template-columns:auto 1fr auto;
+      gap:12px;
+      padding:14px 16px;
+      cursor:pointer;
+      align-items:center;
+    }
+    .pill {
+      padding:4px 9px;
+      border-radius:999px;
+      background:var(--accent-soft);
+      color:#7d3d00;
+      font-size:12px;
+      text-transform:uppercase;
+      letter-spacing:.05em;
+      font-weight:700;
+      min-width:68px;
+      text-align:center;
+    }
+    .pill.method-get { background:#dff5f2; color:var(--get); }
+    .pill.method-post { background:#dff4e6; color:var(--post); }
+    .pill.method-put { background:#ffefd8; color:var(--put); }
+    .pill.method-patch { background:#efe5ff; color:var(--patch); }
+    .pill.method-delete { background:#fde3e3; color:var(--delete); }
+    .path { font-weight:700; font-size:1.03rem; line-height:1.35; }
+    .muted { color:var(--muted); font-size:14px; }
+    .arrow { font-size:13px; color:var(--muted); transition:transform .16s ease; }
+    .card.open .arrow { transform:rotate(180deg); }
+    .body {
+      display:none;
+      border-top:1px dashed var(--line);
+      padding:4px 16px 16px;
+      background:linear-gradient(180deg, rgba(252,247,239,.6) 0%, rgba(255,255,255,.98) 100%);
+    }
+    .card.open .body { display:block; animation:reveal .2s ease-out; }
+    .sec {
+      margin-top:12px;
+      border:1px solid #efe5d7;
+      border-radius:12px;
+      padding:10px;
+      background:#fff;
+    }
+    .sec h4 {
+      margin:0 0 7px;
+      font-size:14px;
+      text-transform:uppercase;
+      letter-spacing:.06em;
+      color:#7c6247;
+      font-weight:700;
+    }
+    pre {
+      margin:0;
+      padding:11px;
+      border-radius:10px;
+      border:1px solid #374151;
+      background:linear-gradient(180deg,#1f2937 0%,#111827 100%);
+      color:#f9fafb;
+      overflow:auto;
+      font-size:12px;
+      line-height:1.45;
+      font-family:"IBM Plex Mono","Consolas",monospace;
+    }
+    table { width:100%; border-collapse:collapse; }
+    th,td { padding:7px 5px; border-bottom:1px solid var(--line); text-align:left; font-size:13px; }
+    th { color:#7d6549; font-weight:700; }
+    .stats { color:var(--muted); margin:0 0 10px; font-weight:600; }
+    @keyframes lift {
+      from { opacity:0; transform:translateY(8px); }
+      to { opacity:1; transform:translateY(0); }
+    }
+    @keyframes reveal {
+      from { opacity:0; transform:translateY(4px); }
+      to { opacity:1; transform:translateY(0); }
+    }
+    @media (max-width:900px) { .toolbar { grid-template-columns:1fr; position:static; } }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>${escapeHtml(title)}</h1>
+    <p class="sub">Search and filter endpoints, inspect schemas, and copy curl commands.</p>
+    <div class="toolbar">
+      <input id="search" placeholder="Search endpoint or path" />
+      <select id="method-filter"><option value="all">All methods</option></select>
+      <select id="controller-filter"><option value="all">All controllers</option></select>
+      <a href="openapi.json" download><button class="btn-primary">Download OpenAPI JSON</button></a>
+    </div>
+    <p id="stats" class="stats"></p>
+    <div id="cards" class="cards"></div>
+  </div>
+  <script id="embedded-ui-data" type="application/json">${embedded}</script>
+  <script>
+    var state = { model: null, search: "", method: "all", controller: "all" };
+    var cardsRoot = document.getElementById("cards");
+    var stats = document.getElementById("stats");
+    var methodFilter = document.getElementById("method-filter");
+    var controllerFilter = document.getElementById("controller-filter");
+    function normalize(v) { return String(v || "").toLowerCase(); }
+    function esc(v) {
+      return String(v || "")
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/\"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+    }
+    function json(v) { return esc(JSON.stringify(v || {}, null, 2)); }
+    function rows(items) {
+      if (!items || items.length === 0) return '<p class="muted">None</p>';
+      var body = items.map(function (r) {
+        return '<tr><td>' + esc(r.name) + '</td><td>' + esc(r.type) + '</td><td>' + (r.required ? "yes" : "no") + '</td></tr>';
+      }).join("");
+      return '<table><thead><tr><th>Name</th><th>Type</th><th>Required</th></tr></thead><tbody>' + body + '</tbody></table>';
+    }
+    function filtered(items) {
+      return items.filter(function (e) {
+        var s = !state.search || normalize(e.operationName).indexOf(normalize(state.search)) >= 0 || normalize(e.path).indexOf(normalize(state.search)) >= 0;
+        var m = state.method === "all" || e.method === state.method;
+        var c = state.controller === "all" || e.controller === state.controller;
+        return s && m && c;
+      });
+    }
+    function attach() {
+      Array.prototype.forEach.call(document.querySelectorAll('[data-toggle]'), function (el) {
+        el.addEventListener('click', function () {
+          var root = el.closest('.card');
+          if (root) root.classList.toggle('open');
+        });
+      });
+      Array.prototype.forEach.call(document.querySelectorAll('[data-copy]'), function (el) {
+        el.addEventListener('click', function (ev) {
+          ev.stopPropagation();
+          var id = el.getAttribute('data-copy');
+          var item = state.model.endpoints.find(function (x) { return x.id === id; });
+          if (!item) return;
+          navigator.clipboard.writeText(item.curl).then(function () {
+            el.textContent = 'Copied';
+            setTimeout(function () { el.textContent = 'Copy curl'; }, 1200);
+          });
+        });
+      });
+    }
+    function render() {
+      if (!state.model) return;
+      var items = filtered(state.model.endpoints);
+      stats.textContent = items.length + ' endpoint(s) shown';
+      cardsRoot.innerHTML = items.map(function (e, idx) {
+        return '<article class="card">'
+          + '<div style="height:' + ((idx % 4) * 1.2) + 'px"></div>'
+          + '<header class="head" data-toggle="' + esc(e.id) + '">'
+          + '<span class="pill method-' + esc(normalize(e.method)) + '">' + esc(e.method) + '</span>'
+          + '<div><div class="path">' + esc(e.path) + '</div><div class="muted">' + esc(e.controller) + ' • ' + esc(e.operationName) + '</div></div>'
+          + '<span class="arrow">▼</span>'
+          + '</header>'
+          + '<section class="body">'
+          + '<div class="sec"><h4>Path Variables</h4>' + rows(e.pathVariables) + '</div>'
+          + '<div class="sec"><h4>Query Params</h4>' + rows(e.queryParams) + '</div>'
+          + '<div class="sec"><h4>Headers</h4>' + rows(e.headers) + '</div>'
+          + '<div class="sec"><h4>Request Body</h4><pre>' + json(e.requestSchema) + '</pre></div>'
+          + '<div class="sec"><h4>Response Body</h4><pre>' + json(e.responseSchema) + '</pre></div>'
+          + '<div class="sec"><h4>curl</h4><pre>' + esc(e.curl) + '</pre></div>'
+          + '<div class="sec"><button data-copy="' + esc(e.id) + '">Copy curl</button></div>'
+          + '</section>'
+          + '</article>';
+      }).join('');
+      attach();
+    }
+    function fillFilters(endpoints) {
+      var methods = Array.from(new Set(endpoints.map(function (e) { return e.method; }))).sort();
+      var ctrls = Array.from(new Set(endpoints.map(function (e) { return e.controller; }))).sort();
+      methodFilter.innerHTML = '<option value="all">All methods</option>' + methods.map(function (m) { return '<option value="' + esc(m) + '">' + esc(m) + '</option>'; }).join('');
+      controllerFilter.innerHTML = '<option value="all">All controllers</option>' + ctrls.map(function (c) { return '<option value="' + esc(c) + '">' + esc(c) + '</option>'; }).join('');
+    }
+    document.getElementById('search').addEventListener('input', function (ev) { state.search = ev.target.value || ''; render(); });
+    methodFilter.addEventListener('change', function (ev) { state.method = ev.target.value; render(); });
+    controllerFilter.addEventListener('change', function (ev) { state.controller = ev.target.value; render(); });
+    function applyModel(data) {
+      state.model = data;
+      fillFilters(data.endpoints || []);
+      render();
+    }
+    function loadFromEmbedded() {
+      var embedded = document.getElementById('embedded-ui-data');
+      if (!embedded || !embedded.textContent || embedded.textContent.trim() === '') return false;
+      try {
+        applyModel(JSON.parse(embedded.textContent));
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    function loadFromFetch() {
+      return fetch('ui-data.json')
+        .then(function (res) {
+          if (!res.ok) throw new Error('relative fetch failed');
+          return res.json();
+        })
+        .catch(function () {
+          return fetch('/ui-data.json').then(function (res) {
+            if (!res.ok) throw new Error('absolute fetch failed');
+            return res.json();
+          });
+        })
+        .then(function (data) { applyModel(data); });
+    }
+    if (!loadFromEmbedded()) {
+      loadFromFetch().catch(function () { stats.textContent = 'Failed to load UI data.'; });
+    }
+  </script>
+</body>
+</html>`;
+}
+function deref(schema, openapi) {
+    if (!schema) {
+        return undefined;
+    }
+    if (schema.$ref) {
+        const name = schema.$ref.split("/").at(-1);
+        if (name && openapi.components.schemas[name]) {
+            return openapi.components.schemas[name];
+        }
+    }
+    return schema;
+}
+function pickResponseSchema(responses, openapi) {
+    if (!responses) {
+        return undefined;
+    }
+    const best = responses["200"] ?? responses["201"];
+    return deref(best?.content?.["application/json"]?.schema, openapi);
+}
+function buildCurl(endpoint) {
+    const parts = [`curl -X ${endpoint.httpMethod} "http://localhost:3000${endpoint.fullPath}"`];
+    for (const header of endpoint.headers) {
+        parts.push(`-H "${header.name}: <${header.name}>"`);
+    }
+    if (endpoint.requestBody) {
+        parts.push('-H "Content-Type: application/json"');
+        parts.push("-d '{ }'");
+    }
+    return parts.join(" \\\n+");
+}
+function guessController(sourceFile) {
+    const file = sourceFile.replaceAll("\\", "/").split("/").at(-1) ?? sourceFile;
+    return file.endsWith(".kt") ? file.slice(0, -3) : file;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function escapeJsonForScriptTag(value) {
+    return JSON.stringify(value)
+        .replaceAll("<", "\\u003c")
+        .replaceAll(">", "\\u003e")
+        .replaceAll("&", "\\u0026")
+        .replaceAll("</script", "<\\/script")
+        .replaceAll("\u2028", "\\u2028")
+        .replaceAll("\u2029", "\\u2029");
+}

package/docs/plans/2026-02-07-complete-remaining-tasks.md ADDED Viewed

@@ -0,0 +1,61 @@
+# Spring API Scanner Remaining Tasks Implementation Plan
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+**Goal:** Complete remaining PLAN.md scope: human-readable UI, robust output artifacts, and stronger integration/golden tests.
+**Architecture:** Keep parser/resolver/OpenAPI pipeline as source of truth and add a small UI data-model builder consumed by a static SPA. Extend output orchestration to write `openapi.json`, `ui-data.json`, and `index.html`, then validate with deterministic tests.
+**Tech Stack:** Node.js, TypeScript, Vitest, static HTML/CSS/vanilla JS.
+---
+### Task 1: UI Data Model + Static UI
+**Files:**
+- Create: `src/ui.ts`
+- Modify: `src/output.ts`
+- Test: `tests/ui.test.ts`
+**Steps:**
+1. Write failing tests for UI model shape and rendered HTML affordances.
+2. Run targeted tests and verify failure.
+3. Implement `buildUiModel` + `renderUiHtml` with search/filter/expand/copy-curl/download.
+4. Run targeted tests and verify pass.
+### Task 2: Wire UI Into Orchestration
+**Files:**
+- Modify: `src/output.ts`, `src/index.ts`
+- Test: `tests/output.test.ts`
+**Steps:**
+1. Write failing tests expecting `ui-data.json` output and warnings surfaced.
+2. Run targeted tests and verify failure.
+3. Implement output writing for UI artifacts and summary integration.
+4. Run targeted tests and verify pass.
+### Task 3: Integration + Golden OpenAPI Test
+**Files:**
+- Create: `tests/fixtures/sample-service/src/main/kotlin/demo/UserController.kt`
+- Create: `tests/fixtures/sample-service/src/main/kotlin/demo/UserDtos.kt`
+- Create: `tests/golden/openapi.sample-service.json`
+- Create/Modify: `tests/integration.test.ts`
+**Steps:**
+1. Add failing integration test generating OpenAPI from fixture.
+2. Add golden-file assertion for deterministic output.
+3. Run tests and verify red.
+4. Implement/fix any gaps in parser/resolver/openapi for fixture pass.
+5. Re-run tests and verify green.
+### Task 4: Final Verification
+**Files:**
+- Modify: `README.md` (create if missing)
+**Steps:**
+1. Add quickstart and command examples.
+2. Run full verification: `npm test`, `npm run build`, CLI smoke run.
+3. Confirm no regressions and summarize completion against PLAN.md.

package/package.json ADDED Viewed

@@ -0,0 +1,23 @@
+{
+  "name": "spring-api-scanner",
+  "version": "0.1.0",
+  "description": "CLI for scanning Spring Boot Kotlin APIs and generating OpenAPI + UI output",
+  "type": "module",
+  "bin": {
+    "spring-api-scanner": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/spring-api-scanner-0.1.0.tgz ADDED Viewed

Binary file

package/src/args.ts ADDED Viewed

@@ -0,0 +1,76 @@
+export interface CliOptions {
+  projectPath: string;
+  port: number;
+  output: string;
+  serve: boolean;
+  title: string;
+  version: string;
+}
+const DEFAULT_PORT = 3000;
+const DEFAULT_OUTPUT = "./api-docs";
+const DEFAULT_TITLE = "Spring API Docs";
+const DEFAULT_VERSION = "1.0.0";
+export function parseCliArgs(argv: string[]): CliOptions {
+  if (argv.length === 0 || argv[0].startsWith("--")) {
+    throw new Error("A project path is required: spring-api-scanner <projectPath>");
+  }
+  const projectPath = argv[0];
+  const options: CliOptions = {
+    projectPath,
+    port: DEFAULT_PORT,
+    output: DEFAULT_OUTPUT,
+    serve: false,
+    title: DEFAULT_TITLE,
+    version: DEFAULT_VERSION
+  };
+  for (let i = 1; i < argv.length; i += 1) {
+    const token = argv[i];
+    switch (token) {
+      case "--serve":
+        options.serve = true;
+        break;
+      case "--no-serve":
+        options.serve = false;
+        break;
+      case "--port":
+        options.port = parseIntegerFlag("--port", argv[++i]);
+        break;
+      case "--output":
+        options.output = parseStringFlag("--output", argv[++i]);
+        break;
+      case "--title":
+        options.title = parseStringFlag("--title", argv[++i]);
+        break;
+      case "--version":
+        options.version = parseStringFlag("--version", argv[++i]);
+        break;
+      default:
+        throw new Error(`Unknown argument: ${token}`);
+    }
+  }
+  return options;
+}
+function parseStringFlag(flagName: string, rawValue?: string): string {
+  if (!rawValue || rawValue.startsWith("--")) {
+    throw new Error(`Missing value for ${flagName}`);
+  }
+  return rawValue;
+}
+function parseIntegerFlag(flagName: string, rawValue?: string): number {
+  const parsed = Number.parseInt(parseStringFlag(flagName, rawValue), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${flagName} must be a positive integer`);
+  }
+  return parsed;
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseCliArgs } from "./args.js";
+import { writePlaceholderArtifacts } from "./output.js";
+import { scanDataClasses } from "./resolver.js";
+import { scanSpringProject } from "./scanner.js";
+async function main(): Promise<void> {
+  const options = parseCliArgs(process.argv.slice(2));
+  await validateProjectPath(options.projectPath);
+  const endpoints = await scanSpringProject(options.projectPath);
+  const types = await scanDataClasses(options.projectPath);
+  const output = await writePlaceholderArtifacts(options, endpoints, types);
+  printSummary(options, endpoints.length, output.warnings);
+  if (options.serve) {
+    await serveOutput(options.output, options.port);
+  }
+}
+async function validateProjectPath(projectPath: string): Promise<void> {
+  const result = await stat(projectPath).catch(() => null);
+  if (!result || !result.isDirectory()) {
+    throw new Error(`Project path not found or not a directory: ${projectPath}`);
+  }
+}
+function printSummary(
+  options: ReturnType<typeof parseCliArgs>,
+  endpointCount: number,
+  warnings: string[]
+): void {
+  console.log("Spring API Scanner");
+  console.log(`- Project: ${path.resolve(options.projectPath)}`);
+  console.log(`- Output: ${path.resolve(options.output)}`);
+  console.log(`- Endpoints discovered: ${endpointCount}`);
+  console.log("- OpenAPI: openapi.json written");
+  console.log(`- Warnings: ${warnings.length}`);
+  for (const warning of warnings.slice(0, 5)) {
+    console.log(`  - ${warning}`);
+  }
+  console.log(`- Serve mode: ${options.serve ? "enabled" : "disabled"}`);
+}
+async function serveOutput(outputDir: string, port: number): Promise<void> {
+  const root = path.resolve(outputDir);
+  const server = createServer(async (req, res) => {
+    const pathname =
+      req.url === "/openapi.json"
+        ? "openapi.json"
+        : req.url === "/ui-data.json"
+          ? "ui-data.json"
+          : "index.html";
+    const fullPath = path.join(root, pathname);
+    try {
+      const contents = await readFile(fullPath);
+      const contentType =
+        pathname === "index.html" ? "text/html; charset=utf-8" : "application/json; charset=utf-8";
+      res.writeHead(200, { "content-type": contentType });
+      res.end(contents);
+    } catch {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Not found");
+    }
+  });
+  server.listen(port, () => {
+    console.log(`Serving docs at http://localhost:${port}`);
+  });
+}
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exitCode = 1;
+});