spring-api-scanner 0.1.0

package/src/scanner.ts

@@ -0,0 +1,409 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+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 async function scanSpringProject(projectPath: string): Promise<ExtractedEndpoint[]> {
+  const kotlinRoot = path.join(projectPath, "src", "main", "kotlin");
+  const files = (await listKotlinFiles(kotlinRoot)).sort();
+  const endpoints: ExtractedEndpoint[] = [];
+
+  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: string,
+  sourceFile: string
+): ExtractedEndpoint[] {
+  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: ExtractedEndpoint[] = [];
+
+  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: 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 extractClassPrefixes(source: string): string[] {
+  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: string,
+  classRequestMappingArgs: Set<string>
+): Array<{ method: string; path: string }> {
+  const mappings: Array<{ method: string; path: string }> = [];
+  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: string): Set<string> {
+  const result = new Set<string>();
+  const classMatch = source.match(/@RequestMapping\s*\(([^)]*)\)\s*class\s+/s);
+  if (classMatch?.[1]) {
+    result.add(normalizeAnnotationArgs(classMatch[1]));
+  }
+  return result;
+}
+
+function normalizeAnnotationArgs(value: string): string {
+  return value.replace(/\s+/g, "").trim();
+}
+
+function extractAnnotationPaths(rawArgs?: string): string[] {
+  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?: string): string[] {
+  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: string): {
+  pathVariables: EndpointField[];
+  queryParams: EndpointField[];
+  headers: EndpointField[];
+  pathVariableRenames: Array<{ from: string; to: string }>;
+  requestBody?: EndpointBody;
+} {
+  const chunks = splitTopLevel(rawParams)
+    .map((chunk) => chunk.trim())
+    .filter((chunk) => chunk.length > 0);
+  const pathVariables: EndpointField[] = [];
+  const queryParams: EndpointField[] = [];
+  const headers: EndpointField[] = [];
+  const pathVariableRenames: Array<{ from: string; to: string }> = [];
+  let requestBody: EndpointBody | undefined;
+
+  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: string
+):
+  | { kind: "path"; name: string; sourceName: string; type: string }
+  | { kind: "query"; name: string; type: string; required: boolean }
+  | { kind: "header"; name: string; type: string; required: boolean }
+  | { kind: "body"; type: string; required: boolean }
+  | null {
+  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 as string) : toSnakeCase(variableName),
+      type,
+      required: requiredFlag ?? !isNullable
+    };
+  }
+  if (annotation === "RequestHeader") {
+    return {
+      kind: "header",
+      name: hasExplicitAlias ? (alias as string) : toSnakeCase(variableName),
+      type,
+      required: requiredFlag ?? !isNullable
+    };
+  }
+  if (annotation === "RequestBody") {
+    return {
+      kind: "body",
+      type,
+      required: requiredFlag ?? !isNullable
+    };
+  }
+
+  return null;
+}
+
+function parseRequiredFlag(annotationArgs: string): boolean | undefined {
+  const match = annotationArgs.match(/required\s*=\s*(true|false)/);
+  if (!match) {
+    return undefined;
+  }
+  return match[1] === "true";
+}
+
+function parseAlias(annotationArgs: string): string | undefined {
+  const keyed = annotationArgs.match(/(?:name|value)\s*=\s*"([^"]+)"/)?.[1];
+  if (keyed) {
+    return keyed;
+  }
+  return annotationArgs.match(/"([^"]+)"/)?.[1];
+}
+
+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 joinPaths(prefix: string, leaf: string): string {
+  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: string): string {
+  if (!raw) {
+    return "/";
+  }
+  if (raw === "/") {
+    return "/";
+  }
+  return raw.startsWith("/") ? raw : `/${raw}`;
+}
+
+function applyPathVariableRenames(
+  fullPath: string,
+  renames: Array<{ from: string; to: string }>
+): string {
+  let updated = fullPath;
+  for (const rename of renames) {
+    updated = updated.replaceAll(`{${rename.from}}`, `{${rename.to}}`);
+  }
+  return updated;
+}
+
+function toSnakeCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+    .toLowerCase();
+}