spring-api-scanner 0.1.0

package/dist/resolver.js

@@ -0,0 +1,206 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+export async function scanDataClasses(projectPath) {
+    const kotlinRoot = path.join(projectPath, "src", "main", "kotlin");
+    const files = (await listKotlinFiles(kotlinRoot)).sort();
+    const registry = {};
+    for (const filePath of files) {
+        const source = await readFile(filePath, "utf8");
+        Object.assign(registry, parseDataClassesFromSource(source));
+    }
+    return registry;
+}
+export function parseDataClassesFromSource(source) {
+    const registry = {};
+    const matches = source.matchAll(/((?:\s*@[^\n]+\n)*)\s*data\s+class\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([\s\S]*?)\)/g);
+    for (const match of matches) {
+        const annotationBlock = match[1] ?? "";
+        const name = match[2] ?? "";
+        const rawProperties = match[3] ?? "";
+        const properties = splitTopLevel(rawProperties)
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)
+            .map(parseProperty)
+            .filter((value) => value !== null);
+        registry[name] = {
+            name,
+            namingStrategy: parseNamingStrategy(annotationBlock),
+            properties
+        };
+    }
+    return registry;
+}
+export function resolveSchemaForType(rawType, registry, components, seen = new Set(), context) {
+    const typeName = cleanType(rawType);
+    const unwrapped = normalizeNullableType(unwrapEntity(typeName));
+    if (isListLike(unwrapped)) {
+        const inner = extractSingleGeneric(unwrapped);
+        return {
+            type: "array",
+            items: resolveSchemaForType(inner, registry, components, seen, context)
+        };
+    }
+    const primitive = mapPrimitive(unwrapped);
+    if (primitive) {
+        return primitive;
+    }
+    if (registry[unwrapped]) {
+        ensureComponent(unwrapped, registry, components, seen, context);
+        return { $ref: `#/components/schemas/${unwrapped}` };
+    }
+    if (context) {
+        context.warnings.add(`Unresolved type: ${unwrapped}`);
+    }
+    return { type: "object" };
+}
+function ensureComponent(typeName, registry, components, seen, context) {
+    if (components[typeName] || seen.has(typeName)) {
+        return;
+    }
+    seen.add(typeName);
+    const dto = registry[typeName];
+    if (!dto) {
+        return;
+    }
+    const properties = {};
+    const required = [];
+    for (const property of dto.properties) {
+        const clean = cleanType(property.type);
+        const serializedName = serializePropertyName(dto.namingStrategy, property.name);
+        properties[serializedName] = resolveSchemaForType(clean, registry, components, seen, context);
+        if (!property.nullable) {
+            required.push(serializedName);
+        }
+    }
+    components[typeName] = {
+        type: "object",
+        properties,
+        required
+    };
+}
+function parseProperty(raw) {
+    const parsed = raw.match(/(?:val|var)\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([^=]+?)(?:\s*=.*)?$/);
+    if (!parsed) {
+        return null;
+    }
+    const name = parsed[1] ?? "";
+    const type = cleanType(parsed[2] ?? "Any");
+    return { name, type, nullable: type.endsWith("?") };
+}
+function cleanType(rawType) {
+    return rawType.trim();
+}
+function normalizeNullableType(typeName) {
+    return typeName.endsWith("?") ? typeName.slice(0, -1) : typeName;
+}
+function unwrapEntity(typeName) {
+    const outer = outerType(typeName);
+    if (outer === "ResponseEntity") {
+        return unwrapEntity(extractSingleGeneric(typeName));
+    }
+    return typeName;
+}
+function isListLike(typeName) {
+    const outer = outerType(typeName);
+    return outer === "List" || outer === "MutableList" || outer === "Page";
+}
+function outerType(typeName) {
+    const idx = typeName.indexOf("<");
+    return idx < 0 ? typeName.replace("?", "") : typeName.slice(0, idx).trim();
+}
+function extractSingleGeneric(typeName) {
+    const start = typeName.indexOf("<");
+    const end = typeName.lastIndexOf(">");
+    if (start < 0 || end < 0 || end <= start + 1) {
+        return "Any";
+    }
+    return typeName.slice(start + 1, end).trim();
+}
+function mapPrimitive(typeName) {
+    const withoutNullable = typeName.endsWith("?") ? typeName.slice(0, -1) : typeName;
+    switch (withoutNullable) {
+        case "String":
+            return { type: "string" };
+        case "Long":
+            return { type: "integer", format: "int64" };
+        case "Int":
+            return { type: "integer", format: "int32" };
+        case "Boolean":
+            return { type: "boolean" };
+        case "Double":
+            return { type: "number", format: "double" };
+        case "Float":
+            return { type: "number", format: "float" };
+        case "Instant":
+            return { type: "string", format: "date-time" };
+        default:
+            return null;
+    }
+}
+async function listKotlinFiles(root) {
+    const entries = (await readdir(root, { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name));
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listKotlinFiles(fullPath)));
+            continue;
+        }
+        if (entry.isFile() && fullPath.endsWith(".kt")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function splitTopLevel(input) {
+    const parts = [];
+    let current = "";
+    let depthParen = 0;
+    let depthAngle = 0;
+    let depthSquare = 0;
+    for (const char of input) {
+        if (char === "(")
+            depthParen += 1;
+        if (char === ")")
+            depthParen -= 1;
+        if (char === "<")
+            depthAngle += 1;
+        if (char === ">")
+            depthAngle -= 1;
+        if (char === "[")
+            depthSquare += 1;
+        if (char === "]")
+            depthSquare -= 1;
+        if (char === "," && depthParen === 0 && depthAngle === 0 && depthSquare === 0) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim().length > 0) {
+        parts.push(current);
+    }
+    return parts;
+}
+function parseNamingStrategy(annotationBlock) {
+    if (!/@JsonNaming\s*\(/.test(annotationBlock)) {
+        return "snake_case";
+    }
+    if (/LowerCamelCaseStrategy/.test(annotationBlock)) {
+        return "camelCase";
+    }
+    if (/SnakeCaseStrategy/.test(annotationBlock)) {
+        return "snake_case";
+    }
+    return "snake_case";
+}
+function serializePropertyName(strategy, name) {
+    if (strategy === "camelCase") {
+        return name;
+    }
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase();
+}

package/dist/scanner.d.ts

@@ -0,0 +1,22 @@
+export interface EndpointField {
+    name: string;
+    type: string;
+    required?: boolean;
+}
+export interface EndpointBody {
+    type: string;
+    required: boolean;
+}
+export interface ExtractedEndpoint {
+    sourceFile: string;
+    operationName: string;
+    httpMethod: string;
+    fullPath: string;
+    returnType: string;
+    pathVariables: EndpointField[];
+    queryParams: EndpointField[];
+    headers: EndpointField[];
+    requestBody?: EndpointBody;
+}
+export declare function scanSpringProject(projectPath: string): Promise<ExtractedEndpoint[]>;
+export declare function parseKotlinControllerFile(source: string, sourceFile: string): ExtractedEndpoint[];

package/dist/scanner.js

@@ -0,0 +1,321 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+export async function scanSpringProject(projectPath) {
+    const kotlinRoot = path.join(projectPath, "src", "main", "kotlin");
+    const files = (await listKotlinFiles(kotlinRoot)).sort();
+    const endpoints = [];
+    for (const filePath of files) {
+        const source = await readFile(filePath, "utf8");
+        endpoints.push(...parseKotlinControllerFile(source, filePath));
+    }
+    return endpoints.sort((a, b) => {
+        const byPath = a.fullPath.localeCompare(b.fullPath);
+        if (byPath !== 0)
+            return byPath;
+        const byMethod = a.httpMethod.localeCompare(b.httpMethod);
+        if (byMethod !== 0)
+            return byMethod;
+        return a.operationName.localeCompare(b.operationName);
+    });
+}
+export function parseKotlinControllerFile(source, sourceFile) {
+    if (!/@RestController\b/.test(source)) {
+        return [];
+    }
+    const classPrefixes = extractClassPrefixes(source);
+    const classRequestMappingArgs = extractClassRequestMappingArgs(source);
+    const methods = source.matchAll(/((?:\s*@[A-Za-z_][A-Za-z0-9_]*(?:\((?:[\s\S]*?)\))?\s*)+)fun\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([\s\S]*?)\)\s*:\s*([^\n{=]+)/g);
+    const endpoints = [];
+    for (const match of methods) {
+        const annotationBlock = match[1] ?? "";
+        const operationName = (match[2] ?? "").trim();
+        const rawParams = match[3] ?? "";
+        const returnType = (match[4] ?? "Unit").trim();
+        const mappings = resolveMappings(annotationBlock, classRequestMappingArgs);
+        if (mappings.length === 0) {
+            continue;
+        }
+        const parsedParams = parseFunctionParameters(rawParams);
+        for (const classPrefix of classPrefixes) {
+            for (const mapping of mappings) {
+                endpoints.push({
+                    sourceFile,
+                    operationName,
+                    httpMethod: mapping.method,
+                    fullPath: applyPathVariableRenames(joinPaths(classPrefix, mapping.path), parsedParams.pathVariableRenames),
+                    returnType,
+                    pathVariables: parsedParams.pathVariables,
+                    queryParams: parsedParams.queryParams,
+                    headers: parsedParams.headers,
+                    requestBody: parsedParams.requestBody
+                });
+            }
+        }
+    }
+    return endpoints;
+}
+async function listKotlinFiles(root) {
+    const entries = (await readdir(root, { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name));
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listKotlinFiles(fullPath)));
+            continue;
+        }
+        if (entry.isFile() && fullPath.endsWith(".kt")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function extractClassPrefixes(source) {
+    const classPrefix = source.match(/@RequestMapping\s*\(([^)]*)\)\s*class\s+/s)?.[1] ?? "";
+    const prefixes = extractAnnotationPaths(classPrefix);
+    return prefixes.length > 0 ? prefixes.map((prefix) => normalizePath(prefix)) : ["/"];
+}
+function resolveMappings(annotationBlock, classRequestMappingArgs) {
+    const mappings = [];
+    const annotations = annotationBlock.matchAll(/@([A-Za-z_][A-Za-z0-9_]*)(?:\((?:([\s\S]*?))\))?/g);
+    for (const annotation of annotations) {
+        const name = annotation[1] ?? "";
+        const args = annotation[2];
+        if (name === "GetMapping") {
+            mappings.push(...extractAnnotationPaths(args).map((pathValue) => ({ method: "GET", path: pathValue })));
+            continue;
+        }
+        if (name === "PostMapping") {
+            mappings.push(...extractAnnotationPaths(args).map((pathValue) => ({ method: "POST", path: pathValue })));
+            continue;
+        }
+        if (name === "PutMapping") {
+            mappings.push(...extractAnnotationPaths(args).map((pathValue) => ({ method: "PUT", path: pathValue })));
+            continue;
+        }
+        if (name === "DeleteMapping") {
+            mappings.push(...extractAnnotationPaths(args).map((pathValue) => ({ method: "DELETE", path: pathValue })));
+            continue;
+        }
+        if (name === "PatchMapping") {
+            mappings.push(...extractAnnotationPaths(args).map((pathValue) => ({ method: "PATCH", path: pathValue })));
+            continue;
+        }
+        if (name === "RequestMapping") {
+            const normalizedArgs = normalizeAnnotationArgs(args ?? "");
+            if (classRequestMappingArgs.has(normalizedArgs)) {
+                continue;
+            }
+            const methods = extractRequestMethods(args);
+            const paths = extractAnnotationPaths(args);
+            for (const method of methods) {
+                for (const pathValue of paths) {
+                    mappings.push({ method, path: pathValue });
+                }
+            }
+        }
+    }
+    return mappings;
+}
+function extractClassRequestMappingArgs(source) {
+    const result = new Set();
+    const classMatch = source.match(/@RequestMapping\s*\(([^)]*)\)\s*class\s+/s);
+    if (classMatch?.[1]) {
+        result.add(normalizeAnnotationArgs(classMatch[1]));
+    }
+    return result;
+}
+function normalizeAnnotationArgs(value) {
+    return value.replace(/\s+/g, "").trim();
+}
+function extractAnnotationPaths(rawArgs) {
+    const args = rawArgs ?? "";
+    const arrayMatch = args.match(/(?:value|path)\s*=\s*\[([^\]]*)\]/);
+    if (arrayMatch) {
+        const values = Array.from(arrayMatch[1].matchAll(/"([^"]*)"/g), (m) => m[1] ?? "");
+        return values.length > 0 ? values : [""];
+    }
+    const keyMatch = args.match(/(?:value|path)\s*=\s*"([^"]*)"/);
+    if (keyMatch) {
+        return [keyMatch[1] ?? ""];
+    }
+    const positional = args.match(/^\s*"([^"]*)"\s*$/);
+    if (positional) {
+        return [positional[1] ?? ""];
+    }
+    return [""];
+}
+function extractRequestMethods(rawArgs) {
+    const args = rawArgs ?? "";
+    const arrayMatch = args.match(/method\s*=\s*\[([^\]]*)\]/);
+    if (arrayMatch) {
+        const methods = Array.from(arrayMatch[1].matchAll(/RequestMethod\.([A-Z]+)/g), (m) => m[1] ?? "GET");
+        return methods.length > 0 ? methods : ["GET"];
+    }
+    const single = args.match(/method\s*=\s*RequestMethod\.([A-Z]+)/);
+    if (single) {
+        return [single[1] ?? "GET"];
+    }
+    return ["GET"];
+}
+function parseFunctionParameters(rawParams) {
+    const chunks = splitTopLevel(rawParams)
+        .map((chunk) => chunk.trim())
+        .filter((chunk) => chunk.length > 0);
+    const pathVariables = [];
+    const queryParams = [];
+    const headers = [];
+    const pathVariableRenames = [];
+    let requestBody;
+    for (const chunk of chunks) {
+        const parsed = parseAnnotatedParameter(chunk);
+        if (!parsed) {
+            continue;
+        }
+        if (parsed.kind === "path") {
+            pathVariables.push({ name: parsed.name, type: parsed.type, required: true });
+            if (parsed.sourceName !== parsed.name) {
+                pathVariableRenames.push({ from: parsed.sourceName, to: parsed.name });
+            }
+        }
+        else if (parsed.kind === "query") {
+            queryParams.push({ name: parsed.name, type: parsed.type, required: parsed.required });
+        }
+        else if (parsed.kind === "header") {
+            headers.push({ name: parsed.name, type: parsed.type, required: parsed.required });
+        }
+        else if (parsed.kind === "body") {
+            requestBody = { type: parsed.type, required: parsed.required };
+        }
+    }
+    return { pathVariables, queryParams, headers, pathVariableRenames, requestBody };
+}
+function parseAnnotatedParameter(chunk) {
+    const shape = chunk.match(/@([A-Za-z]+)(?:\(([^)]*)\))?\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([^=]+?)(?:\s*=.*)?$/);
+    if (!shape) {
+        return null;
+    }
+    const annotation = shape[1] ?? "";
+    const annotationArgs = shape[2] ?? "";
+    const variableName = shape[3] ?? "";
+    const type = (shape[4] ?? "Any").trim();
+    const alias = parseAlias(annotationArgs);
+    const requiredFlag = parseRequiredFlag(annotationArgs);
+    const isNullable = type.endsWith("?");
+    const hasExplicitAlias = alias !== undefined;
+    if (annotation === "PathVariable") {
+        return {
+            kind: "path",
+            name: alias ?? toSnakeCase(variableName),
+            sourceName: variableName,
+            type
+        };
+    }
+    if (annotation === "RequestParam") {
+        return {
+            kind: "query",
+            name: hasExplicitAlias ? alias : toSnakeCase(variableName),
+            type,
+            required: requiredFlag ?? !isNullable
+        };
+    }
+    if (annotation === "RequestHeader") {
+        return {
+            kind: "header",
+            name: hasExplicitAlias ? alias : toSnakeCase(variableName),
+            type,
+            required: requiredFlag ?? !isNullable
+        };
+    }
+    if (annotation === "RequestBody") {
+        return {
+            kind: "body",
+            type,
+            required: requiredFlag ?? !isNullable
+        };
+    }
+    return null;
+}
+function parseRequiredFlag(annotationArgs) {
+    const match = annotationArgs.match(/required\s*=\s*(true|false)/);
+    if (!match) {
+        return undefined;
+    }
+    return match[1] === "true";
+}
+function parseAlias(annotationArgs) {
+    const keyed = annotationArgs.match(/(?:name|value)\s*=\s*"([^"]+)"/)?.[1];
+    if (keyed) {
+        return keyed;
+    }
+    return annotationArgs.match(/"([^"]+)"/)?.[1];
+}
+function splitTopLevel(input) {
+    const parts = [];
+    let current = "";
+    let depthParen = 0;
+    let depthAngle = 0;
+    let depthSquare = 0;
+    for (const char of input) {
+        if (char === "(")
+            depthParen += 1;
+        if (char === ")")
+            depthParen -= 1;
+        if (char === "<")
+            depthAngle += 1;
+        if (char === ">")
+            depthAngle -= 1;
+        if (char === "[")
+            depthSquare += 1;
+        if (char === "]")
+            depthSquare -= 1;
+        if (char === "," && depthParen === 0 && depthAngle === 0 && depthSquare === 0) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim().length > 0) {
+        parts.push(current);
+    }
+    return parts;
+}
+function joinPaths(prefix, leaf) {
+    const normalizedPrefix = normalizePath(prefix);
+    const rawLeaf = leaf.trim();
+    if (normalizedPrefix === "/" && rawLeaf === "/") {
+        return "/";
+    }
+    if (rawLeaf === "") {
+        return normalizedPrefix;
+    }
+    if (normalizedPrefix === "/") {
+        return normalizePath(rawLeaf);
+    }
+    if (rawLeaf === "/") {
+        return normalizedPrefix.endsWith("/") ? normalizedPrefix : `${normalizedPrefix}/`;
+    }
+    return `${normalizedPrefix.replace(/\/$/, "")}/${rawLeaf.replace(/^\//, "")}`;
+}
+function normalizePath(raw) {
+    if (!raw) {
+        return "/";
+    }
+    if (raw === "/") {
+        return "/";
+    }
+    return raw.startsWith("/") ? raw : `/${raw}`;
+}
+function applyPathVariableRenames(fullPath, renames) {
+    let updated = fullPath;
+    for (const rename of renames) {
+        updated = updated.replaceAll(`{${rename.from}}`, `{${rename.to}}`);
+    }
+    return updated;
+}
+function toSnakeCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase();
+}

package/dist/ui.d.ts

@@ -0,0 +1,36 @@
+import type { OpenApiDocument, OpenApiSchema } from "./openapi.js";
+import type { ExtractedEndpoint } from "./scanner.js";
+export interface UiEndpointCard {
+    id: string;
+    operationName: string;
+    method: string;
+    path: string;
+    controller: string;
+    pathVariables: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+    }>;
+    queryParams: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+    }>;
+    headers: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+    }>;
+    requestSchema?: OpenApiSchema;
+    responseSchema?: OpenApiSchema;
+    curl: string;
+}
+export interface UiModel {
+    generatedAt: string;
+    endpoints: UiEndpointCard[];
+}
+export declare function buildUiModel(input: {
+    endpoints: ExtractedEndpoint[];
+    openapi: OpenApiDocument;
+}): UiModel;
+export declare function renderUiHtml(title: string, embeddedModel?: UiModel): string;