@cms-lab/core 1.2.4 → 1.2.6

package/README.md

@@ -40,6 +40,10 @@ routes: [
 probe hit a known-good page or endpoint while normal route probes still use
 `site.url`.
 
+`checks.relationships` supports narrow equality joins across normalized
+documents, for example requiring each `menu_item` to have at least one matching
+`pricing` row by `id -> menu_item_id`.
+
 ## Release History
 
 See the repository [changelog](https://github.com/i-afaqrashid/cms-lab/blob/main/CHANGELOG.md)

package/dist/index.d.ts

@@ -41,6 +41,16 @@ type RequiredFieldRule = {
     path: string;
     severity?: "error" | "warning";
 };
+type RelationshipRule = {
+    from: string;
+    to: string;
+    where: {
+        fromField: string;
+        toField: string;
+    };
+    min?: number;
+    severity?: DiagnosticSeverity;
+};
 type PrismicCmsProviderConfig = {
     provider: "prismic";
     repositoryName: string;
@@ -142,6 +152,7 @@ type CmsLabConfig = {
         fields?: boolean | {
             required?: RequiredFieldRule[];
         };
+        relationships?: RelationshipRule[];
     };
 };
 type ScanSummary = {
@@ -149,14 +160,25 @@ type ScanSummary = {
     warnings: number;
     info: number;
 };
+type DiagnosticGroupSummary = {
+    key: string;
+    severity: DiagnosticSeverity;
+    code: string;
+    count: number;
+    label: string;
+    type?: string;
+    routePattern?: string;
+    examples: string[];
+};
 type ScanResult = {
     project: ProjectInfo;
     documents: CMSDocument[];
     diagnostics: Diagnostic[];
+    diagnosticGroups?: DiagnosticGroupSummary[];
     summary: ScanSummary;
 };
 type FetchLike = typeof fetch;
-type CheckGroup = "routes" | "seo" | "a11y" | "images" | "fields";
+type CheckGroup = "routes" | "seo" | "a11y" | "images" | "fields" | "relationships";
 type ScanFilters = {
     types?: string[];
     only?: CheckGroup[];
@@ -211,4 +233,4 @@ type ScanDocumentsOptions = {
 declare function scanDocuments(options: ScanDocumentsOptions): Promise<ScanResult>;
 declare function resolveSiteHealthUrl(site: CmsLabConfig["site"]): URL;
 
-export { type CMSDocument, type CMSDocumentStatus, type CheckGroup, CmsFetchError, type CmsFieldMappingConfig, type CmsLabConfig, CmsLabError, type CmsProviderConfig, ConfigLoadError, type ContentfulCmsProviderConfig, type ContentfulContentTypeConfig, type Diagnostic, type DiagnosticExplanation, type DiagnosticSeverity, type DirectusCmsProviderConfig, type DirectusCollectionConfig, type FetchLike, type LoadedCmsLabConfig, type PrismicCmsProviderConfig, type ProjectInfo, type RequiredFieldRule, type RouteDefinition, type SanityCmsProviderConfig, type SanityContentTypeConfig, type ScanDocumentsOptions, type ScanFilters, type ScanResult, type ScanSummary, SiteUnreachableError, type StrapiCmsProviderConfig, type StrapiCollectionConfig, type StrapiLocaleConfig, type StrapiSingleTypeConfig, type WordPressCmsProviderConfig, type WordPressContentTypeConfig, createDiagnostic, defineConfig, explainDiagnostic, listDiagnosticExplanations, loadCmsLabConfig, readCmsDataPath, resolveSiteHealthUrl, scanDocuments, strapiRelationSlug, strapiRelationValue, summarizeDiagnostics, validateConfig };
+export { type CMSDocument, type CMSDocumentStatus, type CheckGroup, CmsFetchError, type CmsFieldMappingConfig, type CmsLabConfig, CmsLabError, type CmsProviderConfig, ConfigLoadError, type ContentfulCmsProviderConfig, type ContentfulContentTypeConfig, type Diagnostic, type DiagnosticExplanation, type DiagnosticGroupSummary, type DiagnosticSeverity, type DirectusCmsProviderConfig, type DirectusCollectionConfig, type FetchLike, type LoadedCmsLabConfig, type PrismicCmsProviderConfig, type ProjectInfo, type RelationshipRule, type RequiredFieldRule, type RouteDefinition, type SanityCmsProviderConfig, type SanityContentTypeConfig, type ScanDocumentsOptions, type ScanFilters, type ScanResult, type ScanSummary, SiteUnreachableError, type StrapiCmsProviderConfig, type StrapiCollectionConfig, type StrapiLocaleConfig, type StrapiSingleTypeConfig, type WordPressCmsProviderConfig, type WordPressContentTypeConfig, createDiagnostic, defineConfig, explainDiagnostic, listDiagnosticExplanations, loadCmsLabConfig, readCmsDataPath, resolveSiteHealthUrl, scanDocuments, strapiRelationSlug, strapiRelationValue, summarizeDiagnostics, validateConfig };

package/dist/index.js

@@ -143,6 +143,16 @@ var requiredFieldRuleSchema = z.object({
   path: z.string().min(1),
   severity: z.enum(["error", "warning"]).optional()
 });
+var relationshipRuleSchema = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1),
+  where: z.object({
+    fromField: z.string().min(1),
+    toField: z.string().min(1)
+  }).strict(),
+  min: z.number().int().min(0).optional(),
+  severity: z.enum(["error", "warning", "info"]).optional()
+}).strict();
 var checksSchema = z.object({
   routes: z.boolean().optional(),
   seo: z.union([
@@ -162,7 +172,8 @@ var checksSchema = z.object({
     z.object({
       required: z.array(requiredFieldRuleSchema).optional()
     })
-  ]).optional()
+  ]).optional(),
+  relationships: z.array(relationshipRuleSchema).optional()
 }).strict().optional();
 var configSchema = z.object({
   site: z.object({
@@ -330,6 +341,13 @@ var explanations = [
     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."
+  },
+  {
+    code: "CMS-RELATIONSHIP-MISSING",
+    severity: "warning",
+    title: "CMS relationship rule did not match enough records",
+    meaning: "A relationship rule expected a document to have one or more matching related records, but cms-lab found fewer than the configured minimum.",
+    fix: "Check the related CMS collection, the join fields in checks.relationships, and whether the related content should be published or active."
   }
 ];
 function explainDiagnostic(code) {
@@ -418,10 +436,18 @@ async function scanDocuments(options) {
   if (shouldRunCheck("fields", options.config, options.filters)) {
     diagnostics.push(...checkRequiredFields(options.config, documents));
   }
+  if (shouldRunCheck("relationships", options.config, options.filters)) {
+    diagnostics.push(...checkRelationships(options.config, documents));
+  }
   return {
     project: options.project,
     documents,
     diagnostics,
+    diagnosticGroups: summarizeDiagnosticGroups(
+      diagnostics,
+      options.config,
+      routeCandidates
+    ),
     summary: summarizeDiagnostics(diagnostics)
   };
 }
@@ -709,6 +735,159 @@ function requiredFieldRules(config) {
   }
   return fields.required ?? [];
 }
+function checkRelationships(config, documents) {
+  const rules = relationshipRules(config);
+  if (rules.length === 0) {
+    return [];
+  }
+  const documentsByType = /* @__PURE__ */ new Map();
+  for (const document of documents) {
+    documentsByType.set(document.type, [
+      ...documentsByType.get(document.type) ?? [],
+      document
+    ]);
+  }
+  const diagnostics = [];
+  for (const rule of rules) {
+    const min = rule.min ?? 1;
+    const targets = documentsByType.get(rule.to) ?? [];
+    for (const document of documentsByType.get(rule.from) ?? []) {
+      const fromValues = relationshipValues(document, rule.where.fromField);
+      const matchCount = targets.filter(
+        (target) => hasRelationshipMatch(
+          fromValues,
+          relationshipValues(target, rule.where.toField)
+        )
+      ).length;
+      if (matchCount >= min) {
+        continue;
+      }
+      diagnostics.push(
+        createDiagnostic({
+          severity: rule.severity ?? "warning",
+          code: "CMS-RELATIONSHIP-MISSING",
+          message: `Document ${document.id} of type ${document.type} has ${matchCount} ${rule.to} records matching ${rule.where.fromField} -> ${rule.where.toField}; expected at least ${min}`,
+          path: `relationships.${rule.from}.${rule.to}`,
+          source: sourceFor(config, document)
+        })
+      );
+    }
+  }
+  return diagnostics;
+}
+function relationshipRules(config) {
+  return config.checks?.relationships ?? [];
+}
+function summarizeDiagnosticGroups(diagnostics, config, routeCandidates) {
+  const routePatternBySource = new Map(
+    routeCandidates.map((candidate) => [
+      sourceFor(config, candidate.document),
+      candidate.route.pattern
+    ])
+  );
+  const groups = /* @__PURE__ */ new Map();
+  for (const diagnostic of diagnostics) {
+    const type = typeFromSource(diagnostic.source);
+    const routePattern = routePatternForDiagnostic(
+      diagnostic,
+      type,
+      config,
+      routePatternBySource
+    );
+    const key = diagnosticGroupKey(diagnostic, type, routePattern);
+    const existing = groups.get(key);
+    const example = diagnosticExample(diagnostic);
+    if (existing) {
+      existing.count += 1;
+      if (example && !existing.examples.includes(example)) {
+        existing.examples.push(example);
+      }
+      existing.examples = existing.examples.slice(0, 3);
+      continue;
+    }
+    groups.set(key, {
+      key,
+      severity: diagnostic.severity,
+      code: diagnostic.code,
+      count: 1,
+      ...type ? { type } : {},
+      ...routePattern ? { routePattern } : {},
+      label: diagnosticGroupLabel(type, routePattern),
+      examples: example ? [example] : []
+    });
+  }
+  return [...groups.values()];
+}
+function routePatternForDiagnostic(diagnostic, type, config, routePatternBySource) {
+  if (!isRouteDiagnostic(diagnostic.code) && diagnostic.code !== "CMS-UID-MISSING") {
+    return void 0;
+  }
+  if (diagnostic.source) {
+    const routePattern = routePatternBySource.get(diagnostic.source);
+    if (routePattern) {
+      return routePattern;
+    }
+  }
+  return type ? config.routes.find((route) => route.type === type)?.pattern : void 0;
+}
+function isRouteDiagnostic(code) {
+  return code.startsWith("CMS-ROUTE");
+}
+function diagnosticGroupKey(diagnostic, type, routePattern) {
+  return [diagnostic.severity, diagnostic.code, type, routePattern].filter(Boolean).join(":");
+}
+function diagnosticGroupLabel(type, routePattern) {
+  if (type && routePattern) {
+    return `${type} ${routePattern}`;
+  }
+  return type ?? "project";
+}
+function diagnosticExample(diagnostic) {
+  return diagnostic.path ?? diagnostic.source ?? diagnostic.message;
+}
+function typeFromSource(source) {
+  if (!source) {
+    return void 0;
+  }
+  const match = /^[^:]+:([^#]+)#/.exec(source);
+  return match?.[1];
+}
+function hasRelationshipMatch(fromValues, toValues) {
+  if (fromValues.length === 0 || toValues.length === 0) {
+    return false;
+  }
+  const targetValues = new Set(toValues);
+  return fromValues.some((value) => targetValues.has(value));
+}
+function relationshipValues(document, path) {
+  const dataValue = readCmsDataPath(document.data, path);
+  if (dataValue !== void 0) {
+    return normalizeRelationshipValues(dataValue);
+  }
+  return normalizeRelationshipValues(
+    document[path]
+  );
+}
+function normalizeRelationshipValues(value) {
+  if (value === void 0 || value === null) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => normalizeRelationshipValues(item));
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return [String(value)];
+  }
+  const record = asRecord3(value);
+  if (!record) {
+    return [];
+  }
+  return [
+    ...normalizeRelationshipValues(record.id),
+    ...normalizeRelationshipValues(record.uid),
+    ...normalizeRelationshipValues(record.slug)
+  ];
+}
 function hasSeoValue(config, data, kind) {
   return seoFieldPaths(config.cms.provider, kind).some(
     (path) => !isBlank(readCmsDataPath(data, path))
@@ -836,6 +1015,9 @@ function shouldRunCheck(group, config, filters) {
   if (group === "images") {
     return isCheckEnabled(config.checks?.images, true);
   }
+  if (group === "relationships") {
+    return true;
+  }
   return isCheckEnabled(config.checks?.fields, true);
 }
 function shouldRunImageAltTextCheck(config, filters) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cms-lab/core",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "type": "module",
   "description": "Core config, scan, diagnostics, and checks for cms-lab.",
   "license": "MIT",