@sanity/schema-lint 0.0.1 → 0.0.3

package/dist/index.cjs

@@ -0,0 +1,640 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  arrayMissingConstraints: () => arrayMissingConstraints,
+  booleanInsteadOfList: () => booleanInsteadOfList,
+  headingLevelInSchema: () => headingLevelInSchema,
+  lint: () => lint,
+  lintSchemas: () => lintSchemas,
+  missingDefineField: () => missingDefineField,
+  missingDefineType: () => missingDefineType,
+  missingDescription: () => missingDescription,
+  missingIcon: () => missingIcon,
+  missingRequiredValidation: () => missingRequiredValidation,
+  missingSlugSource: () => missingSlugSource,
+  missingTitle: () => missingTitle,
+  presentationFieldName: () => presentationFieldName,
+  reservedFieldName: () => reservedFieldName,
+  rules: () => rules,
+  unnecessaryReference: () => unnecessaryReference
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/linter.ts
+function getEffectiveSeverity(rule, config) {
+  if (!config?.rules) {
+    return rule.severity;
+  }
+  const ruleConfig = config.rules[rule.id];
+  if (ruleConfig === false) {
+    return null;
+  }
+  if (ruleConfig === true) {
+    return rule.severity;
+  }
+  if (typeof ruleConfig === "object") {
+    if (ruleConfig.enabled === false) {
+      return null;
+    }
+    return ruleConfig.severity ?? rule.severity;
+  }
+  return rule.severity;
+}
+function lint(schema, allRules, options = {}) {
+  const { rules: rules2 = allRules, config, filePath = "" } = options;
+  const firedRules = /* @__PURE__ */ new Set();
+  const allFindings = [];
+  for (const rule of rules2) {
+    const severity = getEffectiveSeverity(rule, config);
+    if (severity === null) {
+      continue;
+    }
+    const ruleFindings = [];
+    const context = {
+      filePath,
+      report: (finding) => {
+        ruleFindings.push({
+          ...finding,
+          ruleId: rule.id,
+          severity: finding.severity ?? severity
+        });
+      }
+    };
+    try {
+      rule.check(schema, context);
+    } catch (error) {
+      console.error(`Rule ${rule.id} threw an error:`, error);
+    }
+    if (ruleFindings.length > 0) {
+      firedRules.add(rule.id);
+      allFindings.push(...ruleFindings);
+    }
+  }
+  const findings = allFindings.filter((finding) => {
+    const isSuperseded = rules2.some(
+      (r) => r.supersedes?.includes(finding.ruleId) && firedRules.has(r.id)
+    );
+    return !isSuperseded;
+  });
+  return { findings };
+}
+function lintSchemas(schemas, allRules, options = {}) {
+  const findings = [];
+  for (const schema of schemas) {
+    const result = lint(schema, allRules, options);
+    findings.push(...result.findings);
+  }
+  return { findings };
+}
+
+// src/rules/missing-define-type.ts
+var missingDefineType = {
+  id: "missing-define-type",
+  name: "Missing defineType()",
+  description: "Schema types should use defineType() wrapper",
+  severity: "error",
+  category: "correctness",
+  check(schema, context) {
+    if (!schema.usesDefineType) {
+      context.report({
+        message: `Schema type "${schema.name}" should be wrapped with defineType()`,
+        severity: "error",
+        ...schema.span && { span: schema.span },
+        help: 'Import defineType from "sanity" and wrap your schema: export const myType = defineType({ ... })'
+      });
+    }
+  }
+};
+
+// src/rules/missing-define-field.ts
+var missingDefineField = {
+  id: "missing-define-field",
+  name: "Missing defineField()",
+  description: "Fields should use defineField() wrapper",
+  severity: "error",
+  category: "correctness",
+  check(schema, context) {
+    if (!schema.usesDefineType) {
+      return;
+    }
+    if (schema.usesDefineField === false && schema.fields && schema.fields.length > 0) {
+      context.report({
+        message: `Schema type "${schema.name}" has fields not wrapped with defineField()`,
+        severity: "error",
+        ...schema.span && { span: schema.span },
+        help: 'Import defineField from "sanity" and wrap each field: defineField({ name: "...", type: "..." })'
+      });
+    }
+  }
+};
+
+// src/rules/missing-icon.ts
+var missingIcon = {
+  id: "missing-icon",
+  name: "Missing icon",
+  description: "Document and object types should have an icon",
+  severity: "warning",
+  category: "style",
+  check(schema, context) {
+    if (schema.type !== "document" && schema.type !== "object") {
+      return;
+    }
+    if (!schema.hasIcon) {
+      context.report({
+        message: `Schema type "${schema.name}" should have an icon`,
+        severity: "warning",
+        ...schema.span && { span: schema.span },
+        help: "Add an icon from @sanity/icons: icon: DocumentIcon"
+      });
+    }
+  }
+};
+
+// src/rules/missing-title.ts
+var missingTitle = {
+  id: "missing-title",
+  name: "Missing title",
+  description: "Schema types should have a title property",
+  severity: "warning",
+  category: "style",
+  check(schema, context) {
+    if (schema.type !== "document" && schema.type !== "object") {
+      return;
+    }
+    if (!schema.title) {
+      context.report({
+        message: `Schema type "${schema.name}" should have a title property`,
+        severity: "warning",
+        ...schema.span && { span: schema.span },
+        help: 'Add a human-readable title: title: "Blog Post"'
+      });
+    }
+  }
+};
+
+// src/rules/missing-description.ts
+var missingDescription = {
+  id: "missing-description",
+  name: "Missing field description",
+  description: "Fields should have descriptions for better editor UX",
+  severity: "info",
+  category: "style",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    const fieldsWithoutDescription = [];
+    for (const field of schema.fields) {
+      if (field.hidden) {
+        continue;
+      }
+      if (["_id", "_type", "_rev", "_createdAt", "_updatedAt"].includes(field.name)) {
+        continue;
+      }
+      if (!field.description) {
+        fieldsWithoutDescription.push(field);
+      }
+    }
+    const visibleFields = schema.fields.filter(
+      (f) => !f.hidden && !["_id", "_type", "_rev", "_createdAt", "_updatedAt"].includes(f.name)
+    );
+    if (fieldsWithoutDescription.length > 0 && fieldsWithoutDescription.length >= visibleFields.length / 2) {
+      const fieldNames = fieldsWithoutDescription.map((f) => f.name).slice(0, 3);
+      const moreCount = fieldsWithoutDescription.length - 3;
+      context.report({
+        message: `Fields in "${schema.name}" lack descriptions: ${fieldNames.join(", ")}${moreCount > 0 ? ` and ${moreCount} more` : ""}`,
+        severity: "info",
+        ...schema.span && { span: schema.span },
+        help: "Add description to fields to help content editors understand what to enter"
+      });
+    }
+  }
+};
+
+// src/rules/presentation-field-name.ts
+var PRESENTATION_PATTERNS = [
+  // Color-based names
+  /^(red|blue|green|yellow|white|black|gray|grey|dark|light)/i,
+  // Size-based names
+  /^(big|small|large|tiny|huge|medium)/i,
+  /(Big|Small|Large|Tiny|Huge|Medium)$/,
+  // Layout-based names
+  /^(left|right|center|top|bottom)/i,
+  /(Left|Right|Center|Top|Bottom)$/,
+  // Column/row names
+  /(two|three|four|five|six)(Column|Row)/i,
+  /^(column|row)\d+$/i,
+  // Explicit presentation terms
+  /(Button|Text|Image|Box|Container|Wrapper|Section|Block|Card|Banner|Hero)$/,
+  /^(hero|banner|sidebar|header|footer)/i
+];
+var SUGGESTIONS = {
+  bigText: "headline, title, heading",
+  smallText: "caption, subtitle, description",
+  redButton: "primaryAction, callToAction",
+  heroSection: "featuredContent, highlight",
+  leftColumn: "primaryContent, mainContent",
+  rightColumn: "secondaryContent, sidebar",
+  threeColumnRow: "featuresGrid, comparisonSection",
+  headerImage: "featuredImage, coverImage",
+  bannerText: "announcement, promotion"
+};
+var presentationFieldName = {
+  id: "presentation-field-name",
+  name: "Presentation-focused field name",
+  description: "Avoid presentation-focused field names; use semantic names instead",
+  severity: "warning",
+  category: "style",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    for (const field of schema.fields) {
+      const name = field.name;
+      for (const pattern of PRESENTATION_PATTERNS) {
+        if (pattern.test(name)) {
+          const suggestion = SUGGESTIONS[name] || "a semantic name describing the content purpose";
+          context.report({
+            message: `Field "${name}" uses presentation-focused naming`,
+            severity: "warning",
+            ...field.span && { span: field.span },
+            help: `Consider using ${suggestion}. Field names should describe content purpose, not visual presentation.`
+          });
+          break;
+        }
+      }
+    }
+  }
+};
+
+// src/rules/boolean-instead-of-list.ts
+var EXPANDABLE_BOOLEAN_PATTERNS = [
+  /^is[A-Z]/,
+  // isActive, isPublished
+  /^has[A-Z]/,
+  // hasFeatured, hasDiscount
+  /^show[A-Z]/,
+  // showBanner, showSidebar
+  /^enable[A-Z]/,
+  // enableComments, enableSharing
+  /^allow[A-Z]/,
+  // allowComments, allowGuests
+  /Status$/,
+  // publicationStatus, reviewStatus
+  /State$/,
+  // publishState, approvalState
+  /Mode$/
+  // displayMode, editMode
+];
+var booleanInsteadOfList = {
+  id: "boolean-instead-of-list",
+  name: "Boolean instead of list",
+  description: "Consider using options.list instead of boolean for expandable states",
+  severity: "info",
+  category: "style",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    for (const field of schema.fields) {
+      if (field.type !== "boolean") {
+        continue;
+      }
+      const name = field.name;
+      for (const pattern of EXPANDABLE_BOOLEAN_PATTERNS) {
+        if (pattern.test(name)) {
+          context.report({
+            message: `Boolean field "${name}" might be better as a string with options.list`,
+            severity: "info",
+            ...field.span && { span: field.span },
+            help: 'Consider using type: "string" with options: { list: [...], layout: "radio" } for future expandability'
+          });
+          break;
+        }
+      }
+    }
+  }
+};
+
+// src/rules/missing-slug-source.ts
+var missingSlugSource = {
+  id: "missing-slug-source",
+  name: "Missing slug source",
+  description: "Slug fields should have options.source for auto-generation",
+  severity: "warning",
+  category: "style",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    for (const field of schema.fields) {
+      if (field.type !== "slug") {
+        continue;
+      }
+      if (!field.options?.source) {
+        context.report({
+          message: `Slug field "${field.name}" should have options.source`,
+          severity: "warning",
+          ...field.span && { span: field.span },
+          help: 'Add options: { source: "title" } to auto-generate slug from another field'
+        });
+      }
+    }
+  }
+};
+
+// src/rules/missing-required-validation.ts
+var TYPICALLY_REQUIRED_FIELDS = ["title", "name", "slug", "email", "url", "headline", "heading"];
+var missingRequiredValidation = {
+  id: "missing-required-validation",
+  name: "Missing required validation",
+  description: "Critical fields should have validation rules",
+  severity: "warning",
+  category: "correctness",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    if (schema.type !== "document") {
+      return;
+    }
+    for (const field of schema.fields) {
+      const name = field.name.toLowerCase();
+      if (TYPICALLY_REQUIRED_FIELDS.includes(name) && !field.hasValidation) {
+        context.report({
+          message: `Field "${field.name}" in document type should have validation`,
+          severity: "warning",
+          ...field.span && { span: field.span },
+          help: "Add validation: (rule) => rule.required() for critical fields"
+        });
+      }
+    }
+  }
+};
+
+// src/rules/reserved-field-name.ts
+var RESERVED_PREFIXES = ["_"];
+var RESERVED_NAMES = [
+  "_id",
+  "_type",
+  "_rev",
+  "_key",
+  "_createdAt",
+  "_updatedAt",
+  "_ref",
+  "_weak",
+  "_strengthenOnPublish"
+];
+var reservedFieldName = {
+  id: "reserved-field-name",
+  name: "Reserved field name",
+  description: "Field names starting with _ are reserved by Sanity",
+  severity: "error",
+  category: "correctness",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    for (const field of schema.fields) {
+      const name = field.name;
+      for (const prefix of RESERVED_PREFIXES) {
+        if (name.startsWith(prefix)) {
+          const isExactReserved = RESERVED_NAMES.includes(name);
+          context.report({
+            message: `Field name "${name}" uses reserved prefix "${prefix}"`,
+            severity: "error",
+            ...field.span && { span: field.span },
+            help: isExactReserved ? `"${name}" is a Sanity system field. Remove this field definition.` : `Field names starting with "${prefix}" are reserved. Use a different name.`
+          });
+          break;
+        }
+      }
+    }
+  }
+};
+
+// src/rules/array-missing-constraints.ts
+var arrayMissingConstraints = {
+  id: "array-missing-constraints",
+  name: "Array missing constraints",
+  description: "Array fields should have min/max/unique validation constraints",
+  severity: "info",
+  category: "style",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    for (const field of schema.fields) {
+      if (field.type !== "array") {
+        continue;
+      }
+      if (field.hasValidation) {
+        continue;
+      }
+      context.report({
+        message: `Array field "${field.name}" has no validation constraints`,
+        severity: "info",
+        ...field.span && { span: field.span },
+        help: "Consider adding validation: (rule) => rule.min(1).max(10).unique() to prevent unbounded arrays"
+      });
+    }
+  }
+};
+
+// src/rules/heading-level-in-schema.ts
+var HEADING_LEVEL_PATTERNS = [/^(heading|header)Level$/i, /^h[1-6]$/i, /Level$/];
+var HEADING_LEVEL_VALUES = ["h1", "h2", "h3", "h4", "h5", "h6"];
+var headingLevelInSchema = {
+  id: "heading-level-in-schema",
+  name: "Heading level in schema",
+  description: "Heading levels should be computed dynamically, not stored in schema",
+  severity: "warning",
+  category: "style",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    for (const field of schema.fields) {
+      for (const pattern of HEADING_LEVEL_PATTERNS) {
+        if (pattern.test(field.name)) {
+          context.report({
+            message: `Field "${field.name}" appears to store heading levels`,
+            severity: "warning",
+            ...field.span && { span: field.span },
+            help: "Heading levels should be computed dynamically in frontend components based on document structure, not stored in content."
+          });
+          break;
+        }
+      }
+      if (field.options?.list && Array.isArray(field.options.list)) {
+        const hasHeadingLevels = field.options.list.some((item) => {
+          const value = typeof item === "object" && item !== null ? item.value : item;
+          return typeof value === "string" && HEADING_LEVEL_VALUES.includes(value.toLowerCase());
+        });
+        if (hasHeadingLevels) {
+          context.report({
+            message: `Field "${field.name}" contains heading level options (h1, h2, etc.)`,
+            severity: "warning",
+            ...field.span && { span: field.span },
+            help: "Heading levels should be computed dynamically in frontend components based on document structure, not stored in content."
+          });
+        }
+      }
+    }
+  }
+};
+
+// src/rules/unnecessary-reference.ts
+var SHARED_TYPE_PATTERNS = [
+  /^author$/i,
+  /^category$/i,
+  /^tag$/i,
+  /^user$/i,
+  /^person$/i,
+  /^organization$/i,
+  /^company$/i,
+  /^brand$/i,
+  /^product$/i,
+  /^page$/i,
+  /^post$/i,
+  /^article$/i,
+  /^media$/i,
+  /^asset$/i,
+  /^file$/i,
+  /^image$/i,
+  /^video$/i,
+  /^document$/i,
+  /^location$/i,
+  /^venue$/i,
+  /^event$/i
+];
+var NON_SHARED_SUFFIXES = [
+  "Settings",
+  "Config",
+  "Configuration",
+  "Options",
+  "Metadata",
+  "Data",
+  "Info",
+  "Details",
+  "Content",
+  "Block",
+  "Section",
+  "Item",
+  "Entry"
+];
+function isLikelySharedType(typeName) {
+  return SHARED_TYPE_PATTERNS.some((pattern) => pattern.test(typeName));
+}
+function hasNonSharedSuffix(typeName) {
+  return NON_SHARED_SUFFIXES.some(
+    (suffix) => typeName.endsWith(suffix) && typeName.length > suffix.length
+  );
+}
+function isTypeSpecificToParent(parentName, referencedType) {
+  const parentLower = parentName.toLowerCase();
+  const refLower = referencedType.toLowerCase();
+  return refLower.startsWith(parentLower) && refLower !== parentLower;
+}
+var unnecessaryReference = {
+  id: "unnecessary-reference",
+  name: "Unnecessary reference",
+  description: "Consider using an embedded object instead of a reference for non-shared content",
+  severity: "info",
+  category: "style",
+  check(schema, context) {
+    if (!schema.fields) {
+      return;
+    }
+    for (const field of schema.fields) {
+      if (field.type !== "reference") {
+        continue;
+      }
+      if (!field.to || field.to.length === 0) {
+        continue;
+      }
+      for (const ref of field.to) {
+        const refType = ref.type;
+        if (isLikelySharedType(refType)) {
+          continue;
+        }
+        if (isTypeSpecificToParent(schema.name, refType)) {
+          context.report({
+            message: `Reference to "${refType}" may be unnecessary`,
+            severity: "info",
+            ...field.span && { span: field.span },
+            help: `"${refType}" appears specific to "${schema.name}". Consider embedding the object directly instead of using a reference.`
+          });
+          continue;
+        }
+        if (hasNonSharedSuffix(refType)) {
+          context.report({
+            message: `Reference to "${refType}" may be unnecessary`,
+            severity: "info",
+            ...field.span && { span: field.span },
+            help: `Types ending in "Settings", "Config", etc. are often better as embedded objects unless shared across multiple documents.`
+          });
+        }
+      }
+    }
+  }
+};
+
+// src/rules/index.ts
+var rules = [
+  // Core rules
+  missingDefineType,
+  missingDefineField,
+  missingIcon,
+  missingTitle,
+  missingDescription,
+  presentationFieldName,
+  // Field rules
+  booleanInsteadOfList,
+  missingSlugSource,
+  missingRequiredValidation,
+  reservedFieldName,
+  // Array & Reference rules
+  arrayMissingConstraints,
+  headingLevelInSchema,
+  unnecessaryReference
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  arrayMissingConstraints,
+  booleanInsteadOfList,
+  headingLevelInSchema,
+  lint,
+  lintSchemas,
+  missingDefineField,
+  missingDefineType,
+  missingDescription,
+  missingIcon,
+  missingRequiredValidation,
+  missingSlugSource,
+  missingTitle,
+  presentationFieldName,
+  reservedFieldName,
+  rules,
+  unnecessaryReference
+});
+//# sourceMappingURL=index.cjs.map