@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

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

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditBrokenImages = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * Audit RichText fields for `<img src="...">` URLs that fail HTTP HEAD.
+ *
+ * Distinct from `audit unused-media` (media-library items with no
+ * inbound refs) and `audit datasource-missing` (rendering datasources
+ * not resolving). Here we follow external URLs in RichText content
+ * and report 404 / timeout / network errors.
+ *
+ * Strategy:
+ *   1. Enumerate items via `scanItemsAndFields`.
+ *   2. For each non-system field, parse `<img src="...">` tags.
+ *   3. De-dup URLs across all items, cap at `--url-limit`.
+ *   4. HEAD each URL with `--request-timeout-ms` timeout.
+ *   5. Report items whose URLs returned non-2xx (or timed out).
+ *
+ * Notes:
+ *   - HEAD is preferred but some CDNs reject HEAD with 405; we fall
+ *     back to GET with Range: bytes=0-0 in that case.
+ *   - `data:` URLs (base64-embedded images) are skipped — they don't
+ *     have a remote target.
+ *   - Sitecore mediaitem URLs (`/-/media/...`) are probed against the
+ *     tenant host (same origin). External CDN URLs hit their own host.
+ *   - `--exclude-domains cdn.example.com` skips that host entirely.
+ */
+const IMG_TAG_PATTERN = /<img\b[^>]*\bsrc=["']([^"']+)["']/gi;
+const runAuditBrokenImages = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    const { envName, environment, client } = (0, shared_1.resolveTenant)(options);
+    const root = options.root ?? "/sitecore/content";
+    const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+    const urlLimit = options.urlLimit ?? 500;
+    const excludeDomains = new Set((options.excludeDomains ?? []).map((d) => d.toLowerCase()));
+    const { scanned, fieldsByItemId, cache } = await (0, shared_1.scanItemsAndFields)({
+        client,
+        envName,
+        root,
+        logger,
+        options,
+    });
+    const pending = [];
+    const uniqueUrls = 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 (!field.value)
+                continue;
+            if (field.name.startsWith("__"))
+                continue;
+            let m;
+            const re = new RegExp(IMG_TAG_PATTERN);
+            while ((m = re.exec(field.value)) !== null) {
+                const url = m[1];
+                if (!url || url.startsWith("data:"))
+                    continue;
+                pending.push({
+                    itemId: item.itemId,
+                    path: item.path,
+                    templateName: item.templateName,
+                    language: item.language,
+                    fieldName: field.name,
+                    url,
+                });
+                uniqueUrls.add(url);
+            }
+        }
+    }
+    logger.verbose(`Found ${pending.length} <img> refs (${uniqueUrls.size} distinct).`);
+    // Resolve relative URLs (Sitecore mediaitem `/-/media/...`) against the
+    // tenant host.
+    const tenantOrigin = environment.host
+        ? environment.host.startsWith("http")
+            ? environment.host.replace(/\/$/, "")
+            : `https://${environment.host}`
+        : null;
+    const resolveUrl = (u) => {
+        if (u.startsWith("http://") || u.startsWith("https://"))
+            return u;
+        if (u.startsWith("//"))
+            return `https:${u}`;
+        if (u.startsWith("/") && tenantOrigin)
+            return `${tenantOrigin}${u}`;
+        return null; // relative path we can't resolve
+    };
+    const absoluteUrls = Array.from(uniqueUrls).slice(0, urlLimit);
+    const statusByUrl = new Map();
+    await (0, cli_tasks_1.mapWithConcurrency)(absoluteUrls, async (rawUrl) => {
+        const abs = resolveUrl(rawUrl);
+        if (!abs) {
+            statusByUrl.set(rawUrl, "skipped");
+            return;
+        }
+        let parsed;
+        try {
+            parsed = new URL(abs);
+        }
+        catch {
+            statusByUrl.set(rawUrl, "skipped");
+            return;
+        }
+        if (excludeDomains.has(parsed.host.toLowerCase())) {
+            statusByUrl.set(rawUrl, "skipped");
+            return;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
+        try {
+            let res = await fetch(abs, { method: "HEAD", signal: controller.signal });
+            // Some CDNs reject HEAD; fall back to a Range-limited GET.
+            if (res.status === 405 || res.status === 501) {
+                res = await fetch(abs, {
+                    method: "GET",
+                    headers: { Range: "bytes=0-0" },
+                    signal: controller.signal,
+                });
+            }
+            statusByUrl.set(rawUrl, res.status);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                statusByUrl.set(rawUrl, "timeout");
+            }
+            else {
+                statusByUrl.set(rawUrl, "network-error");
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }, 8);
+    // Build per-item reports for items with non-2xx URLs.
+    const byItem = new Map();
+    for (const p of pending) {
+        const status = statusByUrl.get(p.url);
+        if (status === undefined || status === "skipped")
+            continue;
+        if (typeof status === "number" && status >= 200 && status < 400)
+            continue;
+        const entry = { fieldName: p.fieldName, url: p.url, status };
+        const existing = byItem.get(p.itemId);
+        if (existing) {
+            if (!existing.brokenImages.some((b) => b.url === entry.url && b.fieldName === entry.fieldName)) {
+                existing.brokenImages.push(entry);
+            }
+        }
+        else {
+            byItem.set(p.itemId, {
+                itemId: p.itemId,
+                path: p.path,
+                templateName: p.templateName,
+                language: p.language,
+                brokenImages: [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.broken-images.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned.length} items; probed ${absoluteUrls.length} URLs; ${reports.length} items have broken images.`,
+        formatLine: (r) => `${r.path} — ${r.brokenImages.length} broken: ${r.brokenImages
+            .slice(0, 2)
+            .map((b) => `${b.fieldName}→${b.url} (${b.status})`)
+            .join("; ")}${r.brokenImages.length > 2 ? "…" : ""}`,
+        extra: {
+            root,
+            scannedCount: scanned.length,
+            urlsProbed: absoluteUrls.length,
+        },
+        options,
+    });
+    return reports;
+};
+exports.runAuditBrokenImages = runAuditBrokenImages;

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

@@ -0,0 +1,53 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditBrokenLinksOptions extends HygieneCommonOptions {
+    /**
+     * Limit the scan to descendants of this content-tree path (or itemId).
+     * Defaults to `/sitecore/content` — most authored content lives there
+     * and scanning the full master DB is rarely useful.
+     */
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    /** Opt-in to the on-disk field cache for this run. */
+    cache?: boolean;
+}
+export interface BrokenLinkReport {
+    itemId: string;
+    path: string;
+    templateName?: string | null;
+    language?: string | null;
+    brokenRefs: Array<{
+        fieldName: string;
+        refItemId: string;
+    }>;
+}
+/**
+ * Audit content for internal links that target items that don't exist.
+ *
+ * Strategy (XM Cloud Authoring API only — no direct link-database query):
+ *
+ *   1. Use `scanItemsAndFields` to page through `search` and batch-fetch
+ *      fields. The helper applies the active perf knobs (concurrency,
+ *      batchSize, pageParallelism) and the optional on-disk field cache.
+ *   2. Run `extractInternalRefs` over field values to collect referenced
+ *      itemIds (RichText `<link>` tags, bare GUIDs, pipe-delimited
+ *      Multilist values).
+ *   3. Resolve refs in bulk via `itemsExistBatch` — same concurrency as
+ *      field reads.
+ *   4. Emit a report row for every (item, field, ref) where ref doesn't
+ *      resolve.
+ *
+ * Notes:
+ *   - Scoped to **internal** Sitecore item refs only — external URLs
+ *     and media refs aren't surfaced here. `audit unused-media list`
+ *     handles the media side.
+ *   - The dotnet `Sitecore.DevEx` plugin had access to the SQL-backed
+ *     link database, which is O(N) in references rather than O(N) in
+ *     items + O(R) in refs. The Authoring GraphQL path is fundamentally
+ *     more expensive, hence the `--limit` cap.
+ */
+export declare const runAuditBrokenLinks: (options: AuditBrokenLinksOptions) => Promise<BrokenLinkReport[]>;

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

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditBrokenLinks = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * Audit content for internal links that target items that don't exist.
+ *
+ * Strategy (XM Cloud Authoring API only — no direct link-database query):
+ *
+ *   1. Use `scanItemsAndFields` to page through `search` and batch-fetch
+ *      fields. The helper applies the active perf knobs (concurrency,
+ *      batchSize, pageParallelism) and the optional on-disk field cache.
+ *   2. Run `extractInternalRefs` over field values to collect referenced
+ *      itemIds (RichText `<link>` tags, bare GUIDs, pipe-delimited
+ *      Multilist values).
+ *   3. Resolve refs in bulk via `itemsExistBatch` — same concurrency as
+ *      field reads.
+ *   4. Emit a report row for every (item, field, ref) where ref doesn't
+ *      resolve.
+ *
+ * Notes:
+ *   - Scoped to **internal** Sitecore item refs only — external URLs
+ *     and media refs aren't surfaced here. `audit unused-media list`
+ *     handles the media side.
+ *   - The dotnet `Sitecore.DevEx` plugin had access to the SQL-backed
+ *     link database, which is O(N) in references rather than O(N) in
+ *     items + O(R) in refs. The Authoring GraphQL path is fundamentally
+ *     more expensive, hence the `--limit` cap.
+ */
+const runAuditBrokenLinks = 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,
+    });
+    // Collect every referenced itemId across all scanned items. De-dup to
+    // avoid asking the API more than once for the same id.
+    const allRefs = new Set();
+    const pendingRefs = [];
+    const scannedById = new Map(scanned.map((s) => [s.itemId, s]));
+    for (const item of scanned) {
+        const fields = fieldsByItemId.get(item.itemId);
+        if (!fields || !Array.isArray(fields))
+            continue;
+        for (const field of fields) {
+            if (!field.value)
+                continue;
+            if (field.name.startsWith("__") && field.name !== "__Source Item")
+                continue;
+            const refs = (0, shared_1.extractInternalRefs)(field.value);
+            for (const ref of refs) {
+                if (ref === item.itemId)
+                    continue;
+                allRefs.add(ref);
+                pendingRefs.push({
+                    itemId: item.itemId,
+                    path: item.path,
+                    fieldName: field.name,
+                    refItemId: ref,
+                });
+            }
+        }
+    }
+    // Resolve refs in batches with the same perf knobs.
+    const refExists = new Map();
+    const refIds = Array.from(allRefs);
+    const refBatches = [];
+    for (let i = 0; i < refIds.length; i += knobs.batchSize) {
+        refBatches.push(refIds.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);
+    }
+    // Build per-item broken-link reports.
+    const byItem = new Map();
+    for (const p of pendingRefs) {
+        if (refExists.get(p.refItemId) !== false)
+            continue;
+        const meta = scannedById.get(p.itemId);
+        if (!meta)
+            continue;
+        const existing = byItem.get(p.itemId);
+        if (existing) {
+            existing.brokenRefs.push({ fieldName: p.fieldName, refItemId: p.refItemId });
+        }
+        else {
+            byItem.set(p.itemId, {
+                itemId: p.itemId,
+                path: meta.path,
+                templateName: meta.templateName,
+                language: meta.language,
+                brokenRefs: [{ fieldName: p.fieldName, refItemId: p.refItemId }],
+            });
+        }
+    }
+    const reports = Array.from(byItem.values()).sort((a, b) => a.path.localeCompare(b.path));
+    await cache?.flush();
+    (0, shared_1.printReport)({
+        logger,
+        command: "audit.broken-links.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned.length} items; ${reports.length} with broken internal links.`,
+        formatLine: (r) => `${r.path} (${r.brokenRefs.length} broken: ${r.brokenRefs
+            .slice(0, 3)
+            .map((b) => `${b.fieldName}→${b.refItemId.slice(0, 8)}`)
+            .join(", ")}${r.brokenRefs.length > 3 ? "…" : ""})`,
+        extra: { root, scannedCount: scanned.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditBrokenLinks = runAuditBrokenLinks;

package/dist/hygiene/tasks/audit/datasource-missing.d.ts

@@ -0,0 +1,44 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditDatasourceMissingOptions extends HygieneCommonOptions {
+    root?: string;
+    index?: string;
+    limit?: number;
+    includeSystem?: boolean;
+    batchSize?: number;
+    concurrency?: number;
+    pageParallelism?: number;
+    cache?: boolean;
+    /**
+     * Whether to flag Sitecore-query datasources (values prefixed with
+     * `query:`). They can't be resolved statically. Default false —
+     * skip them; setting true emits them as a "skipped" diagnostic.
+     */
+    reportQueryDatasources?: boolean;
+}
+export interface DatasourceMissingReport {
+    itemId: string;
+    path: string;
+    templateName?: string | null;
+    language?: string | null;
+    missingDatasources: Array<{
+        fieldName: string;
+        renderingId: string | null;
+        datasource: string;
+    }>;
+}
+/**
+ * Audit page items for rendering datasources that don't resolve.
+ *
+ * Uses `scanItemsAndFields` for the enumeration + field-read pipeline
+ * (concurrency, batch size, page parallelism, optional cache all come
+ * from there). Parses `__Renderings` / `__Final Renderings` XML and
+ * resolves the embedded `ds=` / `s:ds=` attribute values against the
+ * tenant's item index.
+ *
+ * Datasource values come in three shapes — paths, bare GUIDs, and
+ * `query:` selectors. Paths are resolved via batched `_fullpath`
+ * searches; GUIDs via `itemsExistBatch`; `query:` selectors are
+ * skipped by default (or emitted as diagnostics with
+ * `--report-query-datasources`).
+ */
+export declare const runAuditDatasourceMissing: (options: AuditDatasourceMissingOptions) => Promise<DatasourceMissingReport[]>;

package/dist/hygiene/tasks/audit/datasource-missing.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAuditDatasourceMissing = void 0;
+const cli_tasks_1 = require("../../../shared/cli-tasks");
+const shared_1 = require("../shared");
+/**
+ * Audit page items for rendering datasources that don't resolve.
+ *
+ * Uses `scanItemsAndFields` for the enumeration + field-read pipeline
+ * (concurrency, batch size, page parallelism, optional cache all come
+ * from there). Parses `__Renderings` / `__Final Renderings` XML and
+ * resolves the embedded `ds=` / `s:ds=` attribute values against the
+ * tenant's item index.
+ *
+ * Datasource values come in three shapes — paths, bare GUIDs, and
+ * `query:` selectors. Paths are resolved via batched `_fullpath`
+ * searches; GUIDs via `itemsExistBatch`; `query:` selectors are
+ * skipped by default (or emitted as diagnostics with
+ * `--report-query-datasources`).
+ */
+const runAuditDatasourceMissing = 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 idsToResolve = new Set();
+    const pathsToResolve = 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 ds of (0, shared_1.extractRenderingDatasources)(field.value)) {
+                if (!ds.datasource)
+                    continue;
+                if (ds.datasource.startsWith("query:") || ds.datasource.startsWith("local:")) {
+                    if (!options.reportQueryDatasources)
+                        continue;
+                }
+                pending.push({
+                    itemId: item.itemId,
+                    path: item.path,
+                    templateName: item.templateName,
+                    language: item.language,
+                    fieldName: field.name,
+                    renderingId: ds.renderingId,
+                    datasource: ds.datasource,
+                });
+                if (ds.datasource.startsWith("/")) {
+                    pathsToResolve.add(ds.datasource);
+                }
+                else {
+                    const norm = (0, shared_1.normalizeItemId)(ds.datasource);
+                    if (norm.length === 32)
+                        idsToResolve.add(norm);
+                }
+            }
+        }
+    }
+    logger.verbose(`Found ${pending.length} datasource refs; resolving ${idsToResolve.size} ids + ${pathsToResolve.size} paths.`);
+    // Resolve item-id refs in batches with the perf knobs.
+    const idExists = new Map();
+    const idList = Array.from(idsToResolve);
+    const idBatches = [];
+    for (let i = 0; i < idList.length; i += knobs.batchSize) {
+        idBatches.push(idList.slice(i, i + knobs.batchSize));
+    }
+    const idResults = await (0, cli_tasks_1.mapWithConcurrency)(idBatches, (ids) => client.itemsExistBatch(ids), knobs.concurrency);
+    for (const m of idResults)
+        for (const [id, exists] of m)
+            idExists.set(id, exists);
+    // Resolve path refs concurrently.
+    const pathExists = new Map();
+    await (0, cli_tasks_1.mapWithConcurrency)(Array.from(pathsToResolve), async (p) => {
+        const r = await client.search({
+            index: options.index,
+            paging: { pageSize: 1 },
+            searchStatement: {
+                criteria: { field: "_fullpath", value: p.toLowerCase(), criteriaType: "EXACT" },
+            },
+        });
+        pathExists.set(p, r.totalCount > 0);
+    }, knobs.concurrency);
+    // Build the per-item report.
+    const byItem = new Map();
+    for (const p of pending) {
+        let broken = false;
+        if (p.datasource.startsWith("query:") || p.datasource.startsWith("local:")) {
+            broken = true; // operator opted in
+        }
+        else if (p.datasource.startsWith("/")) {
+            broken = pathExists.get(p.datasource) === false;
+        }
+        else {
+            const norm = (0, shared_1.normalizeItemId)(p.datasource);
+            if (norm.length === 32)
+                broken = idExists.get(norm) === false;
+        }
+        if (!broken)
+            continue;
+        const entry = {
+            fieldName: p.fieldName,
+            renderingId: p.renderingId,
+            datasource: p.datasource,
+        };
+        const existing = byItem.get(p.itemId);
+        if (existing) {
+            existing.missingDatasources.push(entry);
+        }
+        else {
+            byItem.set(p.itemId, {
+                itemId: p.itemId,
+                path: p.path,
+                templateName: p.templateName,
+                language: p.language,
+                missingDatasources: [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.datasource-missing.list",
+        envName,
+        results: reports,
+        summary: `Scanned ${scanned.length} items; ${reports.length} have rendering datasources that don't resolve.`,
+        formatLine: (r) => `${r.path} (${r.missingDatasources.length} missing: ${r.missingDatasources
+            .slice(0, 2)
+            .map((d) => `${d.fieldName}→${d.datasource}`)
+            .join(", ")}${r.missingDatasources.length > 2 ? "…" : ""})`,
+        extra: { root, scannedCount: scanned.length },
+        options,
+    });
+    return reports;
+};
+exports.runAuditDatasourceMissing = runAuditDatasourceMissing;

package/dist/hygiene/tasks/audit/dead-templates.d.ts

@@ -0,0 +1,46 @@
+import { type HygieneCommonOptions } from "../shared";
+export interface AuditDeadTemplatesOptions extends HygieneCommonOptions {
+    /**
+     * Template-tree root to scan. Default `/sitecore/templates` —
+     * the templates root. By default the scan excludes `System/` and
+     * `Branches/System/` subtrees (set `--include-system` to include).
+     */
+    root?: string;
+    /** Override the search index. */
+    index?: string;
+    /** Cap on the number of templates inspected. Default 5000. */
+    limit?: number;
+    /** Concurrency for per-template item-count checks. Default 8. */
+    concurrency?: number;
+    /**
+     * Include System / platform templates (`/sitecore/templates/System`,
+     * `/sitecore/templates/Branches/System`) in the scan. Off by default —
+     * these are platform-internal and aren't actionable cleanup targets.
+     */
+    includeSystem?: boolean;
+}
+export interface DeadTemplateReport {
+    templateId: string;
+    name: string;
+    fullName: string | null;
+    /**
+     * Number of items in the master DB that derive from this template.
+     * Zero items → dead template, safe to delete (subject to inbound base-template
+     * references; the cleanup command surfaces those at delete time).
+     */
+    itemCount: number;
+}
+/**
+ * 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.
+ */
+export declare const runAuditDeadTemplates: (options: AuditDeadTemplatesOptions) => Promise<DeadTemplateReport[]>;