// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. // See LICENSE in the project root for license information. import * as path from 'node:path'; import { FileSystem, Path } from '@rushstack/node-core-library'; /** * Information about an incremental build. This information is used to determine which files need to be rebuilt. * @beta */ export interface IIncrementalBuildInfo { /** * A string that represents the configuration inputs for the build. * If the configuration changes, the old build info object should be discarded. */ configHash: string; /** * A map of absolute input file paths to their version strings. * The version string should change if the file changes. */ inputFileVersions: Map; /** * A map of absolute output file paths to the input files they were computed from. */ fileDependencies?: Map; } /** * Serialized version of {@link IIncrementalBuildInfo}. * @beta */ export interface ISerializedIncrementalBuildInfo { /** * A string that represents the configuration inputs for the build. * If the configuration changes, the old build info object should be discarded. */ configHash: string; /** * A map of input files to their version strings. * File paths are specified relative to the folder containing the build info file. */ inputFileVersions: Record; /** * Map of output file names to the corresponding index in `Object.entries(inputFileVersions)`. * File paths are specified relative to the folder containing the build info file. */ fileDependencies?: Record; } /** * Converts an absolute path to a path relative to a base path. */ export const makePathRelative: (absolutePath: string, basePath: string) => string = process.platform === 'win32' ? (absolutePath: string, basePath: string) => { // On Windows, need to normalize slashes return Path.convertToSlashes(path.win32.relative(basePath, absolutePath)); } : (absolutePath: string, basePath: string) => { // On POSIX, can preserve existing slashes return path.posix.relative(basePath, absolutePath); }; /** * Serializes a build info object to a portable format that can be written to disk. * @param state - The build info to serialize * @param makePathPortable - A function that converts an absolute path to a portable path. This is a separate argument to support cross-platform tests. * @returns The serialized build info * @beta */ export function serializeBuildInfo( state: IIncrementalBuildInfo, makePathPortable: (absolutePath: string) => string ): ISerializedIncrementalBuildInfo { const fileIndices: Map = new Map(); const inputFileVersions: Record = {}; for (const [absolutePath, version] of state.inputFileVersions) { const relativePath: string = makePathPortable(absolutePath); fileIndices.set(absolutePath, fileIndices.size); inputFileVersions[relativePath] = version; } const { fileDependencies: newFileDependencies } = state; let fileDependencies: Record | undefined; if (newFileDependencies) { fileDependencies = {}; for (const [absolutePath, dependencies] of newFileDependencies) { const relativePath: string = makePathPortable(absolutePath); const indices: number[] = []; for (const dependency of dependencies) { const index: number | undefined = fileIndices.get(dependency); if (index === undefined) { throw new Error(`Dependency not found: ${dependency}`); } indices.push(index); } fileDependencies[relativePath] = indices; } } const serializedBuildInfo: ISerializedIncrementalBuildInfo = { configHash: state.configHash, inputFileVersions, fileDependencies }; return serializedBuildInfo; } /** * Deserializes a build info object from its portable format. * @param serializedBuildInfo - The build info to deserialize * @param makePathAbsolute - A function that converts a portable path to an absolute path. This is a separate argument to support cross-platform tests. * @returns The deserialized build info */ export function deserializeBuildInfo( serializedBuildInfo: ISerializedIncrementalBuildInfo, makePathAbsolute: (relativePath: string) => string ): IIncrementalBuildInfo { const inputFileVersions: Map = new Map(); const absolutePathByIndex: string[] = []; for (const [relativePath, version] of Object.entries(serializedBuildInfo.inputFileVersions)) { const absolutePath: string = makePathAbsolute(relativePath); absolutePathByIndex.push(absolutePath); inputFileVersions.set(absolutePath, version); } let fileDependencies: Map | undefined; const { fileDependencies: serializedFileDependencies } = serializedBuildInfo; if (serializedFileDependencies) { fileDependencies = new Map(); for (const [relativeOutputFile, indices] of Object.entries(serializedFileDependencies)) { const absoluteOutputFile: string = makePathAbsolute(relativeOutputFile); const dependencies: string[] = []; for (const index of Array.isArray(indices) ? indices : [indices]) { const dependencyAbsolutePath: string | undefined = absolutePathByIndex[index]; if (dependencyAbsolutePath === undefined) { throw new Error(`Dependency index not found: ${index}`); } dependencies.push(dependencyAbsolutePath); } fileDependencies.set(absoluteOutputFile, dependencies); } } const buildInfo: IIncrementalBuildInfo = { configHash: serializedBuildInfo.configHash, inputFileVersions, fileDependencies }; return buildInfo; } /** * Writes a build info object to disk. * @param state - The build info to write * @param filePath - The file path to write the build info to * @beta */ export async function writeBuildInfoAsync(state: IIncrementalBuildInfo, filePath: string): Promise { const basePath: string = path.dirname(filePath); const serializedBuildInfo: ISerializedIncrementalBuildInfo = serializeBuildInfo( state, (absolutePath: string) => { return makePathRelative(absolutePath, basePath); } ); // This file is meant only for machine reading, so don't pretty-print it. const stringified: string = JSON.stringify(serializedBuildInfo); await FileSystem.writeFileAsync(filePath, stringified, { ensureFolderExists: true }); } /** * Reads a build info object from disk. * @param filePath - The file path to read the build info from * @returns The build info object, or undefined if the file does not exist or cannot be parsed * @beta */ export async function tryReadBuildInfoAsync(filePath: string): Promise { let serializedBuildInfo: ISerializedIncrementalBuildInfo | undefined; try { const fileContents: string = await FileSystem.readFileAsync(filePath); serializedBuildInfo = JSON.parse(fileContents) as ISerializedIncrementalBuildInfo; } catch (error) { if (FileSystem.isNotExistError(error)) { return; } throw error; } const basePath: string = path.dirname(filePath); const buildInfo: IIncrementalBuildInfo = deserializeBuildInfo( serializedBuildInfo, (relativePath: string) => { return path.resolve(basePath, relativePath); } ); return buildInfo; }