@angular/compiler-cli 17.0.0-next.4 → 17.0.0-next.5

package/index.d.ts

@@ -11,3 +11,4 @@ export { NgtscProgram } from './src/ngtsc/program';
 export { OptimizeFor } from './src/ngtsc/typecheck/api';
 export { ConsoleLogger, Logger, LogLevel } from './src/ngtsc/logging';
 export { NodeJSFileSystem } from './src/ngtsc/file_system';
+export * from './src/ngtsc/docs/src/entities';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/compiler-cli",
-  "version": "17.0.0-next.4",
+  "version": "17.0.0-next.5",
   "description": "Angular - the compiler CLI for Node.js",
   "typings": "index.d.ts",
   "bin": {
@@ -43,7 +43,7 @@
     }
   },
   "dependencies": {
-    "@babel/core": "7.22.5",
+    "@babel/core": "7.22.19",
     "@jridgewell/sourcemap-codec": "^1.4.14",
     "reflect-metadata": "^0.1.2",
     "chokidar": "^3.0.0",
@@ -53,8 +53,8 @@
     "yargs": "^17.2.1"
   },
   "peerDependencies": {
-    "@angular/compiler": "17.0.0-next.4",
-    "typescript": ">=4.9.3 <5.3"
+    "@angular/compiler": "17.0.0-next.5",
+    "typescript": ">=5.2 <5.3"
   },
   "repository": {
     "type": "git",
@@ -67,7 +67,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": "^16.14.0 || >=18.10.0"
+    "node": ">=18.13.0"
   },
   "bugs": {
     "url": "https://github.com/angular/angular/issues"

package/src/ngtsc/core/src/compiler.d.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import ts from 'typescript';
+import { DocEntry } from '../../docs';
 import { AbsoluteFsPath } from '../../file_system';
 import { IncrementalBuildStrategy, IncrementalCompilation, IncrementalState } from '../../incremental';
 import { IndexedComponent } from '../../indexer';
@@ -230,6 +231,15 @@ export declare class NgCompiler {
      * See the `indexing` package for more details.
      */
     getIndexedComponents(): Map<DeclarationNode, IndexedComponent>;
+    /**
+     * Gets information for the current program that may be used to generate API
+     * reference documentation. This includes Angular-specific information, such
+     * as component inputs and outputs.
+     *
+     * @param entryPoint Path to the entry point for the package for which API
+     *     docs should be extracted.
+     */
+    getApiDocumentation(entryPoint: string): DocEntry[];
     /**
      * Collect i18n messages into the `Xi18nContext`.
      */

package/src/ngtsc/diagnostics/src/error_code.d.ts

@@ -214,6 +214,17 @@ export declare enum ErrorCode {
      * A directive usage isn't binding to one or more required inputs.
      */
     MISSING_REQUIRED_INPUTS = 8008,
+    /**
+     * The tracking expression of a `for` loop block is accessing a variable that is unavailable,
+     * for example:
+     *
+     * ```
+     * <ng-template let-ref>
+     *   {#for item of items; track ref}{/for}
+     * </ng-template>
+     * ```
+     */
+    ILLEGAL_FOR_LOOP_TRACK_ACCESS = 8009,
     /**
      * A two way binding in a template has an incorrect syntax,
      * parentheses outside brackets. For example:

package/src/ngtsc/docs/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+export { DocEntry } from './src/entities';
+export { DocsExtractor } from './src/extractor';

package/src/ngtsc/docs/src/class_extractor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+import { MetadataReader } from '../../metadata';
+import { ClassDeclaration } from '../../reflection';
+import { ClassEntry } from './entities';
+/** Extracts documentation info for a class, potentially including Angular-specific info.  */
+export declare function extractClass(classDeclaration: ClassDeclaration & ts.ClassDeclaration, metadataReader: MetadataReader, typeChecker: ts.TypeChecker): ClassEntry;

package/src/ngtsc/docs/src/constant_extractor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+import { ConstantEntry } from './entities';
+/** Extracts documentation entry for a constant. */
+export declare function extractConstant(declaration: ts.VariableDeclaration, typeChecker: ts.TypeChecker): ConstantEntry;
+/** Gets whether a given constant is an Angular-added const that should be ignored for docs. */
+export declare function isSyntheticAngularConstant(declaration: ts.VariableDeclaration): boolean;

package/src/ngtsc/docs/src/entities.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+/** Type of top-level documentation entry. */
+export declare enum EntryType {
+    Block = "Block",
+    Component = "component",
+    Constant = "constant",
+    Decorator = "decorator",
+    Directive = "directive",
+    Element = "element",
+    Enum = "enum",
+    Function = "function",
+    Interface = "interface",
+    NgModule = "ng_module",
+    Pipe = "pipe",
+    TypeAlias = "type_alias",
+    UndecoratedClass = "undecorated_class"
+}
+/** Types of class members */
+export declare enum MemberType {
+    Property = "property",
+    Method = "method",
+    Getter = "getter",
+    Setter = "setter",
+    EnumItem = "enum_item"
+}
+/** Informational tags applicable to class members. */
+export declare enum MemberTags {
+    Static = "static",
+    Readonly = "readonly",
+    Protected = "protected",
+    Optional = "optional",
+    Input = "input",
+    Output = "output"
+}
+export interface JsDocTagEntry {
+    name: string;
+    comment: string;
+}
+/** Base type for all documentation entities. */
+export interface DocEntry {
+    entryType: EntryType;
+    name: string;
+    description: string;
+    rawComment: string;
+    jsdocTags: JsDocTagEntry[];
+}
+/** Documentation entity for a constant. */
+export interface ConstantEntry extends DocEntry {
+    type: string;
+}
+/** Documentation entity for a TypeScript class. */
+export interface ClassEntry extends DocEntry {
+    members: MemberEntry[];
+}
+/** Documentation entity for a TypeScript enum. */
+export interface EnumEntry extends DocEntry {
+    members: EnumMemberEntry[];
+}
+/** Documentation entity for an Angular directives and components. */
+export interface DirectiveEntry extends ClassEntry {
+    selector: string;
+    exportAs: string[];
+    isStandalone: boolean;
+}
+export interface PipeEntry extends ClassEntry {
+    pipeName: string;
+    isStandalone: boolean;
+}
+export interface FunctionEntry extends DocEntry {
+    params: ParameterEntry[];
+    returnType: string;
+}
+/** Sub-entry for a single class or enum member. */
+export interface MemberEntry {
+    name: string;
+    memberType: MemberType;
+    memberTags: MemberTags[];
+    description: string;
+    jsdocTags: JsDocTagEntry[];
+}
+/** Sub-entry for an enum member. */
+export interface EnumMemberEntry extends MemberEntry {
+    type: string;
+    value: string;
+}
+/** Sub-entry for a class property. */
+export interface PropertyEntry extends MemberEntry {
+    type: string;
+    inputAlias?: string;
+    outputAlias?: string;
+}
+/** Sub-entry for a class method. */
+export type MethodEntry = MemberEntry & FunctionEntry;
+/** Sub-entry for a single function parameter. */
+export interface ParameterEntry {
+    name: string;
+    description: string;
+    type: string;
+    isOptional: boolean;
+    isRestParam: boolean;
+}

package/src/ngtsc/docs/src/enum_extractor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import { EnumEntry } from '@angular/compiler-cli/src/ngtsc/docs/src/entities';
+import ts from 'typescript';
+/** Extracts documentation entry for an enum. */
+export declare function extractEnum(declaration: ts.EnumDeclaration, typeChecker: ts.TypeChecker): EnumEntry;

package/src/ngtsc/docs/src/extractor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+import { MetadataReader } from '../../metadata';
+import { DocEntry } from './entities';
+/**
+ * Extracts all information from a source file that may be relevant for generating
+ * public API documentation.
+ */
+export declare class DocsExtractor {
+    private typeChecker;
+    private metadataReader;
+    constructor(typeChecker: ts.TypeChecker, metadataReader: MetadataReader);
+    /**
+     * Gets the set of all documentable entries from a source file, including
+     * declarations that are re-exported from this file as an entry-point.
+     *
+     * @param sourceFile The file from which to extract documentable entries.
+     */
+    extractAll(sourceFile: ts.SourceFile): DocEntry[];
+}

package/src/ngtsc/docs/src/function_extractor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import { FunctionEntry } from '@angular/compiler-cli/src/ngtsc/docs/src/entities';
+import ts from 'typescript';
+export declare class FunctionExtractor {
+    private declaration;
+    private typeChecker;
+    constructor(declaration: ts.FunctionDeclaration | ts.MethodDeclaration, typeChecker: ts.TypeChecker);
+    extract(): FunctionEntry;
+    private extractAllParams;
+}

package/src/ngtsc/docs/src/jsdoc_extractor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+import { JsDocTagEntry } from './entities';
+/** Gets the set of JsDoc tags applied to a node. */
+export declare function extractJsDocTags(node: ts.HasJSDoc): JsDocTagEntry[];
+/**
+ * Gets the JsDoc description for a node. If the node does not have
+ * a description, returns the empty string.
+ */
+export declare function extractJsDocDescription(node: ts.HasJSDoc): string;
+/**
+ * Gets the raw JsDoc applied to a node. If the node does not have a JsDoc block,
+ * returns the empty string.
+ */
+export declare function extractRawJsDoc(node: ts.HasJSDoc): string;

package/src/ngtsc/docs/src/type_extractor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+/** Gets the string representation of a node's resolved type. */
+export declare function extractResolvedTypeString(node: ts.Node, checker: ts.TypeChecker): string;

package/src/ngtsc/program.d.ts

@@ -9,6 +9,7 @@ import ts from 'typescript';
 import * as api from '../transformers/api';
 import { NgCompiler } from './core';
 import { NgCompilerOptions } from './core/api';
+import { DocEntry } from './docs';
 import { IndexedComponent } from './indexer';
 import { DeclarationNode } from './reflection';
 /**
@@ -46,5 +47,14 @@ export declare class NgtscProgram implements api.Program {
     private emitXi18n;
     emit<CbEmitRes extends ts.EmitResult>(opts?: api.EmitOptions<CbEmitRes> | undefined): ts.EmitResult;
     getIndexedComponents(): Map<DeclarationNode, IndexedComponent>;
+    /**
+     * Gets information for the current program that may be used to generate API
+     * reference documentation. This includes Angular-specific information, such
+     * as component inputs and outputs.
+     *
+     * @param entryPoint Path to the entry point for the package for which API
+     *     docs should be extracted.
+     */
+    getApiDocumentation(entryPoint: string): DocEntry[];
     getEmittedSourceFiles(): Map<string, ts.SourceFile>;
 }

package/src/ngtsc/typecheck/src/oob.d.ts

@@ -5,7 +5,7 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import { BindingPipe, PropertyWrite, TmplAstBoundAttribute, TmplAstBoundEvent, TmplAstElement, TmplAstReference, TmplAstTemplate, TmplAstVariable } from '@angular/compiler';
+import { BindingPipe, PropertyRead, PropertyWrite, TmplAstBoundAttribute, TmplAstBoundEvent, TmplAstElement, TmplAstForLoopBlock, TmplAstReference, TmplAstTemplate, TmplAstVariable } from '@angular/compiler';
 import { ClassDeclaration } from '../../reflection';
 import { TemplateDiagnostic, TemplateId } from '../api';
 import { TemplateSourceResolver } from './tcb_util';
@@ -61,6 +61,10 @@ export interface OutOfBandDiagnosticRecorder {
     splitTwoWayBinding(templateId: TemplateId, input: TmplAstBoundAttribute, output: TmplAstBoundEvent, inputConsumer: ClassDeclaration, outputConsumer: ClassDeclaration | TmplAstElement): void;
     /** Reports required inputs that haven't been bound. */
     missingRequiredInputs(templateId: TemplateId, element: TmplAstElement | TmplAstTemplate, directiveName: string, isComponent: boolean, inputAliases: string[]): void;
+    /**
+     * Reports accesses of properties that aren't available in a `for` block's tracking expression.
+     */
+    illegalForLoopTrackAccess(templateId: TemplateId, block: TmplAstForLoopBlock, access: PropertyRead): void;
 }
 export declare class OutOfBandDiagnosticRecorderImpl implements OutOfBandDiagnosticRecorder {
     private resolver;
@@ -81,4 +85,5 @@ export declare class OutOfBandDiagnosticRecorderImpl implements OutOfBandDiagnos
     suboptimalTypeInference(templateId: TemplateId, variables: TmplAstVariable[]): void;
     splitTwoWayBinding(templateId: TemplateId, input: TmplAstBoundAttribute, output: TmplAstBoundEvent, inputConsumer: ClassDeclaration, outputConsumer: ClassDeclaration | TmplAstElement): void;
     missingRequiredInputs(templateId: TemplateId, element: TmplAstElement | TmplAstTemplate, directiveName: string, isComponent: boolean, inputAliases: string[]): void;
+    illegalForLoopTrackAccess(templateId: TemplateId, block: TmplAstForLoopBlock, access: PropertyRead): void;
 }

package/src/ngtsc/typecheck/src/type_check_block.d.ts

@@ -5,7 +5,7 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import { BoundTarget, SchemaMetadata, TmplAstElement, TmplAstNode, TmplAstReference, TmplAstTemplate, TmplAstVariable } from '@angular/compiler';
+import { BoundTarget, SchemaMetadata, TmplAstElement, TmplAstForLoopBlock, TmplAstIfBlockBranch, TmplAstNode, TmplAstReference, TmplAstTemplate, TmplAstVariable } from '@angular/compiler';
 import ts from 'typescript';
 import { Reference } from '../../imports';
 import { ClassDeclaration } from '../../reflection';
@@ -207,11 +207,13 @@ declare class Scope {
      * @param tcb the overall context of TCB generation.
      * @param parent the `Scope` of the parent template (if any) or `null` if this is the root
      * `Scope`.
-     * @param templateOrNodes either a `TmplAstTemplate` representing the template for which to
+     * @param blockOrNodes either a `TmplAstTemplate` representing the template for which to
      * calculate the `Scope`, or a list of nodes if no outer template object is available.
      * @param guard an expression that is applied to this scope for type narrowing purposes.
      */
-    static forNodes(tcb: Context, parent: Scope | null, templateOrNodes: TmplAstTemplate | (TmplAstNode[]), guard: ts.Expression | null): Scope;
+    static forNodes(tcb: Context, parent: Scope | null, blockOrNodes: TmplAstTemplate | TmplAstIfBlockBranch | TmplAstForLoopBlock | TmplAstNode[], guard: ts.Expression | null): Scope;
+    /** Registers a local variable with a scope. */
+    private static registerVariable;
     /**
      * Look up a `ts.Expression` representing the value of some operation in the current `Scope`,
      * including any parent scope(s). This method always returns a mutable clone of the