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