Module Graph 컴파일 — DFS, 가시성 검증, 에러 설계

export function compileModuleGraph(rootModule: ModuleType, options: BootstrapModuleOptions = {}): CompiledModule[] {
  // 1. 캐시 확인
  const cacheKey = options.moduleGraphCache === true
    ? createModuleGraphCacheKey(rootModule, options)
    : undefined;

  if (cacheKey !== undefined) {
    const cachedModules = moduleGraphCompileCache.get(cacheKey);

    if (cachedModules !== undefined) {
      return cloneCompiledModules(cachedModules);
    }
  }

  // 2. DFS 탐색으로 모듈 수집
  const ordered: CompiledModule[] = [];
  const runtimeProviders = options.providers ?? [];
  const runtimeProviderTokens = mergeRuntimeTokenSets(runtimeProviders, options.validationTokens ?? []);

  compileModule(rootModule, runtimeProviderTokens, new Map(), new Set(), ordered);

  // 3. 가시성·메타데이터 검증
  validateCompiledModules(ordered, runtimeProviders, runtimeProviderTokens);

  // 4. 캐시 저장 (선택적)
  if (cacheKey !== undefined) {
    const cacheSnapshot = createModuleGraphCacheSnapshot(ordered);
    moduleGraphCompileCache.set(cacheKey, cacheSnapshot);

    return cloneCompiledModules(cacheSnapshot);
  }

  return ordered;
}

function compileModule(
  moduleType: ModuleType,
  runtimeProviderTokens: Set<Token>,
  compiled = new Map<ModuleType, CompiledModule>(),
  visiting = new Set<ModuleType>(),
  ordered: CompiledModule[] = [],
) {
  // 이미 컴파일됐으면 재사용
  if (compiled.has(moduleType)) {
    const existing = compiled.get(moduleType);

    if (existing) {
      return existing;
    }
  }

  // 지금 방문 중인 모듈이면 순환 참조
  if (visiting.has(moduleType)) {
    throw new ModuleGraphError(
      `Circular module import detected for ${moduleType.name}.`,
      {
        module: moduleType.name,
        phase: 'module graph compilation',
        hint: 'Break the import cycle by extracting shared providers into a separate module that both sides can import independently.',
      },
    );
  }

  visiting.add(moduleType);

  const definition = normalizeModuleDefinition(getModuleMetadata(moduleType));

  // imports를 먼저 재귀 컴파일 (post-order)
  for (const imported of definition.imports ?? []) {
    compileModule(imported, runtimeProviderTokens, compiled, visiting, ordered);
  }

  const providerTokens = new Set((definition.providers ?? []).map((provider) => providerToken(provider)));

  const compiledModule: CompiledModule = {
    type: moduleType,
    definition,
    accessibleTokens: new Set<Token>(),
    exportedTokens: new Set<Token>(),
    importedExportedTokens: new Set<Token>(),
    providerTokens,
  };

  compiled.set(moduleType, compiledModule);
  visiting.delete(moduleType);
  ordered.push(compiledModule);  // 의존성 먼저, 루트 마지막

  return compiledModule;
}

function validateCompiledModules(
  modules: CompiledModule[],
  runtimeProviders: Provider[],
  runtimeProviderTokens: Set<Token>,
): void {
  const compiledByType = new Map(modules.map((compiledModule) => [compiledModule.type, compiledModule]));

  // 패스 1: global 모듈의 exports 수집
  const globalExportedTokens = new Set<Token>();

  for (const provider of runtimeProviders) {
    validateProviderInjectionMetadata(provider, 'bootstrap runtime');
  }

  for (const compiledModule of modules) {
    if (!compiledModule.definition.global) {
      continue;
    }

    for (const token of compiledModule.definition.exports ?? []) {
      globalExportedTokens.add(token);
    }
  }

  // 패스 2: 모듈별 accessibleTokens 계산 + 검증
  for (const compiledModule of modules) {
    const scope = `module ${compiledModule.type.name}`;
    memoizeAccessibleTokenSet(
      compiledModule,
      resolveImportedModules(compiledModule, compiledByType),
      runtimeProviderTokens,
      globalExportedTokens,
    );

    validateProviderVisibility(compiledModule, scope, compiledModule.accessibleTokens);
    validateControllerVisibility(compiledModule, scope, compiledModule.accessibleTokens);
    compiledModule.exportedTokens = createExportedTokenSet(compiledModule, compiledModule.importedExportedTokens);
  }
}

function validateProviderVisibility(
  compiledModule: CompiledModule,
  scope: string,
  accessibleTokens: Set<Token>,
): void {
  for (const provider of compiledModule.definition.providers ?? []) {
    // 메타데이터 완전성 검증 (inject 개수 확인)
    validateProviderInjectionMetadata(provider, scope);

    for (const rawToken of providerDependencies(provider)) {
      const token = resolveInjectionToken(rawToken); // forwardRef/optional 해제

      if (!accessibleTokens.has(token)) {
        throw new ModuleVisibilityError(
          `Provider ${String(providerToken(provider))} in module ${compiledModule.type.name} cannot access token ${String(
            token,
          )} because it is not local, not exported by an imported module, and not visible through a global module.`,
          {
            module: compiledModule.type.name,
            token,
            phase: 'provider visibility validation',
            hint: `Add ${String(token)} to the exports array of the module that owns it, then import that module into ${compiledModule.type.name}. Alternatively, mark the owning module with @Global() to make its exports universally visible.`,
          },
        );
      }
    }
  }
}

function validateClassInjectionMetadata(
  subject: string,
  implementation: Function,
  inject: readonly InjectionToken[],
  scope: string,
  remedy: string,
): void {
  const required = requiredConstructorParameters(implementation);

  if (required === 0 || inject.length >= required) {
    return;
  }

  const missingIndex = inject.length;
  const configured = inject.length;
  const parameterWord = required === 1 ? 'parameter' : 'parameters';
  const tokenWord = configured === 1 ? 'token is' : 'tokens are';

  throw new ModuleInjectionMetadataError(
    `${subject} in ${scope} declares ${required} constructor ${parameterWord} but only ${configured} injection ${tokenWord} configured. Add ${remedy} for constructor parameter #${missingIndex}.`,
    {
      module: scope,
      phase: 'injection metadata validation',
      hint: `Ensure ${subject} has a matching @Inject(...) decorator or provider.inject array that covers all ${required} constructor parameters. Use @Inject() for an explicit empty override.`,
    },
  );
}

function requiredConstructorParameters(target: Function): number {
  // @Inject()가 명시적으로 달려 있으면 (inject: [] 포함) → 0으로 처리
  if (getOwnClassDiMetadata(target)?.inject !== undefined) {
    return 0;
  }

  // 데코레이터가 없으면 실제 파라미터 개수
  return target.length;
}

function createExportedTokenSet(
  compiledModule: CompiledModule,
  importedExportedTokens: Set<Token>,
): Set<Token> {
  const exportedTokens = new Set<Token>();

  for (const token of compiledModule.definition.exports ?? []) {
    if (!compiledModule.providerTokens.has(token) && !importedExportedTokens.has(token)) {
      throw new ModuleVisibilityError(
        `Module ${compiledModule.type.name} cannot export token ${String(
          token,
        )} because it is neither local nor re-exported from an imported module.`,
        {
          module: compiledModule.type.name,
          token,
          phase: 'export validation',
          hint: `Either add a provider for ${String(token)} to ${compiledModule.type.name}'s providers array, or import a module that exports ${String(token)} so it can be re-exported.`,
        },
      );
    }

    exportedTokens.add(token);
  }

  return exportedTokens;
}

ModuleVisibilityError: Provider UsersService in module UsersModule 
cannot access token DatabaseService because it is not local, 
not exported by an imported module, and not visible through a global module.
  Module: UsersModule
  Token: DatabaseService
  Phase: provider visibility validation
  Hint: Add DatabaseService to the exports array of the module that owns it, 
        then import that module into UsersModule.