chore: docs, cleanup, remove dead code

Author: mscolnick

demo/index.ts

@@ -1,8 +1,7 @@
-import { SQLDialect, StandardSQL, sql } from "@codemirror/lang-sql";
+import { StandardSQL, sql } from "@codemirror/lang-sql";
 import { basicSetup, EditorView } from "codemirror";
 import { cteCompletionSource } from "../src/sql/cte-completion-source.js";
 import { sqlExtension } from "../src/sql/extension.js";
-import type { SqlKeywordInfo } from "../src/sql/hover.js";
 
 // Default SQL content for the demo
 const defaultSqlDoc = `-- Welcome to the SQL Editor Demo!

package.json

@@ -19,8 +19,7 @@
     "demo": "vite build",
     "build": "tsc",
     "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build",
-    "release": "pnpm version",
-    "pre-commit": "lint-staged"
+    "release": "pnpm version"
   },
   "keywords": [
     "codemirror",
@@ -38,9 +37,7 @@
     "@codemirror/view": "^6.36.2",
     "@vitest/coverage-v8": "3.1.3",
     "codemirror": "^6.0.1",
-    "husky": "^9.1.7",
     "jsdom": "^26.0.0",
-    "lint-staged": "^15.4.3",
     "typescript": "^5.7.3",
     "vite": "^7.0.0",
     "vitest": "^3.0.5"
@@ -65,16 +62,9 @@
     "node": "*"
   },
   "module": "./dist/index.js",
-  "lint-staged": {
-    "*.{ts,tsx}": [
-      "biome check --write",
-      "biome format --write",
-      "vitest related --run"
-    ]
-  },
   "dependencies": {
-    "@codemirror/lint": "^6.0.0",
     "@codemirror/autocomplete": "^6.0.0",
+    "@codemirror/lint": "^6.0.0",
     "node-sql-parser": "^5.3.10"
   }
 }

pnpm-lock.yaml

@@ -1,28 +1,49 @@
+import { Text } from "@codemirror/state";
+import type { EditorView } from "@codemirror/view";
 import { describe, expect, it, vi } from "vitest";
 import { sqlLinter } from "../diagnostics.js";
-import { SqlParser } from "../parser.js";
+
+// Mock EditorView
+const _createMockView = (content: string) => {
+  const doc = Text.of(content.split("\n"));
+  return {
+    state: { doc },
+  } as EditorView;
+};
 
 describe("sqlLinter", () => {
   it("should create a linter extension", () => {
     const linter = sqlLinter();
     expect(linter).toBeDefined();
   });
 
-  it("should use custom parser when provided", () => {
-    const mockParser = vi.mocked(new SqlParser());
-    mockParser.validateSql = vi.fn().mockReturnValue([]);
+  it("should accept configuration with custom delay", () => {
+    const linter = sqlLinter({ delay: 1000 });
+    expect(linter).toBeDefined();
+  });
+
+  it("should use custom parser if provided", () => {
+    const mockParser = {
+      validateSql: vi.fn(() => []),
+      parseSql: vi.fn(() => ({ statements: [] })),
+    } as any;
 
     const linter = sqlLinter({ parser: mockParser });
     expect(linter).toBeDefined();
   });
 
-  it("should use default delay if not provided", () => {
+  it("should use default delay when no delay provided", () => {
     const linter = sqlLinter();
     expect(linter).toBeDefined();
   });
 
   it("should use custom delay when provided", () => {
-    const linter = sqlLinter({ delay: 1000 });
+    const linter = sqlLinter({ delay: 500 });
+    expect(linter).toBeDefined();
+  });
+
+  it("should use default parser when no parser provided", () => {
+    const linter = sqlLinter();
     expect(linter).toBeDefined();
   });
 });

src/sql/__tests__/diagnostics.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { sqlExtension } from "../extension.js";
+
+describe("sqlExtension", () => {
+  it("should return an array of extensions with default config", () => {
+    const extensions = sqlExtension();
+    expect(Array.isArray(extensions)).toBe(true);
+    expect(extensions.length).toBeGreaterThan(0);
+  });
+
+  it("should return extensions with all features enabled by default", () => {
+    const extensions = sqlExtension({});
+    // Should include linter, gutter (4 parts), hover, and hover theme
+    expect(extensions.length).toBeGreaterThan(2);
+  });
+
+  it("should exclude linting when disabled", () => {
+    const extensions = sqlExtension({ enableLinting: false });
+    // Should include gutter, hover, and hover theme (no linter)
+    expect(extensions.length).toBeGreaterThan(2);
+  });
+
+  it("should exclude gutter markers when disabled", () => {
+    const extensions = sqlExtension({ enableGutterMarkers: false });
+    // Should include linter, hover, and hover theme (no gutter)
+    expect(extensions.length).toBeGreaterThan(1);
+  });
+
+  it("should exclude hover when disabled", () => {
+    const extensions = sqlExtension({ enableHover: false });
+    // Should include linter and gutter (no hover or hover theme)
+    expect(extensions.length).toBeGreaterThan(0);
+  });
+
+  it("should handle all features disabled", () => {
+    const extensions = sqlExtension({
+      enableLinting: false,
+      enableGutterMarkers: false,
+      enableHover: false,
+    });
+    expect(extensions).toEqual([]);
+  });
+
+  it("should pass config objects to individual extensions", () => {
+    const linterConfig = { delay: 500 };
+    const gutterConfig = { backgroundColor: "#ff0000" };
+    const hoverConfig = { hoverTime: 200 };
+
+    const extensions = sqlExtension({
+      linterConfig,
+      gutterConfig,
+      hoverConfig,
+    });
+
+    expect(extensions.length).toBeGreaterThan(2);
+  });
+
+  it("should handle partial configuration", () => {
+    const extensions = sqlExtension({
+      enableLinting: true,
+      linterConfig: { delay: 100 },
+    });
+
+    expect(extensions.length).toBeGreaterThan(2);
+  });
+});

src/sql/__tests__/extension.test.ts

@@ -233,7 +233,7 @@ describe("Hover Integration Tests", () => {
     });
 
     it("should handle very long paths gracefully", () => {
-      const longPath = "a.".repeat(20) + "final";
+      const longPath = `${"a.".repeat(20)}final`;
       expect(() => {
         resolveNamespaceItem(testNamespace, longPath);
       }).not.toThrow();

src/sql/__tests__/hover-integration.test.ts

@@ -7,7 +7,6 @@ import {
   isArrayNamespace,
   isObjectNamespace,
   isSelfChildrenNamespace,
-  type ResolvedNamespaceItem,
   resolveNamespaceItem,
   traverseNamespacePath,
 } from "../namespace-utils.js";

src/sql/__tests__/namespace-utils.test.ts

@@ -0,0 +1,74 @@
+import { EditorState, Text } from "@codemirror/state";
+import type { EditorView } from "@codemirror/view";
+import { describe, expect, it } from "vitest";
+import { sqlStructureGutter } from "../structure-extension.js";
+
+// Mock EditorView
+const _createMockView = (content: string, hasFocus = true) => {
+  const doc = Text.of(content.split("\n"));
+  const state = EditorState.create({
+    doc,
+    extensions: [sqlStructureGutter()],
+  });
+
+  return {
+    state,
+    hasFocus,
+    dispatch: () => {},
+  } as any as EditorView;
+};
+
+describe("sqlStructureGutter", () => {
+  it("should create a gutter extension with default config", () => {
+    const extensions = sqlStructureGutter();
+    expect(Array.isArray(extensions)).toBe(true);
+    expect(extensions.length).toBeGreaterThan(0);
+  });
+
+  it("should accept custom configuration", () => {
+    const config = {
+      backgroundColor: "#ff0000",
+      errorBackgroundColor: "#00ff00",
+      width: 5,
+      className: "custom-sql-gutter",
+      showInvalid: false,
+      inactiveOpacity: 0.5,
+      hideWhenNotFocused: true,
+    };
+
+    const extensions = sqlStructureGutter(config);
+    expect(Array.isArray(extensions)).toBe(true);
+    expect(extensions.length).toBeGreaterThan(0);
+  });
+
+  it("should handle empty configuration", () => {
+    const extensions = sqlStructureGutter({});
+    expect(Array.isArray(extensions)).toBe(true);
+  });
+
+  it("should create extensions for all required parts", () => {
+    const extensions = sqlStructureGutter();
+    // Should include state field, update listener, theme, and gutter
+    expect(extensions.length).toBe(4);
+  });
+
+  it("should handle unfocusedOpacity configuration", () => {
+    const config = { unfocusedOpacity: 0.2 };
+    const extensions = sqlStructureGutter(config);
+    expect(extensions.length).toBe(4);
+  });
+
+  it("should handle whenHide configuration", () => {
+    const config = {
+      whenHide: (view: EditorView) => view.state.doc.length === 0,
+    };
+    const extensions = sqlStructureGutter(config);
+    expect(extensions.length).toBe(4);
+  });
+
+  it("should work with minimal configuration", () => {
+    const config = { width: 2 };
+    const extensions = sqlStructureGutter(config);
+    expect(extensions.length).toBe(4);
+  });
+});

src/sql/__tests__/structure-extension.test.ts

@@ -1,5 +1,25 @@
 import type { Completion, CompletionContext, CompletionSource } from "@codemirror/autocomplete";
 
+/**
+ * A completion source for Common Table Expressions (CTEs) in SQL
+ *
+ * This function provides autocomplete suggestions for CTE references based on
+ * WITH clauses found in the current SQL document.
+ *
+ * @param context The completion context from CodeMirror
+ * @returns Completion result with CTE suggestions or null if no completions available
+ *
+ * @example
+ * ```ts
+ * import { cteCompletionSource } from '@marimo-team/codemirror-sql';
+ * import { StandardSQL } from '@codemirror/lang-sql';
+ *
+ * // Add to SQL language configuration
+ * StandardSQL.language.data.of({
+ *   autocomplete: cteCompletionSource,
+ * })
+ * ```
+ */
 export const cteCompletionSource: CompletionSource = (context: CompletionContext) => {
   const doc = context.state.doc.toString();
   const cteNames = new Set<string>();

src/sql/cte-completion-source.ts

@@ -5,11 +5,19 @@ import { type SqlParseError, SqlParser } from "./parser.js";
 
 const DEFAULT_DELAY = 750;
 
+/**
+ * Configuration options for the SQL linter
+ */
 export interface SqlLinterConfig {
+  /** Delay in milliseconds before running validation (default: 750) */
   delay?: number;
+  /** Custom SQL parser instance to use for validation */
   parser?: SqlParser;
 }
 
+/**
+ * Converts a SQL parse error to a CodeMirror diagnostic
+ */
 function convertToCodeMirrorDiagnostic(error: SqlParseError, doc: Text): Diagnostic {
   const lineStart = doc.line(error.line).from;
   const from = lineStart + Math.max(0, error.column - 1);
@@ -24,6 +32,22 @@ function convertToCodeMirrorDiagnostic(error: SqlParseError, doc: Text): Diagnos
   };
 }
 
+/**
+ * Creates a SQL linter extension that validates SQL syntax and reports errors
+ *
+ * @param config Configuration options for the linter
+ * @returns A CodeMirror linter extension
+ *
+ * @example
+ * ```ts
+ * import { sqlLinter } from '@marimo-team/codemirror-sql';
+ *
+ * const linter = sqlLinter({
+ *   delay: 500, // 500ms delay before validation
+ *   parser: new SqlParser() // custom parser instance
+ * });
+ * ```
+ */
 export function sqlLinter(config: SqlLinterConfig = {}) {
   const parser = config.parser || new SqlParser();