feat: add extractor config loading

Author: tharropoulos

src/config-schema.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { HttpMethodMap } from "./types.js";
+
+export const httpMethodSchema = z.nativeEnum(HttpMethodMap);
+
+export const locationEnum = z.enum(["path", "query", "body"]);
+
+export const routeOverrideParameterSchema = z.object({
+  location: z.enum(["path", "query", "body"]),
+  name: z.string().min(1),
+  canonicalPath: z.string().min(1).optional(),
+});
+
+export const routeOverrideSchema = z.object({
+  method: httpMethodSchema.optional(),
+  path: z.string().min(1),
+  skip: z.boolean().optional(),
+  removeParams: z.array(z.string().min(1)).optional(),
+  addParams: z.array(routeOverrideParameterSchema).optional(),
+});
+
+export const extractorConfigSchema = z
+  .object({
+    root_dir: z.string().default(""),
+    route_file: z.string().min(1).default("src/main/typesense_server.cpp"),
+    source_branch: z.string().min(1).default("v30"),
+    output_path: z.string().min(1).default("./output/typesense_api_spec.json"),
+    diagnostics_output_path: z
+      .string()
+      .min(1)
+      .optional()
+      .default("./output/typesense_api_diagnostics.json"),
+    base_url: z.string().min(1).optional(),
+    max_call_depth: z.number().finite().default(4),
+    fail_on_diagnostics: z.boolean().default(false),
+    fail_on_unresolved: z.boolean().default(false),
+    include_helpers: z.array(z.string().min(1)).default([]),
+    blacklist: z
+      .object({
+        paths: z.array(z.string().min(1)).default([]),
+        params: z.array(z.string().min(1)).default([]),
+      })
+      .default({
+        paths: [],
+        params: [],
+      }),
+    overrides: z.array(routeOverrideSchema).default([]),
+    debug: z
+      .object({
+        enabled: z.boolean().default(false),
+        route_filter: z.string().min(1).optional(),
+      })
+      .default({
+        enabled: false,
+      }),
+  })
+  .strict();
+
+export type RouteOverrideParameter = z.infer<
+  typeof routeOverrideParameterSchema
+>;
+export type RouteOverride = z.infer<typeof routeOverrideSchema>;
+export type ParsedExtractorConfig = z.infer<typeof extractorConfigSchema>;
+export type ParameterLocation = z.infer<typeof locationEnum>;

src/config.ts

@@ -0,0 +1,79 @@
+import path from "node:path";
+import { cosmiconfig } from "cosmiconfig";
+import { extractorConfigSchema } from "./config-schema.js";
+import type { ParsedExtractorConfig } from "./config-schema.js";
+import type {
+  CliOptions,
+  ExtractorConfig,
+} from "./types.js";
+
+export async function loadConfig(
+  configPath: string,
+  cliOptions: CliOptions,
+): Promise<ExtractorConfig> {
+  const absoluteConfigPath = path.resolve(configPath);
+  const configDir = path.dirname(absoluteConfigPath);
+  const explorer = cosmiconfig("typesense-api-extractor", {
+    searchPlaces: [
+      "package.json",
+      ".typesense-api-extractorrc",
+      ".typesense-api-extractorrc.json",
+      ".typesense-api-extractorrc.yaml",
+      ".typesense-api-extractorrc.yml",
+      ".typesense-api-extractorrc.js",
+      "typesense-api-extractor.config.js",
+      "config.json",
+    ],
+  });
+
+  const result = await explorer.load(absoluteConfigPath);
+  if (result === null) {
+    throw new Error(`Could not load config file ${absoluteConfigPath}.`);
+  }
+
+  const parsedConfig = parseConfig(result.config, absoluteConfigPath);
+  return {
+    rootDir: parsedConfig.root_dir,
+    routeFile: parsedConfig.route_file,
+    sourceBranch: parsedConfig.source_branch,
+    outputPath:
+      cliOptions.outputPath !== undefined
+        ? path.resolve(cliOptions.outputPath)
+        : path.resolve(configDir, parsedConfig.output_path),
+    diagnosticsOutputPath:
+      parsedConfig.diagnostics_output_path === undefined
+        ? undefined
+        : path.resolve(configDir, parsedConfig.diagnostics_output_path),
+    baseUrl: cliOptions.baseUrl ?? parsedConfig.base_url,
+    maxCallDepth: cliOptions.maxCallDepth ?? parsedConfig.max_call_depth,
+    failOnDiagnostics:
+      cliOptions.failOnDiagnostics ?? parsedConfig.fail_on_diagnostics,
+    failOnUnresolved:
+      cliOptions.failOnUnresolved ?? parsedConfig.fail_on_unresolved,
+    blacklist: parsedConfig.blacklist,
+    includeHelpers: parsedConfig.include_helpers,
+    overrides: parsedConfig.overrides,
+    debug: {
+      enabled: cliOptions.verbose || parsedConfig.debug.enabled,
+      routeFilter: cliOptions.debugRoute ?? parsedConfig.debug.route_filter,
+    },
+  };
+}
+
+function parseConfig(
+  config: unknown,
+  configPath: string,
+): ParsedExtractorConfig {
+  const parsedConfig = extractorConfigSchema.safeParse(config);
+  if (parsedConfig.success) {
+    return parsedConfig.data;
+  }
+
+  const message = parsedConfig.error.errors
+    .map(
+      (error) =>
+        `Error for config field '${error.path.join(".")}': ${error.message}`,
+    )
+    .join("\n");
+  throw new Error(`Could not parse config file ${configPath}:\n${message}`);
+}