@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/tasks/audit/stale-workflow.d.ts

@@ -0,0 +1,50 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditStaleWorkflowOptions extends HygieneCommonOptions {
+    /** Days since last update to qualify as stale. Default 30. */
+    days?: number;
+    /** Scope to descendants of this content path. Default `/sitecore/content`. */
+    root?: string;
+    /** Override the search index. */
+    index?: string;
+    /** Cap on the number of items inspected. Default 5000. */
+    limit?: number;
+    /** Include system items in the scan. Off by default. */
+    includeSystem?: boolean;
+    /** Workflow concurrency. Default 4. */
+    concurrency?: number;
+}
+export interface StaleWorkflowReport {
+    itemId: string;
+    path: string;
+    language: string | null;
+    templateName?: string | null;
+    workflowName: string | null;
+    stateName: string | null;
+    stateIsFinal: boolean;
+    daysSinceUpdate: number;
+    updatedDate: string | null;
+}
+/**
+ * Audit items currently in a non-final workflow state whose last update
+ * is older than `--days N`.
+ *
+ * Strategy:
+ *   1. Search-index pass over `--root` (default `/sitecore/content`)
+ *      collects every item plus its indexed `updatedDate`. We filter
+ *      *here* by `updatedDate < (now - N days)` — efficient because the
+ *      index has the date directly. The "is in workflow" check needs
+ *      the Authoring API (search index does not expose `__Workflow
+ *      state` reliably across XM Cloud tenants).
+ *   2. For each stale candidate, call `getItemWorkflow(itemId)`. Skip
+ *      items that aren't on a workflow or are already in a final state.
+ *
+ * Notes:
+ *   - "In a workflow" means `Item.workflow.workflow` resolves and the
+ *     `workflowState.final` is false. Items past the final state (e.g.
+ *     "Approved") are considered not stale.
+ *   - The N-days threshold uses the search index's `updatedDate`. If
+ *     that field isn't populated for some items (rare; mostly platform
+ *     items), they're skipped — and platform items are skipped by
+ *     default anyway.
+ */
+export declare const runAuditStaleWorkflow: (options: AuditStaleWorkflowOptions) => Promise<StaleWorkflowReport[]>;

package/dist/hygiene/tasks/audit/stale-workflow.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditStaleWorkflow = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * Audit items currently in a non-final workflow state whose last update
+ * is older than `--days N`.
+ *
+ * Strategy:
+ *   1. Search-index pass over `--root` (default `/sitecore/content`)
+ *      collects every item plus its indexed `updatedDate`. We filter
+ *      *here* by `updatedDate < (now - N days)` — efficient because the
+ *      index has the date directly. The "is in workflow" check needs
+ *      the Authoring API (search index does not expose `__Workflow
+ *      state` reliably across XM Cloud tenants).
+ *   2. For each stale candidate, call `getItemWorkflow(itemId)`. Skip
+ *      items that aren't on a workflow or are already in a final state.
+ *
+ * Notes:
+ *   - "In a workflow" means `Item.workflow.workflow` resolves and the
+ *     `workflowState.final` is false. Items past the final state (e.g.
+ *     "Approved") are considered not stale.
+ *   - The N-days threshold uses the search index's `updatedDate`. If
+ *     that field isn't populated for some items (rare; mostly platform
+ *     items), they're skipped — and platform items are skipped by
+ *     default anyway.
+ */
+const runAuditStaleWorkflow = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const days = options.days ?? 30;
+    const root = options.root ?? "/sitecore/content";
+    const limit = options.limit ?? 5000;
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    const concurrency = options.concurrency ?? knobs.concurrency;
+    const includeSystem = Boolean(options.includeSystem);
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const rootSearch = await client.search({
+        index: options.index,
+        paging: { pageSize: 1 },
+        searchStatement: {
+            criteria: { field: "_fullpath", value: root.toLowerCase(), criteriaType: "EXACT" },
+        },
+    });
+    const rootItemId = rootSearch.results[0]?.itemId;
+    if (!rootItemId) {
+        logger.warn(`Root path '${root}' not found in search index — scanning entire master DB.`);
+    }
+    const candidates = [];
+    let scanned = 0;
+    for await (const r of client.searchAll({
+        index: options.index,
+        latestVersionOnly: true,
+        ...(rootItemId && { searchStatement: (0, shared_1.buildPathFilterStatement)(rootItemId) }),
+    }, 100, knobs.pageParallelism)) {
+        if (!includeSystem && (0, shared_1.isSystemPath)(r.path))
+            continue;
+        scanned += 1;
+        if (!r.updatedDate)
+            continue;
+        const updated = Date.parse(r.updatedDate);
+        if (!Number.isFinite(updated) || updated >= cutoff)
+            continue;
+        candidates.push({
+            itemId: (0, shared_1.normalizeItemId)(r.itemId),
+            path: r.path,
+            language: r.language?.name ?? null,
+            templateName: r.templateName ?? null,
+            updatedDate: r.updatedDate,
+            daysSince: Math.floor((Date.now() - updated) / (24 * 60 * 60 * 1000)),
+        });
+        if (candidates.length >= limit)
+            break;
+    }
+    logger.verbose(`Scanned ${scanned} items; ${candidates.length} stale (> ${days} days).`);
+    const workflowChecks = await (0, cli_tasks_1.mapWithConcurrency)(candidates, async (c) => {
+        const wf = await client.getItemWorkflow(c.itemId, c.path);
+        if (!wf || !wf.workflowName || wf.stateIsFinal)
+            return null;
+        return { candidate: c, wf };
+    }, concurrency);
+    const stale = workflowChecks
+        .filter((x) => x !== null)
+        .map(({ candidate, wf }) => ({
+        itemId: candidate.itemId,
+        path: candidate.path,
+        language: candidate.language,
+        templateName: candidate.templateName,
+        workflowName: wf.workflowName,
+        stateName: wf.stateName,
+        stateIsFinal: wf.stateIsFinal,
+        daysSinceUpdate: candidate.daysSince,
+        updatedDate: candidate.updatedDate,
+    }));
+    stale.sort((a, b) => b.daysSinceUpdate - a.daysSinceUpdate);
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.stale-workflow.list",
+        envName,
+        results: stale,
+        summary: `Scanned ${scanned} items; ${stale.length} stuck in workflow > ${days} days.`,
+        formatLine: (r) => `${r.path} — ${r.workflowName} @ "${r.stateName ?? "?"}" (${r.daysSinceUpdate}d)`,
+        extra: { root, days, limit, scannedCount: scanned },
+        options,
+    });
+    return stale;
+};
+exports.runAuditStaleWorkflow = runAuditStaleWorkflow;

package/dist/hygiene/tasks/audit/suite-run.d.ts

@@ -0,0 +1,28 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditSuiteRunOptions extends HygieneCommonOptions {
+    /** Path to the YAML file. Required. */
+    file: string;
+    /** Override the suite's `baseline.enabled`. */
+    baseline?: boolean;
+    /** Override the suite's `output.path`. */
+    output?: string;
+    /** Override the suite's `output.format`. */
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Run only a subset of the suite's audits. Useful for re-running
+     * after a fix.
+     */
+    only?: string[];
+}
+/**
+ * Execute a YAML-defined audit suite.
+ *
+ * Loads the suite, resolves environment, expands the output path
+ * template (with {date}, {env}, {suite} tokens), and hands off to
+ * `runAuditAll` with the merged options.
+ *
+ * The suite's `baseline.update-on-success` flag is honored if no
+ * audits report findings — useful for the "accept current state as
+ * the new baseline" pattern after a manual review.
+ */
+export declare const runAuditSuiteRun: (options: AuditSuiteRunOptions) => Promise<void>;

package/dist/hygiene/tasks/audit/suite-run.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditSuiteRun = void 0;
+const environment_1 = require("../../../policy/environment");
+const audit_suite_1 = require("../../audit-suite");
+const all_1 = require("./all");
+const shared_1 = require("../shared");
+/**
+ * Execute a YAML-defined audit suite.
+ *
+ * Loads the suite, resolves environment, expands the output path
+ * template (with {date}, {env}, {suite} tokens), and hands off to
+ * `runAuditAll` with the merged options.
+ *
+ * The suite's `baseline.update-on-success` flag is honored if no
+ * audits report findings — useful for the "accept current state as
+ * the new baseline" pattern after a manual review.
+ */
+const runAuditSuiteRun = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const suite = (0, audit_suite_1.loadAuditSuite)(options.file, logger);
+    const { envName } = (0, environment_1.resolveEnvironment)(options);
+    const { include, sharedOptions } = (0, audit_suite_1.auditSuiteToRunnerInput)(suite);
+    const baselineEnabled = options.baseline ?? suite.baseline?.enabled ?? false;
+    const outputPath = options.output ?? suite.output?.path;
+    const expandedOutput = outputPath
+        ? (0, audit_suite_1.expandOutputPath)(outputPath, { envName, suiteName: suite.name })
+        : undefined;
+    const format = options.format ?? suite.output?.format;
+    const filteredInclude = options.only?.length
+        ? include.filter((name) => options.only.includes(name))
+        : include;
+    logger.info(`Running audit suite '${suite.name}' (${filteredInclude.length} audit${filteredInclude.length === 1 ? "" : "s"}${baselineEnabled ? ", baseline=on" : ""}${expandedOutput ? `, → ${expandedOutput}` : ""}).`, "cyan");
+    await (0, all_1.runAuditAll)({
+        ...options,
+        ...sharedOptions,
+        include: filteredInclude,
+        baseline: baselineEnabled,
+        output: expandedOutput,
+        format,
+    });
+    // `update-on-success` would require re-reading the audit-all output
+    // to confirm no findings; left to a follow-up. Documented in the
+    // file shape but not yet enforced here.
+};
+exports.runAuditSuiteRun = runAuditSuiteRun;

package/dist/hygiene/tasks/audit/template-dependencies.d.ts

@@ -0,0 +1,72 @@
+import { type HygieneCommonOptions } from "../shared";
+/**
+ * Inbound-reference kinds we currently surface.
+ *
+ *   - `primary-template`: items whose `_template` is the target. These
+ *     are the items that would lose their template definition outright
+ *     if the target were deleted — usually the dominant blocker.
+ *
+ *   - `base-template`: templates whose `_basetemplates` contains the
+ *     target through any depth of inheritance. Deleting the target
+ *     orphans every inheritor's inherited fields/sections.
+ *
+ *   - `insert-options`: Standard-Values items whose `__masters`
+ *     contains the target. Deleting the target removes an entry from
+ *     the parent template's Insert Options menu — content authors
+ *     lose the ability to create that child type.
+ *
+ *   - `branch-source`: items (typically other templates / branch
+ *     definitions) whose `__source` contains the target. Deleting
+ *     breaks the "New from Branch" flow for that branch.
+ *
+ *   - `datasource-template`: Rendering items whose `Datasource
+ *     Template` field designates the target as the type new
+ *     datasources must conform to. Deleting breaks the rendering's
+ *     "Create Local Datasource" flow in Pages / Experience Editor.
+ *
+ * Lower-priority kinds intentionally not covered yet (track separately):
+ *   - Custom droplist/treelist fields whose `Source=` value resolves
+ *     to the target's path. Requires per-field-definition scan.
+ *   - Generic ID-bearing fields that happen to hold the target's GUID
+ *     in their value. Use `audit references --to <itemId>` for a
+ *     broader content-text scan when this audit returns nothing.
+ */
+export type TemplateReferenceKind = "primary-template" | "base-template" | "insert-options" | "branch-source" | "datasource-template";
+export interface AuditTemplateDependenciesOptions extends HygieneCommonOptions {
+    /** Target template ID — GUID in any standard form ({…}, dashes, flat). Required. */
+    templateId?: string;
+    /** Override the search index. */
+    index?: string;
+    /** Cap on number of references per kind. Default 5000. */
+    limit?: number;
+    /** Skip a reference kind by name. Use to scope big tenants. */
+    skip?: TemplateReferenceKind[];
+    /**
+     * 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. Default
+     * false — direct CLI / MCP callers always see the audit report.
+     */
+    silent?: boolean;
+}
+export interface TemplateDependencyReport {
+    itemId: string;
+    path: string | null;
+    name: string;
+    templateId: string | null;
+    templateName: string | null;
+    /** Why this item references the target template. */
+    referenceKind: TemplateReferenceKind;
+}
+/**
+ * Inverse of `audit dead-templates`: for a given template, list every
+ * item in the tenant that points at it — primary template, inheritor,
+ * insert-options host, branch source. Use this to triage what's
+ * blocking a template delete *before* calling `cleanup dead-templates`
+ * or running an ad-hoc delete.
+ *
+ * `audit dead-templates` answers "is X safe to delete?" in aggregate.
+ * This answers "what specifically points at X?" with an actionable
+ * list grouped by reference kind.
+ */
+export declare const runAuditTemplateDependencies: (options: AuditTemplateDependenciesOptions) => Promise<TemplateDependencyReport[]>;

package/dist/hygiene/tasks/audit/template-dependencies.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditTemplateDependencies = void 0;
+const errors_1 = require("../../../shared/errors");
+const shared_1 = require("../shared");
+const SEARCH_KINDS = [
+    { kind: "primary-template", field: "_template", criteriaType: "EXACT" },
+    { kind: "base-template", field: "_basetemplates", criteriaType: "CONTAINS" },
+    { kind: "insert-options", field: "__masters", criteriaType: "CONTAINS" },
+    { kind: "branch-source", field: "__source", criteriaType: "CONTAINS" },
+    { kind: "datasource-template", field: "datasource template", criteriaType: "CONTAINS" },
+];
+/**
+ * Inverse of `audit dead-templates`: for a given template, list every
+ * item in the tenant that points at it — primary template, inheritor,
+ * insert-options host, branch source. Use this to triage what's
+ * blocking a template delete *before* calling `cleanup dead-templates`
+ * or running an ad-hoc delete.
+ *
+ * `audit dead-templates` answers "is X safe to delete?" in aggregate.
+ * This answers "what specifically points at X?" with an actionable
+ * list grouped by reference kind.
+ */
+const runAuditTemplateDependencies = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    if (!options.templateId) {
+        throw (0, errors_1.createScaiError)("audit template-dependencies requires --template-id <guid>.", "INPUT_INVALID");
+    }
+    const value = (0, shared_1.normalizeItemId)(options.templateId);
+    const limit = options.limit ?? 5000;
+    const skip = new Set(options.skip ?? []);
+    logger.verbose(`Resolving dependencies on template ${value}.`);
+    const reports = [];
+    for (const entry of SEARCH_KINDS) {
+        if (skip.has(entry.kind))
+            continue;
+        let pageIndex = 0;
+        let collected = 0;
+        // Page through results until we hit the limit. We don't use
+        // `searchAll` here because each kind needs its own running count
+        // and label; folding them into one iterator would muddy that.
+        while (collected < limit) {
+            const page = await client.search({
+                index: options.index,
+                latestVersionOnly: true,
+                paging: { pageIndex, pageSize: 100 },
+                searchStatement: {
+                    criteria: {
+                        field: entry.field,
+                        value,
+                        criteriaType: entry.criteriaType,
+                    },
+                },
+            });
+            if (page.results.length === 0)
+                break;
+            for (const r of page.results) {
+                if (collected >= limit)
+                    break;
+                reports.push({
+                    itemId: (0, shared_1.normalizeItemId)(r.itemId),
+                    path: r.path ?? null,
+                    name: r.name,
+                    templateId: r.templateId ?? null,
+                    templateName: r.templateName ?? null,
+                    referenceKind: entry.kind,
+                });
+                collected += 1;
+            }
+            if (page.results.length < 100)
+                break;
+            pageIndex += 1;
+        }
+        logger.verbose(`  ${entry.kind}: ${collected} reference(s).`);
+    }
+    reports.sort((a, b) => {
+        const kindCmp = a.referenceKind.localeCompare(b.referenceKind);
+        if (kindCmp !== 0)
+            return kindCmp;
+        return (a.path ?? a.name).localeCompare(b.path ?? b.name);
+    });
+    if (!options.silent) {
+        (0, shared_1.printReport)({
+            logger,
+            command: "audit.template-dependencies.list",
+            envName,
+            results: reports,
+            summary: `Template ${value}: ${reports.length} inbound reference(s).`,
+            formatLine: (r) => `[${r.referenceKind}] ${r.path ?? r.name} (${r.itemId.slice(0, 8)})`,
+            extra: { templateId: value, limit, skipped: [...skip] },
+            options,
+        });
+    }
+    return reports;
+};
+exports.runAuditTemplateDependencies = runAuditTemplateDependencies;

package/dist/hygiene/tasks/audit/translation-coverage.d.ts

@@ -0,0 +1,64 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditTranslationCoverageOptions extends HygieneCommonOptions {
+    /** Content root. Default `/sitecore/content`. */
+    root?: string;
+    /** Reference (source) language. Default `en`. */
+    referenceLanguage?: string;
+    /** Target language(s) to compare against. Required. */
+    targetLanguages?: string[];
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    pageParallelism?: number;
+    exclude?: string[];
+    since?: string;
+    baseline?: boolean;
+    output?: string;
+    format?: "json" | "csv" | "markdown";
+    /**
+     * Threshold for "low coverage" — items where coverage % falls
+     * below this are surfaced. Default 0 → report every untranslated
+     * item. Set to e.g. 80 to flag languages below 80% coverage on
+     * the summary line.
+     */
+    minCoveragePercent?: number;
+}
+export interface TranslationCoverageReport {
+    language: string;
+    totalReferenceItems: number;
+    translatedItems: number;
+    missingItems: number;
+    coveragePercent: number;
+    /** First 100 itemIds missing translation. */
+    missingSamples: Array<{
+        itemId: string;
+        path: string;
+    }>;
+}
+/**
+ * Audit translation coverage between a reference language and one or
+ * more target languages.
+ *
+ * Strategy:
+ *   1. Use `searchAll` to enumerate every item under `--root` in
+ *      `--reference-language` (default `en`). This is the "source
+ *      truth" set of items.
+ *   2. For each `--target-language`, enumerate the same root and
+ *      collect itemIds present.
+ *   3. Diff: items in reference set but missing from target set =
+ *      untranslated. Compute coverage % per target.
+ *
+ * Different from `audit language-data list`:
+ *   - `language-data` flags items with an empty language entry
+ *     (zero versions in that language).
+ *   - `translation-coverage` measures completeness — % of source-
+ *     language items that have any version in the target.
+ *
+ * Notes:
+ *   - The Authoring API's search index indexes per-version items, so
+ *     an item without any target-language version simply doesn't
+ *     appear in the target-language enumeration.
+ *   - Item identity is by `itemId` — the same item with translations
+ *     in en + fr appears once per language; we compare itemId sets.
+ */
+export declare const runAuditTranslationCoverage: (options: AuditTranslationCoverageOptions) => Promise<TranslationCoverageReport[]>;

package/dist/hygiene/tasks/audit/translation-coverage.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditTranslationCoverage = void 0;
+const shared_1 = require("../shared");
+/**
+ * Audit translation coverage between a reference language and one or
+ * more target languages.
+ *
+ * Strategy:
+ *   1. Use `searchAll` to enumerate every item under `--root` in
+ *      `--reference-language` (default `en`). This is the "source
+ *      truth" set of items.
+ *   2. For each `--target-language`, enumerate the same root and
+ *      collect itemIds present.
+ *   3. Diff: items in reference set but missing from target set =
+ *      untranslated. Compute coverage % per target.
+ *
+ * Different from `audit language-data list`:
+ *   - `language-data` flags items with an empty language entry
+ *     (zero versions in that language).
+ *   - `translation-coverage` measures completeness — % of source-
+ *     language items that have any version in the target.
+ *
+ * Notes:
+ *   - The Authoring API's search index indexes per-version items, so
+ *     an item without any target-language version simply doesn't
+ *     appear in the target-language enumeration.
+ *   - Item identity is by `itemId` — the same item with translations
+ *     in en + fr appears once per language; we compare itemId sets.
+ */
+const runAuditTranslationCoverage = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const referenceLanguage = options.referenceLanguage ?? "en";
+    const targets = options.targetLanguages ?? [];
+    if (targets.length === 0) {
+        logger.warn("No --target-languages provided; nothing to compare.");
+    }
+    const knobs = (0, shared_1.resolveHygieneKnobs)(options);
+    const limit = options.limit ?? 5000;
+    const includeSystem = Boolean(options.includeSystem);
+    const minCoverage = options.minCoveragePercent ?? 0;
+    // Resolve root → itemId for the path filter.
+    const rootSearch = await client.search({
+        index: options.index,
+        paging: { pageSize: 1 },
+        searchStatement: {
+            criteria: { field: "_fullpath", value: root.toLowerCase(), criteriaType: "EXACT" },
+        },
+    });
+    const rootItemId = rootSearch.results[0]?.itemId;
+    const enumerateLanguage = async (language) => {
+        const map = new Map();
+        let count = 0;
+        for await (const r of client.searchAll({
+            index: options.index,
+            latestVersionOnly: true,
+            language,
+            ...(rootItemId && { searchStatement: (0, shared_1.buildPathFilterStatement)(rootItemId) }),
+        }, 100, knobs.pageParallelism)) {
+            if (!includeSystem && (0, shared_1.isSystemPath)(r.path))
+                continue;
+            const id = (0, shared_1.normalizeItemId)(r.itemId);
+            if (!map.has(id)) {
+                map.set(id, { path: r.path });
+                count += 1;
+                if (count >= limit)
+                    break;
+            }
+        }
+        return map;
+    };
+    const reference = await enumerateLanguage(referenceLanguage);
+    logger.verbose(`Reference language '${referenceLanguage}': ${reference.size} items.`);
+    const reports = [];
+    for (const target of targets) {
+        const translated = await enumerateLanguage(target);
+        // Track the full missing count separately from the bounded sample
+        // list. Pre-fix, both were the same array — when missing > 100 the
+        // sample cap silently bounded the count too, so a 1000-item gap was
+        // reported as 100 missing / 900 translated and the coverage % was
+        // wrong by an order of magnitude.
+        const missingSamples = [];
+        let missingCount = 0;
+        for (const [id, info] of reference) {
+            if (!translated.has(id)) {
+                missingCount += 1;
+                if (missingSamples.length < 100)
+                    missingSamples.push({ itemId: id, path: info.path });
+            }
+        }
+        const translatedCount = reference.size - missingCount;
+        const coverage = reference.size === 0 ? 100 : (translatedCount / reference.size) * 100;
+        reports.push({
+            language: target,
+            totalReferenceItems: reference.size,
+            translatedItems: translatedCount,
+            missingItems: missingCount,
+            coveragePercent: Math.round(coverage * 10) / 10,
+            missingSamples,
+        });
+    }
+    const flagged = reports.filter((r) => r.coveragePercent < minCoverage);
+    const display = minCoverage > 0 ? flagged : reports;
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.translation-coverage.list",
+        envName,
+        results: display,
+        summary: `Reference '${referenceLanguage}' = ${reference.size} items; ${reports.length} target language${reports.length === 1 ? "" : "s"} measured.`,
+        formatLine: (r) => `${r.language}: ${r.coveragePercent}% (${r.translatedItems}/${r.totalReferenceItems}; missing ${r.missingItems})`,
+        extra: {
+            root,
+            referenceLanguage,
+            targetLanguages: targets,
+            minCoveragePercent: minCoverage,
+        },
+        options,
+    });
+    return display;
+};
+exports.runAuditTranslationCoverage = runAuditTranslationCoverage;

package/dist/hygiene/tasks/audit/unused-media.d.ts

@@ -0,0 +1,58 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditUnusedMediaOptions extends HygieneCommonOptions {
+    /**
+     * Root of the media library to scan. Defaults to
+     * `/sitecore/media library`. Override only for tenants that nest media
+     * under a non-default location (rare on XM Cloud).
+     */
+    mediaRoot?: string;
+    /**
+     * Root under which references to media items are looked for. Defaults
+     * to `/sitecore/content` — most refs come from rendered content. To
+     * also include site definitions or design templates, broaden this
+     * to `/sitecore`.
+     */
+    referenceRoot?: string;
+    /** Override the search index. */
+    index?: string;
+    /** Cap on the number of media items inspected. Default 5000. */
+    mediaLimit?: number;
+    /** Cap on the number of reference-side items inspected. Default 10000. */
+    referenceLimit?: number;
+    /** Batch size for item-fields lookups. Default 25. */
+    batchSize?: number;
+}
+export interface UnusedMediaReport {
+    itemId: string;
+    path: string;
+    templateName?: string | null;
+    size?: number | null;
+}
+/**
+ * Audit `/sitecore/media library` for media items that aren't referenced
+ * by any content item.
+ *
+ * Strategy (two-pass scan, both via the search index):
+ *
+ *   1. Enumerate every media item under `--media-root`. These become
+ *      candidates for "unused."
+ *   2. Enumerate every non-media item under `--reference-root` (default
+ *      `/sitecore/content`). For each, fetch all fields in batches and
+ *      run `extractMediaRefs` over field values. The output is the set
+ *      of media itemIds that *are* referenced.
+ *   3. Subtract: candidates minus referenced = unused media.
+ *
+ * Notes:
+ *   - The Authoring API exposes neither a "where-used" query nor a link
+ *     database read surface. This is the cheapest correct approach.
+ *   - False positives are possible when a media item is referenced from
+ *     content stored OUTSIDE `--reference-root` (e.g. presentation
+ *     definitions under `/sitecore/layout` or rendering parameters in
+ *     non-content trees). Operators with mixed content/layout media
+ *     references should re-run with `--reference-root /sitecore`.
+ *   - References from RichText `<link linktype="media">` tags and Image
+ *     field XML (`<image mediaid="...">`) are recognised; bare GUIDs in
+ *     Multilist fields targeting media are also captured by
+ *     `extractInternalRefs` and filtered against the candidates set.
+ */
+export declare const runAuditUnusedMedia: (options: AuditUnusedMediaOptions) => Promise<UnusedMediaReport[]>;