scrabble-solver 2.18.3 → 2.18.5

package/packages/logger/scripts/export-csv.ts

@@ -0,0 +1,113 @@
+import { once } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { CSV_DIRECTORY, EVENT_FIELDS, type EventType, type EventValue, formatCsvRow, type LoggedEvent } from '../src';
+
+import { readEvents } from './readEvents';
+
+interface CsvFile {
+  error: Error | undefined;
+  filename: string;
+  rows: number;
+  stream: fs.WriteStream;
+}
+
+const YEAR_FORMAT = /^\d{4}$/;
+
+await exportCsv(parseYear(process.argv[2]));
+
+async function exportCsv(year: string | undefined): Promise<void> {
+  fs.mkdirSync(CSV_DIRECTORY, { recursive: true });
+  const files = new Map<string, CsvFile>();
+  let skippedLines = 0;
+
+  for await (const event of readEvents()) {
+    if (!event) {
+      skippedLines += 1;
+      continue;
+    }
+
+    const eventYear = event.timestamp.slice(0, 4);
+
+    if (year && eventYear !== year) {
+      continue;
+    }
+
+    await writeRow(getFile(files, event.type, eventYear), formatEventRow(event));
+  }
+
+  await Promise.all([...files.values()].map(closeFile));
+  printSummary(files, skippedLines);
+}
+
+function formatEventRow(event: LoggedEvent): string {
+  const values: Record<string, EventValue> = event;
+  return formatCsvRow([event.timestamp, ...EVENT_FIELDS[event.type].map((field) => values[field])]);
+}
+
+function getFile(files: Map<string, CsvFile>, type: EventType, year: string): CsvFile {
+  const filename = `${type}-${year}.csv`;
+  const openedFile = files.get(filename);
+
+  if (openedFile) {
+    return openedFile;
+  }
+
+  const file = openFile(filename, type);
+  files.set(filename, file);
+  return file;
+}
+
+function openFile(filename: string, type: EventType): CsvFile {
+  const stream = fs.createWriteStream(path.join(CSV_DIRECTORY, filename));
+  const file: CsvFile = { error: undefined, filename, rows: 0, stream };
+  stream.on('error', (error) => {
+    file.error = error;
+  });
+  stream.write(formatCsvRow(['timestamp', ...EVENT_FIELDS[type]]));
+  return file;
+}
+
+async function writeRow(file: CsvFile, row: string): Promise<void> {
+  assertWritable(file);
+  file.rows += 1;
+
+  if (!file.stream.write(row)) {
+    await once(file.stream, 'drain');
+  }
+}
+
+async function closeFile(file: CsvFile): Promise<void> {
+  assertWritable(file);
+  file.stream.end();
+  await once(file.stream, 'finish');
+}
+
+function assertWritable(file: CsvFile): void {
+  if (file.error) {
+    throw file.error;
+  }
+}
+
+function printSummary(files: Map<string, CsvFile>, skippedLines: number): void {
+  if (files.size === 0) {
+    console.log('No events to export');
+  }
+
+  for (const file of [...files.values()].sort((a, b) => a.filename.localeCompare(b.filename))) {
+    console.log(`${path.join(CSV_DIRECTORY, file.filename)}: ${file.rows} rows`);
+  }
+
+  if (skippedLines > 0) {
+    console.log(`Skipped ${skippedLines} unparseable lines`);
+  }
+}
+
+function parseYear(argument: string | undefined): string | undefined {
+  if (argument !== undefined && !YEAR_FORMAT.test(argument)) {
+    throw new Error(`Expected a YYYY year, got "${argument}"`);
+  }
+
+  return argument;
+}

package/packages/logger/scripts/readEvents.ts

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import readline from 'node:readline';
+
+import { EVENT_FIELDS, EVENTS_FILEPATH, type LoggedEvent } from '../src';
+
+export async function* readEvents(): AsyncGenerator<LoggedEvent | undefined> {
+  if (!fs.existsSync(EVENTS_FILEPATH)) {
+    throw new Error(`No events file at ${EVENTS_FILEPATH}`);
+  }
+
+  const lines = readline.createInterface({ input: fs.createReadStream(EVENTS_FILEPATH), crlfDelay: Infinity });
+
+  for await (const line of lines) {
+    yield parseEvent(line);
+  }
+}
+
+function parseEvent(line: string): LoggedEvent | undefined {
+  try {
+    const value: unknown = JSON.parse(line);
+    return isLoggedEvent(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isLoggedEvent(value: unknown): value is LoggedEvent {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const { timestamp, type } = value as Partial<Record<'timestamp' | 'type', unknown>>;
+  return typeof timestamp === 'string' && typeof type === 'string' && Object.hasOwn(EVENT_FIELDS, type);
+}

package/packages/logger/scripts/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+
+  "compilerOptions": {
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"]
+}

package/packages/logger/src/constants.ts

@@ -1,4 +1,13 @@
 import os from 'os';
 import path from 'path';
 
+// bun test exposes the Jest globals to every module, so their presence marks a test run even under an inherited NODE_ENV
+declare const describe: unknown;
+
 export const OUTPUT_DIRECTORY = path.resolve(os.homedir(), '.scrabble-solver', 'logs');
+
+export const EVENTS_FILEPATH = path.resolve(OUTPUT_DIRECTORY, 'events.txt');
+
+export const CSV_DIRECTORY = path.resolve(os.homedir(), '.scrabble-solver', 'csv');
+
+export const IS_TEST_RUN = process.env.NODE_ENV === 'test' || typeof describe === 'function';

package/packages/logger/src/describeError.test.ts

@@ -0,0 +1,44 @@
+import { describeError } from './describeError';
+
+describe('describeError', () => {
+  it('prefixes the message with the error name and keeps the stack', () => {
+    const { message, stack } = describeError(new Error('boom'));
+
+    expect(message).toBe('Error: boom');
+    expect(stack).toStartWith('Error: boom\n');
+  });
+
+  it('includes the error code', () => {
+    const error = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:443'), { code: 'ECONNREFUSED' });
+
+    expect(describeError(error).message).toBe('Error [ECONNREFUSED]: connect ECONNREFUSED 127.0.0.1:443');
+  });
+
+  it('lists the errors behind an AggregateError with an empty message', () => {
+    const error = Object.assign(
+      new AggregateError(
+        [
+          Object.assign(new Error('connect ECONNREFUSED ::1:443'), { code: 'ECONNREFUSED' }),
+          Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:443'), { code: 'ECONNREFUSED' }),
+        ],
+        '',
+      ),
+      { code: 'ECONNREFUSED' },
+    );
+
+    expect(describeError(error).message).toBe(
+      'AggregateError [ECONNREFUSED]: (Error [ECONNREFUSED]: connect ECONNREFUSED ::1:443; Error [ECONNREFUSED]: connect ECONNREFUSED 127.0.0.1:443)',
+    );
+  });
+
+  it('includes the cause', () => {
+    const error = new Error('Could not download word list', { cause: new TypeError('fetch failed') });
+
+    expect(describeError(error).message).toBe('Error: Could not download word list (TypeError: fetch failed)');
+  });
+
+  it('stringifies values that are not errors without a stack', () => {
+    expect(describeError('boom')).toEqual({ message: 'boom', stack: undefined });
+    expect(describeError(undefined)).toEqual({ message: 'undefined', stack: undefined });
+  });
+});

package/packages/logger/src/describeError.ts

@@ -0,0 +1,30 @@
+export interface ErrorDescription {
+  message: string;
+  stack: string | undefined;
+}
+
+export function describeError(error: unknown): ErrorDescription {
+  return { message: formatError(error), stack: error instanceof Error ? error.stack : undefined };
+}
+
+function formatError(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+
+  const heading = `${error.name}${formatCode(error)}: ${error.message}`.trimEnd();
+  const nested = getNestedErrors(error);
+  return nested.length === 0 ? heading : `${heading} (${nested.map(formatError).join('; ')})`;
+}
+
+function formatCode(error: Error): string {
+  return 'code' in error && typeof error.code === 'string' ? ` [${error.code}]` : '';
+}
+
+function getNestedErrors(error: Error): unknown[] {
+  if (error instanceof AggregateError) {
+    return error.errors;
+  }
+
+  return error.cause === undefined ? [] : [error.cause];
+}

package/packages/logger/src/events.ts

@@ -0,0 +1,103 @@
+export type Event = VisitEvent | SolveEvent | VerifyEvent | DownloadEvent | DefinitionEvent | BuildEvent | ErrorEvent;
+
+export type EventType = Event['type'];
+
+export type EventOf<T extends EventType> = Extract<Event, { type: T }>;
+
+export type EventValue = string | number | boolean | undefined;
+
+export type LoggedEvent = Event & { timestamp: string };
+
+export type Operation = 'visit' | 'solve' | 'verify' | 'download' | 'definition' | 'build' | 'cache';
+
+type VisitEvent = {
+  type: 'visit';
+  ip?: string;
+  ua?: string;
+  referrer?: string;
+  locale?: string;
+  game?: string;
+  url?: string;
+};
+
+type SolveEvent = {
+  type: 'solve';
+  ip?: string;
+  ms: number;
+  locale: string;
+  game: string;
+  tiles: number;
+  blanks: number;
+  rack: string;
+  results: number;
+};
+
+type VerifyEvent = {
+  type: 'verify';
+  ip?: string;
+  ms: number;
+  locale: string;
+  game: string;
+  tiles: number;
+  blanks: number;
+  valid: number;
+  invalid: number;
+};
+
+type DownloadEvent = {
+  type: 'download';
+  ip?: string;
+  ms: number;
+  locale: string;
+  status: number;
+  encoding: 'gzip' | 'identity';
+  bytes: number;
+};
+
+type DefinitionEvent = {
+  type: 'definition';
+  ip?: string;
+  ms: number;
+  locale: string;
+  words: string;
+  found: number;
+};
+
+type BuildEvent = {
+  type: 'build';
+  locale: string;
+  words: number;
+  download_ms: number;
+  build_ms: number;
+};
+
+type ErrorEvent = {
+  type: 'error';
+  level: 'error' | 'warn';
+  operation: Operation;
+  locale?: string;
+  ip?: string;
+  ua?: string;
+  message: string;
+  stack?: string;
+  input?: string;
+};
+
+type FieldsOf<T extends EventType> = Exclude<keyof EventOf<T>, 'type'>;
+
+// Field order is the column order of the exported CSV files - append only, never reorder.
+export const EVENT_FIELDS = {
+  visit: ['ip', 'ua', 'referrer', 'locale', 'game', 'url'],
+  solve: ['ip', 'ms', 'locale', 'game', 'tiles', 'blanks', 'rack', 'results'],
+  verify: ['ip', 'ms', 'locale', 'game', 'tiles', 'blanks', 'valid', 'invalid'],
+  download: ['ip', 'ms', 'locale', 'status', 'encoding', 'bytes'],
+  definition: ['ip', 'ms', 'locale', 'words', 'found'],
+  build: ['locale', 'words', 'download_ms', 'build_ms'],
+  error: ['level', 'operation', 'locale', 'ip', 'ua', 'message', 'stack', 'input'],
+} as const satisfies { [T in EventType]: readonly FieldsOf<T>[] };
+
+type UnlistedFields = { [T in EventType]: Exclude<FieldsOf<T>, (typeof EVENT_FIELDS)[T][number]> }[EventType];
+
+type Assert<T extends never> = T;
+
+export type EveryFieldIsListed = Assert<UnlistedFields>;

package/packages/logger/src/formatCsvRow.test.ts

@@ -0,0 +1,41 @@
+import { formatCsvRow } from './formatCsvRow';
+
+describe('formatCsvRow', () => {
+  it('joins values with commas and ends the line', () => {
+    expect(formatCsvRow(['a', 1, true])).toBe('a,1,true\n');
+  });
+
+  it('writes undefined as an empty field', () => {
+    expect(formatCsvRow(['a', undefined, 'b'])).toBe('a,,b\n');
+  });
+
+  it('quotes fields containing commas', () => {
+    expect(formatCsvRow(['x,y'])).toBe('"x,y"\n');
+  });
+
+  it('quotes fields containing quotes and doubles them', () => {
+    expect(formatCsvRow(['say "hi"'])).toBe('"say ""hi"""\n');
+  });
+
+  it('quotes fields containing line breaks', () => {
+    expect(formatCsvRow(['Error: boom\n    at solve'])).toBe('"Error: boom\n    at solve"\n');
+  });
+
+  it('quotes fields with leading or trailing whitespace', () => {
+    expect(formatCsvRow([' ab', 'cd '])).toBe('" ab","cd "\n');
+  });
+
+  it('leaves inner whitespace unquoted', () => {
+    expect(formatCsvRow(['pz cvmt'])).toBe('pz cvmt\n');
+  });
+
+  it('prefixes text a spreadsheet would evaluate as a formula with a quote', () => {
+    expect(formatCsvRow(['=HYPERLINK("http://evil","x")', '+1', '-1', '@x', '\tx'])).toBe(
+      `"'=HYPERLINK(""http://evil"",""x"")",'+1,'-1,'@x,'\tx\n`,
+    );
+  });
+
+  it('leaves negative numbers alone', () => {
+    expect(formatCsvRow([-1])).toBe('-1\n');
+  });
+});

package/packages/logger/src/formatCsvRow.ts

@@ -0,0 +1,24 @@
+import { type EventValue } from './events';
+
+const FORMULA_PREFIX = /^[=+\-@\t\r]/;
+
+export function formatCsvRow(values: EventValue[]): string {
+  return `${values.map(formatCsvField).join(',')}\n`;
+}
+
+function formatCsvField(value: EventValue): string {
+  if (typeof value === 'undefined') {
+    return '';
+  }
+
+  const text = typeof value === 'string' ? escapeFormula(value) : String(value);
+  return needsQuoting(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+function escapeFormula(text: string): string {
+  return FORMULA_PREFIX.test(text) ? `'${text}` : text;
+}
+
+function needsQuoting(text: string): boolean {
+  return /[",\n\r]/.test(text) || text !== text.trim();
+}

package/packages/logger/src/index.ts

@@ -1 +1,13 @@
-export { logger } from './logger';
+export { CSV_DIRECTORY, EVENTS_FILEPATH, OUTPUT_DIRECTORY } from './constants';
+export {
+  EVENT_FIELDS,
+  type Event,
+  type EventOf,
+  type EventType,
+  type EventValue,
+  type LoggedEvent,
+  type Operation,
+} from './events';
+export { formatCsvRow } from './formatCsvRow';
+export { logError } from './logError';
+export { logEvent } from './logEvent';

package/packages/logger/src/logError.ts

@@ -0,0 +1,24 @@
+import { IS_TEST_RUN } from './constants';
+import { describeError, type ErrorDescription } from './describeError';
+import { type EventOf, type Operation } from './events';
+import { logEvent } from './logEvent';
+
+type ErrorContext = Partial<Pick<EventOf<'error'>, 'level' | 'input' | 'ip' | 'locale' | 'ua'>>;
+
+export function logError(
+  operation: Operation,
+  error: unknown,
+  { level = 'error', ...context }: ErrorContext = {},
+): void {
+  const description = describeError(error);
+  logEvent({ type: 'error', level, operation, ...description, ...context });
+
+  if (level === 'error' && !IS_TEST_RUN) {
+    process.stderr.write(formatStderrEntry(operation, description));
+  }
+}
+
+function formatStderrEntry(operation: Operation, { message, stack }: ErrorDescription): string {
+  const frames = stack?.split('\n').filter((line) => line.startsWith('    at ')) ?? [];
+  return `${[`${operation}: ${message}`, ...frames].join('\n')}\n`;
+}

package/packages/logger/src/logEvent.test.ts

@@ -0,0 +1,59 @@
+import { formatEventLine } from './logEvent';
+
+const NOW = new Date('2026-08-23T02:09:02.123Z');
+
+describe('formatEventLine', () => {
+  it('orders keys as timestamp, type, then the declared fields', () => {
+    const line = formatEventLine(
+      {
+        type: 'solve',
+        results: 312,
+        rack: 'p,z, ,c,v,m,t',
+        blanks: 4,
+        tiles: 61,
+        game: 'scrabble',
+        locale: 'en-US',
+        ms: 14,
+        ip: '203.0.113.7',
+      },
+      NOW,
+    );
+
+    expect(Object.keys(JSON.parse(line) as Record<string, unknown>)).toEqual([
+      'timestamp',
+      'type',
+      'ip',
+      'ms',
+      'locale',
+      'game',
+      'tiles',
+      'blanks',
+      'rack',
+      'results',
+    ]);
+  });
+
+  it('formats the timestamp in UTC with seconds precision', () => {
+    const line = formatEventLine({ type: 'build', locale: 'pl-PL', words: 3, download_ms: 1, build_ms: 2 }, NOW);
+
+    expect(line).toBe(
+      '{"timestamp":"2026-08-23T02:09:02Z","type":"build","locale":"pl-PL","words":3,"download_ms":1,"build_ms":2}\n',
+    );
+  });
+
+  it('omits undefined fields', () => {
+    const line = formatEventLine({ type: 'visit', ip: '::1', referrer: undefined }, NOW);
+
+    expect(line).toBe('{"timestamp":"2026-08-23T02:09:02Z","type":"visit","ip":"::1"}\n');
+  });
+
+  it('keeps multi-line values on a single line', () => {
+    const line = formatEventLine(
+      { type: 'error', level: 'error', operation: 'solve', message: 'Error: boom', stack: 'Error: boom\n    at solve' },
+      NOW,
+    );
+
+    expect(line.endsWith('\n')).toBe(true);
+    expect(line.slice(0, -1)).not.toContain('\n');
+  });
+});

package/packages/logger/src/logEvent.ts

@@ -0,0 +1,26 @@
+import fs from 'fs';
+
+import { EVENTS_FILEPATH, IS_TEST_RUN, OUTPUT_DIRECTORY } from './constants';
+import { EVENT_FIELDS, type Event } from './events';
+
+export function logEvent(event: Event): void {
+  if (IS_TEST_RUN) {
+    return;
+  }
+
+  try {
+    fs.mkdirSync(OUTPUT_DIRECTORY, { recursive: true });
+    fs.appendFileSync(EVENTS_FILEPATH, formatEventLine(event, new Date()));
+  } catch (error) {
+    process.stderr.write(`Could not append to ${EVENTS_FILEPATH}: ${String(error)}\n`);
+  }
+}
+
+export function formatEventLine(event: Event, now: Date): string {
+  const line = { timestamp: formatTimestamp(now), ...event };
+  return `${JSON.stringify(line, ['timestamp', 'type', ...EVENT_FIELDS[event.type]])}\n`;
+}
+
+function formatTimestamp(date: Date): string {
+  return `${date.toISOString().slice(0, 19)}Z`;
+}

package/packages/scrabble-solver/.next/BUILD_ID

@@ -1 +1 @@
-8WnIUTe-yJvPD6stltvYI
+YHx536pklAqlc9UGAXCj8

package/packages/scrabble-solver/.next/build-manifest.json

@@ -4,37 +4,37 @@
   ],
   "devFiles": [],
   "lowPriorityFiles": [
-    "static/8WnIUTe-yJvPD6stltvYI/_buildManifest.js",
-    "static/8WnIUTe-yJvPD6stltvYI/_ssgManifest.js"
+    "static/YHx536pklAqlc9UGAXCj8/_buildManifest.js",
+    "static/YHx536pklAqlc9UGAXCj8/_ssgManifest.js"
   ],
   "rootMainFiles": [],
   "rootMainFilesTree": {},
   "pages": {
     "/": [
-      "static/chunks/webpack-d7138f1ef6b8c9d6.js",
-      "static/chunks/framework-626cbd48ac5aca57.js",
-      "static/chunks/main-7e52da35a4beea0b.js",
-      "static/chunks/101-829ab8a8d310e7a0.js",
-      "static/css/a691348b788f8bc0.css",
-      "static/chunks/pages/index-b073a1686818dd26.js"
+      "static/chunks/webpack-31879a8fb6dcffd0.js",
+      "static/chunks/framework-988fd6f19d2744e8.js",
+      "static/chunks/main-d397eb8af33c5163.js",
+      "static/chunks/101-fee295c7587c0836.js",
+      "static/css/8b8087461767360a.css",
+      "static/chunks/pages/index-ea21d96a88f25000.js"
     ],
     "/_app": [
-      "static/chunks/webpack-d7138f1ef6b8c9d6.js",
-      "static/chunks/framework-626cbd48ac5aca57.js",
-      "static/chunks/main-7e52da35a4beea0b.js",
-      "static/css/92f85ce358a0a468.css",
-      "static/chunks/pages/_app-e3fe880e24c024ab.js"
+      "static/chunks/webpack-31879a8fb6dcffd0.js",
+      "static/chunks/framework-988fd6f19d2744e8.js",
+      "static/chunks/main-d397eb8af33c5163.js",
+      "static/css/4dbcacc1122ac6b9.css",
+      "static/chunks/pages/_app-0c68f165d6de8507.js"
     ],
     "/_error": [
-      "static/chunks/webpack-d7138f1ef6b8c9d6.js",
-      "static/chunks/framework-626cbd48ac5aca57.js",
-      "static/chunks/main-7e52da35a4beea0b.js",
+      "static/chunks/webpack-31879a8fb6dcffd0.js",
+      "static/chunks/framework-988fd6f19d2744e8.js",
+      "static/chunks/main-d397eb8af33c5163.js",
       "static/chunks/pages/_error-f0290a98eb3ed0ec.js"
     ],
     "/not-found": [
-      "static/chunks/webpack-d7138f1ef6b8c9d6.js",
-      "static/chunks/framework-626cbd48ac5aca57.js",
-      "static/chunks/main-7e52da35a4beea0b.js",
+      "static/chunks/webpack-31879a8fb6dcffd0.js",
+      "static/chunks/framework-988fd6f19d2744e8.js",
+      "static/chunks/main-d397eb8af33c5163.js",
       "static/css/dee878eb64099d92.css",
       "static/chunks/pages/not-found-a59f9deeeff63d17.js"
     ]

package/packages/scrabble-solver/.next/cache/.previewinfo

@@ -1 +1 @@
-{"previewModeId":"d56d08e80e1c264fb9d5bd2f046d21e9","previewModeSigningKey":"710dfc296ee593a012938c12ca917fa8a7e3ee8c4ee055414ad75479b6de3c74","previewModeEncryptionKey":"b8cd042dcfa5ffc82dead343e6d398a5c6e43f0914c1fcf246c66c0a019c64ed","expireAt":1788815296531}
+{"previewModeId":"e5835b7974ab86517c9c034b6f26b3cc","previewModeSigningKey":"fdd7ae3f3c9bd42534b79ae3f3ad08f8c08815d0712533b6bd6b5ba27ddc1d0e","previewModeEncryptionKey":"8a6fa29105f687ac81798e710d2478624efb911bfef8f3509bc47911dc94b0f6","expireAt":1792442881616}

package/packages/scrabble-solver/.next/cache/.rscinfo

@@ -1 +1 @@
-{"encryption.key":"YarGHnilucy7AOI9ayDZUAGfe4eQGgej5vNDdcCPS2k=","encryption.expire_at":1788815296528}
+{"encryption.key":"9C2t0KMmOagP1Ue6VIKvAFFN+2eDiMLL5yiFkiey4eo=","encryption.expire_at":1792442881614}