From 21b8a412783d32a1a6deb308defa51bc2a50280f Mon Sep 17 00:00:00 2001 From: Charles Lyding <19598772+clydin@users.noreply.github.com> Date: Thu, 31 Jul 2025 16:16:11 -0400 Subject: [PATCH] refactor(@schematics/angular): organize use-application-builder migration Reorganizes the `use-application-builder` migration by extracting the stylesheet-related logic into a separate, more focused file. The key changes include: - Moving stylesheet-related functions (`hasLessStylesheets`, `hasPostcssConfiguration`, `updateStyleImports`, and their helpers) from `migration.ts` into a new `stylesheet-updates.ts` file. - Updating the main `migration.ts` file to import these functions from the new module. --- .../use-application-builder/migration.ts | 172 +---------- .../stylesheet-updates.ts | 282 ++++++++++++++++++ .../stylesheet-updates_spec.ts | 179 +++++++++++ 3 files changed, 467 insertions(+), 166 deletions(-) create mode 100644 packages/schematics/angular/migrations/use-application-builder/stylesheet-updates.ts create mode 100644 packages/schematics/angular/migrations/use-application-builder/stylesheet-updates_spec.ts diff --git a/packages/schematics/angular/migrations/use-application-builder/migration.ts b/packages/schematics/angular/migrations/use-application-builder/migration.ts index 6a59c212fa21..f642a45461a6 100644 --- a/packages/schematics/angular/migrations/use-application-builder/migration.ts +++ b/packages/schematics/angular/migrations/use-application-builder/migration.ts @@ -7,7 +7,6 @@ */ import { - DirEntry, Rule, SchematicContext, SchematicsException, @@ -15,7 +14,7 @@ import { chain, externalSchematic, } from '@angular-devkit/schematics'; -import { basename, dirname, extname, join } from 'node:path/posix'; +import { dirname, join } from 'node:path/posix'; import { removePackageJsonDependency } from '../../utility/dependencies'; import { DependencyType, @@ -27,13 +26,16 @@ import { JSONFile } from '../../utility/json-file'; import { latestVersions } from '../../utility/latest-versions'; import { TargetDefinition, - WorkspaceDefinition, allTargetOptions, allWorkspaceTargets, updateWorkspace, } from '../../utility/workspace'; import { Builders, ProjectType } from '../../utility/workspace-models'; -import { findImports } from './css-import-lexer'; +import { + hasLessStylesheets, + hasPostcssConfiguration, + updateStyleImports, +} from './stylesheet-updates'; function* updateBuildTarget( projectName: string, @@ -334,168 +336,6 @@ function updateProjects(tree: Tree, context: SchematicContext) { }); } -/** - * Searches the schematic tree for files that have a `.less` extension. - * - * @param tree A Schematics tree instance to search - * @returns true if Less stylesheet files are found; otherwise, false - */ -function hasLessStylesheets(tree: Tree) { - const directories = [tree.getDir('/')]; - - let current; - while ((current = directories.pop())) { - for (const path of current.subfiles) { - if (path.endsWith('.less')) { - return true; - } - } - - for (const path of current.subdirs) { - if (path === 'node_modules' || path.startsWith('.')) { - continue; - } - directories.push(current.dir(path)); - } - } -} - -/** - * Searches for a Postcss configuration file within the workspace root - * or any of the project roots. - * - * @param tree A Schematics tree instance to search - * @param workspace A Workspace to check for projects - * @returns true, if a Postcss configuration file is found; otherwise, false - */ -function hasPostcssConfiguration(tree: Tree, workspace: WorkspaceDefinition) { - // Add workspace root - const searchDirectories = ['']; - - // Add each project root - for (const { root } of workspace.projects.values()) { - if (root) { - searchDirectories.push(root); - } - } - - return searchDirectories.some( - (dir) => - tree.exists(join(dir, 'postcss.config.json')) || tree.exists(join(dir, '.postcssrc.json')), - ); -} - -function* visit( - directory: DirEntry, -): IterableIterator<[fileName: string, contents: string, sass: boolean]> { - for (const path of directory.subfiles) { - const sass = path.endsWith('.scss'); - if (path.endsWith('.css') || sass) { - const entry = directory.file(path); - if (entry) { - const content = entry.content; - - yield [entry.path, content.toString(), sass]; - } - } - } - - for (const path of directory.subdirs) { - if (path === 'node_modules' || path.startsWith('.')) { - continue; - } - - yield* visit(directory.dir(path)); - } -} - -// Based on https://github.com/sass/dart-sass/blob/44d6bb6ac72fe6b93f5bfec371a1fffb18e6b76d/lib/src/importer/utils.dart -function* potentialSassImports( - specifier: string, - base: string, - fromImport: boolean, -): Iterable { - const directory = join(base, dirname(specifier)); - const extension = extname(specifier); - const hasStyleExtension = extension === '.scss' || extension === '.sass' || extension === '.css'; - // Remove the style extension if present to allow adding the `.import` suffix - const filename = basename(specifier, hasStyleExtension ? extension : undefined); - - if (hasStyleExtension) { - if (fromImport) { - yield join(directory, filename + '.import' + extension); - yield join(directory, '_' + filename + '.import' + extension); - } - yield join(directory, filename + extension); - yield join(directory, '_' + filename + extension); - } else { - if (fromImport) { - yield join(directory, filename + '.import.scss'); - yield join(directory, filename + '.import.sass'); - yield join(directory, filename + '.import.css'); - yield join(directory, '_' + filename + '.import.scss'); - yield join(directory, '_' + filename + '.import.sass'); - yield join(directory, '_' + filename + '.import.css'); - } - yield join(directory, filename + '.scss'); - yield join(directory, filename + '.sass'); - yield join(directory, filename + '.css'); - yield join(directory, '_' + filename + '.scss'); - yield join(directory, '_' + filename + '.sass'); - yield join(directory, '_' + filename + '.css'); - } -} - -function updateStyleImports(tree: Tree, projectSourceRoot: string, buildTarget: TargetDefinition) { - const external = new Set(); - let needWorkspaceIncludePath = false; - for (const file of visit(tree.getDir(projectSourceRoot))) { - const [path, content, sass] = file; - const relativeBase = dirname(path); - - let updater; - for (const { start, specifier, fromUse } of findImports(content, sass)) { - if (specifier[0] === '~') { - updater ??= tree.beginUpdate(path); - // start position includes the opening quote - updater.remove(start + 1, 1); - } else if (specifier[0] === '^') { - updater ??= tree.beginUpdate(path); - // start position includes the opening quote - updater.remove(start + 1, 1); - // Add to externalDependencies - external.add(specifier.slice(1)); - } else if ( - sass && - [...potentialSassImports(specifier, relativeBase, !fromUse)].every( - (v) => !tree.exists(v), - ) && - [...potentialSassImports(specifier, '/', !fromUse)].some((v) => tree.exists(v)) - ) { - needWorkspaceIncludePath = true; - } - } - if (updater) { - tree.commitUpdate(updater); - } - } - - if (needWorkspaceIncludePath) { - buildTarget.options ??= {}; - buildTarget.options['stylePreprocessorOptions'] ??= {}; - ((buildTarget.options['stylePreprocessorOptions'] as { includePaths?: string[] })[ - 'includePaths' - ] ??= []).push('.'); - } - - if (external.size > 0) { - buildTarget.options ??= {}; - ((buildTarget.options['externalDependencies'] as string[] | undefined) ??= []).push( - ...external, - ); - } -} - function deleteFile(path: string): Rule { return (tree) => { tree.delete(path); diff --git a/packages/schematics/angular/migrations/use-application-builder/stylesheet-updates.ts b/packages/schematics/angular/migrations/use-application-builder/stylesheet-updates.ts new file mode 100644 index 000000000000..ea3eef03ace1 --- /dev/null +++ b/packages/schematics/angular/migrations/use-application-builder/stylesheet-updates.ts @@ -0,0 +1,282 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.dev/license + */ + +import { DirEntry, Tree } from '@angular-devkit/schematics'; +import { basename, dirname, extname, join } from 'node:path/posix'; +import { TargetDefinition, WorkspaceDefinition } from '../../utility/workspace'; +import { findImports } from './css-import-lexer'; + +/** A list of all supported SASS style extensions. + * Order of extension is important and matches Sass behavior. + */ +const SASS_EXTENSIONS = ['.scss', '.sass', '.css']; + +/** The prefix used to indicate a SASS partial file. */ +const SASS_PARTIAL_PREFIX = '_'; + +/** + * An object containing the results of analyzing a single stylesheet file. + */ +interface StylesheetAnalysis { + /** Whether the stylesheet requires the workspace root to be added to the SASS include paths. */ + needsWorkspaceIncludePath: boolean; + + /** A set of external dependencies that were discovered in the stylesheet. */ + externalDependencies: Set; + + /** A list of content changes that need to be applied to the stylesheet. */ + contentChanges: { start: number; length: number }[]; +} + +/** + * Searches the schematic tree for files that have a `.less` extension. + * This is used to determine if the `less` package should be added as a dependency. + * + * @param tree A Schematics tree instance to search. + * @returns `true` if Less stylesheet files are found; otherwise, `false`. + */ +export function hasLessStylesheets(tree: Tree): boolean { + const directories = [tree.getDir('/')]; + + let current; + while ((current = directories.pop())) { + for (const path of current.subfiles) { + if (path.endsWith('.less')) { + return true; + } + } + + for (const path of current.subdirs) { + if (path === 'node_modules' || path.startsWith('.')) { + continue; + } + directories.push(current.dir(path)); + } + } + + return false; +} + +/** + * Searches for a PostCSS configuration file within the workspace root or any of the project roots. + * This is used to determine if the `postcss` package should be added as a dependency. + * + * @param tree A Schematics tree instance to search. + * @param workspace A Workspace to check for projects. + * @returns `true` if a PostCSS configuration file is found; otherwise, `false`. + */ +export function hasPostcssConfiguration(tree: Tree, workspace: WorkspaceDefinition): boolean { + const projectRoots = [...workspace.projects.values()].map((p) => p.root).filter(Boolean); + const searchDirectories = new Set(['', ...projectRoots]); + + for (const dir of searchDirectories) { + if ( + tree.exists(join(dir, 'postcss.config.json')) || + tree.exists(join(dir, '.postcssrc.json')) + ) { + return true; + } + } + + return false; +} + +/** + * Recursively visits all stylesheet files in a directory and yields their path and content. + * + * @param directory The directory to visit. + */ +function* visitStylesheets(directory: DirEntry): IterableIterator<[path: string, content: string]> { + for (const path of directory.subfiles) { + if (path.endsWith('.css') || path.endsWith('.scss') || path.endsWith('.sass')) { + const entry = directory.file(path); + if (entry) { + yield [entry.path, entry.content.toString()]; + } + } + } + + for (const path of directory.subdirs) { + if (path === 'node_modules' || path.startsWith('.')) { + continue; + } + + yield* visitStylesheets(directory.dir(path)); + } +} + +/** + * Determines if a Sass import is likely intended to be relative to the workspace root. + * This is considered true if the import cannot be resolved relative to the containing file, + * but can be resolved relative to the workspace root. + * + * @param specifier The import specifier to check. + * @param filePath The path of the file containing the import. + * @param tree A Schematics tree instance. + * @param fromImport Whether the specifier is from an `@import` rule. + * @returns `true` if the import is likely workspace-relative; otherwise, `false`. + */ +function isWorkspaceRelativeSassImport( + specifier: string, + filePath: string, + tree: Tree, + fromImport: boolean, +): boolean { + const relativeBase = dirname(filePath); + const potentialWorkspacePaths = [...potentialSassImports(specifier, '/', fromImport)]; + + if (potentialWorkspacePaths.some((p) => tree.exists(p))) { + const potentialRelativePaths = [...potentialSassImports(specifier, relativeBase, fromImport)]; + + return potentialRelativePaths.every((p) => !tree.exists(p)); + } + + return false; +} + +/** + * Analyzes a single stylesheet's content for import patterns that need to be updated. + * + * @param filePath The path of the stylesheet file. + * @param content The content of the stylesheet file. + * @param tree A Schematics tree instance. + * @returns A `StylesheetAnalysis` object containing the results of the analysis. + */ +function analyzeStylesheet(filePath: string, content: string, tree: Tree): StylesheetAnalysis { + const isSass = filePath.endsWith('.scss') || filePath.endsWith('.sass'); + const analysis: StylesheetAnalysis = { + needsWorkspaceIncludePath: false, + externalDependencies: new Set(), + contentChanges: [], + }; + + for (const { start, specifier, fromUse } of findImports(content, isSass)) { + if (specifier.startsWith('~')) { + analysis.contentChanges.push({ start: start + 1, length: 1 }); + } else if (specifier.startsWith('^')) { + analysis.contentChanges.push({ start: start + 1, length: 1 }); + analysis.externalDependencies.add(specifier.slice(1)); + } else if (isSass && isWorkspaceRelativeSassImport(specifier, filePath, tree, !fromUse)) { + analysis.needsWorkspaceIncludePath = true; + } + } + + return analysis; +} + +/** + * The main orchestrator function for updating stylesheets. + * It iterates through all stylesheets in a project, analyzes them, and applies the necessary + * changes to the files and the build configuration. + * + * @param tree A Schematics tree instance. + * @param projectSourceRoot The source root of the project being updated. + * @param buildTarget The build target of the project being updated. + */ +export function updateStyleImports( + tree: Tree, + projectSourceRoot: string, + buildTarget: TargetDefinition, +): void { + const allExternalDeps = new Set(); + let projectNeedsIncludePath = false; + + for (const [path, content] of visitStylesheets(tree.getDir(projectSourceRoot))) { + const { needsWorkspaceIncludePath, externalDependencies, contentChanges } = analyzeStylesheet( + path, + content, + tree, + ); + + if (needsWorkspaceIncludePath) { + projectNeedsIncludePath = true; + } + + for (const dep of externalDependencies) { + allExternalDeps.add(dep); + } + + if (contentChanges.length > 0) { + const updater = tree.beginUpdate(path); + // Apply changes in reverse to avoid index shifting + for (const change of contentChanges.sort((a, b) => b.start - a.start)) { + updater.remove(change.start, change.length); + } + tree.commitUpdate(updater); + } + } + + if (projectNeedsIncludePath) { + buildTarget.options ??= {}; + const styleOptions = (buildTarget.options['stylePreprocessorOptions'] ??= {}); + const includePaths = ((styleOptions as { includePaths?: string[] })['includePaths'] ??= []); + if (Array.isArray(includePaths)) { + includePaths.push('.'); + } + } + + if (allExternalDeps.size > 0) { + buildTarget.options ??= {}; + const externalDeps = ((buildTarget.options['externalDependencies'] as string[] | undefined) ??= + []); + if (Array.isArray(externalDeps)) { + externalDeps.push(...allExternalDeps); + } + } +} + +/** + * A helper generator that yields potential Sass import candidates for a given filename and extensions. + * + * @param directory The directory in which to resolve the candidates. + * @param filename The base filename of the import. + * @param extensions The file extensions to try. + * @param fromImport Whether the specifier is from an `@import` rule. + * @returns An iterable of potential import file paths. + */ +function* yieldSassImportCandidates( + directory: string, + filename: string, + extensions: readonly string[], + fromImport: boolean, +): Iterable { + if (fromImport) { + for (const ext of extensions) { + yield join(directory, filename + '.import' + ext); + yield join(directory, SASS_PARTIAL_PREFIX + filename + '.import' + ext); + } + } + for (const ext of extensions) { + yield join(directory, filename + ext); + yield join(directory, SASS_PARTIAL_PREFIX + filename + ext); + } +} + +/** + * Generates a sequence of potential file paths that the Sass compiler would attempt to resolve + * for a given import specifier, following the official Sass resolution algorithm. + * Based on https://github.com/sass/dart-sass/blob/44d6bb6ac72fe6b93f5bfec371a1fffb18e6b76d/lib/src/importer/utils.dart + * + * @param specifier The import specifier to resolve. + * @param base The base path from which to resolve the specifier. + * @param fromImport Whether the specifier is from an `@import` rule. + * @returns An iterable of potential file paths. + */ +function* potentialSassImports( + specifier: string, + base: string, + fromImport: boolean, +): Iterable { + const directory = join(base, dirname(specifier)); + const extension = extname(specifier); + const hasStyleExtension = SASS_EXTENSIONS.includes(extension); + const filename = basename(specifier, hasStyleExtension ? extension : undefined); + + const extensionsToTry = hasStyleExtension ? [extension] : SASS_EXTENSIONS; + yield* yieldSassImportCandidates(directory, filename, extensionsToTry, fromImport); +} diff --git a/packages/schematics/angular/migrations/use-application-builder/stylesheet-updates_spec.ts b/packages/schematics/angular/migrations/use-application-builder/stylesheet-updates_spec.ts new file mode 100644 index 000000000000..fb188cb2ca5f --- /dev/null +++ b/packages/schematics/angular/migrations/use-application-builder/stylesheet-updates_spec.ts @@ -0,0 +1,179 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.dev/license + */ + +import { Tree } from '@angular-devkit/schematics'; +import { ProjectDefinition, TargetDefinition, WorkspaceDefinition } from '../../utility/workspace'; +import { + hasLessStylesheets, + hasPostcssConfiguration, + updateStyleImports, +} from './stylesheet-updates'; + +interface StylePreprocessorOptions { + includePaths?: string[]; + otherOption?: boolean; +} + +describe('Migration to use application builder: stylesheet updates', () => { + let tree: Tree; + let workspace: WorkspaceDefinition; + let buildTarget: TargetDefinition; + + beforeEach(() => { + tree = Tree.empty(); + buildTarget = { + builder: '@angular-devkit/build-angular:browser', + options: {}, + }; + + const testProject: ProjectDefinition = { + root: 'test', + // eslint-disable-next-line @typescript-eslint/no-explicit-any + targets: new Map([['build', buildTarget]]) as any, + prefix: 'app', + sourceRoot: 'test/src', + extensions: {}, + }; + + workspace = { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + projects: new Map([['test', testProject]]) as any, + extensions: {}, + }; + + // Create some common files for testing + tree.create('/node_modules/@angular/material/_index.scss', '// Fake Angular Material styles'); + tree.create('/test/src/styles.scss', '@import "./app/app.component.scss";'); + }); + + describe('hasLessStylesheets', () => { + it('should return true if a .less file exists in the root', () => { + tree.create('/test.less', ''); + expect(hasLessStylesheets(tree)).toBe(true); + }); + + it('should return true if a .less file exists in a subdirectory', () => { + tree.create('/src/app.less', ''); + expect(hasLessStylesheets(tree)).toBe(true); + }); + + it('should return false if no .less files exist', () => { + tree.create('/src/app.css', ''); + expect(hasLessStylesheets(tree)).toBe(false); + }); + + it('should ignore files in node_modules', () => { + tree.create('/node_modules/library/style.less', ''); + expect(hasLessStylesheets(tree)).toBe(false); + }); + + it('should ignore files in dot-prefixed directories', () => { + tree.create('/.hidden/style.less', ''); + expect(hasLessStylesheets(tree)).toBe(false); + }); + }); + + describe('hasPostcssConfiguration', () => { + it('should return true if postcss.config.json exists in the root', () => { + tree.create('/postcss.config.json', '{}'); + expect(hasPostcssConfiguration(tree, workspace)).toBe(true); + }); + + it('should return true if .postcssrc.json exists in the root', () => { + tree.create('/.postcssrc.json', '{}'); + expect(hasPostcssConfiguration(tree, workspace)).toBe(true); + }); + + it('should return true if postcss.config.json exists in a project root', () => { + tree.create('/test/postcss.config.json', '{}'); + expect(hasPostcssConfiguration(tree, workspace)).toBe(true); + }); + + it('should return false if no config files exist', () => { + expect(hasPostcssConfiguration(tree, workspace)).toBe(false); + }); + }); + + describe('updateStyleImports', () => { + it('should remove "~" from an @import rule', () => { + tree.create('/test/src/app/app.component.scss', '@import "~@angular/material";'); + updateStyleImports(tree, 'test/src', buildTarget); + const content = tree.readText('/test/src/app/app.component.scss'); + expect(content).toBe('@import "@angular/material";'); + }); + + it('should remove "~" from a @use rule', () => { + tree.create('/test/src/app/app.component.scss', '@use "~@angular/material";'); + updateStyleImports(tree, 'test/src', buildTarget); + const content = tree.readText('/test/src/app/app.component.scss'); + expect(content).toBe('@use "@angular/material";'); + }); + + it('should remove "^" and add to externalDependencies', () => { + tree.create('/test/src/app/app.component.scss', '@import "^my-lib/styles.css";'); + updateStyleImports(tree, 'test/src', buildTarget); + const content = tree.readText('/test/src/app/app.component.scss'); + expect(content).toBe('@import "my-lib/styles.css";'); + expect(buildTarget.options?.['externalDependencies']).toEqual(['my-lib/styles.css']); + }); + + it('should aggregate multiple external dependencies', () => { + tree.create('/test/src/app/app.component.scss', '@import "^lib-a";'); + tree.create('/test/src/app/other.component.scss', '@import "^lib-b";'); + updateStyleImports(tree, 'test/src', buildTarget); + expect(buildTarget.options?.['externalDependencies']).toEqual(['lib-a', 'lib-b']); + }); + + it('should identify a workspace-relative import and add includePaths', () => { + tree.create('/assets/styles/theme.scss', '// Theme file'); + tree.create('/test/src/app/app.component.scss', '@import "assets/styles/theme.scss";'); + updateStyleImports(tree, 'test/src', buildTarget); + const styleOptions = buildTarget.options?.['stylePreprocessorOptions'] as + | StylePreprocessorOptions + | undefined; + expect(styleOptions?.includePaths).toEqual(['.']); + }); + + it('should not identify a standard relative import as workspace-relative', () => { + tree.create('/test/src/app/theme.scss', '// Theme file'); + tree.create('/test/src/app/app.component.scss', '@import "./theme.scss";'); + updateStyleImports(tree, 'test/src', buildTarget); + const styleOptions = buildTarget.options?.['stylePreprocessorOptions']; + expect(styleOptions).toBeUndefined(); + }); + + it('should correctly add includePaths when stylePreprocessorOptions already exists', () => { + buildTarget.options ??= {}; + buildTarget.options['stylePreprocessorOptions'] = { + otherOption: true, + }; + tree.create('/assets/styles/theme.scss', '// Theme file'); + tree.create('/test/src/app/app.component.scss', '@import "assets/styles/theme.scss";'); + updateStyleImports(tree, 'test/src', buildTarget); + const styleOptions = buildTarget.options?.['stylePreprocessorOptions'] as + | StylePreprocessorOptions + | undefined; + expect(styleOptions?.includePaths).toEqual(['.']); + expect(styleOptions?.otherOption).toBe(true); + }); + + it('should correctly add includePaths when includePaths already exists', () => { + buildTarget.options ??= {}; + buildTarget.options['stylePreprocessorOptions'] = { + includePaths: ['/some/other/path'], + }; + tree.create('/assets/styles/theme.scss', '// Theme file'); + tree.create('/test/src/app/app.component.scss', '@import "assets/styles/theme.scss";'); + updateStyleImports(tree, 'test/src', buildTarget); + const styleOptions = buildTarget.options?.['stylePreprocessorOptions'] as + | StylePreprocessorOptions + | undefined; + expect(styleOptions?.includePaths).toEqual(['/some/other/path', '.']); + }); + }); +});