@consilioweb/spellcheck 0.10.1

package/dist/index.d.cts

@@ -0,0 +1,268 @@
+import { Plugin } from 'payload';
+
+/**
+ * Spellcheck Plugin — Type definitions.
+ */
+interface SpellCheckIssue {
+    /** LanguageTool rule ID (e.g. 'GRAMMAR', 'MORFOLOGIK_RULE_FR') */
+    ruleId: string;
+    /** LanguageTool category (e.g. 'GRAMMAR', 'TYPOS') */
+    category: string;
+    /** Human-readable message explaining the issue */
+    message: string;
+    /** Text context around the error */
+    context: string;
+    /** Offset of the error within the context string */
+    contextOffset: number;
+    /** Offset within the full extracted text */
+    offset: number;
+    /** Length of the problematic text */
+    length: number;
+    /** The original (wrong) text */
+    original: string;
+    /** Suggested replacements (max 3) */
+    replacements: string[];
+    /** Source engine: 'languagetool' or 'claude' */
+    source: 'languagetool' | 'claude';
+    /** Whether this is a premium-only rule */
+    isPremium?: boolean;
+}
+interface SpellCheckResult {
+    /** Document ID */
+    docId: string | number;
+    /** Collection slug */
+    collection: string;
+    /** Score 0-100 (100 = no issues) */
+    score: number;
+    /** Number of issues found */
+    issueCount: number;
+    /** Word count of the extracted text */
+    wordCount: number;
+    /** Detailed issues */
+    issues: SpellCheckIssue[];
+    /** ISO date of last check */
+    lastChecked: string;
+}
+interface SpellCheckPluginConfig {
+    /** Collections to check (default: ['pages', 'posts']) */
+    collections?: string[];
+    /** Rich text field name to extract content from (default: 'content') */
+    contentField?: string;
+    /** Language for LanguageTool (default: 'fr') */
+    language?: string;
+    /** Run spellcheck automatically on save (default: true) */
+    checkOnSave?: boolean;
+    /** Add sidebar field in the editor (default: true) */
+    addSidebarField?: boolean;
+    /** Add dashboard view at /admin/spellcheck (default: true) */
+    addDashboardView?: boolean;
+    /** Add score column in collection list views (default: true) */
+    addListColumn?: boolean;
+    /** Base path for API endpoints (default: '/spellcheck') */
+    endpointBasePath?: string;
+    /** Enable Claude AI as semantic fallback (default: false) */
+    enableAiFallback?: boolean;
+    /** Anthropic API key for Claude fallback */
+    anthropicApiKey?: string;
+    /** LanguageTool rule IDs to skip */
+    skipRules?: string[];
+    /** LanguageTool categories to skip */
+    skipCategories?: string[];
+    /** Custom dictionary — words to never flag */
+    customDictionary?: string[];
+}
+
+/**
+ * Payload CMS Spellcheck Plugin.
+ *
+ * Adds spellchecking capabilities via LanguageTool + optional Claude AI:
+ * - Sidebar field in the editor (real-time spellcheck)
+ * - Dashboard view at /admin/spellcheck
+ * - API endpoints for validate, fix, bulk scan
+ * - afterChange hook for automatic checks on save
+ * - SpellCheckResults collection for storing results
+ *
+ * Usage:
+ *   import { spellcheckPlugin } from '@consilioweb/spellcheck'
+ *
+ *   export default buildConfig({
+ *     plugins: [
+ *       spellcheckPlugin({ collections: ['pages', 'posts'] }),
+ *     ],
+ *   })
+ */
+
+declare const spellcheckPlugin: (pluginConfig?: SpellCheckPluginConfig) => Plugin;
+
+/**
+ * Shared types and constants for Lexical text extraction.
+ * Used by both lexicalParser.ts (scan) and fix.ts (correction)
+ * to ensure identical traversal behavior.
+ */
+interface LexicalNode {
+    type?: string;
+    text?: string;
+    children?: LexicalNode[];
+    root?: LexicalNode;
+    tag?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Extract plain text from Lexical JSON nodes.
+ * Recursively traverses the Lexical AST, extracting text nodes
+ * and skipping code blocks.
+ *
+ * v0.9.8: Single source of truth for text extraction.
+ * extractAllTextFromDocWithSources() returns both the text AND source
+ * references, used by scan (validate/bulk) and fix endpoints.
+ * This eliminates offset divergence between scan and fix.
+ */
+
+interface TextSegment {
+    text: string;
+    source: {
+        type: 'title';
+    } | {
+        type: 'lexical';
+        data: LexicalNode;
+        topField: string;
+    } | {
+        type: 'plain';
+        parent: Record<string, unknown>;
+        key: string;
+        topField: string;
+    };
+}
+interface ExtractedDoc {
+    /** Full text sent to LanguageTool (segments joined by \n, trimmed) */
+    fullText: string;
+    /** Individual text segments with source references (for fix mutation) */
+    segments: TextSegment[];
+}
+/**
+ * Extract all text from a document with source tracking.
+ * Single source of truth — used by scan (validate/bulk) and fix endpoints.
+ */
+declare function extractAllTextFromDocWithSources(doc: any, contentField?: string): ExtractedDoc;
+/**
+ * Extract all plain text from a document (convenience wrapper).
+ * Delegates to extractAllTextFromDocWithSources for consistency.
+ */
+declare function extractAllTextFromDoc(doc: any, contentField?: string): string;
+/**
+ * Extract all plain text from a Lexical JSON structure.
+ * Returns a single string with text nodes separated by newlines.
+ */
+declare function extractTextFromLexical(node: unknown, maxDepth?: number): string;
+/**
+ * Count words in extracted text.
+ */
+declare function countWords(text: string): number;
+
+/**
+ * LanguageTool API client.
+ * Sends text to the public LanguageTool API and parses results into SpellCheckIssue[].
+ *
+ * Rate limit: max 1 request per 3 seconds on the free API.
+ * Max text length: 18,000 characters.
+ */
+
+/**
+ * Check text with LanguageTool API.
+ * Returns raw SpellCheckIssue[] (before filtering).
+ */
+declare function checkWithLanguageTool(text: string, language: string, config: SpellCheckPluginConfig): Promise<SpellCheckIssue[]>;
+
+/**
+ * Claude AI semantic analysis (optional fallback).
+ * Checks for semantic coherence, tone consistency, and register issues.
+ * Does NOT check spelling/grammar (LanguageTool handles that).
+ */
+
+/**
+ * Check text with Claude API for semantic issues.
+ * Returns SpellCheckIssue[] with source='claude'.
+ */
+declare function checkWithClaude(text: string, language: string, apiKey: string): Promise<SpellCheckIssue[]>;
+
+/**
+ * Filter false positives from LanguageTool results.
+ * Removes premium rules, skipped rules/categories, and custom dictionary matches.
+ */
+
+/**
+ * Filter out false positives based on plugin configuration.
+ * Merges hardcoded customDictionary with dynamic DB dictionary words.
+ */
+declare function filterFalsePositives(issues: SpellCheckIssue[], config: SpellCheckPluginConfig, payload?: {
+    find: Function;
+}): Promise<SpellCheckIssue[]>;
+/**
+ * Calculate a spellcheck score (0-100) based on word count and issue count.
+ * 100 = no issues, decreases with each issue relative to word count.
+ */
+declare function calculateScore(wordCount: number, issueCount: number): number;
+
+/**
+ * Dictionary endpoints — CRUD for the dynamic spellcheck dictionary.
+ * GET  /api/spellcheck/dictionary — list all words
+ * POST /api/spellcheck/dictionary — add word(s)
+ * DELETE /api/spellcheck/dictionary — delete word(s) by id
+ */
+
+declare function invalidateDictionaryCache(): void;
+/**
+ * Load dictionary words from DB with in-memory cache.
+ * Returns lowercased word strings.
+ */
+declare function loadDictionaryWords(payload: {
+    find: Function;
+}): Promise<string[]>;
+
+/**
+ * Spellcheck Plugin — i18n translations (FR/EN).
+ */
+type SpellcheckLocale = 'fr' | 'en';
+interface SpellcheckTranslations {
+    dashboardTitle: string;
+    dashboardDescription: string;
+    scanAll: string;
+    scanning: string;
+    scanComplete: string;
+    noIssues: string;
+    issuesFound: (count: number) => string;
+    score: string;
+    wordCount: string;
+    lastChecked: string;
+    collection: string;
+    document: string;
+    issues: string;
+    actions: string;
+    fieldTitle: string;
+    fieldDescription: string;
+    checkNow: string;
+    checking: string;
+    fixAll: string;
+    fix: string;
+    ignore: string;
+    autoChecked: string;
+    suggestion: string;
+    noSuggestion: string;
+    context: string;
+    rule: string;
+    category: string;
+    applied: string;
+    source: string;
+    excellent: string;
+    good: string;
+    needsWork: string;
+    poor: string;
+    errorFetching: string;
+    errorFixing: string;
+    unauthorized: string;
+}
+declare function getTranslations(locale?: SpellcheckLocale): SpellcheckTranslations;
+declare function getScoreLabel(score: number, t: SpellcheckTranslations): string;
+
+export { type ExtractedDoc, type SpellCheckIssue, type SpellCheckPluginConfig, type SpellCheckResult, type SpellcheckLocale, type SpellcheckTranslations, type TextSegment, calculateScore, checkWithClaude, checkWithLanguageTool, countWords, extractAllTextFromDoc, extractAllTextFromDocWithSources, extractTextFromLexical, filterFalsePositives, getScoreLabel, getTranslations, invalidateDictionaryCache, loadDictionaryWords, spellcheckPlugin };

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { Plugin } from 'payload';
+
+/**
+ * Spellcheck Plugin — Type definitions.
+ */
+interface SpellCheckIssue {
+    /** LanguageTool rule ID (e.g. 'GRAMMAR', 'MORFOLOGIK_RULE_FR') */
+    ruleId: string;
+    /** LanguageTool category (e.g. 'GRAMMAR', 'TYPOS') */
+    category: string;
+    /** Human-readable message explaining the issue */
+    message: string;
+    /** Text context around the error */
+    context: string;
+    /** Offset of the error within the context string */
+    contextOffset: number;
+    /** Offset within the full extracted text */
+    offset: number;
+    /** Length of the problematic text */
+    length: number;
+    /** The original (wrong) text */
+    original: string;
+    /** Suggested replacements (max 3) */
+    replacements: string[];
+    /** Source engine: 'languagetool' or 'claude' */
+    source: 'languagetool' | 'claude';
+    /** Whether this is a premium-only rule */
+    isPremium?: boolean;
+}
+interface SpellCheckResult {
+    /** Document ID */
+    docId: string | number;
+    /** Collection slug */
+    collection: string;
+    /** Score 0-100 (100 = no issues) */
+    score: number;
+    /** Number of issues found */
+    issueCount: number;
+    /** Word count of the extracted text */
+    wordCount: number;
+    /** Detailed issues */
+    issues: SpellCheckIssue[];
+    /** ISO date of last check */
+    lastChecked: string;
+}
+interface SpellCheckPluginConfig {
+    /** Collections to check (default: ['pages', 'posts']) */
+    collections?: string[];
+    /** Rich text field name to extract content from (default: 'content') */
+    contentField?: string;
+    /** Language for LanguageTool (default: 'fr') */
+    language?: string;
+    /** Run spellcheck automatically on save (default: true) */
+    checkOnSave?: boolean;
+    /** Add sidebar field in the editor (default: true) */
+    addSidebarField?: boolean;
+    /** Add dashboard view at /admin/spellcheck (default: true) */
+    addDashboardView?: boolean;
+    /** Add score column in collection list views (default: true) */
+    addListColumn?: boolean;
+    /** Base path for API endpoints (default: '/spellcheck') */
+    endpointBasePath?: string;
+    /** Enable Claude AI as semantic fallback (default: false) */
+    enableAiFallback?: boolean;
+    /** Anthropic API key for Claude fallback */
+    anthropicApiKey?: string;
+    /** LanguageTool rule IDs to skip */
+    skipRules?: string[];
+    /** LanguageTool categories to skip */
+    skipCategories?: string[];
+    /** Custom dictionary — words to never flag */
+    customDictionary?: string[];
+}
+
+/**
+ * Payload CMS Spellcheck Plugin.
+ *
+ * Adds spellchecking capabilities via LanguageTool + optional Claude AI:
+ * - Sidebar field in the editor (real-time spellcheck)
+ * - Dashboard view at /admin/spellcheck
+ * - API endpoints for validate, fix, bulk scan
+ * - afterChange hook for automatic checks on save
+ * - SpellCheckResults collection for storing results
+ *
+ * Usage:
+ *   import { spellcheckPlugin } from '@consilioweb/spellcheck'
+ *
+ *   export default buildConfig({
+ *     plugins: [
+ *       spellcheckPlugin({ collections: ['pages', 'posts'] }),
+ *     ],
+ *   })
+ */
+
+declare const spellcheckPlugin: (pluginConfig?: SpellCheckPluginConfig) => Plugin;
+
+/**
+ * Shared types and constants for Lexical text extraction.
+ * Used by both lexicalParser.ts (scan) and fix.ts (correction)
+ * to ensure identical traversal behavior.
+ */
+interface LexicalNode {
+    type?: string;
+    text?: string;
+    children?: LexicalNode[];
+    root?: LexicalNode;
+    tag?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Extract plain text from Lexical JSON nodes.
+ * Recursively traverses the Lexical AST, extracting text nodes
+ * and skipping code blocks.
+ *
+ * v0.9.8: Single source of truth for text extraction.
+ * extractAllTextFromDocWithSources() returns both the text AND source
+ * references, used by scan (validate/bulk) and fix endpoints.
+ * This eliminates offset divergence between scan and fix.
+ */
+
+interface TextSegment {
+    text: string;
+    source: {
+        type: 'title';
+    } | {
+        type: 'lexical';
+        data: LexicalNode;
+        topField: string;
+    } | {
+        type: 'plain';
+        parent: Record<string, unknown>;
+        key: string;
+        topField: string;
+    };
+}
+interface ExtractedDoc {
+    /** Full text sent to LanguageTool (segments joined by \n, trimmed) */
+    fullText: string;
+    /** Individual text segments with source references (for fix mutation) */
+    segments: TextSegment[];
+}
+/**
+ * Extract all text from a document with source tracking.
+ * Single source of truth — used by scan (validate/bulk) and fix endpoints.
+ */
+declare function extractAllTextFromDocWithSources(doc: any, contentField?: string): ExtractedDoc;
+/**
+ * Extract all plain text from a document (convenience wrapper).
+ * Delegates to extractAllTextFromDocWithSources for consistency.
+ */
+declare function extractAllTextFromDoc(doc: any, contentField?: string): string;
+/**
+ * Extract all plain text from a Lexical JSON structure.
+ * Returns a single string with text nodes separated by newlines.
+ */
+declare function extractTextFromLexical(node: unknown, maxDepth?: number): string;
+/**
+ * Count words in extracted text.
+ */
+declare function countWords(text: string): number;
+
+/**
+ * LanguageTool API client.
+ * Sends text to the public LanguageTool API and parses results into SpellCheckIssue[].
+ *
+ * Rate limit: max 1 request per 3 seconds on the free API.
+ * Max text length: 18,000 characters.
+ */
+
+/**
+ * Check text with LanguageTool API.
+ * Returns raw SpellCheckIssue[] (before filtering).
+ */
+declare function checkWithLanguageTool(text: string, language: string, config: SpellCheckPluginConfig): Promise<SpellCheckIssue[]>;
+
+/**
+ * Claude AI semantic analysis (optional fallback).
+ * Checks for semantic coherence, tone consistency, and register issues.
+ * Does NOT check spelling/grammar (LanguageTool handles that).
+ */
+
+/**
+ * Check text with Claude API for semantic issues.
+ * Returns SpellCheckIssue[] with source='claude'.
+ */
+declare function checkWithClaude(text: string, language: string, apiKey: string): Promise<SpellCheckIssue[]>;
+
+/**
+ * Filter false positives from LanguageTool results.
+ * Removes premium rules, skipped rules/categories, and custom dictionary matches.
+ */
+
+/**
+ * Filter out false positives based on plugin configuration.
+ * Merges hardcoded customDictionary with dynamic DB dictionary words.
+ */
+declare function filterFalsePositives(issues: SpellCheckIssue[], config: SpellCheckPluginConfig, payload?: {
+    find: Function;
+}): Promise<SpellCheckIssue[]>;
+/**
+ * Calculate a spellcheck score (0-100) based on word count and issue count.
+ * 100 = no issues, decreases with each issue relative to word count.
+ */
+declare function calculateScore(wordCount: number, issueCount: number): number;
+
+/**
+ * Dictionary endpoints — CRUD for the dynamic spellcheck dictionary.
+ * GET  /api/spellcheck/dictionary — list all words
+ * POST /api/spellcheck/dictionary — add word(s)
+ * DELETE /api/spellcheck/dictionary — delete word(s) by id
+ */
+
+declare function invalidateDictionaryCache(): void;
+/**
+ * Load dictionary words from DB with in-memory cache.
+ * Returns lowercased word strings.
+ */
+declare function loadDictionaryWords(payload: {
+    find: Function;
+}): Promise<string[]>;
+
+/**
+ * Spellcheck Plugin — i18n translations (FR/EN).
+ */
+type SpellcheckLocale = 'fr' | 'en';
+interface SpellcheckTranslations {
+    dashboardTitle: string;
+    dashboardDescription: string;
+    scanAll: string;
+    scanning: string;
+    scanComplete: string;
+    noIssues: string;
+    issuesFound: (count: number) => string;
+    score: string;
+    wordCount: string;
+    lastChecked: string;
+    collection: string;
+    document: string;
+    issues: string;
+    actions: string;
+    fieldTitle: string;
+    fieldDescription: string;
+    checkNow: string;
+    checking: string;
+    fixAll: string;
+    fix: string;
+    ignore: string;
+    autoChecked: string;
+    suggestion: string;
+    noSuggestion: string;
+    context: string;
+    rule: string;
+    category: string;
+    applied: string;
+    source: string;
+    excellent: string;
+    good: string;
+    needsWork: string;
+    poor: string;
+    errorFetching: string;
+    errorFixing: string;
+    unauthorized: string;
+}
+declare function getTranslations(locale?: SpellcheckLocale): SpellcheckTranslations;
+declare function getScoreLabel(score: number, t: SpellcheckTranslations): string;
+
+export { type ExtractedDoc, type SpellCheckIssue, type SpellCheckPluginConfig, type SpellCheckResult, type SpellcheckLocale, type SpellcheckTranslations, type TextSegment, calculateScore, checkWithClaude, checkWithLanguageTool, countWords, extractAllTextFromDoc, extractAllTextFromDocWithSources, extractTextFromLexical, filterFalsePositives, getScoreLabel, getTranslations, invalidateDictionaryCache, loadDictionaryWords, spellcheckPlugin };