@sanity/lint-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Sanity.io
+
+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,119 @@
+# @sanity/lint-core
+
+Shared types, utilities, and testing infrastructure for Sanity lint packages.
+
+## Installation
+
+```bash
+npm install @sanity/lint-core
+# or
+pnpm add @sanity/lint-core
+```
+
+## Usage
+
+### Types
+
+```typescript
+import type { Rule, RuleContext, Finding, Severity, LinterConfig } from '@sanity/lint-core'
+
+// Define a custom rule
+const myRule: Rule = {
+  id: 'my-rule',
+  name: 'My Rule',
+  description: 'Checks for something',
+  severity: 'warning',
+  check(ast, context) {
+    // Return findings
+    return []
+  },
+}
+```
+
+### Reporting Utilities
+
+```typescript
+import { formatFindings, formatFindingsJson, summarizeFindings } from '@sanity/lint-core'
+
+// Format findings for terminal output
+const output = formatFindings(findings)
+
+// Format as JSON for CI
+const json = formatFindingsJson(findings)
+
+// Get summary statistics
+const summary = summarizeFindings(findings)
+console.log(`${summary.errorCount} errors, ${summary.warningCount} warnings`)
+```
+
+### Testing (Vitest)
+
+Import from the `/testing` subpath to use the RuleTester:
+
+```typescript
+import { RuleTester } from '@sanity/lint-core/testing'
+import { myRule } from '../my-rule'
+
+const tester = new RuleTester()
+
+tester.run('my-rule', myRule, {
+  valid: ['*[_type == "post"]', '*[_type == "post"]{ title }'],
+  invalid: [
+    {
+      code: '*[badPattern]',
+      errors: [{ ruleId: 'my-rule' }],
+    },
+  ],
+})
+```
+
+### GROQ Validation
+
+```typescript
+import { isValidGroq, parseGroq, assertValidGroq } from '@sanity/lint-core/testing'
+
+// Check if GROQ is valid
+if (isValidGroq('*[_type == "post"]')) {
+  // Valid query
+}
+
+// Parse and get AST
+const ast = parseGroq('*[_type == "post"]')
+
+// Assert validity (throws on invalid)
+assertValidGroq('*[_type == "post"]')
+```
+
+## API Reference
+
+### Types
+
+| Type           | Description                              |
+| -------------- | ---------------------------------------- |
+| `Rule`         | Lint rule interface                      |
+| `RuleContext`  | Context passed to rule check functions   |
+| `Finding`      | A lint finding (error, warning, or info) |
+| `Severity`     | `'error' \| 'warning' \| 'info'`         |
+| `LinterConfig` | Configuration for the linter             |
+| `SchemaType`   | Re-exported from groq-js                 |
+
+### Reporter Functions
+
+| Function                       | Description                         |
+| ------------------------------ | ----------------------------------- |
+| `formatFindings(findings)`     | Format findings for terminal output |
+| `formatFindingsJson(findings)` | Format findings as JSON             |
+| `summarizeFindings(findings)`  | Get error/warning/info counts       |
+
+### Testing Utilities
+
+| Export                   | Description                                |
+| ------------------------ | ------------------------------------------ |
+| `RuleTester`             | Test harness for lint rules                |
+| `isValidGroq(query)`     | Check if GROQ query is syntactically valid |
+| `parseGroq(query)`       | Parse GROQ and return AST                  |
+| `assertValidGroq(query)` | Assert GROQ is valid (throws on error)     |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { F as Finding } from './types-CPtvWKni.js';
+export { C as Category, L as LinterConfig, d as Rule, e as RuleConfig, R as RuleContext, S as Severity, a as SourceLocation, b as SourceSpan, c as Suggestion } from './types-CPtvWKni.js';
+export { SchemaType } from 'groq-js';
+
+/**
+ * Format findings as a human-readable string
+ */
+declare function formatFindings(query: string, findings: Finding[]): string;
+/**
+ * Format findings as JSON
+ */
+declare function formatFindingsJson(findings: Finding[]): string;
+/**
+ * Summary of findings by severity
+ */
+interface FindingsSummary {
+    total: number;
+    errors: number;
+    warnings: number;
+    infos: number;
+}
+/**
+ * Get a summary of findings
+ */
+declare function summarizeFindings(findings: Finding[]): FindingsSummary;
+
+export { Finding, type FindingsSummary, formatFindings, formatFindingsJson, summarizeFindings };

package/dist/index.js

@@ -0,0 +1,62 @@
+// src/reporter.ts
+function formatFindings(query, findings) {
+  if (findings.length === 0) {
+    return "";
+  }
+  const lines = query.split("\n");
+  const output = [];
+  for (const finding of findings) {
+    const severityPrefix = getSeverityPrefix(finding.severity);
+    output.push(`${severityPrefix}[${finding.ruleId}]: ${finding.message}`);
+    if (finding.span) {
+      const { line, column } = finding.span.start;
+      output.push(`  --> query:${line}:${column}`);
+      const lineContent = lines[line - 1];
+      if (lineContent !== void 0) {
+        const lineNum = String(line).padStart(3, " ");
+        output.push(`   |`);
+        output.push(`${lineNum} | ${lineContent}`);
+        const caretPadding = " ".repeat(column - 1);
+        const caretLength = Math.max(
+          1,
+          finding.span.end.line === line ? finding.span.end.column - column : lineContent.length - column + 1
+        );
+        const caret = "^".repeat(caretLength);
+        output.push(`   | ${caretPadding}${caret}`);
+      }
+      output.push(`   |`);
+    }
+    if (finding.help) {
+      output.push(`  = help: ${finding.help}`);
+    }
+    output.push("");
+  }
+  return output.join("\n");
+}
+function formatFindingsJson(findings) {
+  return JSON.stringify(findings, null, 2);
+}
+function getSeverityPrefix(severity) {
+  switch (severity) {
+    case "error":
+      return "error";
+    case "warning":
+      return "warning";
+    case "info":
+      return "info";
+  }
+}
+function summarizeFindings(findings) {
+  return {
+    total: findings.length,
+    errors: findings.filter((f) => f.severity === "error").length,
+    warnings: findings.filter((f) => f.severity === "warning").length,
+    infos: findings.filter((f) => f.severity === "info").length
+  };
+}
+export {
+  formatFindings,
+  formatFindingsJson,
+  summarizeFindings
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/reporter.ts"],"sourcesContent":["import type { Finding } from './types'\n\n/**\n * Format findings as a human-readable string\n */\nexport function formatFindings(query: string, findings: Finding[]): string {\n  if (findings.length === 0) {\n    return ''\n  }\n\n  const lines = query.split('\\n')\n  const output: string[] = []\n\n  for (const finding of findings) {\n    const severityPrefix = getSeverityPrefix(finding.severity)\n\n    output.push(`${severityPrefix}[${finding.ruleId}]: ${finding.message}`)\n\n    if (finding.span) {\n      const { line, column } = finding.span.start\n      output.push(`  --> query:${line}:${column}`)\n\n      // Show the offending line with context\n      const lineContent = lines[line - 1]\n      if (lineContent !== undefined) {\n        const lineNum = String(line).padStart(3, ' ')\n        output.push(`   |`)\n        output.push(`${lineNum} | ${lineContent}`)\n\n        // Add caret pointing to the issue\n        const caretPadding = ' '.repeat(column - 1)\n        const caretLength = Math.max(\n          1,\n          finding.span.end.line === line\n            ? finding.span.end.column - column\n            : lineContent.length - column + 1\n        )\n        const caret = '^'.repeat(caretLength)\n        output.push(`   | ${caretPadding}${caret}`)\n      }\n      output.push(`   |`)\n    }\n\n    if (finding.help) {\n      output.push(`  = help: ${finding.help}`)\n    }\n\n    output.push('')\n  }\n\n  return output.join('\\n')\n}\n\n/**\n * Format findings as JSON\n */\nexport function formatFindingsJson(findings: Finding[]): string {\n  return JSON.stringify(findings, null, 2)\n}\n\n/**\n * Get severity prefix for display\n */\nfunction getSeverityPrefix(severity: Finding['severity']): string {\n  switch (severity) {\n    case 'error':\n      return 'error'\n    case 'warning':\n      return 'warning'\n    case 'info':\n      return 'info'\n  }\n}\n\n/**\n * Summary of findings by severity\n */\nexport interface FindingsSummary {\n  total: number\n  errors: number\n  warnings: number\n  infos: number\n}\n\n/**\n * Get a summary of findings\n */\nexport function summarizeFindings(findings: Finding[]): FindingsSummary {\n  return {\n    total: findings.length,\n    errors: findings.filter((f) => f.severity === 'error').length,\n    warnings: findings.filter((f) => f.severity === 'warning').length,\n    infos: findings.filter((f) => f.severity === 'info').length,\n  }\n}\n"],"mappings":";AAKO,SAAS,eAAe,OAAe,UAA6B;AACzE,MAAI,SAAS,WAAW,GAAG;AACzB,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,MAAM,MAAM,IAAI;AAC9B,QAAM,SAAmB,CAAC;AAE1B,aAAW,WAAW,UAAU;AAC9B,UAAM,iBAAiB,kBAAkB,QAAQ,QAAQ;AAEzD,WAAO,KAAK,GAAG,cAAc,IAAI,QAAQ,MAAM,MAAM,QAAQ,OAAO,EAAE;AAEtE,QAAI,QAAQ,MAAM;AAChB,YAAM,EAAE,MAAM,OAAO,IAAI,QAAQ,KAAK;AACtC,aAAO,KAAK,eAAe,IAAI,IAAI,MAAM,EAAE;AAG3C,YAAM,cAAc,MAAM,OAAO,CAAC;AAClC,UAAI,gBAAgB,QAAW;AAC7B,cAAM,UAAU,OAAO,IAAI,EAAE,SAAS,GAAG,GAAG;AAC5C,eAAO,KAAK,MAAM;AAClB,eAAO,KAAK,GAAG,OAAO,MAAM,WAAW,EAAE;AAGzC,cAAM,eAAe,IAAI,OAAO,SAAS,CAAC;AAC1C,cAAM,cAAc,KAAK;AAAA,UACvB;AAAA,UACA,QAAQ,KAAK,IAAI,SAAS,OACtB,QAAQ,KAAK,IAAI,SAAS,SAC1B,YAAY,SAAS,SAAS;AAAA,QACpC;AACA,cAAM,QAAQ,IAAI,OAAO,WAAW;AACpC,eAAO,KAAK,QAAQ,YAAY,GAAG,KAAK,EAAE;AAAA,MAC5C;AACA,aAAO,KAAK,MAAM;AAAA,IACpB;AAEA,QAAI,QAAQ,MAAM;AAChB,aAAO,KAAK,aAAa,QAAQ,IAAI,EAAE;AAAA,IACzC;AAEA,WAAO,KAAK,EAAE;AAAA,EAChB;AAEA,SAAO,OAAO,KAAK,IAAI;AACzB;AAKO,SAAS,mBAAmB,UAA6B;AAC9D,SAAO,KAAK,UAAU,UAAU,MAAM,CAAC;AACzC;AAKA,SAAS,kBAAkB,UAAuC;AAChE,UAAQ,UAAU;AAAA,IAChB,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAeO,SAAS,kBAAkB,UAAsC;AACtE,SAAO;AAAA,IACL,OAAO,SAAS;AAAA,IAChB,QAAQ,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,OAAO,EAAE;AAAA,IACvD,UAAU,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,SAAS,EAAE;AAAA,IAC3D,OAAO,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,MAAM,EAAE;AAAA,EACvD;AACF;","names":[]}

package/dist/testing.d.ts

@@ -0,0 +1,124 @@
+import { d as Rule } from './types-CPtvWKni.js';
+import { ExprNode } from 'groq-js';
+
+/**
+ * A valid test case - query that should produce no findings
+ */
+interface ValidTestCase {
+    /** The GROQ query to test */
+    code: string;
+    /** Optional name for the test */
+    name?: string;
+}
+/**
+ * Expected error in an invalid test case
+ */
+interface ExpectedError {
+    /** Expected rule ID (defaults to the rule being tested) */
+    ruleId?: string;
+    /** Expected message (string for exact match, RegExp for pattern) */
+    message?: string | RegExp;
+    /** Expected severity */
+    severity?: 'error' | 'warning' | 'info';
+    /** Expected line number (1-based) */
+    line?: number;
+    /** Expected column number (1-based) */
+    column?: number;
+}
+/**
+ * An invalid test case - query that should produce findings
+ */
+interface InvalidTestCase {
+    /** The GROQ query to test */
+    code: string;
+    /** Optional name for the test */
+    name?: string;
+    /** Expected errors */
+    errors: ExpectedError[];
+}
+/**
+ * Test suite for a rule
+ */
+interface RuleTests {
+    /** Queries that should produce no findings */
+    valid: (string | ValidTestCase)[];
+    /** Queries that should produce findings */
+    invalid: InvalidTestCase[];
+}
+/**
+ * Test utility for lint rules, inspired by ESLint's RuleTester
+ *
+ * @example
+ * ```typescript
+ * import { RuleTester } from '@sanity/lint-core'
+ * import { joinInFilter } from '../join-in-filter'
+ *
+ * const tester = new RuleTester()
+ *
+ * tester.run('join-in-filter', joinInFilter, {
+ *   valid: [
+ *     '*[_type == "post"]',
+ *     '*[_type == "post"]{ author-> }',
+ *   ],
+ *   invalid: [
+ *     {
+ *       code: '*[author->name == "Bob"]',
+ *       errors: [{ ruleId: 'join-in-filter' }]
+ *     }
+ *   ]
+ * })
+ * ```
+ */
+declare class RuleTester {
+    /**
+     * Run tests for a rule
+     * @param ruleName - Name for the test suite
+     * @param rule - The rule to test
+     * @param tests - Valid and invalid test cases
+     */
+    run(ruleName: string, rule: Rule, tests: RuleTests): void;
+    /**
+     * Truncate a string for display
+     */
+    private truncate;
+}
+
+/**
+ * GROQ validation utilities using groq-js as the single source of truth.
+ *
+ * Use these in tests to ensure queries are valid GROQ syntax:
+ *
+ * ```ts
+ * import { assertValidGroq } from '@sanity/lint-core/testing'
+ *
+ * it('produces valid GROQ', () => {
+ *   const result = formatGroq(query)
+ *   assertValidGroq(result) // Throws if invalid
+ * })
+ * ```
+ */
+
+interface GroqParseError {
+    message: string;
+    position?: number;
+    query: string;
+}
+/**
+ * Parse a GROQ query string and return the AST.
+ * Throws a GroqParseError if the query is invalid.
+ */
+declare function parseGroq(query: string): ExprNode;
+/**
+ * Check if a string is valid GROQ syntax.
+ * Returns true if valid, false if invalid.
+ */
+declare function isValidGroq(query: string): boolean;
+/**
+ * Assert that a string is valid GROQ syntax.
+ * Throws an error with helpful context if invalid.
+ *
+ * Use this in tests to validate formatter output or generated queries.
+ */
+declare function assertValidGroq(query: string, context?: string): void;
+
+export { type ExpectedError, type GroqParseError, type InvalidTestCase, RuleTester, type RuleTests, type ValidTestCase, assertValidGroq, isValidGroq, parseGroq };

package/dist/testing.js

@@ -0,0 +1,167 @@
+// src/rule-tester.ts
+import { describe, it, expect } from "vitest";
+import { parse } from "groq-js";
+function runRule(rule, query) {
+  const findings = [];
+  let ast;
+  try {
+    ast = parse(query);
+  } catch {
+    return [];
+  }
+  const context = {
+    query,
+    queryLength: query.length,
+    report: (finding) => {
+      findings.push({
+        ...finding,
+        ruleId: rule.id
+      });
+    }
+  };
+  rule.check(ast, context);
+  return findings;
+}
+function assertFindingMatches(finding, expected, ruleId) {
+  const expectedRuleId = expected.ruleId ?? ruleId;
+  expect(finding.ruleId).toBe(expectedRuleId);
+  if (expected.message !== void 0) {
+    if (typeof expected.message === "string") {
+      expect(finding.message).toBe(expected.message);
+    } else {
+      expect(finding.message).toMatch(expected.message);
+    }
+  }
+  if (expected.severity !== void 0) {
+    expect(finding.severity).toBe(expected.severity);
+  }
+  if (expected.line !== void 0 && finding.span) {
+    expect(finding.span.start.line).toBe(expected.line);
+  }
+  if (expected.column !== void 0 && finding.span) {
+    expect(finding.span.start.column).toBe(expected.column);
+  }
+}
+var RuleTester = class {
+  /**
+   * Run tests for a rule
+   * @param ruleName - Name for the test suite
+   * @param rule - The rule to test
+   * @param tests - Valid and invalid test cases
+   */
+  run(ruleName, rule, tests) {
+    describe(ruleName, () => {
+      describe("valid", () => {
+        for (const test of tests.valid) {
+          const testCase = typeof test === "string" ? { code: test } : test;
+          const testName = testCase.name ?? this.truncate(testCase.code, 60);
+          it(testName, () => {
+            const findings = runRule(rule, testCase.code);
+            expect(findings).toHaveLength(0);
+          });
+        }
+      });
+      describe("invalid", () => {
+        for (const test of tests.invalid) {
+          const testName = test.name ?? this.truncate(test.code, 60);
+          it(testName, () => {
+            const findings = runRule(rule, test.code);
+            expect(findings).toHaveLength(test.errors.length);
+            for (let i = 0; i < test.errors.length; i++) {
+              const finding = findings[i];
+              const expected = test.errors[i];
+              if (finding && expected) {
+                assertFindingMatches(finding, expected, rule.id);
+              }
+            }
+          });
+        }
+      });
+    });
+  }
+  /**
+   * Truncate a string for display
+   */
+  truncate(str, maxLength) {
+    const oneLine = str.replace(/\s+/g, " ").trim();
+    if (oneLine.length <= maxLength) {
+      return oneLine;
+    }
+    return oneLine.slice(0, maxLength - 3) + "...";
+  }
+};
+
+// src/groq-validator.ts
+import { parse as parse2 } from "groq-js";
+function parseGroq(query) {
+  const trimmed = query.trim();
+  if (!trimmed) {
+    const error = {
+      message: "Empty GROQ query",
+      query
+    };
+    throw error;
+  }
+  try {
+    return parse2(trimmed);
+  } catch (e) {
+    const error = {
+      message: e instanceof Error ? e.message : String(e),
+      query
+    };
+    const posMatch = error.message.match(/position (\d+)/);
+    if (posMatch && posMatch[1]) {
+      error.position = parseInt(posMatch[1], 10);
+    }
+    throw error;
+  }
+}
+function isValidGroq(query) {
+  try {
+    parseGroq(query);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function assertValidGroq(query, context) {
+  try {
+    parseGroq(query);
+  } catch (e) {
+    const error = e;
+    let message = `Invalid GROQ syntax: ${error.message}`;
+    if (context) {
+      message = `${context}: ${message}`;
+    }
+    if (error.position !== void 0) {
+      const lines = error.query.split("\n");
+      let charCount = 0;
+      let errorCol = 0;
+      for (const line of lines) {
+        if (charCount + line.length >= error.position) {
+          errorCol = error.position - charCount;
+          break;
+        }
+        charCount += line.length + 1;
+      }
+      message += `
+
+Query:
+${error.query}
+${" ".repeat(errorCol)}^ position ${error.position}`;
+    } else {
+      message += `
+
+Query:
+${error.query}`;
+    }
+    throw new Error(message);
+  }
+}
+export {
+  RuleTester,
+  assertValidGroq,
+  isValidGroq,
+  parseGroq
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rule-tester.ts","../src/groq-validator.ts"],"sourcesContent":["import { describe, it, expect } from 'vitest'\nimport { parse } from 'groq-js'\nimport type { Rule, Finding, RuleContext } from './types'\n\n/**\n * A valid test case - query that should produce no findings\n */\nexport interface ValidTestCase {\n  /** The GROQ query to test */\n  code: string\n  /** Optional name for the test */\n  name?: string\n}\n\n/**\n * Expected error in an invalid test case\n */\nexport interface ExpectedError {\n  /** Expected rule ID (defaults to the rule being tested) */\n  ruleId?: string\n  /** Expected message (string for exact match, RegExp for pattern) */\n  message?: string | RegExp\n  /** Expected severity */\n  severity?: 'error' | 'warning' | 'info'\n  /** Expected line number (1-based) */\n  line?: number\n  /** Expected column number (1-based) */\n  column?: number\n}\n\n/**\n * An invalid test case - query that should produce findings\n */\nexport interface InvalidTestCase {\n  /** The GROQ query to test */\n  code: string\n  /** Optional name for the test */\n  name?: string\n  /** Expected errors */\n  errors: ExpectedError[]\n}\n\n/**\n * Test suite for a rule\n */\nexport interface RuleTests {\n  /** Queries that should produce no findings */\n  valid: (string | ValidTestCase)[]\n  /** Queries that should produce findings */\n  invalid: InvalidTestCase[]\n}\n\n/**\n * Run a single rule against a query and collect findings\n */\nfunction runRule(rule: Rule, query: string): Finding[] {\n  const findings: Finding[] = []\n\n  let ast\n  try {\n    ast = parse(query)\n  } catch {\n    // If query doesn't parse, return empty findings\n    // (parser errors are separate from lint errors)\n    return []\n  }\n\n  const context: RuleContext = {\n    query,\n    queryLength: query.length,\n    report: (finding) => {\n      findings.push({\n        ...finding,\n        ruleId: rule.id,\n      })\n    },\n  }\n\n  rule.check(ast, context)\n\n  return findings\n}\n\n/**\n * Assert that a finding matches expected error\n */\nfunction assertFindingMatches(finding: Finding, expected: ExpectedError, ruleId: string): void {\n  // Check rule ID\n  const expectedRuleId = expected.ruleId ?? ruleId\n  expect(finding.ruleId).toBe(expectedRuleId)\n\n  // Check message if specified\n  if (expected.message !== undefined) {\n    if (typeof expected.message === 'string') {\n      expect(finding.message).toBe(expected.message)\n    } else {\n      expect(finding.message).toMatch(expected.message)\n    }\n  }\n\n  // Check severity if specified\n  if (expected.severity !== undefined) {\n    expect(finding.severity).toBe(expected.severity)\n  }\n\n  // Check location if specified\n  if (expected.line !== undefined && finding.span) {\n    expect(finding.span.start.line).toBe(expected.line)\n  }\n  if (expected.column !== undefined && finding.span) {\n    expect(finding.span.start.column).toBe(expected.column)\n  }\n}\n\n/**\n * Test utility for lint rules, inspired by ESLint's RuleTester\n *\n * @example\n * ```typescript\n * import { RuleTester } from '@sanity/lint-core'\n * import { joinInFilter } from '../join-in-filter'\n *\n * const tester = new RuleTester()\n *\n * tester.run('join-in-filter', joinInFilter, {\n *   valid: [\n *     '*[_type == \"post\"]',\n *     '*[_type == \"post\"]{ author-> }',\n *   ],\n *   invalid: [\n *     {\n *       code: '*[author->name == \"Bob\"]',\n *       errors: [{ ruleId: 'join-in-filter' }]\n *     }\n *   ]\n * })\n * ```\n */\nexport class RuleTester {\n  /**\n   * Run tests for a rule\n   * @param ruleName - Name for the test suite\n   * @param rule - The rule to test\n   * @param tests - Valid and invalid test cases\n   */\n  run(ruleName: string, rule: Rule, tests: RuleTests): void {\n    describe(ruleName, () => {\n      describe('valid', () => {\n        for (const test of tests.valid) {\n          const testCase = typeof test === 'string' ? { code: test } : test\n          const testName = testCase.name ?? this.truncate(testCase.code, 60)\n\n          it(testName, () => {\n            const findings = runRule(rule, testCase.code)\n            expect(findings).toHaveLength(0)\n          })\n        }\n      })\n\n      describe('invalid', () => {\n        for (const test of tests.invalid) {\n          const testName = test.name ?? this.truncate(test.code, 60)\n\n          it(testName, () => {\n            const findings = runRule(rule, test.code)\n\n            // Check we got the expected number of errors\n            expect(findings).toHaveLength(test.errors.length)\n\n            // Check each error matches\n            for (let i = 0; i < test.errors.length; i++) {\n              const finding = findings[i]\n              const expected = test.errors[i]\n              if (finding && expected) {\n                assertFindingMatches(finding, expected, rule.id)\n              }\n            }\n          })\n        }\n      })\n    })\n  }\n\n  /**\n   * Truncate a string for display\n   */\n  private truncate(str: string, maxLength: number): string {\n    const oneLine = str.replace(/\\s+/g, ' ').trim()\n    if (oneLine.length <= maxLength) {\n      return oneLine\n    }\n    return oneLine.slice(0, maxLength - 3) + '...'\n  }\n}\n","/**\n * GROQ validation utilities using groq-js as the single source of truth.\n *\n * Use these in tests to ensure queries are valid GROQ syntax:\n *\n * ```ts\n * import { assertValidGroq } from '@sanity/lint-core/testing'\n *\n * it('produces valid GROQ', () => {\n *   const result = formatGroq(query)\n *   assertValidGroq(result) // Throws if invalid\n * })\n * ```\n */\n\nimport { parse, type ExprNode } from 'groq-js'\n\nexport interface GroqParseError {\n  message: string\n  position?: number\n  query: string\n}\n\n/**\n * Parse a GROQ query string and return the AST.\n * Throws a GroqParseError if the query is invalid.\n */\nexport function parseGroq(query: string): ExprNode {\n  const trimmed = query.trim()\n  if (!trimmed) {\n    const error: GroqParseError = {\n      message: 'Empty GROQ query',\n      query,\n    }\n    throw error\n  }\n\n  try {\n    return parse(trimmed)\n  } catch (e) {\n    const error: GroqParseError = {\n      message: e instanceof Error ? e.message : String(e),\n      query,\n    }\n    // Extract position from groq-js error message if available\n    const posMatch = error.message.match(/position (\\d+)/)\n    if (posMatch && posMatch[1]) {\n      error.position = parseInt(posMatch[1], 10)\n    }\n    throw error\n  }\n}\n\n/**\n * Check if a string is valid GROQ syntax.\n * Returns true if valid, false if invalid.\n */\nexport function isValidGroq(query: string): boolean {\n  try {\n    parseGroq(query)\n    return true\n  } catch {\n    return false\n  }\n}\n\n/**\n * Assert that a string is valid GROQ syntax.\n * Throws an error with helpful context if invalid.\n *\n * Use this in tests to validate formatter output or generated queries.\n */\nexport function assertValidGroq(query: string, context?: string): void {\n  try {\n    parseGroq(query)\n  } catch (e) {\n    const error = e as GroqParseError\n    let message = `Invalid GROQ syntax: ${error.message}`\n    if (context) {\n      message = `${context}: ${message}`\n    }\n    if (error.position !== undefined) {\n      // Show the query with a pointer to the error position\n      const lines = error.query.split('\\n')\n      let charCount = 0\n      let errorCol = 0\n\n      for (const line of lines) {\n        if (charCount + line.length >= error.position) {\n          errorCol = error.position - charCount\n          break\n        }\n        charCount += line.length + 1 // +1 for newline\n      }\n\n      message += `\\n\\nQuery:\\n${error.query}\\n${' '.repeat(errorCol)}^ position ${error.position}`\n    } else {\n      message += `\\n\\nQuery:\\n${error.query}`\n    }\n\n    throw new Error(message)\n  }\n}\n"],"mappings":"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","names":["parse"]}

package/dist/types-CPtvWKni.d.ts

@@ -0,0 +1,112 @@
+import { SchemaType, ExprNode } from 'groq-js';
+
+/**
+ * Severity levels for lint findings
+ */
+type Severity = 'error' | 'warning' | 'info';
+/**
+ * Category of the lint rule
+ */
+type Category = 'performance' | 'correctness' | 'style';
+/**
+ * A location in the source query
+ */
+interface SourceLocation {
+    /** 1-based line number */
+    line: number;
+    /** 1-based column number */
+    column: number;
+    /** 0-based character offset */
+    offset: number;
+}
+/**
+ * A span in the source query
+ */
+interface SourceSpan {
+    start: SourceLocation;
+    end: SourceLocation;
+}
+/**
+ * A suggested fix for a finding
+ */
+interface Suggestion {
+    /** Description of what the suggestion does */
+    description: string;
+    /** The replacement text */
+    replacement: string;
+}
+/**
+ * A lint finding/diagnostic
+ */
+interface Finding {
+    /** Rule ID that produced this finding */
+    ruleId: string;
+    /** Human-readable message */
+    message: string;
+    /** Severity level */
+    severity: Severity;
+    /** Location in source (optional - some rules are query-wide) */
+    span?: SourceSpan;
+    /** Additional help text */
+    help?: string;
+    /** Suggested fixes */
+    suggestions?: Suggestion[];
+}
+/**
+ * Context provided to rules during checking
+ */
+interface RuleContext {
+    /** The raw query string */
+    query: string;
+    /** Length of the query in bytes */
+    queryLength: number;
+    /** Report a finding */
+    report: (finding: Omit<Finding, 'ruleId'>) => void;
+    /** Schema for schema-aware rules (optional) */
+    schema?: SchemaType;
+}
+/**
+ * A lint rule definition
+ */
+interface Rule {
+    /** Unique identifier (kebab-case) */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what the rule checks */
+    description: string;
+    /** Default severity */
+    severity: Severity;
+    /** Rule category */
+    category: Category;
+    /** Rule IDs that this rule supersedes */
+    supersedes?: string[];
+    /** Whether this rule requires a schema to function */
+    requiresSchema?: boolean;
+    /**
+     * Check the AST for violations
+     * @param ast - The parsed GROQ AST
+     * @param context - Context with query info and report function
+     */
+    check: (ast: ExprNode, context: RuleContext) => void;
+}
+/**
+ * Configuration for a rule
+ */
+interface RuleConfig {
+    /** Whether the rule is enabled */
+    enabled?: boolean;
+    /** Override severity */
+    severity?: Severity;
+    /** Rule-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Linter configuration
+ */
+interface LinterConfig {
+    /** Rule configurations keyed by rule ID */
+    rules?: Record<string, RuleConfig | boolean>;
+}
+
+export type { Category as C, Finding as F, LinterConfig as L, RuleContext as R, Severity as S, SourceLocation as a, SourceSpan as b, Suggestion as c, Rule as d, RuleConfig as e };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sanity/lint-core",
+  "version": "0.0.1",
+  "description": "Shared types and utilities for Sanity Lint",
+  "author": "Sanity.io <hello@sanity.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanity-io/sanity-lint.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "sanity",
+    "lint",
+    "eslint"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "groq-js": "^1.14.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}