fix: resolve lint complexity failures blocking CI test check

Extract helpers and apply Biome style fixes so Ultracite passes in the toolkit-docs-generator.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: teallarson

toolkit-docs-generator/scripts/check-stale-summaries.ts

@@ -39,18 +39,29 @@ const listToolkitFiles = (): string[] => {
   }
 };
 
-const main = (): number => {
+const readToolkitShape = (
+  file: string
+): { toolkit: ToolkitShape } | { error: string } => {
+  try {
+    const raw = readFileSync(join(TOOLKITS_DIR, file), "utf8");
+    return { toolkit: JSON.parse(raw) as ToolkitShape };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { error: message };
+  }
+};
+
+const collectStaleSummaries = (
+  files: string[]
+): Array<{ file: string; id: string; reason: string }> => {
   const stale: Array<{ file: string; id: string; reason: string }> = [];
-  for (const file of listToolkitFiles()) {
-    let toolkit: ToolkitShape;
-    try {
-      const raw = readFileSync(join(TOOLKITS_DIR, file), "utf8");
-      toolkit = JSON.parse(raw) as ToolkitShape;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      console.error(`✗ Cannot parse ${file}: ${message}`);
-      return 1;
+  for (const file of files) {
+    const result = readToolkitShape(file);
+    if ("error" in result) {
+      console.error(`✗ Cannot parse ${file}: ${result.error}`);
+      throw new Error(`Cannot parse ${file}`);
     }
+    const toolkit = result.toolkit;
     if (toolkit.summaryStale === true) {
       stale.push({
         file,
@@ -62,6 +73,16 @@ const main = (): number => {
       });
     }
   }
+  return stale;
+};
+
+const main = (): number => {
+  let stale: Array<{ file: string; id: string; reason: string }>;
+  try {
+    stale = collectStaleSummaries(listToolkitFiles());
+  } catch {
+    return 1;
+  }
 
   if (stale.length === 0) {
     console.log(`✓ No stale summaries in ${TOOLKITS_DIR}`);

toolkit-docs-generator/src/cli/exclusion-cleanup.ts

@@ -18,6 +18,37 @@ export interface CleanupExcludedToolkitOutputResult {
   warnings: string[];
 }
 
+const collectRebuildWarnings = (
+  rebuildResult: RebuildIndexResult,
+  verbose: boolean
+): string[] => {
+  const warnings: string[] = [];
+
+  if (rebuildResult.readErrors.length > 0) {
+    warnings.push(
+      `Index rebuild skipped ${rebuildResult.readErrors.length} unreadable toolkit file(s).`
+    );
+    if (verbose) {
+      for (const error of rebuildResult.readErrors) {
+        warnings.push(`Index rebuild read error: ${error}`);
+      }
+    }
+  }
+
+  if (rebuildResult.readWarnings.length > 0) {
+    warnings.push(
+      `Index rebuild reported ${rebuildResult.readWarnings.length} warning(s).`
+    );
+    if (verbose) {
+      for (const warning of rebuildResult.readWarnings) {
+        warnings.push(`Index rebuild warning: ${warning}`);
+      }
+    }
+  }
+
+  return warnings;
+};
+
 export const cleanupExcludedToolkitOutput = async (
   options: CleanupExcludedToolkitOutputOptions
 ): Promise<CleanupExcludedToolkitOutputResult> => {
@@ -33,37 +64,18 @@ export const cleanupExcludedToolkitOutput = async (
     return { deleted, warnings: [] };
   }
 
-  const warnings: string[] = [];
-
   try {
     const rebuildResult = await options.generator.rebuildIndexFromOutput();
-
-    if (rebuildResult.readErrors.length > 0) {
-      warnings.push(
-        `Index rebuild skipped ${rebuildResult.readErrors.length} unreadable toolkit file(s).`
-      );
-      if (options.verbose) {
-        for (const error of rebuildResult.readErrors) {
-          warnings.push(`Index rebuild read error: ${error}`);
-        }
-      }
-    }
-
-    if (rebuildResult.readWarnings.length > 0) {
-      warnings.push(
-        `Index rebuild reported ${rebuildResult.readWarnings.length} warning(s).`
-      );
-      if (options.verbose) {
-        for (const warning of rebuildResult.readWarnings) {
-          warnings.push(`Index rebuild warning: ${warning}`);
-        }
-      }
-    }
+    return {
+      deleted,
+      warnings: collectRebuildWarnings(rebuildResult, options.verbose),
+    };
   } catch (error) {
-    warnings.push(
-      `Excluded toolkit files were deleted, but index rebuild failed: ${error instanceof Error ? error.message : String(error)}`
-    );
+    return {
+      deleted,
+      warnings: [
+        `Excluded toolkit files were deleted, but index rebuild failed: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+    };
   }
-
-  return { deleted, warnings };
 };

toolkit-docs-generator/src/diff/previous-output.ts

@@ -259,6 +259,45 @@ type FallbackToolkitResult = {
   droppedParameterCount: number;
 };
 
+type FallbackSummaryFields = {
+  summary?: string;
+  summaryStale?: boolean;
+  summaryStaleReason?: string;
+  generatedAt?: string;
+};
+
+const readFallbackSummaryFields = (
+  record: Record<string, unknown>
+): FallbackSummaryFields => ({
+  ...(typeof record.summary === "string" ? { summary: record.summary } : {}),
+  ...(typeof record.summaryStale === "boolean"
+    ? { summaryStale: record.summaryStale }
+    : {}),
+  ...(typeof record.summaryStaleReason === "string"
+    ? { summaryStaleReason: record.summaryStaleReason }
+    : {}),
+  ...(typeof record.generatedAt === "string"
+    ? { generatedAt: record.generatedAt }
+    : {}),
+});
+
+const readFallbackCustomSections = (
+  record: Record<string, unknown>
+): Pick<
+  MergedToolkit,
+  "documentationChunks" | "customImports" | "subPages"
+> => ({
+  documentationChunks: Array.isArray(record.documentationChunks)
+    ? (record.documentationChunks as MergedToolkit["documentationChunks"])
+    : [],
+  customImports: Array.isArray(record.customImports)
+    ? (record.customImports as MergedToolkit["customImports"])
+    : [],
+  subPages: Array.isArray(record.subPages)
+    ? (record.subPages as MergedToolkit["subPages"])
+    : [],
+});
+
 const buildFallbackToolkit = (
   record: Record<string, unknown>,
   fallbackId: string
@@ -274,39 +313,16 @@ const buildFallbackToolkit = (
 
   const metadataResult = MergedToolkitMetadataSchema.safeParse(record.metadata);
   const authResult = MergedToolkitAuthSchema.safeParse(record.auth);
-  const summary =
-    typeof record.summary === "string" ? record.summary : undefined;
-  const summaryStale =
-    typeof record.summaryStale === "boolean" ? record.summaryStale : undefined;
-  const summaryStaleReason =
-    typeof record.summaryStaleReason === "string"
-      ? record.summaryStaleReason
-      : undefined;
-  const generatedAt =
-    typeof record.generatedAt === "string" ? record.generatedAt : undefined;
-
-  // Carry forward custom sections even when strict schema parse fails.
-  // These are hand-authored fields — losing them silently on any schema
-  // mismatch would permanently wipe content on the next write.
-  const documentationChunks = Array.isArray(record.documentationChunks)
-    ? (record.documentationChunks as MergedToolkit["documentationChunks"])
-    : [];
-  const customImports = Array.isArray(record.customImports)
-    ? (record.customImports as MergedToolkit["customImports"])
-    : [];
-  const subPages = Array.isArray(record.subPages)
-    ? (record.subPages as MergedToolkit["subPages"])
-    : [];
+  const summaryFields = readFallbackSummaryFields(record);
+  const customSections = readFallbackCustomSections(record);
 
   return {
     toolkit: {
       id: toolkitId,
       label,
       version,
       description,
-      ...(summary ? { summary } : {}),
-      ...(summaryStale !== undefined ? { summaryStale } : {}),
-      ...(summaryStaleReason !== undefined ? { summaryStaleReason } : {}),
+      ...summaryFields,
       metadata: metadataResult.success
         ? metadataResult.data
         : DEFAULT_PREVIOUS_TOOLKIT_METADATA,
@@ -316,10 +332,7 @@ const buildFallbackToolkit = (
         secretsInfo: [],
         documentationChunks: [],
       })),
-      documentationChunks,
-      customImports,
-      subPages,
-      ...(generatedAt ? { generatedAt } : {}),
+      ...customSections,
     },
     droppedToolCount,
     droppedParameterCount,

toolkit-docs-generator/src/diff/toolkit-diff.ts

@@ -243,10 +243,10 @@ const hasRelevantMetadataChanges = (
   // preserve the previous output (or report the recoverable failure). Only
   // two absent snapshots are genuinely unchanged; new toolkits are already
   // selected by their tool-level additions.
-  if (!current && !previous) {
+  if (!(current || previous)) {
     return false;
   }
-  if (!current || !previous) {
+  if (!(current && previous)) {
     return true;
   }
 
@@ -337,7 +337,7 @@ export const compareToolkit = (
   toolkitId: string,
   currentTools: readonly ToolDefinition[],
   previousToolkit: MergedToolkit | undefined,
-  currentMetadata: ToolkitMetadata | null | undefined = undefined
+  currentMetadata?: ToolkitMetadata | null
 ): ToolkitChange => {
   const toolChanges = compareTools(currentTools, previousToolkit);
   const currentVersion = getToolkitVersion(currentTools);