spring-api-scanner 0.1.0

package/src/openapi.ts

@@ -0,0 +1,191 @@
+import type { ExtractedEndpoint } from "./scanner.js";
+import { resolveSchemaForType, type KotlinTypeRegistry, type ResolutionContext } from "./resolver.js";
+
+export interface OpenApiSchema {
+  type?: string;
+  format?: string;
+  items?: OpenApiSchema;
+  properties?: Record<string, OpenApiSchema>;
+  required?: string[];
+  $ref?: string;
+}
+
+export interface OpenApiParameter {
+  in: "path" | "query" | "header";
+  name: string;
+  required: boolean;
+  schema: OpenApiSchema;
+}
+
+export interface OpenApiResponse {
+  description: string;
+  content: {
+    "application/json": {
+      schema: OpenApiSchema;
+    };
+  };
+}
+
+export interface OpenApiOperation {
+  operationId: string;
+  tags: string[];
+  parameters: OpenApiParameter[];
+  requestBody?: {
+    required: boolean;
+    content: {
+      "application/json": {
+        schema: OpenApiSchema;
+      };
+    };
+  };
+  responses: Record<string, OpenApiResponse | { description: string }>;
+}
+
+export interface OpenApiDocument {
+  openapi: string;
+  info: {
+    title: string;
+    version: string;
+  };
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  components: {
+    schemas: Record<string, OpenApiSchema>;
+  };
+}
+
+export interface OpenApiArtifacts {
+  document: OpenApiDocument;
+  warnings: string[];
+}
+
+export function buildOpenApiDocument(input: {
+  title: string;
+  version: string;
+  endpoints: ExtractedEndpoint[];
+  types: KotlinTypeRegistry;
+}): OpenApiDocument {
+  return buildOpenApiArtifacts(input).document;
+}
+
+export function buildOpenApiArtifacts(input: {
+  title: string;
+  version: string;
+  endpoints: ExtractedEndpoint[];
+  types: KotlinTypeRegistry;
+}): OpenApiArtifacts {
+  const schemas: Record<string, OpenApiSchema> = {};
+  const paths: Record<string, Record<string, OpenApiOperation>> = {};
+  const context: ResolutionContext = { warnings: new Set() };
+
+  for (const endpoint of input.endpoints) {
+    const method = endpoint.httpMethod.toLowerCase();
+    const parameters: OpenApiParameter[] = [
+      ...endpoint.pathVariables.map((item): OpenApiParameter => ({
+        in: "path",
+        name: item.name,
+        required: true,
+        schema: resolveSchemaForType(item.type, input.types, schemas, new Set(), context) as OpenApiSchema
+      })),
+      ...endpoint.queryParams.map((item): OpenApiParameter => ({
+        in: "query",
+        name: item.name,
+        required: item.required ?? false,
+        schema: resolveSchemaForType(item.type, input.types, schemas, new Set(), context) as OpenApiSchema
+      })),
+      ...endpoint.headers.map((item): OpenApiParameter => ({
+        in: "header",
+        name: item.name,
+        required: item.required ?? false,
+        schema: resolveSchemaForType(item.type, input.types, schemas, new Set(), context) as OpenApiSchema
+      }))
+    ];
+
+    const requestBody = endpoint.requestBody
+      ? {
+          required: endpoint.requestBody.required,
+          content: {
+            "application/json": {
+              schema: resolveSchemaForType(
+                endpoint.requestBody.type,
+                input.types,
+                schemas,
+                new Set(),
+                context
+              ) as OpenApiSchema
+            }
+          }
+        }
+      : undefined;
+
+    const response = buildOperationResponse(endpoint, input.types, schemas, context);
+
+    const operation: OpenApiOperation = {
+      operationId: endpoint.operationName,
+      tags: [guessTag(endpoint.sourceFile)],
+      parameters,
+      ...(requestBody ? { requestBody } : {}),
+      responses: response
+    };
+
+    if (!paths[endpoint.fullPath]) {
+      paths[endpoint.fullPath] = {};
+    }
+    paths[endpoint.fullPath][method] = operation;
+  }
+
+  return {
+    document: {
+      openapi: "3.0.3",
+      info: {
+        title: input.title,
+        version: input.version
+      },
+      paths,
+      components: {
+        schemas
+      }
+    },
+    warnings: [...context.warnings]
+  };
+}
+
+function guessTag(sourceFile: string): string {
+  const file = sourceFile.replaceAll("\\", "/").split("/").at(-1) ?? sourceFile;
+  return file.endsWith(".kt") ? file.slice(0, -3) : file;
+}
+
+function buildOperationResponse(
+  endpoint: ExtractedEndpoint,
+  types: KotlinTypeRegistry,
+  schemas: Record<string, OpenApiSchema>,
+  context: ResolutionContext
+): Record<string, OpenApiResponse | { description: string }> {
+  const normalizedReturn = endpoint.returnType.trim();
+  const isNoContent = normalizedReturn === "Unit" || normalizedReturn === "Void";
+
+  if (isNoContent) {
+    return {
+      "204": {
+        description: "No Content"
+      }
+    };
+  }
+
+  const statusCode = endpoint.httpMethod === "POST" ? "201" : "200";
+  return {
+    [statusCode]: {
+      description: statusCode === "201" ? "Created" : "OK",
+      content: {
+        "application/json": {
+          schema: resolveSchemaForType(
+            endpoint.returnType,
+            types,
+            schemas,
+            new Set(),
+            context
+          ) as OpenApiSchema
+        }
+      }
+    }
+  };
+}

package/src/output.ts

@@ -0,0 +1,36 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { CliOptions } from "./args.js";
+import { buildOpenApiArtifacts } from "./openapi.js";
+import type { KotlinTypeRegistry } from "./resolver.js";
+import type { ExtractedEndpoint } from "./scanner.js";
+import { buildUiModel, renderUiHtml } from "./ui.js";
+
+export async function writePlaceholderArtifacts(
+  options: CliOptions,
+  endpoints: ExtractedEndpoint[],
+  types: KotlinTypeRegistry
+): Promise<{ warnings: string[] }> {
+  const outputDir = path.resolve(options.output);
+  const openApiPath = path.join(outputDir, "openapi.json");
+  const uiDataPath = path.join(outputDir, "ui-data.json");
+  const indexPath = path.join(outputDir, "index.html");
+  const artifacts = buildOpenApiArtifacts({
+    title: options.title,
+    version: options.version,
+    endpoints,
+    types
+  });
+
+  const uiModel = buildUiModel({
+    endpoints,
+    openapi: artifacts.document
+  });
+
+  await mkdir(outputDir, { recursive: true });
+  await writeFile(openApiPath, JSON.stringify(artifacts.document, null, 2), "utf8");
+  await writeFile(uiDataPath, JSON.stringify(uiModel, null, 2), "utf8");
+  await writeFile(indexPath, renderUiHtml(options.title, uiModel), "utf8");
+
+  return { warnings: artifacts.warnings };
+}

package/src/resolver.ts

@@ -0,0 +1,274 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface KotlinProperty {
+  name: string;
+  type: string;
+  nullable: boolean;
+}
+
+export interface KotlinDataClass {
+  name: string;
+  namingStrategy: "snake_case" | "camelCase";
+  properties: KotlinProperty[];
+}
+
+export type KotlinTypeRegistry = Record<string, KotlinDataClass>;
+
+export interface ResolutionContext {
+  warnings: Set<string>;
+}
+
+export async function scanDataClasses(projectPath: string): Promise<KotlinTypeRegistry> {
+  const kotlinRoot = path.join(projectPath, "src", "main", "kotlin");
+  const files = (await listKotlinFiles(kotlinRoot)).sort();
+  const registry: KotlinTypeRegistry = {};
+
+  for (const filePath of files) {
+    const source = await readFile(filePath, "utf8");
+    Object.assign(registry, parseDataClassesFromSource(source));
+  }
+
+  return registry;
+}
+
+export function parseDataClassesFromSource(source: string): KotlinTypeRegistry {
+  const registry: KotlinTypeRegistry = {};
+  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 is KotlinProperty => value !== null);
+
+    registry[name] = {
+      name,
+      namingStrategy: parseNamingStrategy(annotationBlock),
+      properties
+    };
+  }
+
+  return registry;
+}
+
+export function resolveSchemaForType(
+  rawType: string,
+  registry: KotlinTypeRegistry,
+  components: Record<string, unknown>,
+  seen: Set<string> = new Set(),
+  context?: ResolutionContext
+): Record<string, unknown> {
+  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: string,
+  registry: KotlinTypeRegistry,
+  components: Record<string, unknown>,
+  seen: Set<string>,
+  context?: ResolutionContext
+): void {
+  if (components[typeName] || seen.has(typeName)) {
+    return;
+  }
+  seen.add(typeName);
+
+  const dto = registry[typeName];
+  if (!dto) {
+    return;
+  }
+
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  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: string): KotlinProperty | null {
+  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: string): string {
+  return rawType.trim();
+}
+
+function normalizeNullableType(typeName: string): string {
+  return typeName.endsWith("?") ? typeName.slice(0, -1) : typeName;
+}
+
+function unwrapEntity(typeName: string): string {
+  const outer = outerType(typeName);
+  if (outer === "ResponseEntity") {
+    return unwrapEntity(extractSingleGeneric(typeName));
+  }
+  return typeName;
+}
+
+function isListLike(typeName: string): boolean {
+  const outer = outerType(typeName);
+  return outer === "List" || outer === "MutableList" || outer === "Page";
+}
+
+function outerType(typeName: string): string {
+  const idx = typeName.indexOf("<");
+  return idx < 0 ? typeName.replace("?", "") : typeName.slice(0, idx).trim();
+}
+
+function extractSingleGeneric(typeName: string): string {
+  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: string): Record<string, unknown> | null {
+  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: string): Promise<string[]> {
+  const entries = (await readdir(root, { withFileTypes: true }).catch(() => [])).sort((a, b) =>
+    a.name.localeCompare(b.name)
+  );
+  const files: string[] = [];
+
+  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: string): string[] {
+  const parts: string[] = [];
+  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: string): "snake_case" | "camelCase" {
+  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: "snake_case" | "camelCase", name: string): string {
+  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();
+}