refactor(compiler): add support for compiling NgModules under isolatedDeclarations

This commit adds support for compiling NgModules in isolated declarations mode.

Key changes:
- Removed the unnecessary @NgModule({id}) warning diagnostic in isolated declarations mode.
- Set declarations to never in the generated .d.ts file for isolated NgModules.
- Extracted closures to standalone functions in NgModuleDecoratorHandler to avoid capturing state.
- Removed bootstrap and declarations from R3NgModuleMetadataIsolated as they are not used or always never.
- Extended the foreign function mechanism in PartialEvaluator to handle foreign types like ModuleWithProviders.
- Converted declaration-only compliance tests to use explicit goldens (*_isolated.golden.d.ts) and updated behavioral tests.

These changes are internal refactorings to support isolated declarations and are not relevant to 3rd party Angular users.

Author: alxhub

packages/compiler-cli/src/ngtsc/annotations/ng_module/src/handler.ts

@@ -31,6 +31,7 @@ import {
   ReturnStatement,
   SchemaMetadata,
   Statement,
+  TypeofExpr,
   WrappedNodeExpr,
 } from '@angular/compiler';
 import ts from 'typescript';
@@ -45,6 +46,7 @@ import {
   assertSuccessfulReferenceEmit,
   LocalCompilationExtraImportsTracker,
   Reference,
+  ReferenceEmitKind,
   ReferenceEmitter,
 } from '../../../imports';
 import {
@@ -104,6 +106,7 @@ import {
   ReferencesRegistry,
   resolveProvidersRequiringFactory,
   toR3Reference,
+  tryUnwrapForwardRef,
   unwrapExpression,
   wrapFunctionExpressionsInParens,
   wrapTypeReference,
@@ -352,14 +355,21 @@ export class NgModuleDecoratorHandler implements DecoratorHandler<
       return {};
     }
 
+    // In declaration-only emission the `declarations`/`imports`/`exports` arrays are emitted via a
+    // purely syntactic transform - we don't attempt static resolution at all (that machinery is
+    // only needed for the regular emit path) and produce the `Isolated` metadata kind directly
+    // from the raw decorator expressions.
+    if (this.emitDeclarationOnly) {
+      return this.analyzeForDeclarationOnly(node, name, ngModule, decorator);
+    }
+
     const forwardRefResolver = createForwardRefResolver(this.isCore);
     const moduleResolvers = combineResolvers([
       createModuleWithProvidersResolver(this.reflector, this.isCore),
       forwardRefResolver,
     ]);
 
-    const allowUnresolvedReferences =
-      this.compilationMode === CompilationMode.LOCAL && !this.emitDeclarationOnly;
+    const allowUnresolvedReferences = this.compilationMode === CompilationMode.LOCAL;
     const diagnostics: ts.Diagnostic[] = [];
 
     // Resolving declarations
@@ -552,6 +562,7 @@ export class NgModuleDecoratorHandler implements DecoratorHandler<
     const type = wrapTypeReference(node);
 
     let ngModuleMetadata: R3NgModuleMetadata;
+
     if (allowUnresolvedReferences) {
       ngModuleMetadata = {
         kind: R3NgModuleMetadataKind.Local,
@@ -1093,6 +1104,117 @@ export class NgModuleDecoratorHandler implements DecoratorHandler<
     }
   }
 
+  /**
+   * Analyze path used in `emitDeclarationOnly` (isolated declarations) mode. The
+   * `declarations`/`imports`/`exports` arrays are NOT statically resolved here - they're transformed
+   * syntactically into the `Isolated` metadata kind's type-tuple expressions, which downstream
+   * `.d.ts` metadata readers resolve. This skips the partial-evaluator path entirely.
+   */
+  private analyzeForDeclarationOnly(
+    node: ClassDeclaration,
+    name: string,
+    ngModule: Map<string, ts.Expression>,
+    decorator: Readonly<Decorator>,
+  ): AnalysisOutput<NgModuleAnalysis> {
+    const diagnostics: ts.Diagnostic[] = [];
+    const rawDeclarations = ngModule.get('declarations') ?? null;
+    const rawImports = ngModule.get('imports') ?? null;
+    const rawExports = ngModule.get('exports') ?? null;
+    const rawBootstrap = ngModule.get('bootstrap') ?? null;
+    const rawProviders = ngModule.has('providers') ? ngModule.get('providers')! : null;
+
+    let id: Expression | null = null;
+    if (ngModule.has('id')) {
+      const idExpr = ngModule.get('id')!;
+      if (!isModuleIdExpression(idExpr)) {
+        id = new WrappedNodeExpr(idExpr);
+      }
+    }
+
+    const type = wrapTypeReference(node);
+
+    const ngModuleMetadata: R3NgModuleMetadata = {
+      kind: R3NgModuleMetadataKind.Isolated,
+      type,
+      importsExpression: rawImports
+        ? transformToTypeTupleExpression(
+            rawImports,
+            this.evaluator,
+            this.refEmitter,
+            node.getSourceFile(),
+            this.reflector,
+            diagnostics,
+          )
+        : null,
+      exportsExpression: rawExports
+        ? transformToTypeTupleExpression(
+            rawExports,
+            this.evaluator,
+            this.refEmitter,
+            node.getSourceFile(),
+            this.reflector,
+            diagnostics,
+          )
+        : null,
+      id,
+      selectorScopeMode: R3SelectorScopeMode.Omit,
+      schemas: [],
+    };
+
+    // Providers are emitted as-is - they are needed for the injector but don't go through any
+    // resolution at this stage.
+    let wrappedProviders: WrappedNodeExpr<ts.Expression> | null = null;
+    if (
+      rawProviders !== null &&
+      (!ts.isArrayLiteralExpression(rawProviders) || rawProviders.elements.length > 0)
+    ) {
+      wrappedProviders = new WrappedNodeExpr(
+        this.annotateForClosureCompiler
+          ? wrapFunctionExpressionsInParens(rawProviders)
+          : rawProviders,
+      );
+    }
+
+    const injectorMetadata: R3InjectorMetadata = {
+      name,
+      type,
+      providers: wrappedProviders,
+      imports: [],
+    };
+
+    const factoryMetadata: R3FactoryMetadata = {
+      name,
+      type,
+      typeArgumentCount: 0,
+      deps: getValidConstructorDependencies(node, this.reflector, this.isCore),
+      target: FactoryTarget.NgModule,
+    };
+
+    return {
+      diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+      analysis: {
+        id,
+        schemas: [],
+        mod: ngModuleMetadata,
+        inj: injectorMetadata,
+        fac: factoryMetadata,
+        declarations: [],
+        rawDeclarations,
+        imports: [],
+        rawImports,
+        importRefs: [],
+        exports: [],
+        rawExports,
+        providers: rawProviders,
+        providersRequiringFactory: null,
+        classMetadata: null,
+        factorySymbolName: node.name.text,
+        remoteScopesMayRequireCycleProtection: false,
+        decorator: (decorator?.node as ts.Decorator | null) ?? null,
+      },
+    };
+  }
+
   // Verify that a "Declaration" reference is a `ClassDeclaration` reference.
   private isClassDeclarationReference(ref: Reference): ref is Reference<ClassDeclaration> {
     return this.reflector.isClass(ref.node);
@@ -1176,17 +1298,6 @@ export class NgModuleDecoratorHandler implements DecoratorHandler<
       } else if (entry instanceof DynamicValue && allowUnresolvedReferences) {
         dynamicValueSet.add(entry);
         continue;
-      } else if (
-        this.emitDeclarationOnly &&
-        entry instanceof DynamicValue &&
-        entry.isFromUnknownIdentifier()
-      ) {
-        throw createValueHasWrongTypeError(
-          entry.node,
-          entry,
-          `Value at position ${absoluteIndex} in the NgModule.${arrayName} of ${className} is an external reference. ` +
-            'External references in @NgModule declarations are not supported in experimental declaration-only emission mode',
-        );
       } else {
         // TODO(alxhub): Produce a better diagnostic here - the array index may be an inner array.
         throw createValueHasWrongTypeError(
@@ -1257,3 +1368,129 @@ function makeStandaloneBootstrapDiagnostic(
 function isSyntheticReference(ref: Reference<DeclarationNode>): boolean {
   return ref.synthetic;
 }
+
+/**
+ * Converts a value expression that is an identifier or a chain of property accesses on identifiers
+ * (e.g. `Foo` or `Foo.bar`) into the equivalent `ts.EntityName`, reusing the original identifier
+ * nodes so that any imports they reference are preserved by TypeScript's declaration emitter.
+ * Returns `null` for any other shape of expression.
+ */
+function expressionToEntityName(expr: ts.Expression): ts.EntityName | null {
+  if (ts.isIdentifier(expr)) {
+    return expr;
+  }
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.name)) {
+    const left = expressionToEntityName(expr.expression);
+    return left === null ? null : ts.factory.createQualifiedName(left, expr.name.text);
+  }
+  return null;
+}
+
+function transformToTypeTupleElement(
+  el: ts.Expression,
+  reflector: ReflectionHost,
+  diagnostics: ts.Diagnostic[],
+): Expression {
+  el = unwrapExpression(el);
+
+  const forwardRefUnwrapped = tryUnwrapForwardRef(el, reflector);
+  if (forwardRefUnwrapped !== null) {
+    return transformToTypeTupleElement(forwardRefUnwrapped, reflector, diagnostics);
+  }
+
+  // A call expression (e.g. `Foo.forRoot()` or a bare `fn()`) cannot be referenced with a
+  // `typeof` query directly. Instead emit `ReturnType<typeof callee>` so that the `.d.ts`
+  // reader can resolve the (potentially `ModuleWithProviders<T>`) return type later.
+  if (ts.isCallExpression(el)) {
+    const callee = expressionToEntityName(el.expression);
+    if (callee !== null) {
+      return new WrappedNodeExpr(
+        ts.factory.createTypeReferenceNode(ts.factory.createIdentifier('ReturnType'), [
+          ts.factory.createTypeQueryNode(callee),
+        ]),
+      );
+    }
+  }
+
+  if (expressionToEntityName(el) === null) {
+    const diag = makeDiagnostic(
+      ErrorCode.LOCAL_COMPILATION_UNSUPPORTED_EXPRESSION,
+      el,
+      `In experimental declaration-only emission mode, this expression is not supported in NgModule imports/exports as it cannot be referenced with 'typeof'. Use a direct reference or a supported call.`,
+    );
+    diagnostics.push(diag);
+    return new WrappedNodeExpr(ts.factory.createKeywordTypeNode(ts.SyntaxKind.NeverKeyword));
+  }
+
+  return new TypeofExpr(new WrappedNodeExpr(el));
+}
+
+function resolvedToTypeTupleElement(
+  originalEl: ts.Expression,
+  resolved: ResolvedValue,
+  refEmitter: ReferenceEmitter,
+  sourceFile: ts.SourceFile,
+  reflector: ReflectionHost,
+  diagnostics: ts.Diagnostic[],
+): Expression {
+  if (resolved instanceof Reference) {
+    const emitted = refEmitter.emit(resolved, sourceFile);
+    if (emitted.kind === ReferenceEmitKind.Success) {
+      return new TypeofExpr(emitted.expression);
+    }
+  }
+
+  if (Array.isArray(resolved)) {
+    const elements: Expression[] = [];
+    let allValid = true;
+    for (const item of resolved) {
+      if (item instanceof Reference) {
+        const emitted = refEmitter.emit(item, sourceFile);
+        if (emitted.kind === ReferenceEmitKind.Success) {
+          elements.push(new TypeofExpr(emitted.expression));
+          continue;
+        }
+      }
+      allValid = false;
+      break;
+    }
+    if (allValid && elements.length > 0) {
+      return new LiteralArrayExpr(elements);
+    }
+  }
+
+  // Fallback to syntactic transform
+  return transformToTypeTupleElement(originalEl, reflector, diagnostics);
+}
+
+function transformToTypeTupleExpression(
+  expr: ts.Expression,
+  evaluator: PartialEvaluator,
+  refEmitter: ReferenceEmitter,
+  sourceFile: ts.SourceFile,
+  reflector: ReflectionHost,
+  diagnostics: ts.Diagnostic[],
+): Expression | null {
+  if (ts.isArrayLiteralExpression(expr)) {
+    // An empty array is treated like an omitted slot (emitted as `never` by
+    // `createNgModuleType`), matching the standard compilation path.
+    if (expr.elements.length === 0) {
+      return null;
+    }
+    return new LiteralArrayExpr(
+      expr.elements.map((el) => {
+        const resolved = evaluator.evaluate(el);
+        return resolvedToTypeTupleElement(
+          el,
+          resolved,
+          refEmitter,
+          sourceFile,
+          reflector,
+          diagnostics,
+        );
+      }),
+    );
+  }
+  const resolved = evaluator.evaluate(expr);
+  return resolvedToTypeTupleElement(expr, resolved, refEmitter, sourceFile, reflector, diagnostics);
+}

packages/compiler-cli/src/ngtsc/metadata/BUILD.bazel

@@ -12,6 +12,7 @@ ts_project(
         "//packages/compiler",
         "//packages/compiler-cli/src/ngtsc/file_system",
         "//packages/compiler-cli/src/ngtsc/imports",
+        "//packages/compiler-cli/src/ngtsc/partial_evaluator",
         "//packages/compiler-cli/src/ngtsc/reflection",
         "//packages/compiler-cli/src/ngtsc/util",
     ],