@cms-lab/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afaq Rashid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @cms-lab/core
+
+Core config, types, diagnostics, route resolution, and scan orchestration for cms-lab.
+
+```ts
+import { defineConfig, scanDocuments } from "@cms-lab/core";
+```
+
+Most users should install `cms-lab` and use the CLI. This package is public for
+typed config files, tests, and adapter/report integrations.
+
+`scanDocuments` understands the shared `CMSDocument` contract plus provider
+field shapes from the bundled adapters. SEO checks recognize common Prismic,
+Strapi, Directus, and WordPress SEO fields, while image checks recognize native
+alt fields such as Strapi `alternativeText`, Directus file `description`, and
+WordPress `alt_text`.
+
+## Open Source
+
+MIT licensed. See the repository [license](https://github.com/i-afaqrashid/cms-lab/blob/main/LICENSE), [contributing guide](https://github.com/i-afaqrashid/cms-lab/blob/main/CONTRIBUTING.md), and [support guide](https://github.com/i-afaqrashid/cms-lab/blob/main/SUPPORT.md).

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+type CMSDocumentStatus = "published" | "draft";
+type CMSDocument = {
+    id: string;
+    type: string;
+    uid?: string;
+    url?: string;
+    status: CMSDocumentStatus;
+    data: unknown;
+};
+type DiagnosticSeverity = "error" | "warning" | "info";
+type Diagnostic = {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    path?: string;
+    source?: string;
+};
+type DiagnosticExplanation = {
+    code: string;
+    severity: DiagnosticSeverity;
+    title: string;
+    meaning: string;
+    fix: string;
+};
+type ProjectInfo = {
+    framework: "next";
+    router: "app" | "pages";
+    rootDir: string;
+    appDir?: string;
+    pagesDir?: string;
+};
+type RouteDefinition = {
+    type: string;
+    pattern: string;
+    getPath: (document: CMSDocument) => string;
+};
+type RequiredFieldRule = {
+    type: string;
+    path: string;
+    severity?: "error" | "warning";
+};
+type PrismicCmsProviderConfig = {
+    provider: "prismic";
+    repositoryName: string;
+    accessToken?: string;
+    endpoint?: string;
+};
+type StrapiCollectionConfig = {
+    type: string;
+    endpoint: string;
+};
+type StrapiCmsProviderConfig = {
+    provider: "strapi";
+    url: string;
+    token?: string;
+    collections: StrapiCollectionConfig[];
+};
+type DirectusCollectionConfig = {
+    type: string;
+    collection: string;
+};
+type DirectusCmsProviderConfig = {
+    provider: "directus";
+    url: string;
+    token?: string;
+    collections: DirectusCollectionConfig[];
+};
+type WordPressContentTypeConfig = {
+    type: string;
+    endpoint: string;
+};
+type WordPressCmsProviderConfig = {
+    provider: "wordpress";
+    url: string;
+    contentTypes?: WordPressContentTypeConfig[];
+};
+type CmsProviderConfig = PrismicCmsProviderConfig | StrapiCmsProviderConfig | DirectusCmsProviderConfig | WordPressCmsProviderConfig;
+type CmsLabConfig = {
+    site: {
+        url: string;
+    };
+    framework: {
+        type: "next";
+        router: "app" | "pages";
+    };
+    cms: CmsProviderConfig;
+    routes: RouteDefinition[];
+    checks?: {
+        routes?: boolean;
+        seo?: boolean | {
+            metaTitle?: boolean;
+            metaDescription?: boolean;
+        };
+        images?: boolean;
+        a11y?: boolean | {
+            imgAlt?: boolean;
+        };
+        fields?: boolean | {
+            required?: RequiredFieldRule[];
+        };
+    };
+};
+type ScanSummary = {
+    errors: number;
+    warnings: number;
+    info: number;
+};
+type ScanResult = {
+    project: ProjectInfo;
+    documents: CMSDocument[];
+    diagnostics: Diagnostic[];
+    summary: ScanSummary;
+};
+type FetchLike = typeof fetch;
+type CheckGroup = "routes" | "seo" | "a11y" | "images" | "fields";
+type ScanFilters = {
+    types?: string[];
+    only?: CheckGroup[];
+    skip?: CheckGroup[];
+};
+
+type LoadedCmsLabConfig = {
+    config: CmsLabConfig;
+    configFile?: string;
+};
+declare function defineConfig(config: CmsLabConfig): CmsLabConfig;
+declare function validateConfig(input: unknown): CmsLabConfig;
+declare function loadCmsLabConfig(options: {
+    cwd: string;
+    configPath?: string;
+}): Promise<LoadedCmsLabConfig>;
+
+declare function createDiagnostic(input: Diagnostic): Diagnostic;
+declare function summarizeDiagnostics(diagnostics: Diagnostic[]): ScanSummary;
+declare function explainDiagnostic(code: string): DiagnosticExplanation | undefined;
+declare function listDiagnosticExplanations(): DiagnosticExplanation[];
+
+declare class CmsLabError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare class ConfigLoadError extends CmsLabError {
+    constructor(message: string);
+}
+declare class CmsFetchError extends CmsLabError {
+    constructor(message: string);
+}
+declare class SiteUnreachableError extends CmsLabError {
+    constructor(message: string);
+}
+
+type ScanDocumentsOptions = {
+    config: CmsLabConfig;
+    project: ProjectInfo;
+    documents: CMSDocument[];
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    concurrency?: number;
+    retries?: number;
+    filters?: ScanFilters;
+};
+declare function scanDocuments(options: ScanDocumentsOptions): Promise<ScanResult>;
+
+export { type CMSDocument, type CMSDocumentStatus, type CheckGroup, CmsFetchError, type CmsLabConfig, CmsLabError, type CmsProviderConfig, ConfigLoadError, type Diagnostic, type DiagnosticExplanation, type DiagnosticSeverity, type DirectusCmsProviderConfig, type DirectusCollectionConfig, type FetchLike, type LoadedCmsLabConfig, type PrismicCmsProviderConfig, type ProjectInfo, type RequiredFieldRule, type RouteDefinition, type ScanDocumentsOptions, type ScanFilters, type ScanResult, type ScanSummary, SiteUnreachableError, type StrapiCmsProviderConfig, type StrapiCollectionConfig, type WordPressCmsProviderConfig, type WordPressContentTypeConfig, createDiagnostic, defineConfig, explainDiagnostic, listDiagnosticExplanations, loadCmsLabConfig, scanDocuments, summarizeDiagnostics, validateConfig };

package/dist/index.js

@@ -0,0 +1,844 @@
+// src/config.ts
+import { loadConfig } from "c12";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+
+// src/errors.ts
+var CmsLabError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CmsLabError";
+  }
+  code;
+};
+var ConfigLoadError = class extends CmsLabError {
+  constructor(message) {
+    super(message, "CONFIG_ERROR");
+    this.name = "ConfigLoadError";
+  }
+};
+var CmsFetchError = class extends CmsLabError {
+  constructor(message) {
+    super(message, "CMS_UNREACHABLE");
+    this.name = "CmsFetchError";
+  }
+};
+var SiteUnreachableError = class extends CmsLabError {
+  constructor(message) {
+    super(message, "SITE_UNREACHABLE");
+    this.name = "SiteUnreachableError";
+  }
+};
+
+// src/config.ts
+var routeSchema = z.object({
+  type: z.string().min(1),
+  pattern: z.string().min(1),
+  getPath: z.custom(
+    (value) => typeof value === "function",
+    {
+      message: "routes[].getPath must be a function"
+    }
+  )
+}).strict();
+var prismicConfigSchema = z.object({
+  provider: z.literal("prismic"),
+  repositoryName: z.string().min(1),
+  accessToken: z.string().optional(),
+  endpoint: z.string().url().optional()
+}).strict();
+var strapiConfigSchema = z.object({
+  provider: z.literal("strapi"),
+  url: z.string().url(),
+  token: z.string().optional(),
+  collections: z.array(
+    z.object({
+      type: z.string().min(1),
+      endpoint: z.string().min(1)
+    }).strict()
+  ).min(1)
+}).strict();
+var directusConfigSchema = z.object({
+  provider: z.literal("directus"),
+  url: z.string().url(),
+  token: z.string().optional(),
+  collections: z.array(
+    z.object({
+      type: z.string().min(1),
+      collection: z.string().min(1)
+    }).strict()
+  ).min(1)
+}).strict();
+var wordpressConfigSchema = z.object({
+  provider: z.literal("wordpress"),
+  url: z.string().url(),
+  contentTypes: z.array(
+    z.object({
+      type: z.string().min(1),
+      endpoint: z.string().min(1)
+    }).strict()
+  ).optional()
+}).strict();
+var cmsConfigSchema = z.discriminatedUnion("provider", [
+  prismicConfigSchema,
+  strapiConfigSchema,
+  directusConfigSchema,
+  wordpressConfigSchema
+]);
+var requiredFieldRuleSchema = z.object({
+  type: z.string().min(1),
+  path: z.string().min(1),
+  severity: z.enum(["error", "warning"]).optional()
+});
+var checksSchema = z.object({
+  routes: z.boolean().optional(),
+  seo: z.union([
+    z.boolean(),
+    z.object({
+      metaTitle: z.boolean().optional(),
+      metaDescription: z.boolean().optional()
+    }).strict()
+  ]).optional(),
+  images: z.boolean().optional(),
+  a11y: z.union([
+    z.boolean(),
+    z.object({ imgAlt: z.boolean().optional() }).strict()
+  ]).optional(),
+  fields: z.union([
+    z.boolean(),
+    z.object({
+      required: z.array(requiredFieldRuleSchema).optional()
+    })
+  ]).optional()
+}).strict().optional();
+var configSchema = z.object({
+  site: z.object({
+    url: z.string().url()
+  }).strict(),
+  framework: z.object({
+    type: z.literal("next"),
+    router: z.enum(["app", "pages"])
+  }).strict(),
+  cms: cmsConfigSchema,
+  routes: z.array(routeSchema).min(1),
+  checks: checksSchema
+}).strict();
+function defineConfig(config) {
+  return config;
+}
+function validateConfig(input) {
+  const result = configSchema.safeParse(input);
+  if (!result.success) {
+    throw new ConfigLoadError(z.prettifyError(result.error));
+  }
+  return result.data;
+}
+async function loadCmsLabConfig(options) {
+  try {
+    const result = await loadConfig({
+      name: "cms-lab",
+      cwd: options.cwd,
+      configFile: options.configPath,
+      configFileRequired: true,
+      dotenv: true,
+      jitiOptions: {
+        alias: {
+          "@cms-lab/core": selfEntryPath()
+        }
+      }
+    });
+    return {
+      config: validateConfig(result.config),
+      configFile: result.configFile
+    };
+  } catch (error) {
+    if (error instanceof ConfigLoadError) {
+      throw error;
+    }
+    throw new ConfigLoadError(
+      error instanceof Error ? error.message : "Failed to load cms-lab config"
+    );
+  }
+}
+function selfEntryPath() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const extension = currentFile.endsWith(".ts") ? "ts" : "js";
+  return join(dirname(currentFile), `index.${extension}`);
+}
+
+// src/diagnostics.ts
+function createDiagnostic(input) {
+  return input;
+}
+function summarizeDiagnostics(diagnostics) {
+  return {
+    errors: countSeverity(diagnostics, "error"),
+    warnings: countSeverity(diagnostics, "warning"),
+    info: countSeverity(diagnostics, "info")
+  };
+}
+function countSeverity(diagnostics, severity) {
+  return diagnostics.filter((diagnostic) => diagnostic.severity === severity).length;
+}
+var explanations = [
+  {
+    code: "CMS-UID-MISSING",
+    severity: "error",
+    title: "CMS document is missing a UID",
+    meaning: "A route pattern requires :uid, but the CMS document does not have a usable uid value.",
+    fix: "Publish the document with a UID, or change the cms-lab route mapping so this content type does not depend on :uid."
+  },
+  {
+    code: "CMS-ROUTE-404",
+    severity: "error",
+    title: "CMS route returned 404",
+    meaning: "The route mapping resolved to a URL, but the running site returned a not-found response for that CMS document.",
+    fix: "Check generateStaticParams, dynamicParams, CMS fetch logic, and the getPath mapping for this content type."
+  },
+  {
+    code: "CMS-ROUTE-500",
+    severity: "error",
+    title: "CMS route returned a server error",
+    meaning: "The mapped page crashed or returned a 5xx response when cms-lab probed it.",
+    fix: "Open the path locally or in staging, inspect the server logs, and fix the page data fetching or rendering error."
+  },
+  {
+    code: "CMS-ROUTE-ERROR",
+    severity: "error",
+    title: "CMS route probe failed",
+    meaning: "cms-lab could not complete the HTTP probe for a mapped CMS route, or the route returned an unexpected 4xx response.",
+    fix: "Verify the site is reachable, the route is public, auth middleware allows the probe, and the URL mapping is correct."
+  },
+  {
+    code: "CMS-ROUTE-INVALID",
+    severity: "error",
+    title: "Route mapping returned an invalid path",
+    meaning: "A route getPath function returned an empty value, a value that does not start with /, or a protocol-relative path that could leave the configured site origin.",
+    fix: "Update the getPath function to return a same-origin site path such as /about or /blog/my-post."
+  },
+  {
+    code: "CMS-ROUTE-UNMAPPED",
+    severity: "info",
+    title: "CMS document has no route mapping",
+    meaning: "A fetched CMS document type is not listed in the cms-lab routes config, so cms-lab skipped route probing for that document.",
+    fix: "Add a route mapping if this content type should render a public page, or leave it unmapped for settings/navigation documents."
+  },
+  {
+    code: "CMS-ROUTE-RESOLVE",
+    severity: "error",
+    title: "Route mapping threw an exception",
+    meaning: "A route getPath function failed while resolving a CMS document.",
+    fix: "Make the getPath function tolerate optional fields and return a clear absolute path for every routable document."
+  },
+  {
+    code: "SEO-META-MISSING",
+    severity: "warning",
+    title: "SEO metadata is missing",
+    meaning: "A document is missing one or more configured SEO fields. cms-lab checks common provider fields such as Prismic meta fields, Strapi/Directus seo objects, and WordPress SEO plugin JSON.",
+    fix: "Fill the missing CMS fields or disable the SEO check if this content type intentionally does not use metadata."
+  },
+  {
+    code: "A11Y-IMG-ALT",
+    severity: "warning",
+    title: "Image alt text is missing",
+    meaning: "An image-like CMS field has no useful alt text, or uses a placeholder such as image, photo, or picture. Native fields such as Prismic alt, Strapi alternativeText, Directus file description, and WordPress alt_text are checked.",
+    fix: "Add meaningful alt text in the CMS, or leave decorative images out of content fields that require editorial alt text."
+  },
+  {
+    code: "CMS-FIELD-MISSING",
+    severity: "error",
+    title: "Required CMS field is missing",
+    meaning: "A document is missing a required field declared in cms-lab config.",
+    fix: "Fill the required field in the CMS, or update checks.fields.required if the field is no longer required."
+  }
+];
+function explainDiagnostic(code) {
+  return explanations.find(
+    (explanation) => explanation.code === code.trim().toUpperCase()
+  );
+}
+function listDiagnosticExplanations() {
+  return [...explanations];
+}
+
+// src/scan.ts
+async function scanDocuments(options) {
+  const fetchImpl = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  const concurrency = normalizeConcurrency(options.concurrency);
+  const retries = normalizeRetries(options.retries);
+  const documents = filterDocuments(options.documents, options.filters);
+  const diagnostics = [];
+  await assertSiteReachable(
+    options.config.site.url,
+    fetchImpl,
+    timeoutMs,
+    retries
+  );
+  const shouldRunRoutes = shouldRunCheck(
+    "routes",
+    options.config,
+    options.filters
+  );
+  const routeCandidates = shouldRunRoutes ? resolveRouteCandidates(options.config, documents, diagnostics) : [];
+  if (shouldRunRoutes) {
+    diagnostics.push(
+      ...await checkRouteReachability(
+        options.config,
+        routeCandidates,
+        fetchImpl,
+        timeoutMs,
+        concurrency,
+        retries
+      )
+    );
+  }
+  if (shouldRunCheck("seo", options.config, options.filters)) {
+    diagnostics.push(...checkSeoFields(options.config, documents));
+  }
+  if (shouldRunImageAltTextCheck(options.config, options.filters)) {
+    diagnostics.push(...checkImageAltText(options.config, documents));
+  }
+  if (shouldRunCheck("fields", options.config, options.filters)) {
+    diagnostics.push(...checkRequiredFields(options.config, documents));
+  }
+  return {
+    project: options.project,
+    documents,
+    diagnostics,
+    summary: summarizeDiagnostics(diagnostics)
+  };
+}
+function resolveRouteCandidates(config, documents, diagnostics) {
+  const candidates = [];
+  for (const document of documents) {
+    const route = config.routes.find(
+      (candidate) => candidate.type === document.type
+    );
+    if (!route) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "info",
+          code: "CMS-ROUTE-UNMAPPED",
+          message: `Document ${document.id} of type ${document.type} has no configured route mapping`,
+          source: sourceFor(config, document)
+        })
+      );
+      continue;
+    }
+    if (route.pattern.includes(":uid") && !document.uid) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "CMS-UID-MISSING",
+          message: `Document ${document.id} of type ${document.type} is missing uid`,
+          source: sourceFor(config, document)
+        })
+      );
+      continue;
+    }
+    try {
+      const path = route.getPath(document);
+      if (!path || !isSiteRelativePath(path)) {
+        diagnostics.push(
+          createDiagnostic({
+            severity: "error",
+            code: "CMS-ROUTE-INVALID",
+            message: `Route for document ${document.id} must resolve to a same-origin path starting with a single /`,
+            source: sourceFor(config, document)
+          })
+        );
+        continue;
+      }
+      candidates.push({ document, route, path });
+    } catch (error) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "CMS-ROUTE-RESOLVE",
+          message: messageFrom(
+            error instanceof Error ? error : `Failed to resolve route for document ${document.id}`
+          ),
+          source: sourceFor(config, document)
+        })
+      );
+    }
+  }
+  return candidates;
+}
+async function checkRouteReachability(config, candidates, fetchImpl, timeoutMs, concurrency, retries) {
+  const results = await mapLimit(candidates, concurrency, async (candidate) => {
+    const diagnostics = [];
+    const siteUrl = new URL(config.site.url);
+    const url = new URL(candidate.path, siteUrl);
+    const diagnosticPath = pathForDiagnostic(candidate.path);
+    let response;
+    if (url.origin !== siteUrl.origin) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "CMS-ROUTE-INVALID",
+          message: `Route ${diagnosticPath} resolved outside configured site origin`,
+          path: diagnosticPath,
+          source: sourceFor(config, candidate.document)
+        })
+      );
+      return diagnostics;
+    }
+    try {
+      response = await fetchWithRetries(fetchImpl, url, timeoutMs, retries);
+    } catch (error) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "CMS-ROUTE-ERROR",
+          message: `Route ${diagnosticPath} could not be fetched: ${messageFrom(error)}`,
+          path: diagnosticPath,
+          source: sourceFor(config, candidate.document)
+        })
+      );
+      return diagnostics;
+    }
+    const status = response.status;
+    if (status === 404) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "CMS-ROUTE-404",
+          message: `Route ${diagnosticPath} returned 404`,
+          path: diagnosticPath,
+          source: sourceFor(config, candidate.document)
+        })
+      );
+      return diagnostics;
+    }
+    if (status >= 500) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "CMS-ROUTE-500",
+          message: `Route ${diagnosticPath} returned ${status}`,
+          path: diagnosticPath,
+          source: sourceFor(config, candidate.document)
+        })
+      );
+      return diagnostics;
+    }
+    if (status >= 400) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "error",
+          code: "CMS-ROUTE-ERROR",
+          message: `Route ${diagnosticPath} returned ${status}`,
+          path: diagnosticPath,
+          source: sourceFor(config, candidate.document)
+        })
+      );
+    }
+    return diagnostics;
+  });
+  return results.flat();
+}
+async function assertSiteReachable(siteUrl, fetchImpl, timeoutMs, retries) {
+  try {
+    const response = await fetchWithRetries(
+      fetchImpl,
+      new URL(siteUrl),
+      timeoutMs,
+      retries
+    );
+    if (!response.ok) {
+      throw new SiteUnreachableError(
+        `Site ${siteUrlForDiagnostic(siteUrl)} returned HTTP ${response.status}`
+      );
+    }
+  } catch (error) {
+    if (error instanceof SiteUnreachableError) {
+      throw error;
+    }
+    throw new SiteUnreachableError(
+      error instanceof Error ? messageFrom(error) : `Site ${siteUrlForDiagnostic(siteUrl)} is unreachable`
+    );
+  }
+}
+async function fetchWithTimeout(fetchImpl, url, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetchImpl(url, { method: "GET", signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function fetchWithRetries(fetchImpl, url, timeoutMs, retries) {
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      const response = await fetchWithTimeout(fetchImpl, url, timeoutMs);
+      if (attempt < retries && isRetryableStatus(response.status)) {
+        continue;
+      }
+      return response;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retries) {
+        break;
+      }
+    }
+  }
+  throw lastError;
+}
+function checkSeoFields(config, documents) {
+  const diagnostics = [];
+  const seo = config.checks?.seo;
+  const checkMetaTitle = typeof seo === "object" ? seo.metaTitle !== false : true;
+  const checkMetaDescription = typeof seo === "object" ? seo.metaDescription !== false : true;
+  for (const document of documents) {
+    const data = asRecord(document.data);
+    if (!data) {
+      continue;
+    }
+    const missing = [];
+    if (checkMetaTitle && !hasSeoValue(config, data, "title")) {
+      missing.push("meta_title");
+    }
+    if (checkMetaDescription && !hasSeoValue(config, data, "description")) {
+      missing.push("meta_description");
+    }
+    if (missing.length > 0) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "warning",
+          code: "SEO-META-MISSING",
+          message: `Document ${document.id} is missing ${missing.join(", ")}`,
+          source: sourceFor(config, document)
+        })
+      );
+    }
+  }
+  return diagnostics;
+}
+function checkImageAltText(config, documents) {
+  const diagnostics = [];
+  for (const document of documents) {
+    const missingPaths = collectImagesMissingAlt(
+      document.data,
+      config.cms.provider
+    );
+    for (const path of missingPaths) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "warning",
+          code: "A11Y-IMG-ALT",
+          message: `Image field ${path} is missing useful alt text`,
+          source: sourceFor(config, document)
+        })
+      );
+    }
+  }
+  return diagnostics;
+}
+function checkRequiredFields(config, documents) {
+  const rules = requiredFieldRules(config);
+  if (rules.length === 0) {
+    return [];
+  }
+  const diagnostics = [];
+  for (const document of documents) {
+    for (const rule of rules) {
+      if (rule.type !== document.type) {
+        continue;
+      }
+      const fullPath = `data.${rule.path}`;
+      if (!isMissingFieldValue(readDataPath(document.data, rule.path))) {
+        continue;
+      }
+      diagnostics.push(
+        createDiagnostic({
+          severity: rule.severity ?? "error",
+          code: "CMS-FIELD-MISSING",
+          message: `Document ${document.id} is missing required field ${fullPath}`,
+          path: fullPath,
+          source: sourceFor(config, document)
+        })
+      );
+    }
+  }
+  return diagnostics;
+}
+function requiredFieldRules(config) {
+  const fields = config.checks?.fields;
+  if (!fields || typeof fields === "boolean") {
+    return [];
+  }
+  return fields.required ?? [];
+}
+function hasSeoValue(config, data, kind) {
+  return seoFieldPaths(config.cms.provider, kind).some(
+    (path) => !isBlank(readDataPath(data, path))
+  );
+}
+function seoFieldPaths(provider, kind) {
+  const common = kind === "title" ? [
+    "meta_title",
+    "meta.title",
+    "seo.title",
+    "seo.metaTitle",
+    "seo.meta_title",
+    "seoTitle",
+    "seo_title"
+  ] : [
+    "meta_description",
+    "meta.description",
+    "seo.description",
+    "seo.metaDescription",
+    "seo.meta_description",
+    "seoDescription",
+    "seo_description"
+  ];
+  if (provider === "wordpress") {
+    return kind === "title" ? [
+      ...common,
+      "yoast_head_json.title",
+      "yoast_head_json.og_title",
+      "rank_math_title",
+      "_yoast_wpseo_title"
+    ] : [
+      ...common,
+      "yoast_head_json.description",
+      "yoast_head_json.og_description",
+      "rank_math_description",
+      "_yoast_wpseo_metadesc"
+    ];
+  }
+  if (provider === "prismic") {
+    return kind === "title" ? [...common, "metaTitle"] : [...common, "metaDescription"];
+  }
+  return common;
+}
+function collectImagesMissingAlt(value, provider, path = "data") {
+  if (Array.isArray(value)) {
+    return value.flatMap(
+      (item, index) => collectImagesMissingAlt(item, provider, `${path}[${index}]`)
+    );
+  }
+  const record = asRecord(value);
+  if (!record) {
+    return [];
+  }
+  const imageAlt = imageAltCandidate(provider, record);
+  if (imageAlt.isImage && isBlankOrPlaceholderAlt(imageAlt.value)) {
+    return [path];
+  }
+  return Object.entries(record).flatMap(
+    ([key, nested]) => collectImagesMissingAlt(nested, provider, `${path}.${key}`)
+  );
+}
+function imageAltCandidate(provider, record) {
+  if (typeof record.url === "string" && ("alt" in record || "dimensions" in record)) {
+    return { isImage: true, value: record.alt };
+  }
+  if (provider === "strapi" && typeof record.url === "string" && ("alternativeText" in record || "mime" in record || "formats" in record)) {
+    return { isImage: true, value: record.alternativeText };
+  }
+  if (provider === "wordpress" && typeof record.source_url === "string" && ("alt_text" in record || "media_type" in record || "mime_type" in record)) {
+    return { isImage: true, value: record.alt_text };
+  }
+  if (provider === "directus" && isDirectusImageRecord(record)) {
+    return { isImage: true, value: record.description };
+  }
+  return { isImage: false, value: void 0 };
+}
+function isDirectusImageRecord(record) {
+  return typeof record.type === "string" && record.type.startsWith("image/") || hasImageExtension(record.filename_download) || hasImageExtension(record.filename_disk) || hasImageExtension(record.filename);
+}
+function hasImageExtension(value) {
+  return typeof value === "string" && /\.(?:avif|gif|jpe?g|png|svg|webp)$/i.test(value);
+}
+function isCheckEnabled(value, defaultValue) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return defaultValue;
+}
+function shouldRunCheck(group, config, filters) {
+  const only = normalizeFilterList(filters?.only);
+  const skip = normalizeFilterList(filters?.skip);
+  if (only.length > 0 && !only.includes(group)) {
+    return false;
+  }
+  if (skip.includes(group)) {
+    return false;
+  }
+  if (group === "routes") {
+    return isCheckEnabled(config.checks?.routes, true);
+  }
+  if (group === "seo") {
+    return isCheckEnabled(config.checks?.seo, true);
+  }
+  if (group === "a11y") {
+    return isCheckEnabled(config.checks?.a11y, true);
+  }
+  if (group === "images") {
+    return isCheckEnabled(config.checks?.images, true);
+  }
+  return isCheckEnabled(config.checks?.fields, true);
+}
+function shouldRunImageAltTextCheck(config, filters) {
+  if (!isImageAltCheckEnabled(config)) {
+    return false;
+  }
+  const only = normalizeFilterList(filters?.only);
+  const skip = normalizeFilterList(filters?.skip);
+  if (skip.includes("a11y") || skip.includes("images")) {
+    return false;
+  }
+  if (only.length > 0 && !only.includes("a11y") && !only.includes("images")) {
+    return false;
+  }
+  return true;
+}
+function isImageAltCheckEnabled(config) {
+  if (config.checks?.images === false) {
+    return false;
+  }
+  const a11y = config.checks?.a11y;
+  if (typeof a11y === "boolean") {
+    return a11y;
+  }
+  if (typeof a11y === "object") {
+    return a11y.imgAlt !== false;
+  }
+  return true;
+}
+function filterDocuments(documents, filters) {
+  const types = normalizeFilterList(filters?.types);
+  if (types.length === 0) {
+    return documents;
+  }
+  return documents.filter((document) => types.includes(document.type));
+}
+function normalizeFilterList(values) {
+  return [
+    ...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))
+  ];
+}
+function normalizeConcurrency(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 8;
+  }
+  return Math.max(1, Math.floor(value));
+}
+function normalizeRetries(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 1;
+  }
+  return Math.max(0, Math.floor(value));
+}
+function isRetryableStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function isSiteRelativePath(path) {
+  return path.startsWith("/") && !path.startsWith("//");
+}
+function pathForDiagnostic(path) {
+  try {
+    const url = new URL(path, "https://cms-lab.local");
+    return `${url.pathname}${url.search ? "?[redacted]" : ""}`;
+  } catch {
+    return path;
+  }
+}
+function siteUrlForDiagnostic(value) {
+  try {
+    const url = new URL(value);
+    const auth = url.username || url.password ? "[redacted]@" : "";
+    const hash = url.hash ? "#[redacted]" : "";
+    return `${url.protocol}//${auth}${url.host}${url.pathname}${url.search ? "?[redacted]" : ""}${hash}`;
+  } catch {
+    return redactSensitive(value);
+  }
+}
+async function mapLimit(values, limit, mapper) {
+  const results = new Array(values.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await mapper(values[index], index);
+    }
+  }
+  const workerCount = Math.min(limit, values.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      await worker();
+    })
+  );
+  return results;
+}
+function isBlank(value) {
+  return typeof value !== "string" || value.trim().length === 0;
+}
+function isMissingFieldValue(value) {
+  if (value === void 0 || value === null) {
+    return true;
+  }
+  if (typeof value === "string") {
+    return value.trim().length === 0;
+  }
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+  return false;
+}
+function readDataPath(data, path) {
+  let current = data;
+  for (const segment of path.split(".")) {
+    if (!segment) {
+      return void 0;
+    }
+    const record = asRecord(current);
+    if (!record || !(segment in record)) {
+      return void 0;
+    }
+    current = record[segment];
+  }
+  return current;
+}
+function isBlankOrPlaceholderAlt(value) {
+  return isBlank(value) || typeof value === "string" && ["image", "photo", "picture"].includes(value.trim().toLowerCase());
+}
+function asRecord(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return void 0;
+}
+function sourceFor(config, document) {
+  return `${config.cms.provider}:${document.type}#${document.id}`;
+}
+function messageFrom(error) {
+  return redactSensitive(
+    error instanceof Error ? error.message : String(error)
+  );
+}
+function redactSensitive(value) {
+  return value.replaceAll(/(access_token=)[^&\s]+/gi, "$1[redacted]").replaceAll(/([?&](?:token|password|secret)=)[^&\s]+/gi, "$1[redacted]").replaceAll(/\bBearer\s+[-._~+/=a-z0-9]+/gi, "Bearer [redacted]").replaceAll(/(https?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1[redacted]@");
+}
+export {
+  CmsFetchError,
+  CmsLabError,
+  ConfigLoadError,
+  SiteUnreachableError,
+  createDiagnostic,
+  defineConfig,
+  explainDiagnostic,
+  listDiagnosticExplanations,
+  loadCmsLabConfig,
+  scanDocuments,
+  summarizeDiagnostics,
+  validateConfig
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@cms-lab/core",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Core config, scan, diagnostics, and checks for cms-lab.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/i-afaqrashid/cms-lab.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://cms-lab.dev",
+  "bugs": {
+    "url": "https://github.com/i-afaqrashid/cms-lab/issues"
+  },
+  "keywords": [
+    "cms",
+    "nextjs",
+    "prismic",
+    "testing"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "c12": "^3.3.0",
+    "zod": "^4.1.13"
+  },
+  "author": "Afaq Rashid",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --tsconfig ../../tsconfig.base.json"
+  }
+}