@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/audit/dead-templates.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditDeadTemplates = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+/**
+ * Patterns in GraphQL `errors[].message` payloads that we treat as
+ * transient and retry. Sitecore returns 200-with-errors for several
+ * server-side failures the HTTP retry path never sees:
+ *
+ *   - "Service Unavailable" / "service is currently unavailable" — the
+ *     search backend restarted or is rolling.
+ *   - "timeout" / "took too long" — query was killed by the gateway
+ *     before the search index responded.
+ *   - "transient" / "try again" — explicit retry hints from the API.
+ *   - "circuit breaker" — internal fault tolerance kicked in.
+ *
+ * The matches are intentionally permissive: a false-positive retry on
+ * a permanent error wastes time but doesn't corrupt state — the read
+ * surface is idempotent.
+ */
+const TRANSIENT_GRAPHQL_ERROR_PATTERNS = [
+    /service\s+(is\s+)?(currently\s+)?unavailable/i,
+    /\btransient\b/i,
+    /\btry\s+again\b/i,
+    /\bcircuit\s+breaker\b/i,
+    /\btime(?:d)?\s*out\b/i,
+    /took\s+too\s+long/i,
+];
+const isTransientError = (error) => {
+    if (!(error instanceof Error))
+        return false;
+    return TRANSIENT_GRAPHQL_ERROR_PATTERNS.some((p) => p.test(error.message));
+};
+/**
+ * "The search service is not available" — the environment has no search
+ * index provisioned. Unlike the transient patterns above this never
+ * clears on retry: dead-templates simply cannot run without search.
+ */
+const isSearchUnavailableError = (error) => error instanceof Error && /search service is not available/i.test(error.message);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Wrap a read operation in transient-aware retry. The shared HTTP
+ * transport already retries 503/429 and friends, but Sitecore's search
+ * service surfaces some failures as 200-with-`errors` payloads which
+ * the transport throws as `ScaiError("NETWORK")` — no retry. This
+ * helper catches those, matches against `TRANSIENT_GRAPHQL_ERROR_PATTERNS`,
+ * and retries with exponential backoff.
+ */
+const retryOnTransient = async (op, opts) => {
+    let lastError;
+    for (let attempt = 0; attempt < opts.attempts; attempt += 1) {
+        if (attempt > 0) {
+            const delay = Math.min(15000, opts.baseDelayMs * 2 ** (attempt - 1));
+            opts.logger.verbose(`Retry ${attempt}/${opts.attempts - 1} for ${opts.label} after ${delay}ms (transient error).`);
+            await sleep(delay);
+        }
+        try {
+            return await op();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isTransientError(error))
+                break;
+        }
+    }
+    throw lastError;
+};
+const SYSTEM_TEMPLATE_PREFIXES = ["System/", "Branches/System/"];
+/**
+ * Audit a template tree for templates with zero items based on them.
+ *
+ * Strategy:
+ *   1. List all templates under `--root` via the `itemTemplates`
+ *      Authoring query (paged).
+ *   2. For each template, run a small search (`_template: <templateId>`)
+ *      that ignores standard-values items (templates ship a SV item under
+ *      themselves; that's not a "real" usage). Fastest cap-at-1 page.
+ *   3. Emit a row for every template with zero items.
+ *
+ * Output is sorted by fullName for stable diffs across runs.
+ */
+const runAuditDeadTemplates = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    // Default to `/sitecore/templates` rather than `/sitecore/templates/Project`
+    // because non-SXA tenants don't have a `Project` folder. `/sitecore/templates`
+    // is universal; SYSTEM_PATH_PREFIXES filtering removes `/sitecore/templates/System`
+    // descendants from the scan unless --include-system is passed.
+    const root = options.root ?? "/sitecore/templates";
+    const limit = options.limit ?? 5000;
+    const concurrency = options.concurrency ?? 8;
+    logger.verbose(`Listing templates under ${root} (limit ${limit}).`);
+    const includeSystem = Boolean(options.includeSystem);
+    let raw;
+    try {
+        raw = await client.listItemTemplates({ rootPath: root });
+    }
+    catch (error) {
+        if (!isSearchUnavailableError(error)) {
+            throw error;
+        }
+        // No search index on this environment — dead-templates can't run.
+        // Point the caller at the traversal-based audits that can.
+        throw (0, errors_1.createScaiError)("The dead-templates audit needs a provisioned search index, which this environment does not have.", "NETWORK", {
+            hint: "Use a traversal-based audit — it does not depend on a search index.",
+            remediation: {
+                actor: "agent",
+                fix: `scai hygiene audit heavy-templates list --root ${root}`,
+                detail: "heavy-templates (and the content_browse MCP tool) walk the item tree directly and work without a search index; dead-templates cannot.",
+            },
+        });
+    }
+    const filtered = includeSystem
+        ? raw
+        : raw.filter((t) => {
+            const fn = t.fullName ?? "";
+            return !SYSTEM_TEMPLATE_PREFIXES.some((p) => fn.startsWith(p));
+        });
+    const bounded = filtered.slice(0, limit);
+    if (bounded.length === 0) {
+        logger.warn(`No templates found under '${root}' (after system-filter).`);
+    }
+    logger.verbose(`Listed ${raw.length} templates; ${bounded.length} after filtering (system=${includeSystem}).`);
+    const checks = await (0, cli_tasks_1.mapWithConcurrency)(bounded, async (template) => {
+        const value = (0, shared_1.normalizeItemId)(template.templateId);
+        const runSearch = () => client.search({
+            index: options.index,
+            latestVersionOnly: true,
+            paging: { pageSize: 1 },
+            searchStatement: {
+                operator: "SHOULD",
+                subStatements: [
+                    {
+                        criteria: {
+                            field: "_template",
+                            value,
+                            criteriaType: "EXACT",
+                        },
+                    },
+                    {
+                        criteria: {
+                            field: "_basetemplates",
+                            value,
+                            criteriaType: "CONTAINS",
+                        },
+                    },
+                    {
+                        criteria: {
+                            field: "__masters",
+                            value,
+                            criteriaType: "CONTAINS",
+                        },
+                    },
+                    {
+                        criteria: {
+                            field: "datasource template",
+                            value,
+                            criteriaType: "CONTAINS",
+                        },
+                    },
+                ],
+            },
+        });
+        // Transient GraphQL errors ("Service Unavailable", "circuit
+        // breaker", etc.) surface as 200-with-errors and bypass the
+        // shared HTTP retry. Wrap the per-template search so one flaky
+        // backend response doesn't kill an entire dead-templates run.
+        const page = await retryOnTransient(runSearch, {
+            attempts: 4,
+            baseDelayMs: 1000,
+            logger,
+            label: `template ${template.fullName ?? template.name}`,
+        });
+        return { template, itemCount: page.totalCount };
+    }, concurrency);
+    // A template is "dead" only when nothing — direct or inherited —
+    // depends on it. The SHOULD query above OR's four signals:
+    //   1. `_template = <id>` → items whose primary template IS this one.
+    //      Sitecore typically excludes Standard Values from the index;
+    //      where they leak in, count is 1 and the template is correctly
+    //      NOT flagged as dead.
+    //   2. `_basetemplates CONTAINS <id>` → templates that derive from
+    //      this one through any depth of inheritance. SXA base
+    //      templates (`Project`, `Experience Accelerator`) have zero
+    //      direct items but many derived templates — without this check
+    //      they would be misclassified as dead.
+    //   3. `__masters CONTAINS <id>` → Standard-Values items whose
+    //      Insert Options list this template as an allowed child.
+    //      Deleting the template breaks the "Insert > <Name>" menu.
+    //   4. `datasource template CONTAINS <id>` → Rendering items pinning
+    //      this template as the datasource type. Deleting breaks
+    //      "Create Local Datasource" in Pages / Experience Editor.
+    const dead = checks
+        .filter((c) => c.itemCount === 0)
+        .map((c) => ({
+        templateId: c.template.templateId,
+        name: c.template.name,
+        fullName: c.template.fullName,
+        itemCount: 0,
+    }))
+        .sort((a, b) => (a.fullName ?? a.name).localeCompare(b.fullName ?? b.name));
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.dead-templates.list",
+        envName,
+        results: dead,
+        summary: `Inspected ${bounded.length} templates under ${root}; ${dead.length} dead.`,
+        formatLine: (r) => `${r.fullName ?? r.name} (${r.templateId.slice(0, 8)})`,
+        extra: { root, limit, scannedCount: bounded.length },
+        options,
+    });
+    return dead;
+};
+exports.runAuditDeadTemplates = runAuditDeadTemplates;

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

@@ -0,0 +1,48 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditDuplicatesOptions extends HygieneCommonOptions {
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    includeSystemFields?: boolean;
+    language?: string;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    /**
+     * Only flag groups with size >= `minGroupSize`. Default 2.
+     */
+    minGroupSize?: number;
+    /**
+     * Loosen the grouping key. Default key is
+     * `(contentHash, templateId, parentPath)` so items that hash
+     * identically only because their fields are all empty don't get
+     * conflated across unrelated templates / parents. Set this to
+     * `contentHash` only when you intentionally want to find cross-
+     * template byte-equivalent content (e.g. asset re-use audits).
+     */
+    groupBy?: ReadonlyArray<"contentHash" | "templateId" | "parentPath">;
+}
+export interface DuplicatesGroup {
+    contentHash: string;
+    /** Template ID shared by every member in the group (or null). */
+    templateId: string | null;
+    /** Parent path shared by every member in the group. */
+    parentPath: string | null;
+    count: number;
+    members: Array<{
+        itemId: string;
+        path: string;
+        templateName: string | null;
+        language: string | null;
+        createdDate: string | null;
+        updatedDate: string | null;
+    }>;
+}
+/**
+ * Audit content for items with byte-identical authored content,
+ * grouped by content hash. See `computeContentHash` for the hash
+ * input policy (sorted fields, system fields excluded by default).
+ */
+export declare const runAuditDuplicates: (options: AuditDuplicatesOptions) => Promise<DuplicatesGroup[]>;

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

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditDuplicates = void 0;
+const shared_1 = require("../shared");
+const parentOfPath = (p) => {
+    const idx = p.lastIndexOf("/");
+    return idx > 0 ? p.slice(0, idx) : "/";
+};
+/**
+ * Audit content for items with byte-identical authored content,
+ * grouped by content hash. See `computeContentHash` for the hash
+ * input policy (sorted fields, system fields excluded by default).
+ */
+const runAuditDuplicates = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const minGroupSize = options.minGroupSize ?? 2;
+    const { scanned, fieldsByItemId, cache } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    // Default group key tightens the dedup from "byte-identical content"
+    // to "byte-identical content under the same template at the same
+    // parent". Pre-2026 the key was just contentHash, which lumped
+    // together empty Folder + empty Page items because their field-set
+    // hashes collapse to the same digest. Override via --group-by to opt
+    // back into the looser key when investigating cross-template reuse.
+    const groupBy = new Set(options.groupBy ?? ["contentHash", "templateId", "parentPath"]);
+    if (!groupBy.has("contentHash"))
+        groupBy.add("contentHash");
+    const groups = new Map();
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        const hash = await (0, shared_1.computeContentHash)(fields, {
+            includeSystem: options.includeSystemFields,
+        });
+        if (!hash)
+            continue;
+        const parentPath = parentOfPath(item.path);
+        const keyParts = [
+            hash,
+            groupBy.has("templateId") ? (item.templateId ?? "no-tmpl") : "*",
+            groupBy.has("parentPath") ? parentPath : "*",
+        ];
+        const key = keyParts.join("|");
+        const existing = groups.get(key);
+        const member = {
+            itemId: item.itemId,
+            path: item.path,
+            templateName: item.templateName,
+            language: item.language,
+            createdDate: item.createdDate,
+            updatedDate: item.updatedDate,
+        };
+        if (existing) {
+            existing.members.push(member);
+            existing.count = existing.members.length;
+        }
+        else {
+            groups.set(key, {
+                contentHash: hash,
+                templateId: groupBy.has("templateId") ? item.templateId : null,
+                parentPath: groupBy.has("parentPath") ? parentPath : null,
+                count: 1,
+                members: [member],
+            });
+        }
+    }
+    const duplicates = Array.from(groups.values())
+        .filter((g) => g.count >= minGroupSize)
+        .sort((a, b) => b.count - a.count);
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.duplicates.list",
+        envName,
+        results: duplicates,
+        summary: `Scanned ${scanned.length} items; ${duplicates.length} duplicate group${duplicates.length === 1 ? "" : "s"} (>= ${minGroupSize} members each).`,
+        formatLine: (g) => `[${g.contentHash}] ${g.count}× : ${g.members
+            .slice(0, 3)
+            .map((m) => m.path)
+            .join(", ")}${g.count > 3 ? "…" : ""}`,
+        extra: { root, scannedCount: scanned.length, minGroupSize },
+        options,
+    });
+    return duplicates;
+};
+exports.runAuditDuplicates = runAuditDuplicates;

package/dist/hygiene/tasks/audit/empty-items.d.ts

@@ -0,0 +1,24 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditEmptyItemsOptions extends HygieneCommonOptions {
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    language?: string;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+}
+export interface EmptyItemReport {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string | null;
+    createdDate: string | null;
+    updatedDate: string | null;
+}
+/**
+ * Audit content for items with no authored field values.
+ */
+export declare const runAuditEmptyItems: (options: AuditEmptyItemsOptions) => Promise<EmptyItemReport[]>;

package/dist/hygiene/tasks/audit/empty-items.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditEmptyItems = void 0;
+const shared_1 = require("../shared");
+/**
+ * Audit content for items with no authored field values.
+ */
+const runAuditEmptyItems = 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 } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const empty = [];
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        const authored = fields.filter((f) => !f.name.startsWith("__"));
+        if (authored.length === 0)
+            continue; // folder-like (no author-facing fields).
+        const hasValue = authored.some((f) => (f.value ?? "").trim().length > 0);
+        if (hasValue)
+            continue;
+        empty.push({
+            itemId: item.itemId,
+            path: item.path,
+            templateName: item.templateName,
+            language: item.language,
+            createdDate: item.createdDate,
+            updatedDate: item.updatedDate,
+        });
+    }
+    empty.sort((a, b) => a.path.localeCompare(b.path));
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.empty-items.list",
+        envName,
+        results: empty,
+        summary: `Scanned ${scanned.length} items; ${empty.length} have no authored content.`,
+        formatLine: (r) => `${r.path}${r.templateName ? ` (${r.templateName})` : ""}${r.language ? ` @${r.language}` : ""}`,
+        extra: { root, scannedCount: scanned.length },
+        options,
+    });
+    return empty;
+};
+exports.runAuditEmptyItems = runAuditEmptyItems;

package/dist/hygiene/tasks/audit/empty-links.d.ts

@@ -0,0 +1,37 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditEmptyLinksOptions extends HygieneCommonOptions {
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    language?: string;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    exclude?: string[];
+    since?: string;
+    owner?: string;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Restrict by template name pattern. Default scans every item.
+     * Most operators want to scope this — e.g. `--template-pattern
+     * CTA|Button|Card` — because every Page template has at least one
+     * "navigation" link field that's expected to be empty on standalone
+     * landing pages.
+     */
+    templatePattern?: string;
+}
+export interface EmptyLinkReport {
+    itemId: string;
+    path: string;
+    templateName: string | null;
+    language: string | null;
+    emptyFields: Array<{
+        fieldName: string;
+        reason: "no-link-tag" | "empty-attributes";
+    }>;
+}
+export declare const runAuditEmptyLinks: (options: AuditEmptyLinksOptions) => Promise<EmptyLinkReport[]>;

package/dist/hygiene/tasks/audit/empty-links.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditEmptyLinks = void 0;
+const shared_1 = require("../shared");
+/**
+ * Audit for Sitecore General Link fields whose value is structurally
+ * present but functionally empty.
+ *
+ * General Link fields store XML like:
+ *
+ *   <link linktype="internal" id="{guid}" />
+ *   <link linktype="external" url="https://..." />
+ *   <link linktype="anchor" anchor="section-2" />
+ *   <link linktype="mailto" url="mailto:..." />
+ *
+ * The cases this catches:
+ *
+ *   1. **No `<link>` tag at all** — the field value is empty or just
+ *      whitespace. The button/CTA renders, the link goes nowhere.
+ *   2. **`<link>` with no target** — every targeting attribute (`url`,
+ *      `id`, `anchor`, `mediaid`) is empty or absent. Same outcome
+ *      from the visitor's perspective.
+ *
+ * What this is NOT:
+ *   - `audit broken-links` — internal `id="{guid}"` pointing at an item
+ *     that doesn't exist (the link is filled in, just to a ghost).
+ *   - `audit empty-items` — items where every field is empty.
+ *
+ * Strategy:
+ *   1. Scan items + fields via `scanItemsAndFields`.
+ *   2. For each field value, look for `<link …/>` markup. The
+ *      `linktype` attribute disambiguates "link field" from raw text.
+ *   3. Classify: missing tag (reason: no-link-tag) vs empty-targeting
+ *      attributes (reason: empty-attributes).
+ *
+ * Field detection: General Link fields ALWAYS produce a `<link>` tag
+ * when populated. A non-link field value happens to contain "<link"
+ * only when an operator stuffed XML into a Single-Line Text field —
+ * vanishingly rare, and the false positive rate is "the value really
+ * does encode a broken link," so we don't filter on field type.
+ */
+const LINK_TAG_PATTERN = /<link\b[^>]*\/?>/gi;
+const TARGET_ATTRS = ["url", "id", "anchor", "mediaid", "querystring"];
+const LINKTYPE_ATTR_PATTERN = /\blinktype=["']([^"']*)["']/i;
+const hasMeaningfulTarget = (tag) => {
+    for (const attr of TARGET_ATTRS) {
+        const re = new RegExp(`\\b${attr}=["']([^"']*)["']`, "i");
+        const m = re.exec(tag);
+        if (m && m[1] && m[1].trim().length > 0)
+            return true;
+    }
+    return false;
+};
+const valueLooksLikeLinkField = (value) => {
+    // A populated General Link field has at least one `<link …/>` tag.
+    // Empty / never-populated fields are empty strings — we want to
+    // ignore those unless the operator's pattern says otherwise (e.g.
+    // a CTA template whose Link field should always be set).
+    return /<link\b/i.test(value);
+};
+const runAuditEmptyLinks = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const templateRegex = options.templatePattern ? new RegExp(options.templatePattern, "i") : null;
+    const { scanned, fieldsByItemId, cache } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const reports = [];
+    for (const item of scanned) {
+        if (templateRegex && !templateRegex.test(item.templateName ?? ""))
+            continue;
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        const offending = [];
+        for (const field of fields) {
+            if (field.name.startsWith("__"))
+                continue;
+            // Two cases produce a finding:
+            //   - Field value contains a `<link>` whose targeting attributes
+            //     are empty — reason: empty-attributes.
+            //   - Field name matches a "this is supposed to be a link" hint
+            //     (Link / CallToAction / CTA / Url) and the value is blank —
+            //     reason: no-link-tag.
+            // We DON'T flag every empty field on every template — that's
+            // `audit empty-items`. Without the name hint we'd false-positive
+            // on every Single-Line Text field that happens to be empty.
+            const value = field.value ?? "";
+            if (valueLooksLikeLinkField(value)) {
+                const matches = value.match(LINK_TAG_PATTERN);
+                if (!matches)
+                    continue;
+                for (const tag of matches) {
+                    // Ignore tags with no linktype attribute — they're not real
+                    // General Link payloads (matched by accident on raw <link>
+                    // tags in RichText/HTML, e.g. `<link rel="stylesheet" …>`).
+                    const linktypeMatch = LINKTYPE_ATTR_PATTERN.exec(tag);
+                    if (!linktypeMatch)
+                        continue;
+                    if (!hasMeaningfulTarget(tag)) {
+                        offending.push({ fieldName: field.name, reason: "empty-attributes" });
+                    }
+                }
+            }
+            else if (
+            // Field-name hint: ends in (or equals) "Link" / "Cta" / "CallToAction" / "Url" /
+            // "Href" — case-insensitive. The end-anchor catches camelCase variants like
+            // "PrimaryCTA" / "BaseUrl" / "HeroLink" without false-positive matching against
+            // "Surl" or "Blinking". A separator (start-of-string, [A-Z_-]) at the head
+            // prevents matching mid-word.
+            /(?:^|[A-Z_-])(link|cta|calltoaction|call-to-action|url|href)$/i.test(field.name) &&
+                value.trim().length === 0) {
+                offending.push({ fieldName: field.name, reason: "no-link-tag" });
+            }
+        }
+        if (offending.length > 0) {
+            reports.push({
+                itemId: item.itemId,
+                path: item.path,
+                templateName: item.templateName,
+                language: item.language,
+                emptyFields: offending,
+            });
+        }
+    }
+    reports.sort((a, b) => a.path.localeCompare(b.path));
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.empty-links.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned.length} items; ${reports.length} have empty link fields.`,
+        formatLine: (r) => `${r.path} — ${r.emptyFields.map((f) => `${f.fieldName}(${f.reason})`).join(", ")}`,
+        extra: { root, scannedCount: scanned.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditEmptyLinks = runAuditEmptyLinks;

package/dist/hygiene/tasks/audit/empty-roles.d.ts

@@ -0,0 +1,41 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditEmptyRolesOptions extends HygieneCommonOptions {
+    /**
+     * Restrict to a specific domain. Defaults to all domains. Sitecore's
+     * built-in roles live in the `sitecore` and `extranet` domains; many
+     * tenants add project-specific roles in their own domain.
+     */
+    domain?: string;
+    /** Cap on roles inspected. Default 5000. */
+    limit?: number;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+}
+export interface EmptyRoleReport {
+    name: string;
+    domain: string | null;
+}
+/**
+ * Audit roles that have zero direct members.
+ *
+ * Empty roles accumulate when:
+ *   - A role was created for a project that never shipped.
+ *   - Migrations remove users from a role but leave the role behind.
+ *   - Custom workflows define roles that are referenced by no item.
+ *
+ * The Authoring API's `Role.members` is paged via AccountConnection,
+ * which doesn't expose `totalCount`. The hygiene client uses
+ * `members(first: 1)` to detect "has at least one member" cheaply.
+ * If the connection's `nodes` is empty, the role is empty.
+ *
+ * Notes:
+ *   - Sitecore's `Everyone` role is implicit-membership (every user is
+ *     a member by default); `isEveryone: true` roles are filtered out
+ *     to avoid noise.
+ *   - This audit doesn't detect "role with no permissions attached" —
+ *     the Authoring API exposes role membership but not per-role ACL
+ *     bindings. Such roles can be cleaned up only after a manual
+ *     review of role usage.
+ */
+export declare const runAuditEmptyRoles: (options: AuditEmptyRolesOptions) => Promise<EmptyRoleReport[]>;