@openrewrite/recipes-angular 1.1.4 → 1.1.5

package/src/libraries/primeng/18/add-primeng-provider.ts

@@ -0,0 +1,359 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {ExecutionContext, Recipe, ScanningRecipe, TreeVisitor} from "@openrewrite/rewrite";
+import {JavaScriptVisitor, JS, Template, maybeAddImport} from "@openrewrite/rewrite/javascript";
+import {JsonVisitor, Json, getMemberKeyName, isArray, isLiteral} from "@openrewrite/rewrite/json";
+import {J, isIdentifier, emptySpace, singleSpace} from "@openrewrite/rewrite/java";
+
+type Preset = 'Aura' | 'Lara' | 'Nora' | 'Material';
+
+/**
+ * Tri-state: 'system' is the v18 default (follow OS preference), 'disabled' opts the app
+ * out of dark mode entirely (equivalent to `darkModeSelector: false`), 'unset' means the
+ * recipe shouldn't emit a `darkModeSelector` option (lets v18 default apply).
+ */
+type DarkMode = 'system' | 'disabled' | 'unset';
+
+interface AddPrimengProviderAcc {
+    /** v18 design-token preset to use, derived from the v17 theme found in angular.json. */
+    preset: Preset;
+    /** Whether to emit `darkModeSelector` and what value, derived from the v17 theme name. */
+    darkMode: DarkMode;
+    /** Whether the scanner saw any v17 theme path (used only for diagnostics / future hooks). */
+    detectedFromAngularJson: boolean;
+}
+
+/**
+ * Map a v17 theme name (e.g. `lara-light-blue`, `md-dark-indigo`, `mira`) to the closest
+ * v18 design-token preset. v17 had dozens of themes; v18 ships four presets:
+ * Aura, Lara, Nora, Material. The mapping below picks the closest visual match — for
+ * the long tail of v17 themes that have no clear analogue (mira, nova, saga, vela,
+ * soho, fluent, viva, rhea, tailwind, bootstrap4, arya, luna, …) we fall back to Aura
+ * since it's the default v18 preset.
+ */
+function mapThemeToPreset(themeName: string): Preset {
+    const lower = themeName.toLowerCase();
+    if (lower.startsWith('lara-')) return 'Lara';
+    if (lower.startsWith('md-') || lower.startsWith('mdc-')) return 'Material';
+    if (lower.startsWith('nora') || lower === 'nano') return 'Nora';
+    return 'Aura';
+}
+
+/**
+ * Map a v17 theme name to a v18 `darkModeSelector` policy. v17 themes were single-mode (the
+ * theme file itself was light or dark); v18 presets are mode-agnostic and the app opts in to
+ * dark mode via `darkModeSelector` (defaults to `'system'`, i.e. follow OS preference).
+ *
+ * To preserve the v17 author's intent we default to `'disabled'` (= `false`, keep the app
+ * light-only) for everything that wasn't explicitly authored against a dark theme. Most v17
+ * themes (mira, nova, saga, vela, soho, fluent, viva, rhea, tailwind, bootstrap4, lara-light,
+ * md-light, mdc-light, …) were visually light, and the surrounding app CSS was tested only
+ * against that — letting v18 silently flip to OS-dark usually breaks layouts and contrast.
+ *
+ * Only `*-dark-*` v17 themes (e.g. `lara-dark-blue`, `md-dark-indigo`, `bootstrap4-dark-…`)
+ * map to `'system'`: those apps already worked in dark, and `'system'` is the closest v18
+ * analogue to "this app was dark" since v18 has no permanent-dark flag.
+ */
+function mapThemeToDarkMode(themeName: string): DarkMode {
+    const lower = themeName.toLowerCase();
+    if (lower.includes('-dark-') || lower.endsWith('-dark')) return 'system';
+    return 'disabled';
+}
+
+/**
+ * Internal sub-recipe that strips any `primeng/resources` entry from the `styles`
+ * array in `angular.json`. Folded into `AddPrimengProvider`'s recipeList: now that
+ * the parent recipe wires in the v18 replacement (`providePrimeNG({ theme: { preset } })`),
+ * the v17 paths can be deleted cleanly — no TODO comments, no manual-migration row.
+ */
+class RemovePrimengResourcesFromAngularJson extends Recipe {
+    readonly name = "org.openrewrite.primeng.AddPrimengProvider.remove-primeng-resources";
+    readonly displayName = "Remove `primeng/resources` style references from `angular.json`";
+    readonly description = "Filters every `styles[]` entry containing `primeng/resources` out of " +
+        "`angular.json`. Safe to delete because `AddPrimengProvider` adds the v18 equivalent " +
+        "(`providePrimeNG({ theme: { preset } })`) alongside this step.";
+
+    async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
+        return new class extends JsonVisitor<ExecutionContext> {
+            protected async visitDocument(doc: Json.Document, p: ExecutionContext): Promise<Json | undefined> {
+                if (!doc.sourcePath.endsWith('angular.json')) return doc;
+                return super.visitDocument(doc, p);
+            }
+
+            protected async visitMember(member: Json.Member, p: ExecutionContext): Promise<Json | undefined> {
+                const m = await super.visitMember(member, p) as Json.Member;
+                if (!m) return m;
+
+                if (getMemberKeyName(m) !== 'styles') return m;
+                if (!isArray(m.value)) return m;
+
+                const arr = m.value as Json.Array;
+                const filtered = arr.values.filter(rp => {
+                    const elem = rp.element;
+                    if (!isLiteral(elem)) return true;
+                    const val = elem.value as string;
+                    return !val?.includes('primeng/resources');
+                });
+
+                if (filtered.length === arr.values.length) return m;
+
+                // Preserve the leading whitespace of the original first element on whichever
+                // value is now first, so the array keeps its formatting.
+                const newValues = [...filtered];
+                if (newValues.length > 0 && arr.values.length > 0) {
+                    const originalFirstPrefix = arr.values[0].element.prefix;
+                    const newFirst = newValues[0];
+                    if (newFirst.element.prefix !== originalFirstPrefix) {
+                        newValues[0] = {
+                            ...newFirst,
+                            element: {...newFirst.element, prefix: originalFirstPrefix},
+                        };
+                    }
+                }
+
+                return {
+                    ...m,
+                    value: {
+                        ...arr,
+                        values: newValues,
+                    } as Json.Array,
+                } as Json.Member;
+            }
+        }();
+    }
+}
+
+/**
+ * v18 ships with no default styling — the old SASS theme tree under `primeng/resources` is
+ * gone. Instead, you opt in to a design-token preset via `providePrimeNG({ theme: { preset } })`
+ * in your application providers.
+ *
+ * Scanner phase: looks at `angular.json`'s `styles` array for any `primeng/resources/themes/<X>`
+ * reference and maps `<X>` to the closest v18 preset (Aura, Lara, Nora, or Material).
+ *
+ * Editor phase: in the root `@NgModule` (the one with a `bootstrap:` field), appends
+ * `providePrimeNG({ theme: { preset: <Preset> } })` to its `providers` array and adds
+ *   `import { providePrimeNG } from 'primeng/config';`
+ *   `import <Preset> from '@primeng/themes/<preset>';`
+ *
+ * Sub-recipe: a follow-up `RemovePrimengResourcesFromAngularJson` deletes the v17 theme
+ * paths from `angular.json` since the new provider supersedes them. The two changes go
+ * together — adding the provider without removing the broken paths, or vice versa, leaves
+ * the project unbuildable.
+ */
+export class AddPrimengProvider extends ScanningRecipe<AddPrimengProviderAcc> {
+    readonly name = "org.openrewrite.primeng.AddPrimengProvider";
+    readonly displayName = "Add `providePrimeNG` with a detected theme preset to the root NgModule";
+    readonly description = "Wires the v18 styled mode into an NgModule-based app by adding " +
+        "`providePrimeNG({ theme: { preset: <Preset> } })` to the root `@NgModule`'s providers array " +
+        "(detected by the presence of a `bootstrap:` field). The preset is chosen by scanning " +
+        "`angular.json` for a `primeng/resources/themes/<themeName>/theme.css` entry: `lara-*` maps " +
+        "to Lara, `md-*`/`mdc-*` to Material, `nora`/`nano` to Nora, and any other v17 theme " +
+        "(mira, nova, saga, vela, soho, fluent, viva, rhea, tailwind, bootstrap4, arya, luna, ...) " +
+        "falls back to Aura. The matching imports for `providePrimeNG` and the chosen preset are " +
+        "added automatically. Also deletes the now-defunct `primeng/resources` style entries from " +
+        "`angular.json` so the build doesn't try to load missing files. Idempotent: skips files that " +
+        "already call `providePrimeNG`.";
+
+    initialValue(_ctx: ExecutionContext): AddPrimengProviderAcc {
+        return {preset: 'Aura', darkMode: 'unset', detectedFromAngularJson: false};
+    }
+
+    async scanner(acc: AddPrimengProviderAcc): Promise<TreeVisitor<any, ExecutionContext>> {
+        return new class extends JsonVisitor<ExecutionContext> {
+            protected async visitDocument(doc: Json.Document, p: ExecutionContext): Promise<Json | undefined> {
+                if (!doc.sourcePath.endsWith('angular.json')) return doc;
+                return super.visitDocument(doc, p);
+            }
+
+            protected async visitLiteral(literal: Json.Literal, p: ExecutionContext): Promise<Json | undefined> {
+                const l = await super.visitLiteral(literal, p) as Json.Literal;
+                if (!l || typeof l.value !== 'string') return l;
+
+                // Match e.g. `node_modules/primeng/resources/themes/mira/theme.css`
+                const match = (l.value as string).match(/primeng\/resources\/themes\/([^/]+)\/theme\.css/);
+                if (!match) return l;
+
+                acc.preset = mapThemeToPreset(match[1]);
+                acc.darkMode = mapThemeToDarkMode(match[1]);
+                acc.detectedFromAngularJson = true;
+                return l;
+            }
+        }();
+    }
+
+    async editorWithData(acc: AddPrimengProviderAcc): Promise<TreeVisitor<any, ExecutionContext>> {
+        const preset = acc.preset;
+        const presetModule = preset.toLowerCase();
+
+        // Build the `theme: {...}` body. v18's `darkModeSelector` defaults to 'system' (follow
+        // OS preference). For `*-light-*` v17 themes we emit `darkModeSelector: false` to keep
+        // the app light-only (preserves v17 author's intent). For `*-dark-*` we leave the
+        // default since v18 has no permanent-dark mode and 'system' is the closest analogue.
+        const themeBody = acc.darkMode === 'disabled'
+            ? `{ preset: ${preset}, options: { darkModeSelector: false } }`
+            : `{ preset: ${preset} }`;
+
+        return new class extends JavaScriptVisitor<ExecutionContext> {
+            // Wires the imports + appends `providePrimeNG({...})` to a `providers: [...]`
+            // array inside an object literal (J.NewClass body of PropertyAssignments).
+            // Returns the updated NewClass, or `undefined` to skip (no providers array
+            // or providePrimeNG already present).
+            private async addToObjectLiteral(newClass: J.NewClass): Promise<J.NewClass | undefined> {
+                if (!newClass.body) return undefined;
+
+                let providersIndex = -1;
+                for (let i = 0; i < newClass.body.statements.length; i++) {
+                    const stmt = newClass.body.statements[i].element;
+                    if (stmt.kind !== JS.Kind.PropertyAssignment) continue;
+                    const prop = stmt as JS.PropertyAssignment;
+                    const nameExpr = prop.name.element;
+                    if (!isIdentifier(nameExpr)) continue;
+                    if (nameExpr.simpleName === 'providers') {
+                        providersIndex = i;
+                        break;
+                    }
+                }
+                if (providersIndex === -1) return undefined;
+
+                const provStmt = newClass.body.statements[providersIndex].element as any;
+                const arr = provStmt.initializer;
+                const container = arr?.initializer;
+                const existingElements = container?.elements ?? [];
+                for (const el of existingElements) {
+                    const expr = el.element;
+                    if (expr?.kind === J.Kind.MethodInvocation
+                        && isIdentifier(expr.name)
+                        && (expr.name as J.Identifier).simpleName === 'providePrimeNG') {
+                        return undefined;
+                    }
+                }
+
+                const provideCall = await Template.builder()
+                    .code(`providePrimeNG({ theme: ${themeBody} })`)
+                    .build()
+                    .apply(newClass, this.cursor) as any;
+
+                const newProviderRP = {
+                    kind: J.Kind.RightPadded,
+                    element: {...provideCall, prefix: existingElements.length > 0 ? singleSpace : emptySpace},
+                    after: emptySpace,
+                    markers: {kind: 'org.openrewrite.marker.Markers', id: newClass.id, markers: []},
+                };
+
+                const updatedProvStmt = {
+                    ...provStmt,
+                    initializer: {
+                        ...arr,
+                        initializer: {
+                            ...container,
+                            elements: [...existingElements, newProviderRP],
+                        },
+                    },
+                };
+
+                const newStatements = [...newClass.body.statements];
+                newStatements[providersIndex] = {
+                    ...newStatements[providersIndex],
+                    element: updatedProvStmt,
+                };
+
+                maybeAddImport(this, {
+                    module: 'primeng/config',
+                    member: 'providePrimeNG',
+                    onlyIfReferenced: false,
+                });
+                maybeAddImport(this, {
+                    module: `@primeng/themes/${presetModule}`,
+                    member: 'default',
+                    alias: preset,
+                    onlyIfReferenced: false,
+                });
+
+                return {...newClass, body: {...newClass.body, statements: newStatements}};
+            }
+
+            override async visitAnnotation(annotation: J.Annotation, p: ExecutionContext): Promise<J | undefined> {
+                let a = await super.visitAnnotation(annotation, p) as J.Annotation;
+                if (!a) return a;
+
+                const annotType = a.annotationType;
+                if (!isIdentifier(annotType)) return a;
+                if (annotType.simpleName !== 'NgModule') return a;
+
+                if (!a.arguments?.elements?.length) return a;
+                const firstArg = a.arguments.elements[0].element;
+                if (firstArg.kind !== J.Kind.NewClass) return a;
+
+                const newClass = firstArg as J.NewClass;
+                // Only target the root NgModule (the one with bootstrap:).
+                const hasBootstrap = newClass.body?.statements.some(s => {
+                    const stmt = s.element;
+                    if (stmt.kind !== JS.Kind.PropertyAssignment) return false;
+                    const nameExpr = (stmt as JS.PropertyAssignment).name.element;
+                    return isIdentifier(nameExpr) && (nameExpr as J.Identifier).simpleName === 'bootstrap';
+                });
+                if (!hasBootstrap) return a;
+
+                const updated = await this.addToObjectLiteral(newClass);
+                if (!updated) return a;
+
+                return {
+                    ...a,
+                    arguments: {
+                        ...a.arguments!,
+                        elements: [{
+                            ...a.arguments!.elements[0],
+                            element: updated,
+                        }],
+                    },
+                } as J.Annotation;
+            }
+
+            // Standalone apps: `export const appConfig: ApplicationConfig = { providers: [...] }`.
+            // Detected by the type annotation on the variable declaration; the variable name
+            // is irrelevant. The `: ApplicationConfig` annotation parses as JS.TypeInfo wrapping
+            // the actual identifier, so unwrap one level before checking the simple name.
+            override async visitVariableDeclarations(varDecls: J.VariableDeclarations, p: ExecutionContext): Promise<J | undefined> {
+                const v = await super.visitVariableDeclarations(varDecls, p) as J.VariableDeclarations;
+                if (!v) return v;
+
+                let typeExpr: any = v.typeExpression;
+                if (typeExpr?.kind === JS.Kind.TypeInfo) typeExpr = (typeExpr as JS.TypeInfo).typeIdentifier;
+                if (!typeExpr || !isIdentifier(typeExpr)) return v;
+                if ((typeExpr as J.Identifier).simpleName !== 'ApplicationConfig') return v;
+                if (!v.variables.length) return v;
+
+                const variableRP = v.variables[0];
+                const namedVar = variableRP.element as J.VariableDeclarations.NamedVariable;
+                const initializer = namedVar.initializer?.element;
+                if (!initializer || initializer.kind !== J.Kind.NewClass) return v;
+
+                const updated = await this.addToObjectLiteral(initializer as J.NewClass);
+                if (!updated) return v;
+
+                return {
+                    ...v,
+                    variables: [{
+                        ...variableRP,
+                        element: {
+                            ...namedVar,
+                            initializer: {
+                                ...namedVar.initializer!,
+                                element: updated,
+                            },
+                        },
+                    }, ...v.variables.slice(1)],
+                } as J.VariableDeclarations;
+            }
+        };
+    }
+
+    async recipeList(): Promise<Recipe[]> {
+        return [new RemovePrimengResourcesFromAngularJson()];
+    }
+}

package/src/libraries/primeng/18/index.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+export {UpgradeToPrimeNG18} from './upgrade-to-primeng-18';
+export {UpgradeComponentsTo18} from './upgrade-components-to-18';
+export {MigratePrimeNgConfigToPrimeNG} from './migrate-primeng-config';
+export {MigratePrimeNGSignalAssignments} from './migrate-primeng-signal-assignments';
+export {MigrateMessagesToMessageLoop} from './migrate-messages-to-message-loop';
+export {RenameCalendarToDatePicker} from './rename-calendar-to-datepicker';
+export {RenameDropdownToSelect} from './rename-dropdown-to-select';
+export {RenameInputSwitchToToggleSwitch} from './rename-inputswitch-to-toggleswitch';
+export {RenameOverlayPanelToPopover} from './rename-overlaypanel-to-popover';
+export {RenameSidebarToDrawer} from './rename-sidebar-to-drawer';
+export {RenameMessageInterface} from './rename-message-interface';
+export {RenameTemplateSelectors} from './rename-template-selectors';
+export {MarkRemovedPrimengModules} from './mark-removed-primeng-modules';
+export {MarkDeprecatedPrimengComponents} from './mark-deprecated-components';
+export {MarkDeprecatedPrimengCssClasses} from './mark-deprecated-css-classes';
+export {MarkDrawerSize} from './mark-drawer-size';
+export {AddPrimengProvider} from './add-primeng-provider';
+export {ManualMigrationStep} from './manual-migration-steps';

package/src/libraries/primeng/18/manual-migration-steps.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {Column} from "@openrewrite/rewrite";
+
+/**
+ * Row schema shared by every PrimeNG 18 recipe that leaves a manual-migration step (TODO
+ * comment, structural rewrite that needs review, removed-but-unmigratable reference).
+ *
+ * Each recipe instantiates its own `new DataTable<ManualMigrationStep>(MANUAL_MIGRATION_STEPS_NAME, …)`
+ * — the framework groups rows by table name when writing CSVs, so multiple recipes
+ * naturally end up in the same `org.openrewrite.primeng.ManualMigrationSteps.csv`.
+ */
+export class ManualMigrationStep {
+    @Column({displayName: "Source path", description: "Path of the file containing the migration site."})
+    sourcePath!: string;
+
+    @Column({displayName: "Recipe", description: "Recipe that flagged this step."})
+    recipe!: string;
+
+    @Column({displayName: "Subject", description: "Identifier or selector that needs migration (e.g. `ChipsModule`, `<p-chips>`)."})
+    subject!: string;
+
+    @Column({displayName: "Reason", description: "Why this needs manual migration (component removed, structural change, etc.)."})
+    reason!: string;
+
+    @Column({displayName: "Action", description: "Concrete instruction for the agent or developer to follow."})
+    action!: string;
+}
+
+export const MANUAL_MIGRATION_STEPS_NAME = "org.openrewrite.primeng.ManualMigrationSteps";
+export const MANUAL_MIGRATION_STEPS_DISPLAY_NAME = "PrimeNG 18 manual migration steps";
+export const MANUAL_MIGRATION_STEPS_DESCRIPTION =
+    "Migration steps the automated PrimeNG 18 recipes could not complete and that need a human or AI agent to finish.";

package/src/libraries/primeng/18/mark-deprecated-components.ts

@@ -0,0 +1,128 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {DataTable, ExecutionContext, Recipe, TreeVisitor} from "@openrewrite/rewrite";
+import {JavaScriptVisitor, JS} from "@openrewrite/rewrite/javascript";
+import {J, isIdentifier} from "@openrewrite/rewrite/java";
+import {
+    ManualMigrationStep,
+    MANUAL_MIGRATION_STEPS_DESCRIPTION,
+    MANUAL_MIGRATION_STEPS_DISPLAY_NAME,
+    MANUAL_MIGRATION_STEPS_NAME,
+} from "./manual-migration-steps";
+
+interface DeprecatedModule {
+    members: string[];
+    todo: string;
+}
+
+// Modules that still exist in PrimeNG 18 but are deprecated. Their replacement components
+// have different APIs / template structures and cannot be migrated automatically, so we
+// only mark them: leading TODO comment on the import + a row in `ManualMigrationSteps`.
+// (Chips, TriStateCheckbox, Messages, DataViewLayoutOptions, pAnimate are *removed*, not
+// deprecated — they're handled by `MarkRemovedPrimengModules`.)
+const DEPRECATED_MODULES: Record<string, DeprecatedModule> = {
+    'primeng/tabmenu': {
+        members: ['TabMenu', 'TabMenuModule'],
+        todo: "`TabMenu` is deprecated in PrimeNG 18. Use `Tabs` without panels (import from `primeng/tabs`).",
+    },
+    'primeng/steps': {
+        members: ['Steps', 'StepsModule'],
+        todo: "`Steps` is deprecated in PrimeNG 18. Use `Stepper` without panels (import from `primeng/stepper`).",
+    },
+    'primeng/inlinemessage': {
+        members: ['InlineMessage', 'InlineMessageModule'],
+        todo: "`InlineMessage` is deprecated in PrimeNG 18. Use the `Message` component (import from `primeng/message`).",
+    },
+    'primeng/tabview': {
+        members: ['TabView', 'TabViewModule', 'TabPanel'],
+        todo: "`TabView`/`TabPanel` are deprecated in PrimeNG 18. Use the new `Tabs`+`TabList`+`Tab`+`TabPanels`+`TabPanel` set (import from `primeng/tabs`).",
+    },
+    'primeng/defer': {
+        members: ['DeferModule'],
+        todo: "`pDefer` is deprecated in PrimeNG 18. Use Angular's `@defer` control flow instead.",
+    },
+};
+
+export class MarkDeprecatedPrimengComponents extends Recipe {
+    readonly name = "org.openrewrite.primeng.MarkDeprecatedPrimengComponents";
+    readonly displayName = "Mark deprecated PrimeNG components with TODO comments";
+    readonly description = "For every TS file that imports a component / module deprecated in PrimeNG 18 " +
+        "(`TabMenu`, `Steps`, `InlineMessage`, `TabView`, `pDefer`), prepends a TODO comment to the import " +
+        "describing the recommended v18 replacement and writes a row to the `ManualMigrationSteps` data " +
+        "table. The import itself is left intact — these modules still exist in v18 but their replacements " +
+        "have different APIs that require manual migration.";
+
+    private dataTable = new DataTable<ManualMigrationStep>(
+        MANUAL_MIGRATION_STEPS_NAME,
+        MANUAL_MIGRATION_STEPS_DISPLAY_NAME,
+        MANUAL_MIGRATION_STEPS_DESCRIPTION,
+        ManualMigrationStep,
+    );
+
+    async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
+        const recipeName = this.name;
+        const dataTable = this.dataTable;
+        return new class extends JavaScriptVisitor<ExecutionContext> {
+            protected async visitImportDeclaration(jsImport: JS.Import, p: ExecutionContext): Promise<J | undefined> {
+                const imp = await super.visitImportDeclaration(jsImport, p) as JS.Import;
+                if (!imp?.moduleSpecifier) return imp;
+
+                const moduleSpec = imp.moduleSpecifier.element;
+                if (moduleSpec.kind !== J.Kind.Literal) return imp;
+                const moduleName = (moduleSpec as J.Literal).value as string;
+                const deprecation = DEPRECATED_MODULES[moduleName];
+                if (!deprecation) return imp;
+
+                // Idempotence: skip if our TODO marker is already attached.
+                const existingComments = imp.prefix?.comments ?? [];
+                if (existingComments.some(c => (c as any).text?.includes('TODO: PrimeNG 18'))) {
+                    return imp;
+                }
+
+                const importedNames: string[] = [];
+                const namedBindings = imp.importClause?.namedBindings;
+                if (namedBindings?.kind === JS.Kind.NamedImports) {
+                    for (const specifier of (namedBindings as JS.NamedImports).elements.elements) {
+                        const spec = specifier.element as JS.ImportSpecifier;
+                        if (isIdentifier(spec.specifier)) {
+                            importedNames.push((spec.specifier as J.Identifier).simpleName);
+                        }
+                    }
+                }
+                if (importedNames.length === 0) return imp;
+
+                const sourcePath = (this.cursor.firstEnclosing<any>((o: any): o is any => !!o?.sourcePath)?.sourcePath) ?? '';
+                for (const name of importedNames) {
+                    dataTable.insertRow(p, {
+                        sourcePath,
+                        recipe: recipeName,
+                        subject: `${name} (${moduleName})`,
+                        reason: "Component deprecated in PrimeNG 18; replacement has a different API.",
+                        action: deprecation.todo,
+                    });
+                }
+
+                const todoComment = {
+                    kind: J.Kind.TextComment,
+                    multiline: true,
+                    text: ` TODO: PrimeNG 18 — ${deprecation.todo} (import: \`{ ${importedNames.join(', ')} } from '${moduleName}'\`) `,
+                    suffix: '\n',
+                    markers: {kind: 'org.openrewrite.marker.Markers', id: imp.id, markers: []},
+                };
+
+                const originalPrefix = imp.prefix ?? {kind: J.Kind.Space, whitespace: '', comments: []};
+                return {
+                    ...imp,
+                    prefix: {
+                        ...originalPrefix,
+                        comments: [...existingComments, todoComment],
+                    },
+                } as JS.Import;
+            }
+        };
+    }
+}

package/src/libraries/primeng/18/mark-deprecated-css-classes.ts

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Moderne Proprietary. Only for use by Moderne customers under the terms of a commercial contract.
+ */
+
+import {DataTable, ExecutionContext, Recipe, TreeVisitor} from "@openrewrite/rewrite";
+import {PlainText, PlainTextVisitor} from "@openrewrite/rewrite/text";
+import {
+    ManualMigrationStep,
+    MANUAL_MIGRATION_STEPS_DESCRIPTION,
+    MANUAL_MIGRATION_STEPS_DISPLAY_NAME,
+    MANUAL_MIGRATION_STEPS_NAME,
+} from "./manual-migration-steps";
+
+interface DeprecatedClass {
+    className: string;
+    todo: string;
+}
+
+const DEPRECATED_CLASSES: DeprecatedClass[] = [
+    {
+        className: 'p-link',
+        todo: "`.p-link` CSS class is removed in PrimeNG 18. Replace `<a class=\"p-link\">` with a `<p-button [link]=\"true\">` (or a `pButton` with `[link]=\"true\"`).",
+    },
+    {
+        className: 'p-highlight',
+        todo: "`.p-highlight` CSS class is removed in PrimeNG 18. Each component now has its own class — replace with the component-specific selector (e.g. `.p-select-option-selected`, `.p-datatable-row-selected`, `.p-tree-node-selected`).",
+    },
+    // Note: `.p-fluid` is auto-migrated by `MigratePFluidToWrapper` (rewrites `<div class="…p-fluid…">`
+    // to `<p-fluid class="…">` and adds the FluidModule import). It's intentionally not flagged here.
+];
+
+/**
+ * Mark every occurrence of a removed PrimeNG v17 CSS class (`p-link`, `p-highlight`,
+ * `p-fluid`) in HTML templates with an HTML TODO comment, and write a row to the
+ * `ManualMigrationSteps` data table. The class itself is left in place — replacements
+ * are component-specific and need a human/AI agent to choose the right substitute.
+ */
+export class MarkDeprecatedPrimengCssClasses extends Recipe {
+    readonly name = "org.openrewrite.primeng.MarkDeprecatedPrimengCssClasses";
+    readonly displayName = "Mark deprecated PrimeNG CSS classes with TODO comments";
+    readonly description = "For every HTML template that references a CSS class removed in PrimeNG 18 " +
+        "(`.p-link`, `.p-highlight`, `.p-fluid`), inserts a `<!-- TODO: ... -->` comment immediately before " +
+        "the offending element and writes a row to the `ManualMigrationSteps` data table. The class itself " +
+        "is left in place — the replacements are context-dependent (component-specific selectors, the new " +
+        "`fluid` input, etc.) and need a human or AI agent to apply.";
+
+    private dataTable = new DataTable<ManualMigrationStep>(
+        MANUAL_MIGRATION_STEPS_NAME,
+        MANUAL_MIGRATION_STEPS_DISPLAY_NAME,
+        MANUAL_MIGRATION_STEPS_DESCRIPTION,
+        ManualMigrationStep,
+    );
+
+    async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
+        const recipeName = this.name;
+        const dataTable = this.dataTable;
+        return new class extends PlainTextVisitor<ExecutionContext> {
+            override async visitText(text: PlainText, p: ExecutionContext): Promise<PlainText | undefined> {
+                const t = await super.visitText(text, p) as PlainText;
+                if (!t) return t;
+                if (!t.sourcePath.endsWith('.html')) return t;
+
+                let updated = t.text;
+                let modified = false;
+
+                for (const {className, todo} of DEPRECATED_CLASSES) {
+                    // Match an opening tag whose attributes contain the deprecated class name
+                    // either as a bare class token (`class="… p-link …"`) or via a binding
+                    // (`[class.p-link]="…"` / `[ngClass]="… p-link …"`). We don't try to be
+                    // perfect about parsing HTML — false positives are tolerable for a
+                    // search-style recipe; missed matches are not.
+                    const tagRe = new RegExp(`(^|\\n)([ \\t]*)(<[a-zA-Z][\\w-]*(?:\\s+[^>]*?)?\\b(?:class\\s*=\\s*"[^"]*\\b${className}\\b[^"]*"|class\\s*=\\s*'[^']*\\b${className}\\b[^']*')[^>]*>)`, 'g');
+                    const todoMarker = `<!-- TODO: PrimeNG 18 — ${todo} -->`;
+
+                    let alreadyMarked = false;
+                    updated = updated.replace(tagRe, (match, lead, indent, tag) => {
+                        // Idempotence: skip if a previous run already inserted this exact TODO above.
+                        const before = match.indexOf(tag);
+                        const precedingChunk = updated.slice(0, updated.indexOf(match) + before);
+                        if (precedingChunk.endsWith(todoMarker + '\n' + indent)
+                            || precedingChunk.endsWith(todoMarker + indent)) {
+                            alreadyMarked = true;
+                            return match;
+                        }
+                        modified = true;
+                        dataTable.insertRow(p, {
+                            sourcePath: t.sourcePath,
+                            recipe: recipeName,
+                            subject: `class .${className}`,
+                            reason: "PrimeNG 18 removed this CSS class; replacement is component-specific.",
+                            action: todo,
+                        });
+                        return `${lead}${indent}${todoMarker}\n${indent}${tag}`;
+                    });
+                    void alreadyMarked;
+                }
+
+                if (!modified) return t;
+                return {
+                    ...t,
+                    text: updated,
+                    snippets: [],
+                };
+            }
+        }();
+    }
+}