// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. // See LICENSE in the project root for license information. import * as nodeJsPath from 'node:path'; import { JSONPath } from 'jsonpath-plus'; import { JsonSchema, JsonFile, Import, FileSystem } from '@rushstack/node-core-library'; import type { ITerminal } from '@rushstack/terminal'; interface IConfigurationJson { extends?: string; } /* eslint-disable @typescript-eslint/typedef,@typescript-eslint/no-redeclare,@typescript-eslint/no-namespace,@typescript-eslint/naming-convention */ // This structure is used so that consumers can pass raw string literals and have it typecheck, without breaking existing callers. /** * @beta * * The set of possible mechanisms for merging properties from parent configuration files. * If a child configuration file sets a property value to `null`, that will always delete the value * specified in the parent configuration file, regardless of the inheritance type. */ const InheritanceType = { /** * Append additional elements after elements from the parent file's property. Only applicable * for arrays. */ append: 'append', /** * Perform a shallow merge of additional elements after elements from the parent file's property. * Only applicable for objects. */ merge: 'merge', /** * Discard elements from the parent file's property */ replace: 'replace', /** * Custom inheritance functionality */ custom: 'custom' } as const; /** * @beta */ type InheritanceType = (typeof InheritanceType)[keyof typeof InheritanceType]; /** * @beta */ declare namespace InheritanceType { /** * Append additional elements after elements from the parent file's property. Only applicable * for arrays. */ export type append = typeof InheritanceType.append; /** * Perform a shallow merge of additional elements after elements from the parent file's property. * Only applicable for objects. */ export type merge = typeof InheritanceType.merge; /** * Discard elements from the parent file's property */ export type replace = typeof InheritanceType.replace; /** * Custom inheritance functionality */ export type custom = typeof InheritanceType.custom; } export { InheritanceType }; /** * @beta * * The set of possible resolution methods for fields that refer to paths. */ const PathResolutionMethod = { /** * Resolve a path relative to the configuration file */ resolvePathRelativeToConfigurationFile: 'resolvePathRelativeToConfigurationFile', /** * Resolve a path relative to the root of the project containing the configuration file */ resolvePathRelativeToProjectRoot: 'resolvePathRelativeToProjectRoot', /** * Treat the property as a NodeJS-style require/import reference and resolve using standard * NodeJS filesystem resolution * * @deprecated * Use {@link (PathResolutionMethod:variable).nodeResolve} instead */ NodeResolve: 'NodeResolve', /** * Treat the property as a NodeJS-style require/import reference and resolve using standard * NodeJS filesystem resolution */ nodeResolve: 'nodeResolve', /** * Resolve the property using a custom resolver. */ custom: 'custom' } as const; /** * @beta */ type PathResolutionMethod = (typeof PathResolutionMethod)[keyof typeof PathResolutionMethod]; /** * @beta */ declare namespace PathResolutionMethod { /** * Resolve a path relative to the configuration file */ export type resolvePathRelativeToConfigurationFile = typeof PathResolutionMethod.resolvePathRelativeToConfigurationFile; /** * Resolve a path relative to the root of the project containing the configuration file */ export type resolvePathRelativeToProjectRoot = typeof PathResolutionMethod.resolvePathRelativeToProjectRoot; /** * Treat the property as a NodeJS-style require/import reference and resolve using standard * NodeJS filesystem resolution * * @deprecated * Use {@link (PathResolutionMethod:namespace).nodeResolve} instead */ export type NodeResolve = typeof PathResolutionMethod.NodeResolve; /** * Treat the property as a NodeJS-style require/import reference and resolve using standard * NodeJS filesystem resolution */ export type nodeResolve = typeof PathResolutionMethod.nodeResolve; /** * Resolve the property using a custom resolver. */ export type custom = typeof PathResolutionMethod.custom; } export { PathResolutionMethod }; /* eslint-enable @typescript-eslint/typedef,@typescript-eslint/no-redeclare,@typescript-eslint/no-namespace,@typescript-eslint/naming-convention */ const CONFIGURATION_FILE_MERGE_BEHAVIOR_FIELD_REGEX: RegExp = /^\$([^\.]+)\.inheritanceType$/; export const CONFIGURATION_FILE_FIELD_ANNOTATION: unique symbol = Symbol( 'configuration-file-field-annotation' ); export interface IAnnotatedField< TField, TConfigurationFileFieldAnnotation extends IConfigurationFileFieldAnnotation = IConfigurationFileFieldAnnotation > { [CONFIGURATION_FILE_FIELD_ANNOTATION]: TConfigurationFileFieldAnnotation; } type IAnnotatedObject = Partial>; type IRootAnnotatedObject = Partial< IAnnotatedField> >; interface IConfigurationFileFieldAnnotation { configurationFilePath: string | undefined; originalValues: { [propertyName in keyof TField]: unknown }; } interface IRootConfigurationFileFieldAnnotation extends IConfigurationFileFieldAnnotation { schemaPropertyOriginalValue?: string; } interface IObjectWithSchema { $schema?: string; } /** * Options provided to the custom resolver specified in {@link ICustomJsonPathMetadata}. * * @beta */ export interface IJsonPathMetadataResolverOptions { /** * The name of the property being resolved. */ propertyName: string; /** * The value of the path property being resolved. */ propertyValue: string; /** * The path to the configuration file the property was obtained from. */ configurationFilePath: string; /** * The configuration file the property was obtained from. */ configurationFile: Partial; /** * If this is a project configuration file, the root folder of the project. */ projectFolderPath?: string; } /** * Used to specify how node(s) in a JSON object should be processed after being loaded. * * @beta */ export interface ICustomJsonPathMetadata { /** * If `ICustomJsonPathMetadata.pathResolutionMethod` is set to `PathResolutionMethod.custom`, * this property be used to resolve the path. */ customResolver?: (resolverOptions: IJsonPathMetadataResolverOptions) => string; /** * If this property describes a filesystem path, use this property to describe * how the path should be resolved. */ pathResolutionMethod?: PathResolutionMethod.custom; } /** * Used to specify how node(s) in a JSON object should be processed after being loaded. * * @beta */ export interface INonCustomJsonPathMetadata { /** * If this property describes a filesystem path, use this property to describe * how the path should be resolved. */ pathResolutionMethod?: | PathResolutionMethod.NodeResolve // TODO: Remove | PathResolutionMethod.nodeResolve | PathResolutionMethod.resolvePathRelativeToConfigurationFile | PathResolutionMethod.resolvePathRelativeToProjectRoot; } /** * @beta */ export type PropertyInheritanceCustomFunction = ( currentObject: TObject, parentObject: TObject ) => TObject; /** * @beta */ export interface IPropertyInheritance { inheritanceType: TInheritanceType; } /** * @beta */ export interface ICustomPropertyInheritance extends IPropertyInheritance { /** * Provides a custom inheritance function. This function takes two arguments: the first is the * child file's object, and the second is the parent file's object. The function should return * the resulting combined object. * This function will not be invoked if the current value is `null`, the property will simply be deleted. */ inheritanceFunction: PropertyInheritanceCustomFunction; } /** * @beta */ export type IPropertiesInheritance = { [propertyName in keyof TConfigurationFile]?: | IPropertyInheritance | ICustomPropertyInheritance; }; /** * @beta */ export interface IPropertyInheritanceDefaults { array?: IPropertyInheritance; object?: IPropertyInheritance; } /** * @beta */ export type IJsonPathMetadata = ICustomJsonPathMetadata | INonCustomJsonPathMetadata; /** * Keys in this object are JSONPaths {@link https://jsonpath.com/}, and values are objects * that describe how node(s) selected by the JSONPath are processed after loading. * * @beta */ export interface IJsonPathsMetadata { [jsonPath: string]: IJsonPathMetadata; } /** * A function to invoke after schema validation to validate the configuration file. * If this function returns any value other than `true`, the configuration file API * will throw an error indicating that custom validation failed. If the function wishes * to provide its own error message, it may use any combination of the terminal and throwing * its own error. * @beta */ export type CustomValidationFunction = ( configurationFile: TConfigurationFile, resolvedConfigurationFilePathForLogging: string, terminal: ITerminal ) => boolean; /** * @beta */ export interface IConfigurationFileOptionsBase { /** * Use this property to specify how JSON nodes are postprocessed. */ jsonPathMetadata?: IJsonPathsMetadata; /** * Use this property to control how root-level properties are handled between parent and child * configuration files. */ propertyInheritance?: IPropertiesInheritance; /** * Use this property to control how specific property types are handled between parent and child * configuration files. */ propertyInheritanceDefaults?: IPropertyInheritanceDefaults; /** * Use this property if you need to validate the configuration file in ways beyond what JSON schema can handle. * This function will be invoked after JSON schema validation. * * If the file is valid, this function should return `true`, otherwise `ConfigurationFile` will throw an error * indicating that custom validation failed. To suppress this error, the function may itself choose to throw. */ customValidationFunction?: CustomValidationFunction; } /** * @beta */ export type IConfigurationFileOptionsWithJsonSchemaFilePath< TConfigurationFile, TExtraOptions extends {} > = IConfigurationFileOptionsBase & TExtraOptions & { /** * The path to the schema for the configuration file. */ jsonSchemaPath: string; jsonSchemaObject?: never; }; /** * @beta */ export type IConfigurationFileOptionsWithJsonSchemaObject< TConfigurationFile, TExtraOptions extends {} > = IConfigurationFileOptionsBase & TExtraOptions & { /** * The schema for the configuration file. */ jsonSchemaObject: object; jsonSchemaPath?: never; }; /** * @beta */ export type IConfigurationFileOptions = | IConfigurationFileOptionsWithJsonSchemaFilePath | IConfigurationFileOptionsWithJsonSchemaObject; interface IJsonPathCallbackObject { path: string; parent: object; parentProperty: string; value: string; } /** * @beta */ export interface IOriginalValueOptions { parentObject: Partial; propertyName: keyof TParentProperty; } interface IConfigurationFileCacheEntry { resolvedConfigurationFilePath: string; resolvedConfigurationFilePathForLogging: string; parent?: IConfigurationFileCacheEntry; configurationFile: TConfigFile & IConfigurationJson; } /** * Callback that returns a fallback configuration file path if the original configuration file was not found. * @beta */ export type IOnConfigurationFileNotFoundCallback = ( resolvedConfigurationFilePathForLogging: string ) => string | undefined; /** * @beta */ export abstract class ConfigurationFileBase { readonly #getSchema: () => JsonSchema; readonly #jsonPathMetadata: readonly [string, IJsonPathMetadata][]; readonly #propertyInheritanceTypes: IPropertiesInheritance; readonly #defaultPropertyInheritance: IPropertyInheritanceDefaults; readonly #customValidationFunction: CustomValidationFunction | undefined; #_schema: JsonSchema | undefined; get #schema(): JsonSchema { if (!this.#_schema) { this.#_schema = this.#getSchema(); } return this.#_schema; } readonly #configCache: Map> = new Map(); readonly #configPromiseCache: Map< string, Promise> > = new Map(); public constructor(options: IConfigurationFileOptions) { const { jsonSchemaObject, jsonSchemaPath, jsonPathMetadata = {}, propertyInheritance = {}, propertyInheritanceDefaults = {}, customValidationFunction } = options; if (jsonSchemaObject) { this.#getSchema = () => JsonSchema.fromLoadedObject(jsonSchemaObject); } else { this.#getSchema = () => JsonSchema.fromFile(jsonSchemaPath); } this.#jsonPathMetadata = Object.entries(jsonPathMetadata); this.#propertyInheritanceTypes = propertyInheritance; this.#defaultPropertyInheritance = propertyInheritanceDefaults; this.#customValidationFunction = customValidationFunction; } /** * @internal */ public static _formatPathForLogging: (path: string) => string = (path: string) => path; /** * Get the path to the source file that the referenced property was originally * loaded from. */ public getObjectSourceFilePath(obj: TObject): string | undefined { const { [CONFIGURATION_FILE_FIELD_ANNOTATION]: annotation }: IAnnotatedObject = obj; return annotation?.configurationFilePath; } /** * Get the value of the specified property on the specified object that was originally * loaded from a configuration file. */ public getPropertyOriginalValue( options: IOriginalValueOptions ): TValue | undefined { const { parentObject, propertyName } = options; const { [CONFIGURATION_FILE_FIELD_ANNOTATION]: annotation }: IAnnotatedObject = parentObject; if (annotation?.originalValues.hasOwnProperty(propertyName)) { return annotation.originalValues[propertyName] as TValue; } } /** * Get the original value of the `$schema` property from the original configuration file, it one was present. */ public getSchemaPropertyOriginalValue(obj: TObject): string | undefined { const { [CONFIGURATION_FILE_FIELD_ANNOTATION]: annotation }: IRootAnnotatedObject = obj; return annotation?.schemaPropertyOriginalValue; } protected _loadConfigurationFileInnerWithCache( terminal: ITerminal, resolvedConfigurationFilePath: string, projectFolderPath: string | undefined, onConfigurationFileNotFound?: IOnConfigurationFileNotFoundCallback ): TConfigurationFile { const visitedConfigurationFilePaths: Set = new Set(); const cacheEntry: IConfigurationFileCacheEntry = this.#loadConfigurationFileEntryWithCache( terminal, resolvedConfigurationFilePath, visitedConfigurationFilePaths, onConfigurationFileNotFound ); const result: TConfigurationFile = this.#finalizeConfigurationFile( cacheEntry, projectFolderPath, terminal ); return result; } protected async _loadConfigurationFileInnerWithCacheAsync( terminal: ITerminal, resolvedConfigurationFilePath: string, projectFolderPath: string | undefined, onFileNotFound?: IOnConfigurationFileNotFoundCallback ): Promise { const visitedConfigurationFilePaths: Set = new Set(); const cacheEntry: IConfigurationFileCacheEntry = await this.#loadConfigurationFileEntryWithCacheAsync( terminal, resolvedConfigurationFilePath, visitedConfigurationFilePaths, onFileNotFound ); const result: TConfigurationFile = this.#finalizeConfigurationFile( cacheEntry, projectFolderPath, terminal ); return result; } #loadConfigurationFileEntryWithCache( terminal: ITerminal, resolvedConfigurationFilePath: string, visitedConfigurationFilePaths: Set, onFileNotFound?: IOnConfigurationFileNotFoundCallback ): IConfigurationFileCacheEntry { if (visitedConfigurationFilePaths.has(resolvedConfigurationFilePath)) { const resolvedConfigurationFilePathForLogging: string = ConfigurationFileBase._formatPathForLogging( resolvedConfigurationFilePath ); throw new Error( 'A loop has been detected in the "extends" properties of configuration file at ' + `"${resolvedConfigurationFilePathForLogging}".` ); } visitedConfigurationFilePaths.add(resolvedConfigurationFilePath); let cacheEntry: IConfigurationFileCacheEntry | undefined = this.#configCache.get( resolvedConfigurationFilePath ); if (!cacheEntry) { cacheEntry = this.#loadConfigurationFileEntry( terminal, resolvedConfigurationFilePath, visitedConfigurationFilePaths, onFileNotFound ); this.#configCache.set(resolvedConfigurationFilePath, cacheEntry); } return cacheEntry; } async #loadConfigurationFileEntryWithCacheAsync( terminal: ITerminal, resolvedConfigurationFilePath: string, visitedConfigurationFilePaths: Set, onConfigurationFileNotFound?: IOnConfigurationFileNotFoundCallback ): Promise> { if (visitedConfigurationFilePaths.has(resolvedConfigurationFilePath)) { const resolvedConfigurationFilePathForLogging: string = ConfigurationFileBase._formatPathForLogging( resolvedConfigurationFilePath ); throw new Error( 'A loop has been detected in the "extends" properties of configuration file at ' + `"${resolvedConfigurationFilePathForLogging}".` ); } visitedConfigurationFilePaths.add(resolvedConfigurationFilePath); let cacheEntryPromise: Promise> | undefined = this.#configPromiseCache.get(resolvedConfigurationFilePath); if (!cacheEntryPromise) { cacheEntryPromise = this.#loadConfigurationFileEntryAsync( terminal, resolvedConfigurationFilePath, visitedConfigurationFilePaths, onConfigurationFileNotFound ).then((value: IConfigurationFileCacheEntry) => { this.#configCache.set(resolvedConfigurationFilePath, value); return value; }); this.#configPromiseCache.set(resolvedConfigurationFilePath, cacheEntryPromise); } return await cacheEntryPromise; } /** * Parses the raw JSON-with-comments text of the configuration file. * @param fileText - The text of the configuration file * @param resolvedConfigurationFilePathForLogging - The path to the configuration file, formatted for logs * @returns The parsed configuration file */ #parseConfigurationFile( fileText: string, resolvedConfigurationFilePathForLogging: string ): IConfigurationJson & TConfigurationFile { let configurationJson: IConfigurationJson & TConfigurationFile; try { configurationJson = JsonFile.parseString(fileText); } catch (e) { throw new Error(`In configuration file "${resolvedConfigurationFilePathForLogging}": ${e}`); } return configurationJson; } /** * Resolves all path properties and annotates properties with their original values. * @param entry - The cache entry for the loaded configuration file * @param projectFolderPath - The project folder path, if applicable * @returns The configuration file with all path properties resolved */ #contextualizeConfigurationFile( entry: IConfigurationFileCacheEntry, projectFolderPath: string | undefined ): IConfigurationJson & TConfigurationFile { // Deep copy the configuration file because different callers might contextualize properties differently. const result: IConfigurationJson & TConfigurationFile = structuredClone< IConfigurationJson & TConfigurationFile >(entry.configurationFile); const { resolvedConfigurationFilePath } = entry; this.#annotateProperties(resolvedConfigurationFilePath, result); for (const [jsonPath, metadata] of this.#jsonPathMetadata) { JSONPath({ path: jsonPath, json: result, callback: (payload: unknown, payloadType: string, fullPayload: IJsonPathCallbackObject) => { const resolvedPath: string = this.#resolvePathProperty( { propertyName: fullPayload.path, propertyValue: fullPayload.value, configurationFilePath: resolvedConfigurationFilePath, configurationFile: result, projectFolderPath }, metadata ); (fullPayload.parent as Record)[fullPayload.parentProperty] = resolvedPath; }, otherTypeCallback: () => { throw new Error('@other() tags are not supported'); } }); } return result; } /** * Resolves all path properties and merges parent properties. * @param entry - The cache entry for the loaded configuration file * @param projectFolderPath - The project folder path, if applicable * @returns The flattened, unvalidated configuration file, with path properties resolved */ #contextualizeAndFlattenConfigurationFile( entry: IConfigurationFileCacheEntry, projectFolderPath: string | undefined ): Partial { const { parent, resolvedConfigurationFilePath } = entry; const parentConfig: TConfigurationFile | {} = parent ? this.#contextualizeAndFlattenConfigurationFile(parent, projectFolderPath) : {}; const currentConfig: IConfigurationJson & TConfigurationFile = this.#contextualizeConfigurationFile( entry, projectFolderPath ); const result: Partial = this.#mergeConfigurationFiles( parentConfig, currentConfig, resolvedConfigurationFilePath ); return result; } /** * Resolves all path properties, merges parent properties, and validates the configuration file. * @param entry - The cache entry for the loaded configuration file * @param projectFolderPath - The project folder path, if applicable * @param terminal - The terminal to log validation messages to * @returns The finalized configuration file */ #finalizeConfigurationFile( entry: IConfigurationFileCacheEntry, projectFolderPath: string | undefined, terminal: ITerminal ): TConfigurationFile { const { resolvedConfigurationFilePathForLogging } = entry; const result: Partial = this.#contextualizeAndFlattenConfigurationFile( entry, projectFolderPath ); try { this.#schema.validateObject(result, resolvedConfigurationFilePathForLogging); } catch (e) { throw new Error(`Resolved configuration object does not match schema: ${e}`); } if ( this.#customValidationFunction && !this.#customValidationFunction( result as TConfigurationFile, resolvedConfigurationFilePathForLogging, terminal ) ) { // To suppress this error, the function may throw its own error, such as an AlreadyReportedError if it already // logged to the terminal. throw new Error( `Resolved configuration file at "${resolvedConfigurationFilePathForLogging}" failed custom validation.` ); } // If the schema validates, we can assume that the configuration file is complete. return result as TConfigurationFile; } // NOTE: Internal calls to load a configuration file should use `_loadConfigurationFileInnerWithCache`. // Don't call this function directly, as it does not provide config file loop detection, // and you won't get the advantage of queueing up for a config file that is already loading. #loadConfigurationFileEntry( terminal: ITerminal, resolvedConfigurationFilePath: string, visitedConfigurationFilePaths: Set, fileNotFoundFallback?: IOnConfigurationFileNotFoundCallback ): IConfigurationFileCacheEntry { const resolvedConfigurationFilePathForLogging: string = ConfigurationFileBase._formatPathForLogging( resolvedConfigurationFilePath ); let fileText: string; try { fileText = FileSystem.readFile(resolvedConfigurationFilePath); } catch (e) { if (FileSystem.isNotExistError(e as Error)) { const fallbackPath: string | undefined = fileNotFoundFallback?.( resolvedConfigurationFilePathForLogging ); if (fallbackPath) { try { return this.#loadConfigurationFileEntryWithCache( terminal, fallbackPath, visitedConfigurationFilePaths ); } catch (fallbackError) { if (!FileSystem.isNotExistError(fallbackError as Error)) { throw fallbackError; } // Otherwise report the missing original file. } } terminal.writeDebugLine(`Configuration file "${resolvedConfigurationFilePathForLogging}" not found.`); (e as Error).message = `File does not exist: ${resolvedConfigurationFilePathForLogging}`; } throw e; } const configurationJson: IConfigurationJson & TConfigurationFile = this.#parseConfigurationFile( fileText, resolvedConfigurationFilePathForLogging ); let parentConfiguration: IConfigurationFileCacheEntry | undefined; if (configurationJson.extends) { try { const resolvedParentConfigPath: string = Import.resolveModule({ modulePath: configurationJson.extends, baseFolderPath: nodeJsPath.dirname(resolvedConfigurationFilePath) }); parentConfiguration = this.#loadConfigurationFileEntryWithCache( terminal, resolvedParentConfigPath, visitedConfigurationFilePaths ); } catch (e) { if (FileSystem.isNotExistError(e as Error)) { throw new Error( `In file "${resolvedConfigurationFilePathForLogging}", file referenced in "extends" property ` + `("${configurationJson.extends}") cannot be resolved.` ); } else { throw e; } } } const result: IConfigurationFileCacheEntry = { configurationFile: configurationJson, resolvedConfigurationFilePath, resolvedConfigurationFilePathForLogging, parent: parentConfiguration }; return result; } // NOTE: Internal calls to load a configuration file should use `_loadConfigurationFileInnerWithCacheAsync`. // Don't call this function directly, as it does not provide config file loop detection, // and you won't get the advantage of queueing up for a config file that is already loading. async #loadConfigurationFileEntryAsync( terminal: ITerminal, resolvedConfigurationFilePath: string, visitedConfigurationFilePaths: Set, fileNotFoundFallback?: IOnConfigurationFileNotFoundCallback ): Promise> { const resolvedConfigurationFilePathForLogging: string = ConfigurationFileBase._formatPathForLogging( resolvedConfigurationFilePath ); let fileText: string; try { fileText = await FileSystem.readFileAsync(resolvedConfigurationFilePath); } catch (e) { if (FileSystem.isNotExistError(e as Error)) { const fallbackPath: string | undefined = fileNotFoundFallback?.( resolvedConfigurationFilePathForLogging ); if (fallbackPath) { try { return await this.#loadConfigurationFileEntryWithCacheAsync( terminal, fallbackPath, visitedConfigurationFilePaths ); } catch (fallbackError) { if (!FileSystem.isNotExistError(fallbackError as Error)) { throw fallbackError; } // Otherwise report the missing original file. } } terminal.writeDebugLine(`Configuration file "${resolvedConfigurationFilePathForLogging}" not found.`); (e as Error).message = `File does not exist: ${resolvedConfigurationFilePathForLogging}`; } throw e; } const configurationJson: IConfigurationJson & TConfigurationFile = this.#parseConfigurationFile( fileText, resolvedConfigurationFilePathForLogging ); let parentConfiguration: IConfigurationFileCacheEntry | undefined; if (configurationJson.extends) { try { const resolvedParentConfigPath: string = await Import.resolveModuleAsync({ modulePath: configurationJson.extends, baseFolderPath: nodeJsPath.dirname(resolvedConfigurationFilePath) }); parentConfiguration = await this.#loadConfigurationFileEntryWithCacheAsync( terminal, resolvedParentConfigPath, visitedConfigurationFilePaths ); } catch (e) { if (FileSystem.isNotExistError(e as Error)) { throw new Error( `In file "${resolvedConfigurationFilePathForLogging}", file referenced in "extends" property ` + `("${configurationJson.extends}") cannot be resolved.` ); } else { throw e; } } } const result: IConfigurationFileCacheEntry = { configurationFile: configurationJson, resolvedConfigurationFilePath, resolvedConfigurationFilePathForLogging, parent: parentConfiguration }; return result; } #annotateProperties(resolvedConfigurationFilePath: string, root: TObject): void { if (!root) { return; } const queue: Set = new Set([root]); for (const obj of queue) { if (obj && typeof obj === 'object') { (obj as unknown as IAnnotatedField)[CONFIGURATION_FILE_FIELD_ANNOTATION] = { configurationFilePath: resolvedConfigurationFilePath, originalValues: { ...obj } }; for (const objValue of Object.values(obj)) { queue.add(objValue as TObject); } } } } #resolvePathProperty( resolverOptions: IJsonPathMetadataResolverOptions, metadata: IJsonPathMetadata ): string { const { propertyValue, configurationFilePath, projectFolderPath } = resolverOptions; const resolutionMethod: PathResolutionMethod | undefined = metadata.pathResolutionMethod; if (resolutionMethod === undefined) { return propertyValue; } switch (metadata.pathResolutionMethod) { case PathResolutionMethod.resolvePathRelativeToConfigurationFile: { return nodeJsPath.resolve(nodeJsPath.dirname(configurationFilePath), propertyValue); } case PathResolutionMethod.resolvePathRelativeToProjectRoot: { const packageRoot: string | undefined = projectFolderPath; if (!packageRoot) { throw new Error( `Project-relative resolution was requested in "${ConfigurationFileBase._formatPathForLogging( configurationFilePath )}" but no project root was provided to the configuration file loader.` ); } return nodeJsPath.resolve(packageRoot, propertyValue); } case PathResolutionMethod.NodeResolve: // TODO: Remove case PathResolutionMethod.nodeResolve: { return Import.resolveModule({ modulePath: propertyValue, baseFolderPath: nodeJsPath.dirname(configurationFilePath) }); } case PathResolutionMethod.custom: { if (!metadata.customResolver) { throw new Error( `The pathResolutionMethod was set to "${PathResolutionMethod[resolutionMethod]}", but a custom ` + 'resolver was not provided.' ); } return metadata.customResolver(resolverOptions); } default: { throw new Error( `Unsupported PathResolutionMethod: ${PathResolutionMethod[resolutionMethod]} (${resolutionMethod})` ); } } } #mergeConfigurationFiles( parentConfiguration: Partial, configurationJson: Partial, resolvedConfigurationFilePath: string ): Partial { const ignoreProperties: Set = new Set(['extends', '$schema']); // Need to do a dance with the casting here because while we know that JSON keys are always // strings, TypeScript doesn't. const result: Partial = this.#mergeObjects( parentConfiguration as { [key: string]: unknown }, configurationJson as { [key: string]: unknown }, resolvedConfigurationFilePath, this.#defaultPropertyInheritance, this.#propertyInheritanceTypes as IPropertiesInheritance<{ [key: string]: unknown }>, ignoreProperties ) as Partial; const schemaPropertyOriginalValue: string | undefined = (configurationJson as IObjectWithSchema).$schema; (result as unknown as Required>)[ CONFIGURATION_FILE_FIELD_ANNOTATION ].schemaPropertyOriginalValue = schemaPropertyOriginalValue; return result; } #mergeObjects( parentObject: Partial, currentObject: Partial, resolvedConfigurationFilePath: string, defaultPropertyInheritance: IPropertyInheritanceDefaults, configuredPropertyInheritance?: IPropertiesInheritance, ignoreProperties?: Set ): Partial { const resultAnnotation: IConfigurationFileFieldAnnotation> = { configurationFilePath: resolvedConfigurationFilePath, originalValues: {} as Partial }; const result: Partial = { [CONFIGURATION_FILE_FIELD_ANNOTATION]: resultAnnotation } as unknown as Partial; // An array of property names that are on the merging object. Typed as Set since it may // contain inheritance type annotation keys, or other built-in properties that we ignore // (eg. "extends", "$schema"). const currentObjectPropertyNames: Set = new Set(Object.keys(currentObject)); // A map of property names to their inheritance type. const inheritanceTypeMap: Map> = new Map(); // The set of property names that should be included in the resulting object // All names from the parent are assumed to already be filtered. const mergedPropertyNames: Set = new Set(Object.keys(parentObject)); // Do a first pass to gather and strip the inheritance type annotations from the merging object. for (const propertyName of currentObjectPropertyNames) { if (ignoreProperties && ignoreProperties.has(propertyName)) { continue; } // Try to get the inheritance type annotation from the merging object using the regex. // Note: since this regex matches a specific style of property name, we should not need to // allow for any escaping of $-prefixed properties. If this ever changes (eg. to allow for // `"$propertyName": { ... }` options), then we'll likely need to handle that error case, // as well as allow escaping $-prefixed properties that developers want to be serialized, // possibly by using the form `$$propertyName` to escape `$propertyName`. const inheritanceTypeMatches: RegExpMatchArray | null = propertyName.match( CONFIGURATION_FILE_MERGE_BEHAVIOR_FIELD_REGEX ); if (inheritanceTypeMatches) { // Should always be of length 2, since the first match is the entire string and the second // match is the capture group. const mergeTargetPropertyName: string = inheritanceTypeMatches[1]; const inheritanceTypeRaw: unknown | undefined = currentObject[propertyName]; if (!currentObjectPropertyNames.has(mergeTargetPropertyName)) { throw new Error( `Issue in processing configuration file property "${propertyName}". ` + `An inheritance type was provided but no matching property was found in the parent.` ); } else if (typeof inheritanceTypeRaw !== 'string') { throw new Error( `Issue in processing configuration file property "${propertyName}". ` + `An unsupported inheritance type was provided: ${JSON.stringify(inheritanceTypeRaw)}` ); } else if (typeof currentObject[mergeTargetPropertyName] !== 'object') { throw new Error( `Issue in processing configuration file property "${propertyName}". ` + `An inheritance type was provided for a property that is not a keyed object or array.` ); } switch (inheritanceTypeRaw.toLowerCase()) { case 'append': inheritanceTypeMap.set(mergeTargetPropertyName, { inheritanceType: InheritanceType.append }); break; case 'merge': inheritanceTypeMap.set(mergeTargetPropertyName, { inheritanceType: InheritanceType.merge }); break; case 'replace': inheritanceTypeMap.set(mergeTargetPropertyName, { inheritanceType: InheritanceType.replace }); break; default: throw new Error( `Issue in processing configuration file property "${propertyName}". ` + `An unsupported inheritance type was provided: "${inheritanceTypeRaw}"` ); } } else { mergedPropertyNames.add(propertyName); } } // Cycle through properties and merge them for (const propertyName of mergedPropertyNames) { const propertyValue: TField[keyof TField] | undefined = currentObject[propertyName]; const parentPropertyValue: TField[keyof TField] | undefined = parentObject[propertyName]; let newValue: TField[keyof TField] | undefined; const usePropertyValue: () => void = () => { resultAnnotation.originalValues[propertyName] = this.getPropertyOriginalValue({ parentObject: currentObject, propertyName: propertyName }); newValue = propertyValue; }; const useParentPropertyValue: () => void = () => { resultAnnotation.originalValues[propertyName] = this.getPropertyOriginalValue({ parentObject: parentObject, propertyName: propertyName }); newValue = parentPropertyValue; }; if (propertyValue === null) { if (parentPropertyValue !== undefined) { resultAnnotation.originalValues[propertyName] = this.getPropertyOriginalValue({ parentObject: parentObject, propertyName: propertyName }); } newValue = undefined; } else if (propertyValue !== undefined && parentPropertyValue === undefined) { usePropertyValue(); } else if (parentPropertyValue !== undefined && propertyValue === undefined) { useParentPropertyValue(); } else if (propertyValue !== undefined && parentPropertyValue !== undefined) { // If the property is an inheritance type annotation, use it, otherwise fallback to the configured // top-level property inheritance, if one is specified. let propertyInheritance: IPropertyInheritance | undefined = inheritanceTypeMap.get(propertyName) ?? configuredPropertyInheritance?.[propertyName]; if (!propertyInheritance) { const bothAreArrays: boolean = Array.isArray(propertyValue) && Array.isArray(parentPropertyValue); if (bothAreArrays) { // If both are arrays, use the configured default array inheritance and fallback to appending // if one is not specified propertyInheritance = defaultPropertyInheritance.array ?? { inheritanceType: InheritanceType.append }; } else { const bothAreObjects: boolean = propertyValue && parentPropertyValue && typeof propertyValue === 'object' && typeof parentPropertyValue === 'object'; if (bothAreObjects) { // If both are objects, use the configured default object inheritance and fallback to replacing // if one is not specified propertyInheritance = defaultPropertyInheritance.object ?? { inheritanceType: InheritanceType.replace }; } else { // Fall back to replacing if they are of different types, since we don't know how to merge these propertyInheritance = { inheritanceType: InheritanceType.replace }; } } } switch (propertyInheritance.inheritanceType) { case InheritanceType.replace: { usePropertyValue(); break; } case InheritanceType.append: { if (!Array.isArray(propertyValue) || !Array.isArray(parentPropertyValue)) { throw new Error( `Issue in processing configuration file property "${propertyName.toString()}". ` + `Property is not an array, but the inheritance type is set as "${InheritanceType.append}"` ); } newValue = [...parentPropertyValue, ...propertyValue] as TField[keyof TField]; (newValue as unknown as IAnnotatedField)[CONFIGURATION_FILE_FIELD_ANNOTATION] = { configurationFilePath: undefined, originalValues: { // eslint-disable-next-line @typescript-eslint/no-explicit-any ...(parentPropertyValue as any)[CONFIGURATION_FILE_FIELD_ANNOTATION].originalValues, // eslint-disable-next-line @typescript-eslint/no-explicit-any ...(propertyValue as any)[CONFIGURATION_FILE_FIELD_ANNOTATION].originalValues } }; break; } case InheritanceType.merge: { if (parentPropertyValue === null || propertyValue === null) { throw new Error( `Issue in processing configuration file property "${propertyName.toString()}". ` + `Null values cannot be used when the inheritance type is set as "${InheritanceType.merge}"` ); } else if ( (propertyValue && typeof propertyValue !== 'object') || (parentPropertyValue && typeof parentPropertyValue !== 'object') ) { throw new Error( `Issue in processing configuration file property "${propertyName.toString()}". ` + `Primitive types cannot be provided when the inheritance type is set as "${InheritanceType.merge}"` ); } else if (Array.isArray(propertyValue) || Array.isArray(parentPropertyValue)) { throw new Error( `Issue in processing configuration file property "${propertyName.toString()}". ` + `Property is not a keyed object, but the inheritance type is set as "${InheritanceType.merge}"` ); } // Recursively merge the parent and child objects. Don't pass the configuredPropertyInheritance or // ignoreProperties because we are no longer at the top level of the configuration file. We also know // that it must be a string-keyed object, since the JSON spec requires it. newValue = this.#mergeObjects( parentPropertyValue as { [key: string]: unknown }, propertyValue as { [key: string]: unknown }, resolvedConfigurationFilePath, defaultPropertyInheritance ) as TField[keyof TField]; break; } case InheritanceType.custom: { const customInheritance: ICustomPropertyInheritance = propertyInheritance as ICustomPropertyInheritance; if ( !customInheritance.inheritanceFunction || typeof customInheritance.inheritanceFunction !== 'function' ) { throw new Error( 'For property inheritance type "InheritanceType.custom", an inheritanceFunction must be provided.' ); } newValue = customInheritance.inheritanceFunction(propertyValue, parentPropertyValue); break; } default: { throw new Error(`Unknown inheritance type "${propertyInheritance}"`); } } } if (newValue !== undefined) { // Don't attach the key for undefined values so that they don't enumerate. result[propertyName] = newValue; } } return result; } }