@lota-sdk/core 0.1.5

package/src/workers/utils/repo-structure-extractor.ts

@@ -0,0 +1,645 @@
+import { readdir, readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import {
+  RepositoryStructureArtifactSchema,
+  RepositoryStructureSummarySchema,
+} from '@lota-sdk/shared/schemas/repository-structure'
+import type {
+  RepositoryStructureArtifact,
+  RepositoryStructureComponent,
+  RepositoryStructureShape,
+  RepositoryStructureSignal,
+  RepositoryStructureSummary,
+} from '@lota-sdk/shared/schemas/repository-structure'
+
+const EXTRACTOR_VERSION = 'repository-structure-extractor.v1'
+const IGNORED_DIR_NAMES = new Set([
+  '.git',
+  '.idea',
+  '.next',
+  '.turbo',
+  '.vscode',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'target',
+])
+
+const LANGUAGE_BY_EXTENSION: Record<string, string> = {
+  '.cjs': 'JavaScript',
+  '.cpp': 'C++',
+  '.cs': 'C#',
+  '.go': 'Go',
+  '.java': 'Java',
+  '.js': 'JavaScript',
+  '.jsx': 'React JSX',
+  '.kt': 'Kotlin',
+  '.md': 'Markdown',
+  '.mjs': 'JavaScript',
+  '.php': 'PHP',
+  '.py': 'Python',
+  '.rb': 'Ruby',
+  '.rs': 'Rust',
+  '.sql': 'SQL',
+  '.swift': 'Swift',
+  '.ts': 'TypeScript',
+  '.tsx': 'React TSX',
+  '.vue': 'Vue',
+}
+
+type PackageJson = {
+  name?: string
+  private?: boolean
+  scripts?: Record<string, string>
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+type ExtractParams = {
+  rootDir: string
+  repositoryKey: string
+  repositoryFullName: string
+  defaultBranch: string
+  indexBranch: string
+  commitSha: string | undefined
+}
+
+type ExtractResult = {
+  repoStructure: RepositoryStructureArtifact
+  structureSummary: RepositoryStructureSummary
+  structureMarkdown: string
+}
+
+function normalizePath(value: string): string {
+  return value.replaceAll(path.sep, '/')
+}
+
+function unique<T>(values: T[]): T[] {
+  return [...new Set(values)]
+}
+
+function truncate<T>(values: T[], limit: number): T[] {
+  return values.slice(0, limit)
+}
+
+function normalizeEvidencePaths(values: string[]): string[] {
+  return truncate(unique(values), 20)
+}
+
+function createSignal(params: {
+  key: string
+  label: string
+  reason: string
+  evidencePaths?: string[]
+}): RepositoryStructureSignal {
+  return {
+    key: params.key,
+    label: params.label,
+    reason: params.reason,
+    evidencePaths: normalizeEvidencePaths(params.evidencePaths ?? []),
+  }
+}
+
+async function collectRelativeFilePaths(rootDir: string, currentDir = ''): Promise<string[]> {
+  const absoluteDir = path.join(rootDir, currentDir)
+  const entries = await readdir(absoluteDir, { withFileTypes: true })
+  const filePaths: string[] = []
+
+  for (const entry of entries) {
+    const relativePath = normalizePath(path.join(currentDir, entry.name))
+    if (entry.isDirectory()) {
+      if (IGNORED_DIR_NAMES.has(entry.name)) continue
+      filePaths.push(...(await collectRelativeFilePaths(rootDir, relativePath)))
+      continue
+    }
+    filePaths.push(relativePath)
+  }
+
+  return filePaths
+}
+
+async function readPackageJson(rootDir: string, relativePath: string): Promise<PackageJson | null> {
+  try {
+    const raw = await readFile(path.join(rootDir, relativePath), 'utf8')
+    return JSON.parse(raw) as PackageJson
+  } catch {
+    return null
+  }
+}
+
+function gatherTopLevelEntries(filePaths: string[]): string[] {
+  return truncate(
+    [...new Set(filePaths.map((filePath) => filePath.split('/')[0]).filter((entry) => entry && entry !== ''))].sort(),
+    200,
+  )
+}
+
+function gatherLanguageSignals(filePaths: string[]): RepositoryStructureSignal[] {
+  const languageEvidence = new Map<string, string[]>()
+
+  for (const filePath of filePaths) {
+    const language = LANGUAGE_BY_EXTENSION[path.extname(filePath).toLowerCase()]
+    if (!language) continue
+    const entries = languageEvidence.get(language) ?? []
+    entries.push(filePath)
+    languageEvidence.set(language, entries)
+  }
+
+  return [...languageEvidence.entries()].map(([language, evidencePaths]) =>
+    createSignal({
+      key: language.toLowerCase().replaceAll(/\s+/g, '-'),
+      label: language,
+      reason: `Detected ${language} source files in the repository.`,
+      evidencePaths,
+    }),
+  )
+}
+
+function findPaths(filePaths: string[], matcher: (filePath: string) => boolean): string[] {
+  return filePaths.filter(matcher)
+}
+
+function buildPathSignals(params: {
+  keyPrefix: string
+  label: string
+  reason: string
+  filePaths: string[]
+}): RepositoryStructureSignal[] {
+  return params.filePaths.map((filePath, index) =>
+    createSignal({
+      key: `${params.keyPrefix}-${index + 1}`,
+      label: filePath,
+      reason: params.reason,
+      evidencePaths: [filePath],
+    }),
+  )
+}
+
+function inferFrameworkSignals(packageJsons: Array<{ path: string; data: PackageJson }>): RepositoryStructureSignal[] {
+  const dependencyMap = new Map<string, { label: string; reason: string; evidencePaths: string[] }>()
+
+  const register = (dependencyName: string, label: string, reason: string, evidencePath: string) => {
+    const current = dependencyMap.get(dependencyName) ?? { label, reason, evidencePaths: [] }
+    current.evidencePaths.push(evidencePath)
+    dependencyMap.set(dependencyName, current)
+  }
+
+  for (const packageJson of packageJsons) {
+    const dependencyNames = [
+      ...Object.keys(packageJson.data.dependencies ?? {}),
+      ...Object.keys(packageJson.data.devDependencies ?? {}),
+    ]
+    for (const dependencyName of dependencyNames) {
+      if (dependencyName === 'next') {
+        register('next', 'Next.js', 'Detected the Next.js framework dependency.', packageJson.path)
+      }
+      if (dependencyName === 'react') {
+        register('react', 'React', 'Detected the React dependency.', packageJson.path)
+      }
+      if (dependencyName === 'vite') {
+        register('vite', 'Vite', 'Detected the Vite build tool dependency.', packageJson.path)
+      }
+      if (dependencyName === 'hono') {
+        register('hono', 'Hono', 'Detected the Hono server framework dependency.', packageJson.path)
+      }
+      if (dependencyName === 'express') {
+        register('express', 'Express', 'Detected the Express server framework dependency.', packageJson.path)
+      }
+      if (dependencyName === '@tanstack/react-router') {
+        register(
+          'tanstack-router',
+          'TanStack Router',
+          'Detected TanStack Router in package dependencies.',
+          packageJson.path,
+        )
+      }
+      if (dependencyName === 'tailwindcss') {
+        register('tailwindcss', 'Tailwind CSS', 'Detected Tailwind CSS in package dependencies.', packageJson.path)
+      }
+      if (dependencyName === '@better-auth/better-auth' || dependencyName === 'better-auth') {
+        register('better-auth', 'Better Auth', 'Detected Better Auth in package dependencies.', packageJson.path)
+      }
+      if (dependencyName === 'bullmq') {
+        register('bullmq', 'BullMQ', 'Detected BullMQ job processing.', packageJson.path)
+      }
+      if (dependencyName === 'prisma') {
+        register('prisma', 'Prisma', 'Detected Prisma ORM.', packageJson.path)
+      }
+      if (dependencyName === 'surrealdb') {
+        register('surrealdb', 'SurrealDB', 'Detected SurrealDB client usage.', packageJson.path)
+      }
+    }
+  }
+
+  return [...dependencyMap.entries()].map(([dependencyName, value]) =>
+    createSignal({ key: dependencyName, label: value.label, reason: value.reason, evidencePaths: value.evidencePaths }),
+  )
+}
+
+function inferPackageManagerSignals(filePaths: string[]): RepositoryStructureSignal[] {
+  const signals: RepositoryStructureSignal[] = []
+  if (filePaths.includes('bun.lock') || filePaths.includes('bun.lockb')) {
+    signals.push(
+      createSignal({ key: 'bun', label: 'Bun', reason: 'Detected Bun lockfile.', evidencePaths: ['bun.lock'] }),
+    )
+  }
+  if (filePaths.includes('package-lock.json')) {
+    signals.push(
+      createSignal({
+        key: 'npm',
+        label: 'npm',
+        reason: 'Detected npm lockfile.',
+        evidencePaths: ['package-lock.json'],
+      }),
+    )
+  }
+  if (filePaths.includes('pnpm-lock.yaml')) {
+    signals.push(
+      createSignal({
+        key: 'pnpm',
+        label: 'pnpm',
+        reason: 'Detected pnpm lockfile.',
+        evidencePaths: ['pnpm-lock.yaml'],
+      }),
+    )
+  }
+  if (filePaths.includes('yarn.lock')) {
+    signals.push(
+      createSignal({ key: 'yarn', label: 'Yarn', reason: 'Detected Yarn lockfile.', evidencePaths: ['yarn.lock'] }),
+    )
+  }
+  return signals
+}
+
+function inferRepoShape(params: {
+  topLevelEntries: string[]
+  components: RepositoryStructureComponent[]
+  frameworks: RepositoryStructureSignal[]
+  filePaths: string[]
+}): { kind: RepositoryStructureShape; reason: string; evidencePaths: string[] } {
+  if (
+    params.topLevelEntries.includes('apps') ||
+    params.topLevelEntries.includes('packages') ||
+    params.components.length >= 3
+  ) {
+    return {
+      kind: 'monorepo',
+      reason: 'Multiple package or app roots were detected, which indicates a monorepo-style repository.',
+      evidencePaths: normalizeEvidencePaths(params.components.map((component) => component.path)),
+    }
+  }
+
+  if (
+    params.topLevelEntries.every((entry) => ['docs', 'documentation', 'website'].includes(entry)) ||
+    params.filePaths.every((filePath) => filePath.endsWith('.md') || filePath.startsWith('docs/'))
+  ) {
+    return {
+      kind: 'docs-only',
+      reason: 'The repository appears to be documentation-centric with little or no application source.',
+      evidencePaths: normalizeEvidencePaths(params.topLevelEntries),
+    }
+  }
+
+  if (params.frameworks.some((framework) => ['React', 'Next.js', 'Vite'].includes(framework.label))) {
+    return {
+      kind: 'single-project',
+      reason: 'A single primary web application framework was detected without strong monorepo signals.',
+      evidencePaths: normalizeEvidencePaths(params.frameworks.flatMap((framework) => framework.evidencePaths)),
+    }
+  }
+
+  return {
+    kind: 'uncertain',
+    reason: 'The repository structure did not clearly match a single canonical shape.',
+    evidencePaths: normalizeEvidencePaths(params.topLevelEntries),
+  }
+}
+
+function inferComponentKind(componentPath: string, packageJson: PackageJson): RepositoryStructureComponent['kind'] {
+  const dependencyNames = [
+    ...Object.keys(packageJson.dependencies ?? {}),
+    ...Object.keys(packageJson.devDependencies ?? {}),
+  ]
+
+  if (componentPath.startsWith('docs/') || componentPath === 'docs') return 'docs'
+  if (componentPath.startsWith('apps/') || dependencyNames.includes('next') || dependencyNames.includes('react')) {
+    return 'app'
+  }
+  if (
+    componentPath.startsWith('services/') ||
+    dependencyNames.includes('hono') ||
+    dependencyNames.includes('express')
+  ) {
+    return 'service'
+  }
+  if (componentPath.startsWith('packages/')) return 'package'
+  if (packageJson.private === false) return 'library'
+  return 'unknown'
+}
+
+function inferComponentFrameworks(packageJson: PackageJson): string[] {
+  return unique(
+    [
+      packageJson.dependencies?.next ? 'Next.js' : null,
+      packageJson.dependencies?.react ? 'React' : null,
+      packageJson.dependencies?.hono ? 'Hono' : null,
+      packageJson.dependencies?.express ? 'Express' : null,
+      packageJson.dependencies?.tailwindcss ? 'Tailwind CSS' : null,
+    ].filter((value): value is string => Boolean(value)),
+  )
+}
+
+function inferComponentLanguages(filePaths: string[], componentPath: string): string[] {
+  const componentFiles = filePaths.filter(
+    (filePath) => filePath === componentPath || filePath.startsWith(`${componentPath}/`),
+  )
+  return unique(
+    componentFiles
+      .map((filePath) => LANGUAGE_BY_EXTENSION[path.extname(filePath).toLowerCase()])
+      .filter((value): value is string => Boolean(value)),
+  ).slice(0, 20)
+}
+
+function summarizeSignals(signals: RepositoryStructureSignal[], limit = 20): string[] {
+  return truncate(unique(signals.map((signal) => signal.label)), limit)
+}
+
+function buildStructureMarkdown(params: {
+  repoStructure: RepositoryStructureArtifact
+  structureSummary: RepositoryStructureSummary
+}): string {
+  const summary = params.structureSummary
+  return [
+    '# Repository Structure',
+    '',
+    `- Shape: ${summary.repoShape}`,
+    `- Package managers: ${summary.packageManagers.join(', ') || 'none detected'}`,
+    `- Languages: ${summary.languages.join(', ') || 'none detected'}`,
+    `- Frameworks: ${summary.frameworks.join(', ') || 'none detected'}`,
+    `- Components: ${
+      summary.components.length > 0
+        ? summary.components.map((component) => `${component.kind}:${component.name}@${component.path}`).join(', ')
+        : 'none detected'
+    }`,
+    `- Entry points: ${summary.entryPoints.join(', ') || 'none detected'}`,
+    `- Routes: ${summary.routeSignals.join(', ') || 'none detected'}`,
+    `- APIs: ${summary.apiSignals.join(', ') || 'none detected'}`,
+    `- Database: ${summary.databaseSignals.join(', ') || 'none detected'}`,
+    `- Auth: ${summary.authSignals.join(', ') || 'none detected'}`,
+    `- Jobs: ${summary.jobSignals.join(', ') || 'none detected'}`,
+    `- Environment files: ${summary.envFiles.join(', ') || 'none detected'}`,
+    `- Docker: ${summary.dockerFiles.join(', ') || 'none detected'}`,
+    `- CI/CD: ${summary.ciCdFiles.join(', ') || 'none detected'}`,
+    `- Deployment: ${summary.deploymentSignals.join(', ') || 'none detected'}`,
+    `- Tests: ${summary.testSignals.join(', ') || 'none detected'}`,
+    `- Linting: ${summary.lintSignals.join(', ') || 'none detected'}`,
+    `- Formatting: ${summary.formatSignals.join(', ') || 'none detected'}`,
+    `- Typechecking: ${summary.typecheckSignals.join(', ') || 'none detected'}`,
+    `- Unknowns: ${summary.unknowns.join(' | ') || 'none'}`,
+  ].join('\n')
+}
+
+export async function extractRepositoryStructure(params: ExtractParams): Promise<ExtractResult> {
+  const filePaths = await collectRelativeFilePaths(params.rootDir)
+  const topLevelEntries = gatherTopLevelEntries(filePaths)
+  const packageJsonPaths = filePaths.filter((filePath) => filePath.endsWith('package.json')).slice(0, 200)
+  const packageJsons = (
+    await Promise.all(
+      packageJsonPaths.map(async (packageJsonPath) => {
+        const data = await readPackageJson(params.rootDir, packageJsonPath)
+        return data ? { path: packageJsonPath, data } : null
+      }),
+    )
+  ).filter((value): value is { path: string; data: PackageJson } => value !== null)
+
+  const packageManagers = inferPackageManagerSignals(filePaths)
+  const components: RepositoryStructureComponent[] = packageJsons.map((packageJson) => {
+    const componentPath = packageJson.path === 'package.json' ? '.' : normalizePath(path.dirname(packageJson.path))
+    return {
+      kind: inferComponentKind(componentPath, packageJson.data),
+      name: packageJson.data.name?.trim() || path.basename(componentPath === '.' ? params.rootDir : componentPath),
+      path: componentPath,
+      packageManager: packageManagers[0]?.label,
+      languages: inferComponentLanguages(filePaths, componentPath),
+      frameworks: inferComponentFrameworks(packageJson.data),
+      reason: 'Detected a package manifest in this directory.',
+      evidencePaths: [packageJson.path],
+    }
+  })
+
+  const languages = gatherLanguageSignals(filePaths)
+  const frameworks = inferFrameworkSignals(packageJsons)
+  const routeSignals = buildPathSignals({
+    keyPrefix: 'route',
+    label: 'Routes',
+    reason: 'Detected route-related directories or files.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)(routes|pages|app\/routes)\//.test(filePath)),
+      20,
+    ),
+  })
+  const apiSignals = buildPathSignals({
+    keyPrefix: 'api',
+    label: 'API',
+    reason: 'Detected API or server route surfaces.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)(api|server|openapi|rpc)\//.test(filePath)),
+      20,
+    ),
+  })
+  const databaseSignals = buildPathSignals({
+    keyPrefix: 'database',
+    label: 'Database',
+    reason: 'Detected database schemas, migrations, or data-access directories.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)(db|database|migrations|prisma|drizzle|schema)\b/.test(filePath)),
+      20,
+    ),
+  })
+  const authSignals = buildPathSignals({
+    keyPrefix: 'auth',
+    label: 'Auth',
+    reason: 'Detected authentication-related code or configuration.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)(auth|better-auth|clerk|next-auth)\b/.test(filePath)),
+      20,
+    ),
+  })
+  const jobSignals = buildPathSignals({
+    keyPrefix: 'job',
+    label: 'Jobs',
+    reason: 'Detected jobs, queues, or worker execution surfaces.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)(jobs|queues|workers?)\b/.test(filePath)),
+      20,
+    ),
+  })
+  const envFiles = buildPathSignals({
+    keyPrefix: 'env',
+    label: 'Environment',
+    reason: 'Detected environment variable files.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)\.env(\.|$)/.test(filePath)),
+      20,
+    ),
+  })
+  const dockerFiles = buildPathSignals({
+    keyPrefix: 'docker',
+    label: 'Docker',
+    reason: 'Detected Docker build or compose files.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(Dockerfile|docker-compose|compose\.ya?ml|\.dockerignore)/i.test(filePath)),
+      20,
+    ),
+  })
+  const ciCdFiles = buildPathSignals({
+    keyPrefix: 'cicd',
+    label: 'CI/CD',
+    reason: 'Detected continuous integration or delivery workflow files.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /^\.github\/workflows\/|\.gitlab-ci\.yml$|circleci\//.test(filePath)),
+      20,
+    ),
+  })
+  const deploymentFiles = buildPathSignals({
+    keyPrefix: 'deploy',
+    label: 'Deployment',
+    reason: 'Detected deployment platform or infrastructure descriptors.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) =>
+        /(vercel\.json|fly\.toml|render\.ya?ml|netlify\.toml|railway\.json|k8s|helm)/i.test(filePath),
+      ),
+      20,
+    ),
+  })
+  const testSignals = buildPathSignals({
+    keyPrefix: 'test',
+    label: 'Tests',
+    reason: 'Detected repository test files.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)(__tests__|tests?)\/|(\.test\.|\.(spec)\.)/.test(filePath)),
+      20,
+    ),
+  })
+  const lintSignals = buildPathSignals({
+    keyPrefix: 'lint',
+    label: 'Linting',
+    reason: 'Detected linting configuration files.',
+    filePaths: truncate(
+      findPaths(
+        filePaths,
+        (filePath) => /(eslint|oxlint|biome|lint)/i.test(filePath) && /\.(json|js|ts|mjs|cjs|yaml|yml)$/.test(filePath),
+      ),
+      20,
+    ),
+  })
+  const formatSignals = buildPathSignals({
+    keyPrefix: 'format',
+    label: 'Formatting',
+    reason: 'Detected code-formatting configuration files.',
+    filePaths: truncate(
+      findPaths(
+        filePaths,
+        (filePath) => /(prettier|oxfmt|biome)/i.test(filePath) && /\.(json|js|ts|mjs|cjs|yaml|yml)$/.test(filePath),
+      ),
+      20,
+    ),
+  })
+  const typecheckSignals = buildPathSignals({
+    keyPrefix: 'typecheck',
+    label: 'Typechecking',
+    reason: 'Detected typechecking configuration files.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(tsconfig|mypy|pyright)/i.test(filePath)),
+      20,
+    ),
+  })
+  const entryPoints = buildPathSignals({
+    keyPrefix: 'entry',
+    label: 'Entry point',
+    reason: 'Detected likely application entry points.',
+    filePaths: truncate(
+      findPaths(filePaths, (filePath) => /(^|\/)(main|index|app|server|worker)\.(ts|tsx|js|jsx|py|go)$/.test(filePath)),
+      20,
+    ),
+  })
+
+  const repoShape = inferRepoShape({ topLevelEntries, components, frameworks, filePaths })
+
+  const repoStructure = RepositoryStructureArtifactSchema.parse({
+    schemaVersion: 'repository-structure.v1',
+    extractorVersion: EXTRACTOR_VERSION,
+    generatedAt: new Date().toISOString(),
+    repository: {
+      repositoryKey: params.repositoryKey,
+      repositoryFullName: params.repositoryFullName,
+      defaultBranch: params.defaultBranch,
+      indexBranch: params.indexBranch,
+      commitSha: params.commitSha,
+    },
+    topLevelEntries,
+    repoShape,
+    packageManagers,
+    languages,
+    frameworks,
+    components: truncate(components, 200),
+    entryPoints,
+    routeSignals,
+    apiSignals,
+    databaseSignals,
+    authSignals,
+    jobSignals,
+    envFiles,
+    dockerFiles,
+    ciCdFiles,
+    deploymentFiles,
+    testSignals,
+    lintSignals,
+    formatSignals,
+    typecheckSignals,
+    unknowns: repoShape.kind === 'uncertain' ? ['Repository shape could not be confidently classified.'] : [],
+  })
+
+  const structureSummary = RepositoryStructureSummarySchema.parse({
+    schemaVersion: 'repository-structure-summary.v1',
+    extractorVersion: EXTRACTOR_VERSION,
+    generatedAt: repoStructure.generatedAt,
+    repository: repoStructure.repository,
+    repoShape: repoStructure.repoShape.kind,
+    topLevelEntries: truncate(repoStructure.topLevelEntries, 20),
+    packageManagers: summarizeSignals(repoStructure.packageManagers),
+    languages: summarizeSignals(repoStructure.languages),
+    frameworks: summarizeSignals(repoStructure.frameworks),
+    components: truncate(
+      repoStructure.components.map((component) => ({
+        kind: component.kind,
+        name: component.name,
+        path: component.path,
+      })),
+      40,
+    ),
+    entryPoints: summarizeSignals(repoStructure.entryPoints),
+    routeSignals: summarizeSignals(repoStructure.routeSignals),
+    apiSignals: summarizeSignals(repoStructure.apiSignals),
+    databaseSignals: summarizeSignals(repoStructure.databaseSignals),
+    authSignals: summarizeSignals(repoStructure.authSignals),
+    jobSignals: summarizeSignals(repoStructure.jobSignals),
+    envFiles: summarizeSignals(repoStructure.envFiles),
+    dockerFiles: summarizeSignals(repoStructure.dockerFiles),
+    ciCdFiles: summarizeSignals(repoStructure.ciCdFiles),
+    testSignals: summarizeSignals(repoStructure.testSignals),
+    lintSignals: summarizeSignals(repoStructure.lintSignals),
+    formatSignals: summarizeSignals(repoStructure.formatSignals),
+    typecheckSignals: summarizeSignals(repoStructure.typecheckSignals),
+    deploymentSignals: summarizeSignals(repoStructure.deploymentFiles),
+    unknowns: repoStructure.unknowns.slice(0, 20),
+  })
+
+  return {
+    repoStructure,
+    structureSummary,
+    structureMarkdown: buildStructureMarkdown({ repoStructure, structureSummary }),
+  }
+}

package/src/workers/utils/repomix-process-concurrency.ts

@@ -0,0 +1,65 @@
+import os from 'node:os'
+
+type MutableOsModule = Omit<typeof os, 'availableParallelism'> & { availableParallelism?: () => number }
+
+const mutableOs = os as MutableOsModule
+
+function toPositiveSafeInteger(value: unknown): number | null {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : null
+}
+
+function readAvailableParallelism(read?: () => unknown): number | null {
+  if (!read) return null
+
+  try {
+    return toPositiveSafeInteger(read())
+  } catch {
+    return null
+  }
+}
+
+export function resolveSafeRepomixProcessConcurrency(params?: {
+  availableParallelism?: () => unknown
+  getCpuCount?: () => unknown
+}): number {
+  const availableParallelism = readAvailableParallelism(params?.availableParallelism ?? mutableOs.availableParallelism)
+  if (availableParallelism) {
+    return availableParallelism
+  }
+
+  const cpuCount = toPositiveSafeInteger(params?.getCpuCount?.() ?? os.cpus().length)
+  if (cpuCount) {
+    return cpuCount
+  }
+
+  return 1
+}
+
+export function installSafeRepomixAvailableParallelism(): {
+  processConcurrency: number
+  patched: boolean
+  restore: () => void
+} {
+  const originalAvailableParallelism = mutableOs.availableParallelism
+  const processConcurrency = resolveSafeRepomixProcessConcurrency()
+  const currentValue = readAvailableParallelism(originalAvailableParallelism)
+
+  if (currentValue === processConcurrency) {
+    return { processConcurrency, patched: false, restore: () => {} }
+  }
+
+  mutableOs.availableParallelism = () => processConcurrency
+
+  return {
+    processConcurrency,
+    patched: true,
+    restore: () => {
+      if (originalAvailableParallelism) {
+        mutableOs.availableParallelism = originalAvailableParallelism
+        return
+      }
+
+      delete mutableOs.availableParallelism
+    },
+  }
+}