1 | /**
|
---|
2 | * @license
|
---|
3 | * Copyright Google LLC All Rights Reserved.
|
---|
4 | *
|
---|
5 | * Use of this source code is governed by an MIT-style license that can be
|
---|
6 | * found in the LICENSE file at https://angular.io/license
|
---|
7 | */
|
---|
8 | /// <amd-module name="@angular/compiler-cli/src/ngtsc/typecheck/api/checker" />
|
---|
9 | import { AST, LiteralPrimitive, MethodCall, ParseSourceSpan, PropertyRead, SafeMethodCall, SafePropertyRead, TmplAstElement, TmplAstNode, TmplAstTemplate } from '@angular/compiler';
|
---|
10 | import { AbsoluteFsPath } from '@angular/compiler-cli/src/ngtsc/file_system';
|
---|
11 | import { TextAttribute } from '@angular/compiler/src/render3/r3_ast';
|
---|
12 | import * as ts from 'typescript';
|
---|
13 | import { ErrorCode } from '../../diagnostics';
|
---|
14 | import { FullTemplateMapping, NgTemplateDiagnostic, TypeCheckableDirectiveMeta } from './api';
|
---|
15 | import { GlobalCompletion } from './completion';
|
---|
16 | import { DirectiveInScope, PipeInScope } from './scope';
|
---|
17 | import { ElementSymbol, ShimLocation, Symbol, TemplateSymbol } from './symbols';
|
---|
18 | /**
|
---|
19 | * Interface to the Angular Template Type Checker to extract diagnostics and intelligence from the
|
---|
20 | * compiler's understanding of component templates.
|
---|
21 | *
|
---|
22 | * This interface is analogous to TypeScript's own `ts.TypeChecker` API.
|
---|
23 | *
|
---|
24 | * In general, this interface supports two kinds of operations:
|
---|
25 | * - updating Type Check Blocks (TCB)s that capture the template in the form of TypeScript code
|
---|
26 | * - querying information about available TCBs, including diagnostics
|
---|
27 | *
|
---|
28 | * Once a TCB is available, information about it can be queried. If no TCB is available to answer a
|
---|
29 | * query, depending on the method either `null` will be returned or an error will be thrown.
|
---|
30 | */
|
---|
31 | export interface TemplateTypeChecker {
|
---|
32 | /**
|
---|
33 | * Retrieve the template in use for the given component.
|
---|
34 | */
|
---|
35 | getTemplate(component: ts.ClassDeclaration): TmplAstNode[] | null;
|
---|
36 | /**
|
---|
37 | * Get all `ts.Diagnostic`s currently available for the given `ts.SourceFile`.
|
---|
38 | *
|
---|
39 | * This method will fail (throw) if there are components within the `ts.SourceFile` that do not
|
---|
40 | * have TCBs available.
|
---|
41 | *
|
---|
42 | * Generating a template type-checking program is expensive, and in some workflows (e.g. checking
|
---|
43 | * an entire program before emit), it should ideally only be done once. The `optimizeFor` flag
|
---|
44 | * allows the caller to hint to `getDiagnosticsForFile` (which internally will create a template
|
---|
45 | * type-checking program if needed) whether the caller is interested in just the results of the
|
---|
46 | * single file, or whether they plan to query about other files in the program. Based on this
|
---|
47 | * flag, `getDiagnosticsForFile` will determine how much of the user's program to prepare for
|
---|
48 | * checking as part of the template type-checking program it creates.
|
---|
49 | */
|
---|
50 | getDiagnosticsForFile(sf: ts.SourceFile, optimizeFor: OptimizeFor): ts.Diagnostic[];
|
---|
51 | /**
|
---|
52 | * Given a `shim` and position within the file, returns information for mapping back to a template
|
---|
53 | * location.
|
---|
54 | */
|
---|
55 | getTemplateMappingAtShimLocation(shimLocation: ShimLocation): FullTemplateMapping | null;
|
---|
56 | /**
|
---|
57 | * Get all `ts.Diagnostic`s currently available that pertain to the given component.
|
---|
58 | *
|
---|
59 | * This method always runs in `OptimizeFor.SingleFile` mode.
|
---|
60 | */
|
---|
61 | getDiagnosticsForComponent(component: ts.ClassDeclaration): ts.Diagnostic[];
|
---|
62 | /**
|
---|
63 | * Ensures shims for the whole program are generated. This type of operation would be required by
|
---|
64 | * operations like "find references" and "refactor/rename" because references may appear in type
|
---|
65 | * check blocks generated from templates anywhere in the program.
|
---|
66 | */
|
---|
67 | generateAllTypeCheckBlocks(): void;
|
---|
68 | /**
|
---|
69 | * Returns `true` if the given file is in the record of known shims generated by the compiler,
|
---|
70 | * `false` if we cannot find the file in the shim records.
|
---|
71 | */
|
---|
72 | isTrackedTypeCheckFile(filePath: AbsoluteFsPath): boolean;
|
---|
73 | /**
|
---|
74 | * Retrieve the top-level node representing the TCB for the given component.
|
---|
75 | *
|
---|
76 | * This can return `null` if there is no TCB available for the component.
|
---|
77 | *
|
---|
78 | * This method always runs in `OptimizeFor.SingleFile` mode.
|
---|
79 | */
|
---|
80 | getTypeCheckBlock(component: ts.ClassDeclaration): ts.Node | null;
|
---|
81 | /**
|
---|
82 | * Retrieves a `Symbol` for the node in a component's template.
|
---|
83 | *
|
---|
84 | * This method can return `null` if a valid `Symbol` cannot be determined for the node.
|
---|
85 | *
|
---|
86 | * @see Symbol
|
---|
87 | */
|
---|
88 | getSymbolOfNode(node: TmplAstElement, component: ts.ClassDeclaration): ElementSymbol | null;
|
---|
89 | getSymbolOfNode(node: TmplAstTemplate, component: ts.ClassDeclaration): TemplateSymbol | null;
|
---|
90 | getSymbolOfNode(node: AST | TmplAstNode, component: ts.ClassDeclaration): Symbol | null;
|
---|
91 | /**
|
---|
92 | * Get "global" `Completion`s in the given context.
|
---|
93 | *
|
---|
94 | * Global completions are completions in the global context, as opposed to completions within an
|
---|
95 | * existing expression. For example, completing inside a new interpolation expression (`{{|}}`) or
|
---|
96 | * inside a new property binding `[input]="|" should retrieve global completions, which will
|
---|
97 | * include completions from the template's context component, as well as any local references or
|
---|
98 | * template variables which are in scope for that expression.
|
---|
99 | */
|
---|
100 | getGlobalCompletions(context: TmplAstTemplate | null, component: ts.ClassDeclaration, node: AST | TmplAstNode): GlobalCompletion | null;
|
---|
101 | /**
|
---|
102 | * For the given expression node, retrieve a `ShimLocation` that can be used to perform
|
---|
103 | * autocompletion at that point in the expression, if such a location exists.
|
---|
104 | */
|
---|
105 | getExpressionCompletionLocation(expr: PropertyRead | SafePropertyRead | MethodCall | SafeMethodCall, component: ts.ClassDeclaration): ShimLocation | null;
|
---|
106 | /**
|
---|
107 | * For the given node represents a `LiteralPrimitive`(the `TextAttribute` represents a string
|
---|
108 | * literal), retrieve a `ShimLocation` that can be used to perform autocompletion at that point in
|
---|
109 | * the node, if such a location exists.
|
---|
110 | */
|
---|
111 | getLiteralCompletionLocation(strNode: LiteralPrimitive | TextAttribute, component: ts.ClassDeclaration): ShimLocation | null;
|
---|
112 | /**
|
---|
113 | * Get basic metadata on the directives which are in scope for the given component.
|
---|
114 | */
|
---|
115 | getDirectivesInScope(component: ts.ClassDeclaration): DirectiveInScope[] | null;
|
---|
116 | /**
|
---|
117 | * Get basic metadata on the pipes which are in scope for the given component.
|
---|
118 | */
|
---|
119 | getPipesInScope(component: ts.ClassDeclaration): PipeInScope[] | null;
|
---|
120 | /**
|
---|
121 | * Retrieve a `Map` of potential template element tags, to either the `DirectiveInScope` that
|
---|
122 | * declares them (if the tag is from a directive/component), or `null` if the tag originates from
|
---|
123 | * the DOM schema.
|
---|
124 | */
|
---|
125 | getPotentialElementTags(component: ts.ClassDeclaration): Map<string, DirectiveInScope | null>;
|
---|
126 | /**
|
---|
127 | * Retrieve any potential DOM bindings for the given element.
|
---|
128 | *
|
---|
129 | * This returns an array of objects which list both the attribute and property names of each
|
---|
130 | * binding, which are usually identical but can vary if the HTML attribute name is for example a
|
---|
131 | * reserved keyword in JS, like the `for` attribute which corresponds to the `htmlFor` property.
|
---|
132 | */
|
---|
133 | getPotentialDomBindings(tagName: string): {
|
---|
134 | attribute: string;
|
---|
135 | property: string;
|
---|
136 | }[];
|
---|
137 | /**
|
---|
138 | * Retrieve the type checking engine's metadata for the given directive class, if available.
|
---|
139 | */
|
---|
140 | getDirectiveMetadata(dir: ts.ClassDeclaration): TypeCheckableDirectiveMeta | null;
|
---|
141 | /**
|
---|
142 | * Reset the `TemplateTypeChecker`'s state for the given class, so that it will be recomputed on
|
---|
143 | * the next request.
|
---|
144 | */
|
---|
145 | invalidateClass(clazz: ts.ClassDeclaration): void;
|
---|
146 | /**
|
---|
147 | * Constructs a `ts.Diagnostic` for a given `ParseSourceSpan` within a template.
|
---|
148 | */
|
---|
149 | makeTemplateDiagnostic<T extends ErrorCode>(clazz: ts.ClassDeclaration, sourceSpan: ParseSourceSpan, category: ts.DiagnosticCategory, errorCode: T, message: string, relatedInformation?: {
|
---|
150 | text: string;
|
---|
151 | start: number;
|
---|
152 | end: number;
|
---|
153 | sourceFile: ts.SourceFile;
|
---|
154 | }[]): NgTemplateDiagnostic<T>;
|
---|
155 | }
|
---|
156 | /**
|
---|
157 | * Describes the scope of the caller's interest in template type-checking results.
|
---|
158 | */
|
---|
159 | export declare enum OptimizeFor {
|
---|
160 | /**
|
---|
161 | * Indicates that a consumer of a `TemplateTypeChecker` is only interested in results for a given
|
---|
162 | * file, and wants them as fast as possible.
|
---|
163 | *
|
---|
164 | * Calling `TemplateTypeChecker` methods successively for multiple files while specifying
|
---|
165 | * `OptimizeFor.SingleFile` can result in significant unnecessary overhead overall.
|
---|
166 | */
|
---|
167 | SingleFile = 0,
|
---|
168 | /**
|
---|
169 | * Indicates that a consumer of a `TemplateTypeChecker` intends to query for results pertaining to
|
---|
170 | * the entire user program, and so the type-checker should internally optimize for this case.
|
---|
171 | *
|
---|
172 | * Initial calls to retrieve type-checking information may take longer, but repeated calls to
|
---|
173 | * gather information for the whole user program will be significantly faster with this mode of
|
---|
174 | * optimization.
|
---|
175 | */
|
---|
176 | WholeProgram = 1
|
---|
177 | }
|
---|