@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/audit/orphans.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditOrphans = void 0;
+const shared_1 = require("../shared");
+/**
+ * List orphan items — i.e., items in the Sitecore archive (recycle bin).
+ *
+ * **XM Cloud reality check.** The dotnet `Sitecore.DevEx`
+ * `clean-orphan-items` operation targeted SQL-layer orphans (items in
+ * the master DB whose `ParentID` referenced a nonexistent parent).
+ * That state isn't reachable through the XM Cloud Authoring API: the
+ * GraphQL schema enforces parent integrity on every mutation, and
+ * delete cascades from parent → children, so a "missing parent"
+ * orphan can't be produced through normal use.
+ *
+ * What XM Cloud *does* expose is the archive (recycle bin). When an
+ * operator deletes an item via XM Cloud UIs or via `deleteItem(input:
+ * { permanently: false })`, it moves to the archive — visible only via
+ * the `archivedItems` query. This is the closest analogue to
+ * "orphaned" content on XM Cloud and is what an operator would mean by
+ * "find items I can clean up."
+ *
+ * For genuine missing-parent items (extremely rare on XM Cloud, but
+ * possible in disaster-recovery scenarios), a follow-up command could
+ * walk the tree via `getChildren` and flag dangling refs — not in
+ * this PR's scope.
+ */
+const runAuditOrphans = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const pageSize = options.pageSize ?? 100;
+    const limit = options.limit ?? 1000;
+    const archived = [];
+    let pageIndex = 0;
+    while (archived.length < limit) {
+        const page = await client.listArchivedItems({
+            archiveName: options.archiveName,
+            pageIndex,
+            pageSize,
+        });
+        if (page.length === 0)
+            break;
+        for (const item of page) {
+            if (archived.length >= limit)
+                break;
+            archived.push({
+                archivalId: item.archivalId,
+                itemId: item.itemId,
+                name: item.name,
+                originalLocation: item.originalLocation,
+                archivedBy: item.archivedBy,
+                archivedDate: item.archivedDate,
+            });
+        }
+        if (page.length < pageSize)
+            break;
+        pageIndex += 1;
+    }
+    archived.sort((a, b) => {
+        const aDate = a.archivedDate ?? "";
+        const bDate = b.archivedDate ?? "";
+        return bDate.localeCompare(aDate);
+    });
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.orphans.list",
+        envName,
+        results: archived,
+        summary: archived.length === 0
+            ? "Archive is empty — no orphan items."
+            : `${archived.length} archived item${archived.length === 1 ? "" : "s"}.`,
+        formatLine: (r) => `${r.name} from ${r.originalLocation}${r.archivedDate ? ` (${r.archivedDate.slice(0, 10)} by ${r.archivedBy ?? "?"})` : ""}`,
+        extra: { archiveName: options.archiveName ?? null, limit },
+        options,
+    });
+    return archived;
+};
+exports.runAuditOrphans = runAuditOrphans;

package/dist/hygiene/tasks/audit/page-design-orphans.d.ts

@@ -0,0 +1,24 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditPageDesignOrphansOptions extends HygieneCommonOptions {
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+}
+export interface PageDesignOrphanReport {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string | null;
+    fieldName: string;
+    pageDesignRef: string;
+}
+/**
+ * XM Cloud SXA — find pages whose `__Final Page Design` / `__Page Design`
+ * field references a missing item.
+ */
+export declare const runAuditPageDesignOrphans: (options: AuditPageDesignOrphansOptions) => Promise<PageDesignOrphanReport[]>;

package/dist/hygiene/tasks/audit/page-design-orphans.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditPageDesignOrphans = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * XM Cloud SXA — find pages whose `__Final Page Design` / `__Page Design`
+ * field references a missing item.
+ */
+const runAuditPageDesignOrphans = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const { scanned, fieldsByItemId, cache, knobs } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const pending = [];
+    const refsToResolve = new Set();
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        for (const field of fields) {
+            if (!(0, shared_1.isPageDesignField)(field.name))
+                continue;
+            if (!field.value || !field.value.trim())
+                continue;
+            const refItemId = (0, shared_1.normalizeItemId)(field.value.trim());
+            if (refItemId.length !== 32)
+                continue;
+            pending.push({
+                itemId: item.itemId,
+                path: item.path,
+                templateName: item.templateName,
+                language: item.language,
+                fieldName: field.name,
+                refItemId,
+            });
+            refsToResolve.add(refItemId);
+        }
+    }
+    const refExists = new Map();
+    const refList = Array.from(refsToResolve);
+    const refBatches = [];
+    for (let i = 0; i < refList.length; i += knobs.batchSize) {
+        refBatches.push(refList.slice(i, i + knobs.batchSize));
+    }
+    const existResults = await (0, cli_tasks_1.mapWithConcurrency)(refBatches, (ids) => client.itemsExistBatch(ids), knobs.concurrency);
+    for (const m of existResults)
+        for (const [id, exists] of m)
+            refExists.set(id, exists);
+    const orphans = pending
+        .filter((p) => refExists.get(p.refItemId) === false)
+        .map((p) => ({
+        itemId: p.itemId,
+        path: p.path,
+        templateName: p.templateName,
+        language: p.language,
+        fieldName: p.fieldName,
+        pageDesignRef: p.refItemId,
+    }))
+        .sort((a, b) => a.path.localeCompare(b.path));
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.page-design-orphans.list",
+        envName,
+        results: orphans,
+        summary: `Scanned ${scanned.length} items; ${orphans.length} reference missing page designs.`,
+        formatLine: (r) => `${r.path} — ${r.fieldName}→${r.pageDesignRef.slice(0, 8)}`,
+        extra: { root, scannedCount: scanned.length },
+        options,
+    });
+    return orphans;
+};
+exports.runAuditPageDesignOrphans = runAuditPageDesignOrphans;

package/dist/hygiene/tasks/audit/personalization-broken.d.ts

@@ -0,0 +1,25 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditPersonalizationBrokenOptions extends HygieneCommonOptions {
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+}
+export interface PersonalizationBrokenReport {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string | null;
+    brokenRefs: Array<{
+        fieldName: string;
+        refItemId: string;
+    }>;
+}
+/**
+ * Audit page items for personalization rules referencing missing items.
+ */
+export declare const runAuditPersonalizationBroken: (options: AuditPersonalizationBrokenOptions) => Promise<PersonalizationBrokenReport[]>;

package/dist/hygiene/tasks/audit/personalization-broken.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditPersonalizationBroken = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * Audit page items for personalization rules referencing missing items.
+ */
+const runAuditPersonalizationBroken = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const { scanned, fieldsByItemId, cache, knobs } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const pending = [];
+    const refsToResolve = new Set();
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        for (const field of fields) {
+            if (!(0, shared_1.isRenderingField)(field.name) || !field.value)
+                continue;
+            for (const raw of (0, shared_1.extractPersonalizationRefs)(field.value)) {
+                const norm = (0, shared_1.normalizeItemId)(raw);
+                if (norm.length !== 32)
+                    continue;
+                if (norm === item.itemId)
+                    continue;
+                pending.push({
+                    itemId: item.itemId,
+                    path: item.path,
+                    templateName: item.templateName,
+                    language: item.language,
+                    fieldName: field.name,
+                    refItemId: norm,
+                });
+                refsToResolve.add(norm);
+            }
+        }
+    }
+    logger.verbose(`Found ${pending.length} personalization refs (${refsToResolve.size} distinct).`);
+    const refExists = new Map();
+    const refList = Array.from(refsToResolve);
+    const refBatches = [];
+    for (let i = 0; i < refList.length; i += knobs.batchSize) {
+        refBatches.push(refList.slice(i, i + knobs.batchSize));
+    }
+    const existResults = await (0, cli_tasks_1.mapWithConcurrency)(refBatches, (ids) => client.itemsExistBatch(ids), knobs.concurrency);
+    for (const m of existResults)
+        for (const [id, exists] of m)
+            refExists.set(id, exists);
+    const byItem = new Map();
+    for (const p of pending) {
+        if (refExists.get(p.refItemId) !== false)
+            continue;
+        const existing = byItem.get(p.itemId);
+        const entry = { fieldName: p.fieldName, refItemId: p.refItemId };
+        if (existing) {
+            if (!existing.brokenRefs.some((b) => b.refItemId === entry.refItemId)) {
+                existing.brokenRefs.push(entry);
+            }
+        }
+        else {
+            byItem.set(p.itemId, {
+                itemId: p.itemId,
+                path: p.path,
+                templateName: p.templateName,
+                language: p.language,
+                brokenRefs: [entry],
+            });
+        }
+    }
+    const reports = Array.from(byItem.values()).sort((a, b) => a.path.localeCompare(b.path));
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.personalization-broken.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned.length} items; ${reports.length} have broken personalization refs.`,
+        formatLine: (r) => `${r.path} — ${r.brokenRefs.length} broken: ${r.brokenRefs
+            .slice(0, 3)
+            .map((b) => b.refItemId.slice(0, 8))
+            .join(", ")}${r.brokenRefs.length > 3 ? "…" : ""}`,
+        extra: { root, scannedCount: scanned.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditPersonalizationBroken = runAuditPersonalizationBroken;

package/dist/hygiene/tasks/audit/references.d.ts

@@ -0,0 +1,70 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditReferencesOptions extends HygieneCommonOptions {
+    /** Required. Item ID to find inbound references for. Any GUID form accepted. */
+    to?: string;
+    /** Content root to scan. Default `/sitecore/content`. */
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    language?: string;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    /** Include `__`-prefixed system fields in the scan. On by default — that's where most refs live. */
+    includeSystemFields?: boolean;
+    /** Restrict the scan to these field names. */
+    fields?: string[];
+    /**
+     * Suppress the audit's own report. Used by cleanup tasks that call
+     * this audit as a pre-flight check and surface blockers in their own
+     * combined report rather than as a separate audit record. Pair with
+     * `cache: true` when running back-to-back checks against the same
+     * `--root` so subsequent calls hit the field cache. Default false.
+     */
+    silent?: boolean;
+}
+export interface ReferenceReport {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string | null;
+    /** One entry per field that mentions the target. */
+    matches: Array<{
+        fieldName: string;
+        /**
+         * How the target appears in the field value: as a raw 32-char id
+         * (`abc123…`), a dashed id (`abc-123-…`), a curly-wrapped id
+         * (`{abc-123-…}`), or a path that contains the target's normalized
+         * id. Mostly diagnostic — the operator usually just needs to know
+         * "this field references the target," not which form.
+         */
+        form: "flat" | "dashed" | "curly-upper" | "curly-lower" | "path-ancestor";
+    }>;
+}
+/**
+ * Inbound-reference scan: walk items + fields under `--root` and
+ * report every field whose value mentions the target item id in any
+ * of the canonical Sitecore GUID forms. The companion primitive to
+ * `audit template-dependencies` — that audit uses the search index's
+ * indexed-field criteria (template-specific signals like `__masters`,
+ * `_basetemplates`); this one walks raw field values to catch the
+ * long tail of custom droplist/treelist/link fields the index doesn't
+ * classify.
+ *
+ * Performance: cost scales with `--root` size, not with how many
+ * references actually exist. On a tenant with 50k items, expect
+ * 30s–2min depending on `--page-parallelism` and `--concurrency`. The
+ * field cache (`--cache`) makes re-runs against the same root nearly
+ * free for the unchanged items.
+ *
+ * Use this when:
+ *   - The target is NOT a template (template-dependencies has stronger
+ *     signals for templates).
+ *   - `audit template-dependencies` returned empty and you suspect a
+ *     custom field type the index doesn't classify.
+ *   - You need to find every author-facing field referencing a media
+ *     item / rendering / data-source before deleting it.
+ */
+export declare const runAuditReferences: (options: AuditReferencesOptions) => Promise<ReferenceReport[]>;

package/dist/hygiene/tasks/audit/references.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditReferences = void 0;
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+/**
+ * Build the candidate strings we'll search for in field values.
+ * Sitecore stores GUIDs in many forms depending on the field type
+ * and authoring path — multi-list fields use `{ABC-DEF-…}` separated
+ * by `|`, droplist values are `{abc-def-…}` or raw dashed, link XML
+ * uses `id="ABC..."`, and computed `_path` mirrors stored as flat
+ * concatenations. Match permissively so a single audit catches the
+ * full surface.
+ */
+const buildPatterns = (normalized) => {
+    const flat = normalized;
+    const dashed = `${flat.slice(0, 8)}-${flat.slice(8, 12)}-${flat.slice(12, 16)}-${flat.slice(16, 20)}-${flat.slice(20)}`;
+    return [
+        { pattern: flat, form: "flat" },
+        { pattern: dashed, form: "dashed" },
+        { pattern: `{${dashed.toUpperCase()}}`, form: "curly-upper" },
+        { pattern: `{${dashed}}`, form: "curly-lower" },
+    ];
+};
+/**
+ * Inbound-reference scan: walk items + fields under `--root` and
+ * report every field whose value mentions the target item id in any
+ * of the canonical Sitecore GUID forms. The companion primitive to
+ * `audit template-dependencies` — that audit uses the search index's
+ * indexed-field criteria (template-specific signals like `__masters`,
+ * `_basetemplates`); this one walks raw field values to catch the
+ * long tail of custom droplist/treelist/link fields the index doesn't
+ * classify.
+ *
+ * Performance: cost scales with `--root` size, not with how many
+ * references actually exist. On a tenant with 50k items, expect
+ * 30s–2min depending on `--page-parallelism` and `--concurrency`. The
+ * field cache (`--cache`) makes re-runs against the same root nearly
+ * free for the unchanged items.
+ *
+ * Use this when:
+ *   - The target is NOT a template (template-dependencies has stronger
+ *     signals for templates).
+ *   - `audit template-dependencies` returned empty and you suspect a
+ *     custom field type the index doesn't classify.
+ *   - You need to find every author-facing field referencing a media
+ *     item / rendering / data-source before deleting it.
+ */
+const runAuditReferences = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.to) {
+        throw (0, errors_1.createScaiError)("audit references requires --to <itemId>.", "INPUT_INVALID");
+    }
+    const normalized = (0, shared_1.normalizeItemId)(options.to);
+    const root = options.root ?? "/sitecore/content";
+    const patterns = buildPatterns(normalized);
+    const fieldFilter = options.fields?.length
+        ? new Set(options.fields.map((f) => f.toLowerCase()))
+        : null;
+    // Default to ON for system fields — these audits exist precisely
+    // because system fields (`__Renderings`, `__Layout`, `__masters`,
+    // and so on) carry most cross-item references in Sitecore.
+    const includeSystemFields = options.includeSystemFields ?? true;
+    logger.verbose(`Scanning ${root} for references to ${normalized}.`);
+    const { scanned, fieldsByItemId, cache } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const reports = [];
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        // Self-reference is uninteresting noise — every item's _path /
+        // _ancestors fields contain its own id.
+        if (item.itemId === normalized)
+            continue;
+        const fieldMatches = [];
+        for (const field of fields) {
+            if (!field.value)
+                continue;
+            if (fieldFilter && !fieldFilter.has(field.name.toLowerCase()))
+                continue;
+            if (!includeSystemFields && field.name.startsWith("__"))
+                continue;
+            // Match permissively: any of the canonical id forms appearing
+            // anywhere in the field value counts as a reference. Pick the
+            // most specific form seen so the report tells the operator
+            // "this is a curly-wrapped GUID, probably a multi-list" vs.
+            // "this is a flat 32-char id, probably an index-only mirror."
+            let bestForm = null;
+            const lower = field.value.toLowerCase();
+            for (const { pattern, form } of patterns) {
+                const target = form === "curly-upper" ? field.value : lower;
+                const needle = form === "curly-upper" ? pattern : pattern.toLowerCase();
+                if (target.includes(needle)) {
+                    bestForm = form;
+                    // Curly forms are more specific than dashed; dashed is more
+                    // specific than flat. Keep the more specific one when both
+                    // would match a substring.
+                    if (form.startsWith("curly"))
+                        break;
+                }
+            }
+            if (bestForm) {
+                fieldMatches.push({ fieldName: field.name, form: bestForm });
+            }
+        }
+        if (fieldMatches.length > 0) {
+            reports.push({
+                itemId: item.itemId,
+                path: item.path,
+                templateName: item.templateName,
+                language: item.language,
+                matches: fieldMatches,
+            });
+        }
+    }
+    reports.sort((a, b) => a.path.localeCompare(b.path));
+    await cache?.flush();
+    if (!options.silent) {
+        (0, shared_1.printReport)({
+            logger,
+            command: "audit.references.list",
+            envName,
+            results: reports,
+            summary: `Scanned ${scanned.length} items under ${root}; ${reports.length} item(s) reference ${normalized}.`,
+            formatLine: (r) => `${r.path} — ${r.matches
+                .slice(0, 3)
+                .map((m) => `${m.fieldName}(${m.form})`)
+                .join(", ")}${r.matches.length > 3 ? "…" : ""}`,
+            extra: { to: normalized, root, scannedCount: scanned.length },
+            options,
+        });
+    }
+    return reports;
+};
+exports.runAuditReferences = runAuditReferences;

package/dist/hygiene/tasks/audit/role-bloat.d.ts

@@ -0,0 +1,42 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditRoleBloatOptions extends HygieneCommonOptions {
+    /** Role-count threshold per user. Default 10. */
+    threshold?: number;
+    /** Cap on users inspected. Default 5000. */
+    limit?: number;
+    /**
+     * Include administrators in the audit. Off by default — admins
+     * legitimately accumulate roles for emergency-access reasons.
+     */
+    includeAdmins?: boolean;
+    concurrency?: number;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+}
+export interface RoleBloatReport {
+    user: string;
+    isAdministrator: boolean;
+    roleCount: number;
+    roles: string[];
+}
+/**
+ * Audit users with an unusually large number of role memberships.
+ *
+ * Strategy:
+ *   1. List every user via `listUsers`.
+ *   2. For each, fetch full detail (`getUserDetail`) to count
+ *      direct role memberships.
+ *   3. Flag users with `roleCount >= --threshold` (default 10).
+ *
+ * Notes:
+ *   - This counts DIRECT memberships only — transitive roles (a user
+ *     in role A, where role A is a member of role B) aren't summed.
+ *     The Authoring API exposes `User.roles` as the direct set.
+ *   - Administrators are excluded by default; pass `--include-admins`
+ *     to include them.
+ *   - The Authoring API doesn't expose role-permission detail per
+ *     item, so this audit is a count signal, not an actual
+ *     permission analysis.
+ */
+export declare const runAuditRoleBloat: (options: AuditRoleBloatOptions) => Promise<RoleBloatReport[]>;

package/dist/hygiene/tasks/audit/role-bloat.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditRoleBloat = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * Audit users with an unusually large number of role memberships.
+ *
+ * Strategy:
+ *   1. List every user via `listUsers`.
+ *   2. For each, fetch full detail (`getUserDetail`) to count
+ *      direct role memberships.
+ *   3. Flag users with `roleCount >= --threshold` (default 10).
+ *
+ * Notes:
+ *   - This counts DIRECT memberships only — transitive roles (a user
+ *     in role A, where role A is a member of role B) aren't summed.
+ *     The Authoring API exposes `User.roles` as the direct set.
+ *   - Administrators are excluded by default; pass `--include-admins`
+ *     to include them.
+ *   - The Authoring API doesn't expose role-permission detail per
+ *     item, so this audit is a count signal, not an actual
+ *     permission analysis.
+ */
+const runAuditRoleBloat = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const threshold = options.threshold ?? 10;
+    const limit = options.limit ?? 5000;
+    const includeAdmins = Boolean(options.includeAdmins);
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    const concurrency = options.concurrency ?? knobs.concurrency;
+    const users = await client.listUsers();
+    const bounded = users.slice(0, limit);
+    logger.verbose(`Inspecting ${bounded.length} users (concurrency ${concurrency}).`);
+    const details = await (0, cli_tasks_1.mapWithConcurrency)(bounded, async (u) => {
+        if (!includeAdmins && u.isAdministrator)
+            return null;
+        const detail = await client.getUserDetail(u.name);
+        return detail;
+    }, concurrency);
+    const reports = details
+        .filter((d) => d !== null)
+        .filter((d) => d.roles.length >= threshold)
+        .map((d) => ({
+        user: d.name,
+        isAdministrator: d.isAdministrator,
+        roleCount: d.roles.length,
+        roles: d.roles,
+    }))
+        .sort((a, b) => b.roleCount - a.roleCount);
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.role-bloat.list",
+        envName,
+        results: reports,
+        summary: `Inspected ${bounded.length} users; ${reports.length} with >= ${threshold} role membership${threshold === 1 ? "" : "s"}.`,
+        formatLine: (r) => `${r.user} — ${r.roleCount} roles`,
+        extra: { threshold, scannedCount: bounded.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditRoleBloat = runAuditRoleBloat;

package/dist/hygiene/tasks/audit/site-residue.d.ts

@@ -0,0 +1,39 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditSiteResidueOptions extends HygieneCommonOptions {
+    /**
+     * Additional roots to scan on top of the three SXA defaults. Pass
+     * repeatedly or comma-separate. Defaults to the standard SXA
+     * Project folders under templates / layout / media library.
+     */
+    root?: string[];
+    /** Override the content root walked when discovering active sites.
+     *  Default `/sitecore/content` — same as `scai provision deploy site list`. */
+    contentRoot?: string;
+    index?: string;
+    concurrency?: number;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Suppress this audit's own report — the caller owns the printed
+     * output. Used by `explain` verbs that compose this audit with
+     * others (e.g. `explain orphan-site`).
+     */
+    silent?: boolean;
+}
+export type SiteResidueKind = "orphan-tenant" | "orphan-site";
+export interface SiteResidueReport {
+    kind: SiteResidueKind;
+    /** Root path under which the residue was found (e.g. `/sitecore/templates/Project`). */
+    root: string;
+    /** Tenant folder name as it appears in the residue tree. */
+    tenant: string;
+    /** Site folder name — null for `orphan-tenant`. */
+    site: string | null;
+    itemId: string;
+    path: string;
+    /** Descendant count from the search index (`_path CONTAINS itemId`).
+     *  Useful for prioritising which residue tree to clean up first. */
+    descendantCount: number;
+}
+export declare const runAuditSiteResidue: (options: AuditSiteResidueOptions) => Promise<SiteResidueReport[]>;