@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/api/graphql.d.ts

@@ -0,0 +1,4 @@
+import type { EnvironmentConfiguration } from "../../config/types";
+import { type GraphQLRequestOptions } from "../../shared/graphql";
+export type AuthoringRequestOptions = GraphQLRequestOptions;
+export declare const runHygieneAuthoringGraphQL: <T>(environment: EnvironmentConfiguration, query: string, variables?: Record<string, unknown>, options?: AuthoringRequestOptions) => Promise<T>;

package/dist/hygiene/api/graphql.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHygieneAuthoringGraphQL = void 0;
+const graphql_1 = require("../../shared/graphql");
+const auth_1 = require("../../serialization/api/auth");
+const DEFAULT_AUTHORING_PATH = "/sitecore/api/authoring/graphql/v1";
+const resolveAuthoringPath = () => process.env.SITECOREAI_AUTHORING_PATH ?? DEFAULT_AUTHORING_PATH;
+const DEFAULT_AUTHORING_RETRY = { maxAttempts: 5 };
+const runHygieneAuthoringGraphQL = (environment, query, variables, options) => (0, graphql_1.runSitecoreGraphQL)(environment, query, variables, {
+    servicePath: resolveAuthoringPath(),
+    label: "Authoring",
+    requireToken: true,
+    getAccessToken: auth_1.getAccessToken,
+}, {
+    ...options,
+    retry: { ...DEFAULT_AUTHORING_RETRY, ...(options?.retry ?? {}) },
+});
+exports.runHygieneAuthoringGraphQL = runHygieneAuthoringGraphQL;

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

@@ -0,0 +1,84 @@
+import { Logger } from "../shared/logger";
+/**
+ * Audit suite — a YAML-defined pipeline of audits that an operator
+ * can codify per-project and check into version control. Lets teams
+ * standardise their hygiene policy without each operator memorising
+ * the right flags.
+ *
+ * File shape:
+ *
+ *   version: 1
+ *   name: monthly-hygiene
+ *   audits:
+ *     - name: broken-links
+ *       options:
+ *         root: /sitecore/content/MySite
+ *         limit: 1000
+ *     - name: duplicates
+ *       options:
+ *         min-group-size: 3
+ *     - name: stale-content
+ *       options:
+ *         not-updated-in-days: 180
+ *   output:
+ *     format: markdown
+ *     path: ./reports/{date}.md
+ *   baseline:
+ *     enabled: true
+ *     update-on-success: false
+ *
+ * Output path templating:
+ *   {date}       — YYYY-MM-DD
+ *   {datetime}   — YYYY-MM-DDTHH-mm-ss
+ *   {env}        — environment name
+ *   {suite}      — suite `name:` from the file
+ */
+export interface AuditSuiteFile {
+    version: number;
+    name: string;
+    audits: AuditSuiteEntry[];
+    output?: {
+        format?: "json" | "csv" | "markdown";
+        path?: string;
+    };
+    baseline?: {
+        enabled?: boolean;
+        "update-on-success"?: boolean;
+    };
+}
+export interface AuditSuiteEntry {
+    name: string;
+    /** Free-form per-audit options. Validated by the audit task itself. */
+    options?: Record<string, unknown>;
+}
+export declare const loadAuditSuite: (filePath: string, logger?: Logger) => AuditSuiteFile;
+/**
+ * Substitute templated tokens in an output path.
+ *   {date}       — YYYY-MM-DD
+ *   {datetime}   — YYYY-MM-DDTHH-mm-ss
+ *   {env}        — environment name
+ *   {suite}      — suite name
+ */
+export declare const expandOutputPath: (template: string, context: {
+    envName: string;
+    suiteName: string;
+    now?: Date;
+}) => string;
+/**
+ * Convert audit suite entries to the option shape `runAuditAll`
+ * expects. The suite declares one entry per audit with free-form
+ * options; `runAuditAll` takes a flat options object with `include`
+ * (which audits) and shared defaults.
+ *
+ * Because `runAuditAll` shares one option object across all sub-audits,
+ * per-audit option overrides aren't directly expressible — operators
+ * who need per-audit knobs run them individually rather than through
+ * a suite. The suite covers the common "run this set with these
+ * shared options" case.
+ *
+ * Returns the suite's audit names plus the merged shared options.
+ */
+export declare const auditSuiteToRunnerInput: (suite: AuditSuiteFile) => {
+    include: string[];
+    sharedOptions: Record<string, unknown>;
+};

package/dist/hygiene/audit-suite.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditSuiteToRunnerInput = exports.expandOutputPath = exports.loadAuditSuite = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const yaml_1 = require("yaml");
+const errors_1 = require("../shared/errors");
+const SUPPORTED_VERSION = 1;
+const loadAuditSuite = (filePath, logger) => {
+    const abs = node_path_1.default.resolve(filePath);
+    if (!node_fs_1.default.existsSync(abs)) {
+        throw (0, errors_1.createScaiError)(`Audit suite file not found: ${abs}`, "CONFIG_NOT_FOUND");
+    }
+    const raw = node_fs_1.default.readFileSync(abs, "utf8");
+    let parsed;
+    try {
+        parsed = (0, yaml_1.parse)(raw);
+    }
+    catch (error) {
+        throw (0, errors_1.createScaiError)(`Audit suite file is not valid YAML: ${error instanceof Error ? error.message : String(error)}`, "CONFIG_INVALID", { hint: `File: ${abs}` });
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw (0, errors_1.createScaiError)("Audit suite file must be a YAML mapping with at least 'version' and 'audits'.", "CONFIG_INVALID");
+    }
+    const suite = parsed;
+    if (suite.version !== SUPPORTED_VERSION) {
+        throw (0, errors_1.createScaiError)(`Unsupported audit-suite version: ${suite.version} (expected ${SUPPORTED_VERSION}).`, "CONFIG_INVALID");
+    }
+    if (!suite.name || typeof suite.name !== "string") {
+        throw (0, errors_1.createScaiError)("Audit suite must have a 'name'.", "CONFIG_INVALID");
+    }
+    if (!Array.isArray(suite.audits) || suite.audits.length === 0) {
+        throw (0, errors_1.createScaiError)("Audit suite must have a non-empty 'audits' list.", "CONFIG_INVALID");
+    }
+    for (const a of suite.audits) {
+        if (!a || typeof a !== "object" || typeof a.name !== "string") {
+            throw (0, errors_1.createScaiError)("Each audit suite entry must be a mapping with a 'name' string.", "CONFIG_INVALID");
+        }
+    }
+    logger?.verbose(`Loaded audit suite '${suite.name}' with ${suite.audits.length} audits.`);
+    return suite;
+};
+exports.loadAuditSuite = loadAuditSuite;
+/**
+ * Substitute templated tokens in an output path.
+ *   {date}       — YYYY-MM-DD
+ *   {datetime}   — YYYY-MM-DDTHH-mm-ss
+ *   {env}        — environment name
+ *   {suite}      — suite name
+ */
+const expandOutputPath = (template, context) => {
+    const now = context.now ?? new Date();
+    const pad = (n) => n.toString().padStart(2, "0");
+    const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    const datetime = `${date}T${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+    return template
+        .replace(/\{date\}/g, date)
+        .replace(/\{datetime\}/g, datetime)
+        .replace(/\{env\}/g, context.envName)
+        .replace(/\{suite\}/g, context.suiteName);
+};
+exports.expandOutputPath = expandOutputPath;
+/**
+ * Convert audit suite entries to the option shape `runAuditAll`
+ * expects. The suite declares one entry per audit with free-form
+ * options; `runAuditAll` takes a flat options object with `include`
+ * (which audits) and shared defaults.
+ *
+ * Because `runAuditAll` shares one option object across all sub-audits,
+ * per-audit option overrides aren't directly expressible — operators
+ * who need per-audit knobs run them individually rather than through
+ * a suite. The suite covers the common "run this set with these
+ * shared options" case.
+ *
+ * Returns the suite's audit names plus the merged shared options.
+ */
+const auditSuiteToRunnerInput = (suite) => {
+    const include = suite.audits.map((a) => a.name);
+    // Merge per-audit options into one shared bag. Conflicts are last-wins.
+    const sharedOptions = {};
+    for (const a of suite.audits) {
+        if (!a.options)
+            continue;
+        for (const [key, value] of Object.entries(a.options)) {
+            const camel = toCamelCase(key);
+            sharedOptions[camel] = value;
+        }
+    }
+    return { include, sharedOptions };
+};
+exports.auditSuiteToRunnerInput = auditSuiteToRunnerInput;
+const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());

package/dist/hygiene/baseline.d.ts

@@ -0,0 +1,56 @@
+import { Logger } from "../shared/logger";
+export interface BaselineEntry {
+    /** Stable identifier derived by `fingerprintFinding`. */
+    fingerprint: string;
+    /** Human-readable note (optional) for why this finding was accepted. */
+    note?: string;
+    /** ISO date when added to the baseline. */
+    addedAt: string;
+}
+export interface BaselineFile {
+    version: number;
+    envName: string;
+    createdAt: string;
+    /** Map of audit-name (e.g. "broken-links") → list of accepted findings. */
+    ignored: Record<string, BaselineEntry[]>;
+}
+export interface BaselineHandle {
+    envName: string;
+    filePath: string;
+    /** Returns true if the audit+finding is in the ignore list. */
+    isIgnored(audit: string, finding: unknown): boolean;
+    /** Add a finding to the ignore list. No-op if already present. */
+    add(audit: string, finding: unknown, note?: string): void;
+    /** Remove a finding from the ignore list. */
+    remove(audit: string, fingerprint: string): void;
+    /** Persist to disk. Safe to call multiple times. */
+    flush(): Promise<void>;
+    /** Snapshot of current state for reporting. */
+    snapshot(): BaselineFile;
+}
+/**
+ * Compute a stable fingerprint for a finding row. Each audit's
+ * row shape gets its own identity rule. Falls back to a JSON hash
+ * for audit names we don't know about (future-audit-tolerant).
+ *
+ * Why per-audit rules: an audit may carry transient fields (e.g.
+ * `daysSinceUpdate` on stale-content changes every run). The
+ * fingerprint MUST exclude those, otherwise baselines never match
+ * and the ignore-list is useless.
+ */
+export declare const fingerprintFinding: (audit: string, finding: unknown) => string;
+export interface OpenBaselineOptions {
+    envName: string;
+    configDir: string;
+    logger?: Logger;
+}
+export declare const openBaseline: (options: OpenBaselineOptions) => BaselineHandle;
+/**
+ * Filter an audit's results to only NEW findings (not in baseline).
+ * Returns a tuple of [kept, ignored] so the report can show both
+ * counts in its summary.
+ */
+export declare const splitByBaseline: <T>(audit: string, findings: T[], baseline: BaselineHandle) => {
+    kept: T[];
+    ignored: T[];
+};

package/dist/hygiene/baseline.js

@@ -0,0 +1,248 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitByBaseline = exports.openBaseline = exports.fingerprintFinding = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../shared/errors");
+/**
+ * Per-env audit baseline.
+ *
+ * Records the set of findings that an operator has explicitly chosen
+ * to "accept" — usually known-debt items that aren't going to be fixed
+ * right now but shouldn't fail CI. When an audit runs with `--baseline`,
+ * findings that match a recorded entry are filtered out of the report.
+ *
+ * **File location.** `.scai/audit-baseline-<envName>.json` in the
+ * project root (same dir as `sitecoreai.cli.json`). One file per env
+ * keeps sandbox/prod independent — sandbox can ignore experimental
+ * debt that prod must still catch.
+ *
+ * **Identity model.** Each audit emits a different shape of finding,
+ * so the baseline stores a fingerprint per finding rather than the
+ * full row. The fingerprint is computed by `fingerprintFinding(audit,
+ * finding)` — it picks the stable identifying fields (e.g. for
+ * broken-links: itemId + fieldName + refItemId; for duplicates: just
+ * contentHash). Two findings with the same fingerprint are treated as
+ * equivalent.
+ *
+ * **What's NOT here.** History/trend tracking is Phase F — that
+ * stores full snapshots over time. Baselines are an ignore-list, not
+ * a journal.
+ */
+const BASELINE_VERSION = 1;
+/**
+ * Compute a stable fingerprint for a finding row. Each audit's
+ * row shape gets its own identity rule. Falls back to a JSON hash
+ * for audit names we don't know about (future-audit-tolerant).
+ *
+ * Why per-audit rules: an audit may carry transient fields (e.g.
+ * `daysSinceUpdate` on stale-content changes every run). The
+ * fingerprint MUST exclude those, otherwise baselines never match
+ * and the ignore-list is useless.
+ */
+const fingerprintFinding = (audit, finding) => {
+    if (!finding || typeof finding !== "object") {
+        return hashJson({ audit, finding });
+    }
+    const f = finding;
+    switch (audit) {
+        case "broken-links":
+            // (item, field, ref) — the actual broken edge.
+            return hashJson({
+                audit,
+                itemId: f.itemId,
+                brokenRefs: f.brokenRefs?.map((b) => `${b.fieldName}:${b.refItemId}`),
+            });
+        case "unused-media":
+        case "empty-items":
+        case "page-design-orphans":
+        case "personalization-broken":
+            return hashJson({ audit, itemId: f.itemId });
+        case "alt-text-missing":
+            // One row per (item, field, mediaId) — the mediaId disambiguates
+            // when an item has multiple Image fields with the same name in
+            // different languages, and the fieldName disambiguates the common
+            // case of an item with both a Banner and a Thumbnail.
+            return hashJson({
+                audit,
+                itemId: f.itemId,
+                fieldName: f.fieldName,
+                mediaId: f.mediaId,
+            });
+        case "datasource-missing":
+            return hashJson({
+                audit,
+                itemId: f.itemId,
+                missing: f.missingDatasources?.map((d) => `${d.fieldName}:${d.datasource}`),
+            });
+        case "orphans":
+            return hashJson({ audit, archivalId: f.archivalId });
+        case "stale-workflow":
+        case "stale-content":
+            // Workflow/staleness — fingerprint by item, NOT by days-since (days
+            // change every run; we want the ignored item to stay ignored).
+            return hashJson({ audit, itemId: f.itemId, workflowState: f.workflowState ?? f.stateName });
+        case "language-data":
+            return hashJson({ audit, itemId: f.itemId, langs: f.emptyLanguages?.sort() });
+        case "dead-templates":
+            return hashJson({ audit, templateId: f.templateId });
+        case "duplicates":
+            // Hash IS the identity for duplicates.
+            return hashJson({ audit, contentHash: f.contentHash });
+        case "slug-conflicts":
+            // (parent, slug, sorted member ids) — the conflict's identity. Sort
+            // the member ids so an audit run that returns the same group in a
+            // different order produces the same fingerprint.
+            return hashJson({
+                audit,
+                parentPath: f.parentPath,
+                slug: f.slug,
+                members: f.members?.map((m) => m.itemId).sort(),
+            });
+        case "find-replace":
+            // Per (item, pattern) since the same item could match different
+            // patterns. The pattern is part of the call, not the row, so we
+            // include it via the audit name's suffix; callers should
+            // qualify the audit key when adding to baseline if needed.
+            return hashJson({
+                audit,
+                itemId: f.itemId,
+                fields: f.matches?.map((m) => m.fieldName),
+            });
+        default:
+            return hashJson({ audit, finding: f });
+    }
+};
+exports.fingerprintFinding = fingerprintFinding;
+const hashJson = (value) => {
+    // Stable JSON.stringify (sort keys) so identical content always hashes
+    // the same. Crypto SHA-1 is fine here (we're not security-sensitive).
+    const stable = stableStringify(value);
+    // Use a simple FNV-1a hash — no need to pull crypto for an ignore-list
+    // key. Collisions at 8-byte output are negligible at audit-finding
+    // scale (< 1e6 entries per env file).
+    let h = 0xcbf29ce484222325n;
+    for (let i = 0; i < stable.length; i += 1) {
+        h ^= BigInt(stable.charCodeAt(i));
+        h = (h * 0x100000001b3n) & 0xffffffffffffffffn;
+    }
+    return h.toString(16).padStart(16, "0");
+};
+const stableStringify = (value) => {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+};
+const resolveBaselinePath = (envName, configDir) => {
+    const safeName = envName.replace(/[^A-Za-z0-9._-]/g, "_");
+    return node_path_1.default.join(configDir, ".scai", `audit-baseline-${safeName}.json`);
+};
+const loadBaseline = (filePath, envName, logger) => {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return {
+            version: BASELINE_VERSION,
+            envName,
+            createdAt: new Date().toISOString(),
+            ignored: {},
+        };
+    }
+    try {
+        const raw = node_fs_1.default.readFileSync(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== BASELINE_VERSION || parsed.envName !== envName) {
+            throw (0, errors_1.createScaiError)(`Baseline file ${filePath} is for env '${parsed.envName}' v${parsed.version}; expected '${envName}' v${BASELINE_VERSION}.`, "CONFIG_INVALID");
+        }
+        if (!parsed.ignored)
+            parsed.ignored = {};
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "CONFIG_INVALID") {
+            throw error;
+        }
+        logger?.warn(`Baseline file ${filePath} is unreadable; starting fresh. (${error instanceof Error ? error.message : String(error)})`);
+        return {
+            version: BASELINE_VERSION,
+            envName,
+            createdAt: new Date().toISOString(),
+            ignored: {},
+        };
+    }
+};
+const openBaseline = (options) => {
+    const filePath = resolveBaselinePath(options.envName, options.configDir);
+    const file = loadBaseline(filePath, options.envName, options.logger);
+    let dirty = false;
+    return {
+        envName: options.envName,
+        filePath,
+        isIgnored(audit, finding) {
+            const list = file.ignored[audit];
+            if (!list?.length)
+                return false;
+            const fp = (0, exports.fingerprintFinding)(audit, finding);
+            return list.some((e) => e.fingerprint === fp);
+        },
+        add(audit, finding, note) {
+            const fp = (0, exports.fingerprintFinding)(audit, finding);
+            if (!file.ignored[audit])
+                file.ignored[audit] = [];
+            const list = file.ignored[audit];
+            if (list.some((e) => e.fingerprint === fp))
+                return;
+            list.push({
+                fingerprint: fp,
+                ...(note !== undefined && { note }),
+                addedAt: new Date().toISOString(),
+            });
+            dirty = true;
+        },
+        remove(audit, fingerprint) {
+            const list = file.ignored[audit];
+            if (!list?.length)
+                return;
+            const before = list.length;
+            file.ignored[audit] = list.filter((e) => e.fingerprint !== fingerprint);
+            if (file.ignored[audit].length !== before)
+                dirty = true;
+        },
+        async flush() {
+            if (!dirty)
+                return;
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+            node_fs_1.default.writeFileSync(filePath, JSON.stringify(file, null, 2), "utf8");
+            dirty = false;
+        },
+        snapshot() {
+            return JSON.parse(JSON.stringify(file));
+        },
+    };
+};
+exports.openBaseline = openBaseline;
+/**
+ * Filter an audit's results to only NEW findings (not in baseline).
+ * Returns a tuple of [kept, ignored] so the report can show both
+ * counts in its summary.
+ */
+const splitByBaseline = (audit, findings, baseline) => {
+    const kept = [];
+    const ignored = [];
+    for (const f of findings) {
+        if (baseline.isIgnored(audit, f))
+            ignored.push(f);
+        else
+            kept.push(f);
+    }
+    return { kept, ignored };
+};
+exports.splitByBaseline = splitByBaseline;

package/dist/hygiene/cache.d.ts

@@ -0,0 +1,35 @@
+import { Logger } from "../shared/logger";
+import type { ItemField } from "./api/client";
+export interface FieldCacheOptions {
+    envName: string;
+    maxEntries?: number;
+    cacheDir?: string;
+    logger?: Logger;
+}
+export interface FieldCache {
+    /** Look up cached fields. Returns null on miss or stale entry. */
+    get(itemId: string, updatedDate: string | null | undefined): ItemField[] | null;
+    /** Store a field bundle. No-op when `updatedDate` is missing. */
+    set(itemId: string, updatedDate: string | null | undefined, fields: ItemField[]): void;
+    /** Persist the cache to disk. Safe to call multiple times. */
+    flush(): Promise<void>;
+    /** Read-only stats for reporting. */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+}
+export declare const createFieldCache: (options: FieldCacheOptions) => FieldCache;
+/**
+ * Wrap `getItemFieldsBatch` with a field-cache layer. The returned
+ * function consults the cache first per item, then defers to the
+ * underlying batch for any cache misses, and finally writes the
+ * fresh results back into the cache.
+ *
+ * `searchResults` is required so the wrapper knows each item's
+ * `updatedDate` — that's the cache freshness key. Callers pass the
+ * search results from the same enumeration pass.
+ */
+export declare const wrapFieldsBatchWithCache: (underlying: (itemIds: readonly string[]) => Promise<Map<string, ItemField[] | null>>, cache: FieldCache, updatedDateByItemId: Map<string, string | null>) => (itemIds: readonly string[]) => Promise<Map<string, ItemField[] | null>>;
+export declare const isAuditCacheEnabled: () => boolean;