@trackunit/iris-app 2.5.11 → 2.5.13

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 2.5.13 (2026-08-20)
+
+### 🧱 Updated Dependencies
+
+- Updated iris-app-build-utilities to 2.4.13
+- Updated iris-app-api to 2.4.9
+- Updated react-vite-test-setup to 0.0.112
+- Updated css-classname-utils to 0.0.20
+- Updated react-graphql-tools to 1.15.17
+- Updated shared-utils to 1.16.20
+
+## 2.5.12 (2026-08-20)
+
+### 🧱 Updated Dependencies
+
+- Updated iris-app-build-utilities to 2.4.12
+- Updated iris-app-api to 2.4.8
+- Updated react-vite-test-setup to 0.0.111
+- Updated css-classname-utils to 0.0.19
+- Updated react-graphql-tools to 1.15.16
+- Updated shared-utils to 1.16.19
+
 ## 2.5.11 (2026-08-19)
 
 ### 🧱 Updated Dependencies

package/migrations/p-content-space-codemod/invent-content-space.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inventContentSpace = exports.ASSET_SITE_ADMIN_TYPES = void 0;
+const css_classname_utils_1 = require("@trackunit/css-classname-utils");
+const types_1 = require("@typescript-eslint/types");
+const typescript_estree_1 = require("@typescript-eslint/typescript-estree");
+const classname_ast_rewrite_1 = require("../utils/classname-ast-rewrite");
+const report_unresolved_1 = require("./report-unresolved");
+const resolve_content_shell_1 = require("./resolve-content-shell");
+const CONTENT_SPACE_TOKEN = "p-content-space";
+/**
+ * Extension types that may invent/convert content-shell padding. Fleet/Customer
+ * remain swap-only (page-content rewrite) and must never invent or convert.
+ * Shared with the orchestrator so the ASA gate lives in exactly one place.
+ */
+exports.ASSET_SITE_ADMIN_TYPES = new Set([
+    "ASSET_HOME_EXTENSION",
+    "SITE_HOME_EXTENSION",
+    "ADMIN_EXTENSION",
+]);
+const SHELL_INSET_SIDES = ["p", "px", "py", "pt", "pr", "pb", "pl"];
+const SHELL_INSET_VALUES = [
+    "1",
+    "1.5",
+    "2",
+    "2.5",
+    "3",
+    "3.5",
+    "4",
+    "5",
+    "6",
+    "7",
+    "8",
+    "9",
+    "10",
+    "11",
+    "12",
+    "14",
+    "16",
+    "20",
+    "24",
+    "28",
+    "32",
+    "36",
+    "40",
+    "44",
+    "48",
+    "52",
+    "56",
+    "60",
+    "64",
+    "72",
+    "80",
+    "96",
+    "responsive-space",
+];
+const BREAKPOINT_VARIANTS = ["sm", "md", "lg", "xl", "2xl"];
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Tailwind padding utilities treated as content-region shell inset candidates.
+ * Enumerated (not `.+`) so reset tokens (`px-0`, `pb-0.5`) and state/print
+ * variants (`hover:`, `focus:`, `print:`) are left alone. Breakpoint variants
+ * (`md:p-6`) are still converted — those are lossy and logged as such.
+ */
+const SHELL_PADDING_TOKEN = new RegExp(`^(?:(?:${BREAKPOINT_VARIANTS.join("|")}):)?(?:${SHELL_INSET_SIDES.join("|")})-(?:${SHELL_INSET_VALUES.map(escapeRegExp).join("|")})$`);
+const tokenBase = (token) => (token.includes(":") ? token.slice(token.lastIndexOf(":") + 1) : token);
+const isContentSpaceToken = (token) => tokenBase(token) === CONTENT_SPACE_TOKEN;
+const isShellPaddingToken = (token) => {
+    if (isContentSpaceToken(token)) {
+        return false;
+    }
+    return SHELL_PADDING_TOKEN.test(token);
+};
+const emptyResult = (unresolvedReason = null) => ({
+    filesChanged: [],
+    changes: [],
+    skippedRouteNames: [],
+    unresolvedReason,
+});
+/**
+ * Ensures each resolved ASA content shell carries `p-content-space`:
+ * - invents the token on a bare shell (reported as `addition`)
+ * - converts custom shell padding (`p-*` / `px-*` / `py-*` / sides /
+ *   `p-responsive-space` / `pb-responsive-space`) to `p-content-space`,
+ *   removing those custom tokens (reported as `conversion`)
+ *
+ * Uses {@link resolveContentShells}: shared layout Outlet shells yield one
+ * target; multi-route without a shared layout invents/converts each clear
+ * leaf. Only classname locations bound to each host are edited — inner layout
+ * padding is left alone. Idempotent when a shell already has `p-content-space`
+ * (including a variant-prefixed form) and no custom shell padding (including
+ * whitespace-only differences). Never invents an `overflow-*` token — existing
+ * scroll ownership is preserved. Fleet/Customer types are a no-op (swap-only
+ * surfaces).
+ *
+ * Returns empty `filesChanged` / `changes` (never throws) when shells are
+ * unresolved, the extension type is out of scope, or already in the desired state.
+ * `skippedRouteNames` names unanalysable routes on a partial graph so the
+ * orchestrator can report them instead of treating the extension as fully migrated.
+ */
+const inventContentSpace = (tree, extension) => {
+    if (!exports.ASSET_SITE_ADMIN_TYPES.has(extension.type)) {
+        return emptyResult();
+    }
+    const resolved = (0, resolve_content_shell_1.resolveContentShells)(tree, extension);
+    if (resolved.status === "unresolved") {
+        return emptyResult(resolved.reason);
+    }
+    const skippedRouteNames = [...resolved.skippedRouteNames];
+    // Single resolved shell that already carries the token (or page-content):
+    // do not invent a second inset. A token on a *nested* file is not enough —
+    // that hid Device Administration's layout shell (GLU-1903). Multi-route
+    // graphs skip this so a padded sibling leaf does not leave other leaves flush.
+    if (resolved.shells.length === 1 && (0, report_unresolved_1.findUnresolvedSurface)(tree, extension) === null) {
+        return { filesChanged: [], changes: [], skippedRouteNames, unresolvedReason: null };
+    }
+    const shellsByFile = groupShellsByFile(resolved.shells);
+    const filesChanged = [];
+    const changes = [];
+    for (const [filePath, shells] of shellsByFile) {
+        const content = tree.read(filePath, "utf-8");
+        if (content === null) {
+            continue;
+        }
+        let program;
+        try {
+            program = (0, classname_ast_rewrite_1.parseTsestreeSource)(content);
+        }
+        catch {
+            continue;
+        }
+        // Edit later ranges first so earlier offsets stay valid in one applyEdits pass.
+        const orderedShells = [...shells].sort((left, right) => right.location.reportNode.range[0] - left.location.reportNode.range[0]);
+        const fileEdits = [];
+        const fileChanges = [];
+        for (const shell of orderedShells) {
+            const hostLocations = collectHostClassnameLocations(program, shell.location);
+            const combinedBefore = hostLocations.map(hostLocation => hostLocation.value).join(" ");
+            const combinedPlan = planContentSpaceOnShell(combinedBefore);
+            if (!combinedPlan.changed) {
+                continue;
+            }
+            const alreadyHasContentSpace = (0, css_classname_utils_1.splitClasses)(combinedBefore).some(isContentSpaceToken);
+            const primaryRange = shell.location.fixNode.range;
+            const orderedLocations = [...hostLocations].sort((left, right) => {
+                const leftIsPrimary = rangesEqual(left.fixNode.range, primaryRange);
+                const rightIsPrimary = rangesEqual(right.fixNode.range, primaryRange);
+                if (leftIsPrimary === rightIsPrimary) {
+                    return left.fixNode.range[0] - right.fixNode.range[0];
+                }
+                return leftIsPrimary ? -1 : 1;
+            });
+            let addedToken = alreadyHasContentSpace;
+            const shellEdits = [];
+            for (const hostLocation of orderedLocations) {
+                const locationEdits = (0, classname_ast_rewrite_1.buildEditsForLocation)(hostLocation, value => {
+                    const next = transformClassnamePreservingWhitespace(value, { addContentSpace: !addedToken });
+                    if (!addedToken && (0, css_classname_utils_1.splitClasses)(next).some(isContentSpaceToken)) {
+                        addedToken = true;
+                    }
+                    return next;
+                }, content);
+                shellEdits.push(...locationEdits);
+            }
+            if (shellEdits.length === 0) {
+                continue;
+            }
+            fileEdits.push(...shellEdits);
+            fileChanges.push({
+                extensionId: extension.id,
+                sourceRoot: extension.sourceRoot,
+                filePath,
+                kind: combinedPlan.removedTokens.length > 0 ? "conversion" : "addition",
+                before: shell.classnameValue,
+                after: planContentSpaceOnShell(shell.location.value).next,
+                removedTokens: combinedPlan.removedTokens,
+            });
+        }
+        if (fileEdits.length === 0) {
+            continue;
+        }
+        tree.write(filePath, (0, classname_ast_rewrite_1.applyEdits)(content, fileEdits));
+        filesChanged.push(filePath);
+        changes.push(...fileChanges.reverse());
+    }
+    if (filesChanged.length === 0) {
+        return { filesChanged: [], changes: [], skippedRouteNames, unresolvedReason: null };
+    }
+    return { filesChanged, changes, skippedRouteNames, unresolvedReason: null };
+};
+exports.inventContentSpace = inventContentSpace;
+const groupShellsByFile = (shells) => {
+    const byFile = new Map();
+    for (const shell of shells) {
+        const existing = byFile.get(shell.filePath);
+        if (existing === undefined) {
+            byFile.set(shell.filePath, [shell]);
+        }
+        else {
+            existing.push(shell);
+        }
+    }
+    return byFile;
+};
+/**
+ * Strips custom shell-inset padding tokens and ensures `p-content-space` is
+ * present, preserving the relative order of non-padding tokens.
+ *
+ * `changed` is true only when custom padding was stripped or `p-content-space`
+ * was missing — not when the only difference would be whitespace normalization.
+ */
+const planContentSpaceOnShell = (classnameValue) => {
+    const classes = (0, css_classname_utils_1.splitClasses)(classnameValue);
+    const removedTokens = classes.filter(isShellPaddingToken);
+    const withoutCustomPadding = classes.filter(token => !isShellPaddingToken(token));
+    const hadContentSpace = withoutCustomPadding.some(isContentSpaceToken);
+    const nextClasses = hadContentSpace ? withoutCustomPadding : [...withoutCustomPadding, CONTENT_SPACE_TOKEN];
+    return {
+        next: nextClasses.join(" "),
+        changed: removedTokens.length > 0 || !hadContentSpace,
+        removedTokens,
+    };
+};
+const transformClassnamePreservingWhitespace = (value, options) => {
+    const trimmedStart = value.length - value.trimStart().length;
+    const trimmedEnd = value.length - value.trimEnd().length;
+    const leading = value.slice(0, trimmedStart);
+    const trailing = trimmedStart === value.length ? "" : value.slice(value.length - trimmedEnd);
+    const classes = (0, css_classname_utils_1.splitClasses)(value);
+    const kept = classes.filter(token => !isShellPaddingToken(token));
+    const hasToken = kept.some(isContentSpaceToken);
+    const nextClasses = options.addContentSpace && !hasToken ? [...kept, CONTENT_SPACE_TOKEN] : kept;
+    const core = nextClasses.join(" ");
+    if (core === "") {
+        return `${leading}${trailing}`;
+    }
+    return `${leading}${core}${trailing}`;
+};
+const rangesEqual = (left, right) => left[0] === right[0] && left[1] === right[1];
+/**
+ * All editable classname args bound to the same host as `primary` (every
+ * string argument of a `cn()` / `cva()` call). Plain JSX literals stay a
+ * single location. CVA variant objects are excluded so variant padding is
+ * not stripped as if it were shell inset.
+ */
+const collectHostClassnameLocations = (program, primary) => {
+    if (primary.context.type !== "function-call" && primary.context.type !== "array-element") {
+        return [primary];
+    }
+    const callRange = findSmallestEnclosingCallRange(program, primary.reportNode);
+    if (callRange === null) {
+        return [primary];
+    }
+    const siblings = (0, classname_ast_rewrite_1.findClassnameLocations)(program).filter(location => {
+        if (location.reportNode.range[0] < callRange[0] || location.reportNode.range[1] > callRange[1]) {
+            return false;
+        }
+        return location.context.type === "function-call" || location.context.type === "array-element";
+    });
+    return siblings.length > 0 ? siblings : [primary];
+};
+const findSmallestEnclosingCallRange = (program, inner) => {
+    let best = null;
+    (0, typescript_estree_1.simpleTraverse)(program, {
+        enter: node => {
+            if (node.type !== types_1.AST_NODE_TYPES.CallExpression)
+                return;
+            if (inner.range[0] < node.range[0] || inner.range[1] > node.range[1])
+                return;
+            if (best === null || node.range[1] - node.range[0] < best[1] - best[0]) {
+                best = node.range;
+            }
+        },
+    });
+    return best;
+};
+//# sourceMappingURL=invent-content-space.js.map

package/migrations/p-content-space-codemod/orchestrator.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pContentSpaceCodemod = pContentSpaceCodemod;
+const devkit_1 = require("@nx/devkit");
+const resolve_extension_types_1 = require("../utils/resolve-extension-types");
+const invent_content_space_1 = require("./invent-content-space");
+const remove_redundant_padding_1 = require("./remove-redundant-padding");
+const report_run_messaging_1 = require("./report-run-messaging");
+const report_unresolved_1 = require("./report-unresolved");
+const rewrite_page_content_1 = require("./rewrite-page-content");
+const MIGRATION_NAME = "p-content-space-codemod";
+/**
+ * Extension types that get the swap-only `page-content` -> `overflow-auto
+ * p-content-space` rewrite (GLU-1732). Unlike `ASSET_SITE_ADMIN_TYPES`, these
+ * are always expected to already have a `page-content` region, so redundant-
+ * padding removal, invent/convert, and unresolved-surface reporting don't apply
+ * to this group — Fleet/Customer Home never received platform inset.
+ */
+const FLEET_CUSTOMER_HOME_TYPES = new Set(["FLEET_EXTENSION", "CUSTOMER_HOME_EXTENSION"]);
+/**
+ * Composes the extension-type resolver with the page-content rewrite,
+ * redundant-padding removal, content-shell invent/convert, change reporting,
+ * and unresolved-surface report for every resolved Asset Home/Site Home/Admin
+ * extension in the workspace, and the swap-only page-content rewrite for every
+ * resolved Fleet/Customer Home extension. Every other extension type is left
+ * untouched.
+ *
+ * Ordering for Asset Home/Site Home/Admin:
+ * 1. `rewritePageContent` — so a just-migrated region already carries
+ *    `p-content-space` before invent and padding cleanup look for it.
+ * 2. `inventContentSpace` — invents or converts `p-content-space` on a
+ *    high-confidence content shell (ASA only); change reports distinguish
+ *    addition vs conversion.
+ * 3. `removeRedundantPadding` — only strips `pb-*` from classname strings
+ *    that carry `p-content-space`, including tokens invent just added, so
+ *    unresolved extensions (no padded region) and local component spacing
+ *    are left alone by construction.
+ * 4. `findUnresolvedSurface` — against post-rewrite/invent Tree state;
+ *    invented/converted surfaces must not be reported as unresolved.
+ *
+ * Formatting is intentionally the caller's job: `@trackunit/migrations`'
+ * `run-migrations` generator already awaits `formatFiles(tree)` after every
+ * migration. Invoking this orchestrator directly (e.g. against an `FsTree`
+ * for an in-repo corpus run) must also call `formatFiles` before flushing,
+ * otherwise Prettier/Tailwind class order will leave migrated files failing
+ * the format gate.
+ */
+function pContentSpaceCodemod(tree) {
+    const { resolved, unresolved } = (0, resolve_extension_types_1.resolveExtensionTypes)(tree);
+    const filesChanged = new Set();
+    const changes = [];
+    const reports = [];
+    let asaWorkOccurred = false;
+    for (const extension of resolved) {
+        if (invent_content_space_1.ASSET_SITE_ADMIN_TYPES.has(extension.type)) {
+            asaWorkOccurred = true;
+            addAll(filesChanged, (0, rewrite_page_content_1.rewritePageContent)(tree, extension).filesChanged);
+            const inventResult = (0, invent_content_space_1.inventContentSpace)(tree, extension);
+            addAll(filesChanged, inventResult.filesChanged);
+            changes.push(...inventResult.changes);
+            // Runs after invent so a just-invented shell also loses redundant `pb-*`.
+            // Removal is keyed on `p-content-space` being present in the same
+            // classname string, so unresolved surfaces are a no-op.
+            addAll(filesChanged, (0, remove_redundant_padding_1.removeRedundantPadding)(tree, extension).filesChanged);
+            const entryComponentPath = `${extension.sourceRoot}/${extension.main ?? "index.tsx"}`;
+            for (const skippedRouteName of inventResult.skippedRouteNames) {
+                reports.push({
+                    extensionId: extension.id,
+                    sourceRoot: extension.sourceRoot,
+                    entryComponentPath: tree.exists(entryComponentPath) ? entryComponentPath : null,
+                    docsLink: report_unresolved_1.PADDING_DOCS_LINK,
+                    skippedRouteName,
+                    skipReason: {
+                        code: "router-no-analysable-leaves",
+                        message: `route "${skippedRouteName}" could not be analysed into an inventable overflow content shell`,
+                    },
+                });
+            }
+            const report = (0, report_unresolved_1.findUnresolvedSurface)(tree, extension);
+            if (report !== null) {
+                reports.push({
+                    ...report,
+                    skipReason: inventResult.unresolvedReason ?? report.skipReason,
+                });
+            }
+            continue;
+        }
+        if (FLEET_CUSTOMER_HOME_TYPES.has(extension.type)) {
+            addAll(filesChanged, (0, rewrite_page_content_1.rewritePageContent)(tree, extension).filesChanged);
+            continue;
+        }
+    }
+    const lossyConversionCount = changes.filter(isLossyConversion).length;
+    logSummary(filesChanged.size, reports.length + lossyConversionCount);
+    for (const change of changes) {
+        const message = formatChangeReport(change);
+        if (isLossyConversion(change)) {
+            devkit_1.logger.warn(message);
+        }
+        else {
+            devkit_1.logger.info(message);
+        }
+    }
+    for (const report of reports) {
+        devkit_1.logger.warn((0, report_run_messaging_1.formatUnresolvedReport)(report));
+    }
+    for (const message of (0, report_run_messaging_1.collectAsaEndOfRunMessages)({ asaWorkOccurred, changes, unresolvedReports: reports })) {
+        devkit_1.logger.info(message);
+    }
+    for (const item of unresolved) {
+        devkit_1.logger.warn(`  ${MIGRATION_NAME}: could not resolve extension import "${item.specifier}" referenced by app "${item.app}"`);
+    }
+}
+function addAll(target, items) {
+    for (const item of items)
+        target.add(item);
+}
+const isLossyConversion = (change) => change.kind === "conversion" && change.removedTokens.some(token => token.includes(":") || /-(?:0|0\.5)$/.test(token));
+/** Mirrors the log style of `logSummary` in `libs/react/components/migrations/utils/jsx-utils.ts`. */
+function logSummary(touched, manualReviewNeeded) {
+    if (touched === 0) {
+        devkit_1.logger.info(`  ${MIGRATION_NAME}: no files changed`);
+        return;
+    }
+    const reviewSuffix = manualReviewNeeded > 0 ? ` (${manualReviewNeeded} location(s) need manual review)` : "";
+    devkit_1.logger.info(`  ${MIGRATION_NAME}: updated ${touched} file(s)${reviewSuffix}`);
+}
+/**
+ * Explicit addition/conversion log so a third-party reading the migration
+ * output knows exactly what invent/convert did on each shell.
+ */
+function formatChangeReport(change) {
+    if (change.kind === "addition") {
+        return `  ${MIGRATION_NAME}: addition on "${change.extensionId}" (${change.filePath}): "${change.before}" → "${change.after}"`;
+    }
+    const removed = change.removedTokens.join(", ");
+    return `  ${MIGRATION_NAME}: conversion on "${change.extensionId}" (${change.filePath}): removed [${removed}]; "${change.before}" → "${change.after}"`;
+}
+exports.default = pContentSpaceCodemod;
+//# sourceMappingURL=orchestrator.js.map

package/migrations/p-content-space-codemod/remove-redundant-padding.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeRedundantPadding = removeRedundantPadding;
+const css_classname_utils_1 = require("@trackunit/css-classname-utils");
+const classname_ast_rewrite_1 = require("../utils/classname-ast-rewrite");
+const REDUNDANT_INSET_TOKENS = ["pb-8", "pb-6", "pb-4", "pb-responsive-space"];
+const PADDED_REGION_TOKEN = "p-content-space";
+/**
+ * Removes the redundant bottom-inset Tailwind tokens (`pb-8`, `pb-6`, `pb-4`,
+ * `pb-responsive-space`) from classname strings that already carry
+ * `p-content-space` under a single resolved extension's `sourceRoot`.
+ *
+ * Scoped to the padded region on purpose: local `pb-*` used as component
+ * spacing (cards, timeline entries, wizard steps) must not be stripped just
+ * because they live under the same `sourceRoot`. Callers must run
+ * `rewritePageContent` first so a just-migrated `page-content` region already
+ * reads as `p-content-space` before this transform looks for it. Extensions
+ * with no padded region (the ones `findUnresolvedSurface` will report) are
+ * therefore a complete no-op here — there is no `p-content-space` token to
+ * key off.
+ *
+ * Scoped to one extension per call — the caller (the orchestrator) loops
+ * over every Asset Home/Site Home/Admin extension.
+ */
+function removeRedundantPadding(tree, extension) {
+    return (0, classname_ast_rewrite_1.transformClassnamesUnderSourceRoot)(tree, extension.sourceRoot, content => content.includes(PADDED_REGION_TOKEN) && REDUNDANT_INSET_TOKENS.some(token => content.includes(token)), value => {
+        if (!(0, css_classname_utils_1.splitClasses)(value).includes(PADDED_REGION_TOKEN)) {
+            return value;
+        }
+        let result = value;
+        for (const token of REDUNDANT_INSET_TOKENS) {
+            result = (0, css_classname_utils_1.replaceClassToken)(result, token, "");
+        }
+        return result;
+    });
+}
+//# sourceMappingURL=remove-redundant-padding.js.map

package/migrations/p-content-space-codemod/report-run-messaging.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectAsaEndOfRunMessages = exports.buildScrollbarAdvisoryMessages = exports.formatUnresolvedReport = exports.buildUnresolvedInventGuidance = exports.buildVerifyAndEdgeToEdgeReminder = void 0;
+const css_classname_utils_1 = require("@trackunit/css-classname-utils");
+const report_unresolved_1 = require("./report-unresolved");
+const MIGRATION_NAME = "p-content-space-codemod";
+/**
+ * Developer-facing end-of-run reminder: verify appearance after migration, and
+ * note that intentional edge-to-edge (no content inset) remains an allowed choice.
+ * Emitted at most once per run when any ASA work happened — including runs that
+ * only produced unresolved reports and no invent/convert edits.
+ */
+const buildVerifyAndEdgeToEdgeReminder = () => `  ${MIGRATION_NAME}: verify UI after migration; edge-to-edge content (no p-content-space) is an allowed choice when intentional`;
+exports.buildVerifyAndEdgeToEdgeReminder = buildVerifyAndEdgeToEdgeReminder;
+/**
+ * Explains what an inventable overflow content shell is when the migration
+ * could not auto-pad one or more Asset/Site/Admin surfaces. Emitted once per
+ * run that produced unresolved reports.
+ */
+const buildUnresolvedInventGuidance = () => `  ${MIGRATION_NAME}: could not auto-invent p-content-space on the surface(s) above — invent only targets a single inventable overflow content shell (a div/main/section with an editable className that itself owns overflow-auto/scroll, with no PageHeader/Topbar child). Card-only roots, multi-route graphs, and unclear shells need a manual p-content-space on that scroll owner (or accept edge-to-edge). See ${report_unresolved_1.PADDING_DOCS_LINK}`;
+exports.buildUnresolvedInventGuidance = buildUnresolvedInventGuidance;
+/**
+ * Per-extension unresolved warning. Prefer this over a bare "no token" line so
+ * developers learn *why* invent skipped them.
+ */
+const formatUnresolvedReport = (report) => {
+    const reasonSuffix = report.skipReason === undefined ? "" : ` — reason [${report.skipReason.code}]: ${report.skipReason.message}`;
+    if (report.skippedRouteName !== undefined) {
+        return `  ${MIGRATION_NAME}: extension "${report.extensionId}" (${report.sourceRoot}) skipped route "${report.skippedRouteName}"${reasonSuffix || " — no inventable overflow content shell on that route"}; see ${report.docsLink}`;
+    }
+    if (report.skipReason !== undefined) {
+        return `  ${MIGRATION_NAME}: extension "${report.extensionId}" (${report.sourceRoot}) not auto-invented${reasonSuffix}; add p-content-space manually on the scroll owner or accept edge-to-edge — see ${report.docsLink}`;
+    }
+    return `  ${MIGRATION_NAME}: extension "${report.extensionId}" (${report.sourceRoot}) has no page-content/p-content-space and no inventable overflow content shell (needs a scrolling div/main/section with editable className, not e.g. a bare Card) — add p-content-space manually or accept edge-to-edge; see ${report.docsLink}`;
+};
+exports.formatUnresolvedReport = formatUnresolvedReport;
+/**
+ * Advisory-only scrollbar notes for invent/convert onto a self-scrolling
+ * (`overflow-*`) shell. Cannot measure real DOM scrollbars in the codemod —
+ * documents the preferred flush-scrollbar outcome after content owns padding.
+ */
+const buildScrollbarAdvisoryMessages = (changes) => {
+    const messages = [];
+    for (const change of changes) {
+        if (!shellHasOverflowScroll(change.before) && !shellHasOverflowScroll(change.after)) {
+            continue;
+        }
+        messages.push(`  ${MIGRATION_NAME}: scrollbar note on "${change.extensionId}" (${change.filePath}): shell uses overflow scrolling — prefer a flush scrollbar at the panel edge after content owns padding`);
+    }
+    return messages;
+};
+exports.buildScrollbarAdvisoryMessages = buildScrollbarAdvisoryMessages;
+/**
+ * Collects end-of-run ASA developer messages (scrollbar advisories, unresolved
+ * invent guidance when needed, + single verify/edge-to-edge reminder). Empty
+ * when no ASA work occurred this run.
+ */
+const collectAsaEndOfRunMessages = (context) => {
+    if (!context.asaWorkOccurred) {
+        return [];
+    }
+    const messages = (0, exports.buildScrollbarAdvisoryMessages)(context.changes);
+    if (context.unresolvedReports.length > 0) {
+        messages.push((0, exports.buildUnresolvedInventGuidance)());
+    }
+    messages.push((0, exports.buildVerifyAndEdgeToEdgeReminder)());
+    return messages;
+};
+exports.collectAsaEndOfRunMessages = collectAsaEndOfRunMessages;
+const shellHasOverflowScroll = (classnameValue) => {
+    return (0, css_classname_utils_1.splitClasses)(classnameValue).some(cls => /(^|:)overflow-/.test(cls));
+};
+//# sourceMappingURL=report-run-messaging.js.map

package/migrations/p-content-space-codemod/report-unresolved.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PADDING_DOCS_LINK = void 0;
+exports.findUnresolvedSurface = findUnresolvedSurface;
+const css_classname_utils_1 = require("@trackunit/css-classname-utils");
+const classname_ast_rewrite_1 = require("../utils/classname-ast-rewrite");
+const resolve_content_shell_1 = require("./resolve-content-shell");
+const PAGE_CONTENT_TOKEN = "page-content";
+const CONTENT_SPACE_TOKEN = "p-content-space";
+const RESOLVED_TOKENS = [PAGE_CONTENT_TOKEN, CONTENT_SPACE_TOKEN];
+const tokenBase = (token) => (token.includes(":") ? token.slice(token.lastIndexOf(":") + 1) : token);
+const isResolvedToken = (token) => RESOLVED_TOKENS.includes(tokenBase(token));
+const DEFAULT_ENTRY_COMPONENT_FILE = "index.tsx";
+/** In-repo docs for inventable overflow content shells (GLU-1571 / p-content-space migration). */
+exports.PADDING_DOCS_LINK = "docs/tech/TAILWIND-ARCHITECTURE.md#p-content-space-inventable-shell";
+/**
+ * Read-only check for whether a single file already contains `page-content`
+ * or `p-content-space` as a whole classname token (not matching inside e.g.
+ * `page-content-with-gap`). Used as a suppressor on unresolvable graphs so
+ * resolver limits do not permanently light up already-migrated extensions.
+ */
+function fileHasResolvedToken(content) {
+    if (!RESOLVED_TOKENS.some(token => content.includes(token)))
+        return false;
+    const program = (0, classname_ast_rewrite_1.parseTsestreeSource)(content);
+    const locations = (0, classname_ast_rewrite_1.findClassnameLocations)(program);
+    return locations.some(location => (0, css_classname_utils_1.splitClasses)(location.value).some(isResolvedToken));
+}
+function sourceRootHasResolvedToken(tree, extension) {
+    let found = false;
+    (0, classname_ast_rewrite_1.visitRewritableFiles)(tree, extension.sourceRoot, (_filePath, content) => {
+        if (found)
+            return;
+        if (fileHasResolvedToken(content)) {
+            found = true;
+        }
+    });
+    return found;
+}
+/**
+ * Determines whether the inventable content shell of an Asset Home/Site Home/Admin
+ * extension still lacks `page-content` / `p-content-space`, and if so, builds a
+ * report entry describing it.
+ *
+ * A token on a nested file is not enough when the graph *resolves*: Device
+ * Administration hid behind `p-content-space` on a job-details leaf while the
+ * layout shell still used `pb-responsive-space` (GLU-1903). Returns `null` only
+ * when every *resolved content shell* already carries a resolved token (or still
+ * uses `page-content`, which `rewritePageContent` handles separately so it must
+ * not be double-reported).
+ *
+ * An unresolvable graph is *not* treated as a leftover if any rewritable file
+ * already has a resolved token — otherwise Device Administration (and ~24 other
+ * ASA extensions the walker cannot follow) stay permanently-on after padding.
+ * Unresolvable graphs with no token anywhere still report.
+ *
+ * This function is read-only: it never calls `tree.write`. Callers must run it
+ * against Tree state that already reflects `rewritePageContent`'s and
+ * `removeRedundantPadding`'s edits for the same extension, since those two
+ * transforms mutate `page-content` into `p-content-space` in place — running
+ * this check first, against pre-rewrite content, would misreport a
+ * just-fixed extension as unresolved.
+ *
+ * A `sourceRoot` that doesn't exist in the Tree at all (or contains no
+ * rewritable files) is treated the same as "no page-content and no
+ * p-content-space found": it gets reported, not silently skipped.
+ */
+function findUnresolvedSurface(tree, extension) {
+    const resolved = (0, resolve_content_shell_1.resolveContentShells)(tree, extension);
+    if (resolved.status === "resolved") {
+        const everyShellHasResolvedToken = resolved.shells.every(shell => (0, css_classname_utils_1.splitClasses)(shell.combinedClassnameValue).some(isResolvedToken));
+        if (everyShellHasResolvedToken) {
+            return null;
+        }
+    }
+    else if (sourceRootHasResolvedToken(tree, extension)) {
+        return null;
+    }
+    const entryComponentPath = `${extension.sourceRoot}/${extension.main ?? DEFAULT_ENTRY_COMPONENT_FILE}`;
+    return {
+        extensionId: extension.id,
+        sourceRoot: extension.sourceRoot,
+        entryComponentPath: tree.exists(entryComponentPath) ? entryComponentPath : null,
+        docsLink: exports.PADDING_DOCS_LINK,
+    };
+}
+//# sourceMappingURL=report-unresolved.js.map