color-name-list 12.2.0 → 13.1.0

package/tests/_utils/report.js

@@ -0,0 +1,76 @@
+// Small utility to build consistent, helpful failure messages in tests.
+// Keeps output informative while avoiding repeated boilerplate in each test file.
+
+/**
+ * Simple pluralization helper
+ * @param {number} n
+ * @param {string} singular
+ * @param {string} [plural]
+ * @returns {string}
+ */
+export function pluralize(n, singular, plural = `${singular}s`) {
+  return n === 1 ? singular : plural;
+}
+
+/**
+ * Join values as a readable, comma-separated list.
+ * Ensures uniqueness and stable order.
+ * @param {Array<string|number>} items
+ * @returns {string}
+ */
+export function list(items) {
+  if (!items || !items.length) return '';
+  const uniq = [...new Set(items.map(String))];
+  return uniq.join(', ');
+}
+
+/**
+ * Build a consistent failure message for test assertions.
+ *
+ * @param {Object} opts
+ * @param {string} opts.title - Heading/title of the error (without counts)
+ * @param {Array<string>} [opts.offenders] - Values to summarize in a one-line list.
+ * @param {string} [opts.offenderLabel] - Label for offenders list (e.g. "name", "hex code").
+ * @param {Array<string>} [opts.details] - Additional bullet/section lines to include.
+ * @param {Array<string>} [opts.tips] - How-to-fix tips appended at the end.
+ * @param {number} [opts.count] - Optional explicit count (defaults to offenders.length).
+ * @param {string} [opts.icon] - Optional icon/emphasis prefix, default ⛔.
+ * @returns {string}
+ */
+export function buildFailureMessage({
+  title,
+  offenders = [],
+  offenderLabel = 'item',
+  details = [],
+  tips = [],
+  count,
+  icon = '⛔',
+} = {}) {
+  const msgLines = [];
+  const n = typeof count === 'number' ? count : offenders.length;
+
+  msgLines.push(
+    `${icon} ${title.replace('{n}', String(n)).replace('{items}', pluralize(n, offenderLabel))}`
+  );
+  msgLines.push('');
+
+  if (offenders.length) {
+    msgLines.push(`Offending ${pluralize(offenders.length, offenderLabel)}: ${list(offenders)}`);
+    msgLines.push('*-------------------------*');
+    msgLines.push('');
+  }
+
+  if (details.length) {
+    for (const line of details) msgLines.push(line);
+    msgLines.push('');
+  }
+
+  if (tips.length) {
+    msgLines.push('Tip:');
+    for (const t of tips) msgLines.push(`  - ${t}`);
+    msgLines.push('');
+  }
+
+  msgLines.push('*-------------------------*');
+  return msgLines.join('\n');
+}

package/tests/csv-test-data.js

@@ -0,0 +1,108 @@
+import fs from 'fs';
+import path from 'path';
+import { parseCSVString } from '../scripts/lib.js';
+
+/**
+ * Shared CSV test data loader
+ * Provides consistent CSV data across all test files
+ */
+class CSVTestData {
+  constructor() {
+    this._data = null;
+    this._raw = null;
+    this._lines = null;
+    this._items = null;
+  }
+
+  /**
+   * Load and parse the CSV file once
+   */
+  load() {
+    if (this._data) return; // Already loaded
+
+    const csvPath = path.resolve('./src/colornames.csv');
+    this._raw = fs.readFileSync(csvPath, 'utf8').replace(/\r\n/g, '\n').trimEnd();
+
+    // Parse with parseCSVString for structured access
+    this._data = parseCSVString(this._raw);
+
+    // Parse for line-by-line access (used by duplicates/sorting tests)
+    this._lines = this._raw.split('\n');
+    const header = this._lines.shift();
+
+    if (!header.startsWith('name,hex,good name')) {
+      throw new Error('Invalid CSV header format');
+    }
+
+    // Create items array with line numbers for duplicate checking
+    this._items = this._lines
+      .map((l, idx) => {
+        const lineNumber = idx + 2; // +1 for header, +1 because idx is 0-based
+        if (!l.trim()) return null;
+        const firstComma = l.indexOf(',');
+        const name = firstComma === -1 ? l : l.slice(0, firstComma);
+        return { name, lineNumber };
+      })
+      .filter(Boolean);
+  }
+
+  /**
+   * Get the parsed CSV data (using parseCSVString format)
+   */
+  get data() {
+    this.load();
+    return this._data;
+  }
+
+  /**
+   * Get the raw CSV content
+   */
+  get raw() {
+    this.load();
+    return this._raw;
+  }
+
+  /**
+   * Get CSV lines (without header)
+   */
+  get lines() {
+    this.load();
+    return this._lines;
+  }
+
+  /**
+   * Get items array with line numbers for duplicate checking
+   */
+  get items() {
+    this.load();
+    return this._items;
+  }
+
+  /**
+   * Get colors in simple format (name, hex)
+   */
+  get colors() {
+    this.load();
+    return this._data.entries.map((entry) => ({
+      name: entry.name,
+      hex: entry.hex,
+    }));
+  }
+
+  /**
+   * Get line count including header
+   */
+  get lineCount() {
+    this.load();
+    return this._lines.length + 1; // +1 for header
+  }
+}
+
+// Export a singleton instance
+export const csvTestData = new CSVTestData();
+
+// Export a convenience function to ensure data is loaded
+export function loadCSVTestData() {
+  csvTestData.load();
+  return csvTestData;
+}

package/tests/duplicate-allowlist.json

@@ -8,5 +8,33 @@
   "Sable",
   "Sablé",
   "Rosé",
-  "Fresh Water"
+  "Fresh Water",
+  "Undersea",
+  "In the Twilight",
+  "In the Tropics",
+  "Teal With It",
+  "In the Spotlight",
+  "In the Shadows",
+  "By the Sea",
+  "Sail On",
+  "In the Red",
+  "In the Pink",
+  "In A Pickle",
+  "In for a Penny",
+  "On the Nile",
+  "In the Navy",
+  "Mint to Be",
+  "Mauve It",
+  "At the Beach",
+  "In the Blue",
+  "Blue by You",
+  "In the Buff",
+  "Buff It",
+  "Buzz-In",
+  "Coffee With Cream",
+  "In the Dark",
+  "Dark as Night",
+  "Green With Envy",
+  "Lost in Space",
+  "Fruit of Passion"
 ]

package/tests/duplicate-plurals-allowlist.json

@@ -3,5 +3,8 @@
   "Blues",
   "Greens",
   "Nighthawks",
-  "Spearmints"
+  "Spearmints",
+  "In the Vines",
+  "On the Rocks",
+  "Sea of Stars"
 ]

package/tests/duplicates.test.js

@@ -1,44 +1,147 @@
-import { describe, it, expect } from 'vitest';
-import fs from 'fs';
-import path from 'path';
-import { findNearDuplicateNameConflicts } from '../scripts/lib.js';
+import { describe, it, expect, beforeAll } from 'vitest';
+import { findNearDuplicateNameConflicts, findDuplicates } from '../scripts/lib.js';
 import allowlist from './duplicate-allowlist.json';
 import pluralAllowlist from './duplicate-plurals-allowlist.json';
+import { csvTestData } from './csv-test-data.js';
+import { buildFailureMessage } from './_utils/report.js';
 
 describe('Duplicate-like color names', () => {
-  it('should not contain names that only differ by spacing/punctuation/case/accents', () => {
-    const csvPath = path.resolve('./src/colornames.csv');
-    const raw = fs.readFileSync(csvPath, 'utf8').replace(/\r\n/g, '\n').trimEnd();
-    const lines = raw.split('\n');
-    expect(lines.length).toBeGreaterThan(1);
+  beforeAll(() => {
+    // Load CSV data once for all tests
+    csvTestData.load();
+  });
+
+  // Shared stopwords for normalization across tests
+  const STOPWORDS = [
+    'of', 'the', 'and', 'a', 'an',
+    'in', 'on', 'at', 'to', 'for',
+    'by', 'with', 'from', 'as', 'is',
+    'it', 'this', 'that', 'these', 'those',
+    'be', 'are', 'was', 'were', 'or',
+  ];
+
+  // Helper: normalize a phrase similar to scripts/lib normalization but keeping token boundaries
+  const normalize = (s) => String(s)
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+
+  const tokenize = (name) => {
+    const base = normalize(name);
+    const tokens = base.match(/[a-z0-9]+/g) || [];
+    const stopSet = new Set(STOPWORDS.map((w) => normalize(w)));
+    return tokens.filter((t) => t && !stopSet.has(t));
+  };
 
-    const header = lines.shift();
-    expect(header.startsWith('name,hex')).toBe(true);
+  // Detect two-word names that are exact reversals of each other (after stopword filtering)
+  function findTwoWordReversedPairs(items) {
+    const groups = new Map(); // key: sorted pair "a|b" -> list of { name, lineNumber, order: "a b" }
+
+    for (const item of items) {
+      if (!item || typeof item.name !== 'string') continue;
+      const tokens = tokenize(item.name);
+      if (tokens.length !== 2) continue; // only 2-token (after stopword removal)
+      const [a, b] = tokens;
+      if (!a || !b) continue;
+      if (a === b) continue; // "blue blue" reversed is the same – ignore
+
+      const key = [a, b].sort().join('|');
+      const order = `${a} ${b}`;
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push({ name: item.name, lineNumber: item.lineNumber, order });
+    }
 
-    const items = lines.map((l, idx) => {
-      const lineNumber = idx + 2; // +1 for header, +1 because idx is 0-based
-      if (!l.trim()) return null;
-      const firstComma = l.indexOf(',');
-      const name = firstComma === -1 ? l : l.slice(0, firstComma);
-      return { name, lineNumber };
-    }).filter(Boolean);
+    const conflicts = [];
+    for (const [key, entries] of groups.entries()) {
+      // We have a potential conflict if we see both orders "a b" and "b a"
+      const uniqOrders = [...new Set(entries.map((e) => e.order))];
+      if (uniqOrders.length < 2) continue;
+
+      const [t1, t2] = key.split('|');
+      const forward = `${t1} ${t2}`;
+      const backward = `${t2} ${t1}`;
+
+      const hasForward = uniqOrders.includes(forward);
+      const hasBackward = uniqOrders.includes(backward);
+
+      if (hasForward && hasBackward) {
+        // Keep entries unique by name@line and sorted by line number for stable output
+        const seen = new Set();
+        const unique = entries
+          .filter((e) => {
+            const k = `${e.name}@${e.lineNumber}`;
+            if (seen.has(k)) return false;
+            seen.add(k);
+            return true;
+          })
+          .sort((a, b) => a.lineNumber - b.lineNumber);
+
+        // Respect allowlist: if either direction string is allowlisted, skip
+        const allowSet = new Set(
+          (Array.isArray(allowlist) ? allowlist : [])
+            .filter((v) => typeof v === 'string' && v.trim().length)
+            .map((v) => normalize(v))
+        );
+        if (allowSet.has(forward) || allowSet.has(backward)) continue;
+
+        conflicts.push({ key, tokens: [t1, t2], entries: unique });
+      }
+    }
 
-    const conflicts = findNearDuplicateNameConflicts(items, { allowlist, foldPlurals: true, pluralAllowlist });
+    return conflicts;
+  }
+
+  it('should not contain the same name twice', () => {
+    expect(csvTestData.lineCount).toBeGreaterThan(1);
+
+    const duplicates = findDuplicates(csvTestData.data.values['name']);
+
+    if (duplicates.length) {
+      throw new Error(
+        buildFailureMessage({
+          title: 'Found {n} duplicate {items}:',
+          offenders: duplicates,
+          offenderLabel: 'name',
+          details: [
+            'Exact duplicate names are not allowed.',
+            'Please remove duplicates or consolidate to a single preferred name.',
+          ],
+          tips: [
+            'Edit src/colornames.csv and keep only one entry per name',
+            'When in doubt, prefer the most common or descriptive name',
+          ],
+        })
+      );
+    }
+
+    expect(duplicates.length).toBe(0);
+  });
+
+  it('should not contain names that only differ by spacing/punctuation/case/accents/stopwords', () => {
+    expect(csvTestData.lineCount).toBeGreaterThan(1);
+
+    const conflicts = findNearDuplicateNameConflicts(csvTestData.items, {
+      allowlist,
+      foldPlurals: true,
+      pluralAllowlist,
+      foldStopwords: true,
+      stopwords: STOPWORDS,
+    });
 
     if (conflicts.length) {
-      // Create a helpful error message with examples and hints.
-      const groupCount = conflicts.length;
-      const msgLines = [
-        `Found ${groupCount} duplicate-like group${groupCount === 1 ? '' : 's'} (case/accents/punctuation-insensitive):`,
-        '',
-      ];
+      // Create a summary of all names across conflict groups
+      const allOffendingNames = new Set();
+      conflicts.forEach(({ entries }) => entries.forEach((e) => allOffendingNames.add(e.name)));
+
+      // Build detailed section: groups with line numbers (stable + unique)
+      const details = [];
       conflicts
-        // make message deterministic by sorting
         .sort((a, b) => a.norm.localeCompare(b.norm))
         .forEach(({ norm, entries }) => {
           const unique = [];
           const seen = new Set();
-          // De-duplicate exact same name+line pairs in output
           for (const e of entries) {
             const key = `${e.name}@${e.lineNumber}`;
             if (!seen.has(key)) {
@@ -46,26 +149,129 @@ describe('Duplicate-like color names', () => {
               unique.push(e);
             }
           }
-          // sort entries by line number for readability
           unique.sort((a, b) => a.lineNumber - b.lineNumber);
-          msgLines.push(`  • ${norm}:`);
-          unique.forEach((e) => msgLines.push(`      - line ${e.lineNumber}: "${e.name}"`));
+          details.push(`  • ${norm}:`);
+          unique.forEach((e) => details.push(`      - line ${e.lineNumber}: "${e.name}"`));
+          details.push('');
         });
 
-      msgLines.push(
-        '',
-        'This typically indicates near-duplicates that only differ by spacing/punctuation, like "Snow Pink" vs "Snowpink".',
-        'Please unify or remove duplicates to keep the dataset clean.',
-        '',
-        'Tip:',
-        '  - Edit src/colornames.csv and keep a single preferred spelling. When in doubt, prefer the most common or simplest form or the British spelling.',
-        '  - After changes, run: npm run sort-colors',
+      throw new Error(
+        buildFailureMessage({
+          title: 'Found {n} duplicate-like {items} (case/accents/punctuation/stopwords-insensitive):',
+          offenders: [...allOffendingNames],
+          offenderLabel: 'name',
+          details: [
+            ...details,
+            'This typically indicates near-duplicates that only differ by spacing/punctuation, like "Snow Pink" vs "Snowpink".',
+            'Please unify or remove duplicates to keep the dataset clean.',
+          ],
+          tips: [
+            'Edit src/colornames.csv and keep a single preferred spelling. When in doubt, prefer the most common or simplest form or the British spelling.',
+            'After changes, run: npm run sort-colors',
+          ],
+          count: conflicts.length,
+        })
       );
-
-      throw new Error(msgLines.join('\n'));
     }
 
     // If we reach here, no conflicts were found.
     expect(conflicts.length).toBe(0);
   });
+
+  it('should not contain duplicate hex codes', () => {
+    // Find duplicates in hex values
+    const hexDuplicates = findDuplicates(csvTestData.data.values['hex']);
+
+    if (hexDuplicates.length) {
+      const details = [];
+      hexDuplicates.forEach((duplicateHex) => {
+        const entriesWithHex = csvTestData.data.entries
+          .map((entry, index) => ({ ...entry, lineNumber: index + 2 }))
+          .filter((entry) => entry.hex === duplicateHex);
+
+        details.push(`  • ${duplicateHex}:`);
+        entriesWithHex.forEach((entry) => {
+          details.push(`      - line ${entry.lineNumber}: "${entry.name}" (${entry.hex})`);
+        });
+        details.push('');
+      });
+
+      throw new Error(
+        buildFailureMessage({
+          title: 'Found {n} duplicate {items}:',
+          offenders: hexDuplicates,
+          offenderLabel: 'hex code',
+          details: [
+            ...details,
+            'Duplicate hex codes indicate multiple color names pointing to the same exact color.',
+            'Please remove duplicates or consolidate to a single preferred name.',
+          ],
+          tips: [
+            'Edit src/colornames.csv and keep only one entry per hex code',
+            'When in doubt, prefer the most common or descriptive name',
+          ],
+        })
+      );
+    }
+
+    expect(hexDuplicates.length).toBe(0);
+  });
+
+  it('should detect names that only differ by stopwords when enabled', () => {
+    const items = [
+      { name: 'Heart Gold' },
+      { name: 'Heart of Gold' },
+    ];
+    const conflicts = findNearDuplicateNameConflicts(items, {
+      foldStopwords: true,
+      stopwords: STOPWORDS,
+    });
+
+    expect(conflicts.length).toBe(1);
+    expect(conflicts[0].entries.length).toBe(2);
+  });
+
+  it.skip('should not contain two-word names that are exact reversals of each other', () => {
+    expect(csvTestData.lineCount).toBeGreaterThan(1);
+
+    const conflicts = findTwoWordReversedPairs(csvTestData.items);
+
+    if (conflicts.length) {
+      // Build helpful details with line numbers
+      const details = [];
+      const offenderNames = new Set();
+
+      conflicts
+        .sort((a, b) => a.tokens.join(' ').localeCompare(b.tokens.join(' ')))
+        .forEach(({ tokens, entries }) => {
+          const [a, b] = tokens;
+          details.push(`  • ${a} / ${b}:`);
+          entries.forEach((e) => {
+            offenderNames.add(e.name);
+            details.push(`      - line ${e.lineNumber}: "${e.name}"`);
+          });
+          details.push('');
+        });
+
+      throw new Error(
+        buildFailureMessage({
+          title: 'Found {n} word-order reversed {items}:',
+          offenders: [...offenderNames],
+          offenderLabel: 'name',
+          details: [
+            ...details,
+            'Names that only differ by word order (e.g., "Beach Sand" vs "Sand Beach") should be unified.',
+            'Please keep a single preferred order and remove the other.',
+          ],
+          tips: [
+            'Edit src/colornames.csv and keep only one order for each two-word pair.',
+            'After changes, run: npm run sort-colors',
+          ],
+          count: conflicts.length,
+        })
+      );
+    }
+
+    expect(conflicts.length).toBe(0);
+  });
 });

package/tests/formats.test.js

@@ -1,16 +1,17 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeAll } from 'vitest';
 import fs from 'fs';
 import path from 'path';
 import { parseCSVString } from '../scripts/lib.js';
+import { csvTestData } from './csv-test-data.js';
 
 describe('Other Format Tests', () => {
-  // Load CSV data for comparison
-  const csvSource = fs.readFileSync(path.resolve('./src/colornames.csv'), 'utf8').toString();
-  const csvData = parseCSVString(csvSource);
-  const csvColors = csvData.entries.map(entry => ({
-    name: entry.name,
-    hex: entry.hex
-  }));
+  let csvColors;
+
+  beforeAll(() => {
+    // Load CSV data once for all tests
+    csvTestData.load();
+    csvColors = csvTestData.colors;
+  });
 
   describe('CSV Output', () => {
     it('should correctly generate CSV files', () => {

package/tests/imports.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeAll } from 'vitest';
 
 import * as esmColors from '../dist/colornames.esm.js';
 import * as esmBestOfColors from '../dist/colornames.bestof.esm.js';
@@ -15,18 +15,16 @@ import jsonMinBestOfColors from '../dist/colornames.bestof.min.json' assert { ty
 import jsonMinShortColors from '../dist/colornames.short.min.json' assert { type: 'json' };
 
 // Also import the source CSV file for verification
-import fs from 'fs';
-import path from 'path';
-import { parseCSVString } from '../scripts/lib.js';
+import { csvTestData } from './csv-test-data.js';
 
 describe('Color Names Import Tests', () => {
-  // Load CSV data for comparison
-  const csvSource = fs.readFileSync(path.resolve('./src/colornames.csv'), 'utf8').toString();
-  const csvData = parseCSVString(csvSource);
-  const csvColors = csvData.entries.map(entry => ({
-    name: entry.name,
-    hex: entry.hex
-  }));
+  let csvColors;
+
+  beforeAll(() => {
+    // Load CSV data for comparison
+    csvTestData.load();
+    csvColors = csvTestData.colors;
+  });
 
   describe('JSON Files', () => {
     it('should import main JSON file correctly', () => {
@@ -108,11 +106,11 @@ describe('Color Names Import Tests', () => {
       const commonColors = ['black', 'white', 'red', 'blue', 'green', 'yellow', 'purple', 'pink'];
 
       // Convert to lowercase for easier comparison
-      const allNames = jsonColors.map(color => color.name.toLowerCase());
+      const allNames = jsonColors.map((color) => color.name.toLowerCase());
 
-      commonColors.forEach(color => {
+      commonColors.forEach((color) => {
         // Check if at least one entry contains this common color name
-        expect(allNames.some(name => name.includes(color))).toBe(true);
+        expect(allNames.some((name) => name.includes(color))).toBe(true);
       });
     });
   });

package/tests/sorting.test.js

@@ -1,22 +1,20 @@
-import { describe, it, expect } from 'vitest';
-import fs from 'fs';
-import path from 'path';
+import { describe, it, expect, beforeAll } from 'vitest';
+import { csvTestData } from './csv-test-data.js';
 
 /**
  * Ensures that the source CSV file is already sorted alphabetically (case-insensitive)
  * by the color name. If not, it throws with a helpful message telling how to fix it.
  */
 describe('Source CSV sorting', () => {
-  it('colornames.csv should be sorted by name (case-insensitive)', () => {
-    const csvPath = path.resolve('./src/colornames.csv');
-    const raw = fs.readFileSync(csvPath, 'utf8').replace(/\r\n/g, '\n').trimEnd();
-    const lines = raw.split('\n');
-    expect(lines.length).toBeGreaterThan(1);
+  beforeAll(() => {
+    // Load CSV data once
+    csvTestData.load();
+  });
 
-    const header = lines.shift();
-    expect(header.startsWith('name,hex')).toBe(true);
+  it('colornames.csv should be sorted by name (case-insensitive)', () => {
+    expect(csvTestData.lineCount).toBeGreaterThan(1);
 
-    const entries = lines
+    const entries = csvTestData.lines
       .filter((l) => l.trim().length)
       .map((l, idx) => {
         const [name, hex] = l.split(',');
@@ -36,7 +34,7 @@ describe('Source CSV sorting', () => {
             'To fix automatically run:',
             '  npm run sort-colors',
             '',
-            'Commit the updated src/colornames.csv after sorting.'
+            'Commit the updated src/colornames.csv after sorting.',
           ].join('\n')
         );
       }