UNPKG

7.33 kBTypeScriptView Raw
1/**
2 * @license
3 * Copyright (c) 2016 The Polymer Project Authors. All rights reserved.
4 * This code may only be used under the BSD style license found at
5 * http://polymer.github.io/LICENSE.txt
6 * The complete set of authors may be found at
7 * http://polymer.github.io/AUTHORS.txt
8 * The complete set of contributors may be found at
9 * http://polymer.github.io/CONTRIBUTORS.txt
10 * Code distributed by Google as part of the polymer project is also
11 * subject to an additional IP rights grant found at
12 * http://polymer.github.io/PATENTS.txt
13 */
14import { ProjectBuildOptions } from './builds';
15import { FsUrlLoader, PackageUrlResolver, WarningFilter, Analyzer } from 'polymer-analyzer';
16export { ProjectBuildOptions, JsCompileTarget, applyBuildPreset } from './builds';
17/**
18 * The default globs for matching all user application source files.
19 */
20export declare const defaultSourceGlobs: string[];
21export declare type ModuleResolutionStrategy = 'none' | 'node';
22export interface LintOptions {
23 /**
24 * The lint rules to run. Can be the code of a collection of rules like
25 * "polymer-2" or an individual rule like "dom-module-invalid-attrs".
26 */
27 rules: string[];
28 /**
29 * Warnings to ignore. After the rules are run, any warning that matches
30 * one of these codes is ignored, project-wide.
31 */
32 warningsToIgnore?: string[];
33 /**
34 * Deprecated way of spelling the `warningsToIgnore` lint option.
35 *
36 * Used only if `warningsToIgnore` is not specified.
37 */
38 ignoreWarnings?: string[];
39 /**
40 * An array of file globs to never report warnings for.
41 *
42 * The globs follow [minimatch] syntax, and any file that matches any
43 * of the listed globs will never show any linter warnings. This will
44 * typically not have a performance benefit, as the file will usually
45 * still need to be analyzed.
46 *
47 * [minimatch]: https://github.com/isaacs/minimatch
48 */
49 filesToIgnore?: string[];
50}
51export interface ProjectOptions {
52 /**
53 * Path to the root of the project on the filesystem. This can be an absolute
54 * path, or a path relative to the current working directory. Defaults to the
55 * current working directory of the process.
56 */
57 root?: string;
58 /**
59 * The path relative to `root` of the entrypoint file that will be served for
60 * app-shell style projects. Usually this is index.html.
61 */
62 entrypoint?: string;
63 /**
64 * The path relative to `root` of the app shell element.
65 */
66 shell?: string;
67 /**
68 * The path relative to `root` of the lazily loaded fragments. Usually the
69 * pages of an app or other bundles of on-demand resources.
70 */
71 fragments?: string[];
72 /**
73 * List of glob patterns, relative to root, of this project's sources to read
74 * from the file system.
75 */
76 sources?: string[];
77 /**
78 * List of file paths, relative to the project directory, that should be
79 * included as extraDependencies in the build target.
80 */
81 extraDependencies?: string[];
82 /**
83 * List of build option configurations.
84 */
85 builds?: ProjectBuildOptions[];
86 /**
87 * Set `basePath: true` on all builds. See that option for more details.
88 */
89 autoBasePath?: boolean;
90 /**
91 * Options for the Polymer Linter.
92 */
93 lint?: LintOptions;
94 /**
95 * Sets other options' defaults to NPM-appropriate values:
96 *
97 * - 'componentDir': 'node_modules/'
98 */
99 npm?: boolean;
100 /**
101 * The directory containing this project's dependencies.
102 */
103 componentDir?: string;
104 /**
105 * Algorithm to use for resolving module specifiers in import and export
106 * statements when rewriting them to be web-compatible. Valid values are:
107 *
108 * "none": Disable module specifier rewriting. This is the default.
109 * "node": Use Node.js resolution to find modules.
110 */
111 moduleResolution?: ModuleResolutionStrategy;
112}
113export declare class ProjectConfig {
114 readonly root: string;
115 readonly entrypoint: string;
116 readonly shell?: string;
117 readonly fragments: string[];
118 readonly sources: string[];
119 readonly extraDependencies: string[];
120 readonly componentDir?: string;
121 readonly npm?: boolean;
122 readonly moduleResolution: ModuleResolutionStrategy;
123 readonly builds: ProjectBuildOptions[];
124 readonly autoBasePath: boolean;
125 readonly allFragments: string[];
126 readonly lint: LintOptions | undefined;
127 /**
128 * Given an absolute file path to a polymer.json-like ProjectOptions object,
129 * read that file. If no file exists, null is returned. If the file exists
130 * but there is a problem reading or parsing it, throw an exception.
131 *
132 * TODO: in the next major version we should make this method and the one
133 * below async.
134 */
135 static loadOptionsFromFile(filepath: string): ProjectOptions | null;
136 /**
137 * Given an absolute file path to a polymer.json-like ProjectOptions object,
138 * return a new ProjectConfig instance created with those options.
139 */
140 static loadConfigFromFile(filepath: string): ProjectConfig | null;
141 /**
142 * Returns the given configJsonObject if it is a valid ProjectOptions object,
143 * otherwise throws an informative error message.
144 */
145 static validateOptions(configJsonObject: {}): ProjectOptions;
146 /**
147 * Returns a new ProjectConfig from the given JSON object if it's valid.
148 *
149 * TODO(rictic): For the next major version we should mark the constructor
150 * private, or perhaps make it validating. Also, we should standardize the
151 * naming scheme across the static methods on this class.
152 *
153 * Throws if the given JSON object is an invalid ProjectOptions.
154 */
155 static validateAndCreate(configJsonObject: {}): ProjectConfig;
156 /**
157 * Given a project directory, return an Analyzer (and related objects) with
158 * configuration inferred from polymer.json (and possibly other config files
159 * that we find and interpret).
160 */
161 static initializeAnalyzerFromDirectory(dirname: string): Promise<{
162 urlLoader: FsUrlLoader;
163 urlResolver: PackageUrlResolver;
164 analyzer: Analyzer;
165 warningFilter: WarningFilter;
166 }>;
167 /**
168 * constructor - given a ProjectOptions object, create the correct project
169 * configuration for those options. This involves setting the correct
170 * defaults, validating options, warning on deprecated options, and
171 * calculating some additional properties.
172 */
173 constructor(options: ProjectOptions);
174 /**
175 * Get an analyzer (and other related objects) with configuration determined
176 * by this ProjectConfig.
177 */
178 initializeAnalyzer(): Promise<{
179 urlLoader: FsUrlLoader;
180 urlResolver: PackageUrlResolver;
181 analyzer: Analyzer;
182 warningFilter: WarningFilter;
183 }>;
184 isFragment(filepath: string): boolean;
185 isShell(filepath: string): boolean;
186 isSource(filepath: string): boolean;
187 /**
188 * Validates that a configuration is accurate, and that all paths are
189 * contained within the project root.
190 */
191 validate(): boolean;
192 /**
193 * Generate a JSON string serialization of this configuration. File paths
194 * will be relative to root.
195 */
196 toJSON(): string;
197}