scrabble-solver 2.18.2 → 2.18.4

package/packages/logger/build/describeError.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeError = describeError;
+function describeError(error) {
+    return { message: formatError(error), stack: error instanceof Error ? error.stack : undefined };
+}
+function formatError(error) {
+    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) {
+    return 'code' in error && typeof error.code === 'string' ? ` [${error.code}]` : '';
+}
+function getNestedErrors(error) {
+    if (error instanceof AggregateError) {
+        return error.errors;
+    }
+    return error.cause === undefined ? [] : [error.cause];
+}

package/packages/logger/build/events.d.ts

@@ -0,0 +1,92 @@
+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'>;
+export declare const EVENT_FIELDS: {
+    readonly visit: readonly ["ip", "ua", "referrer", "locale", "game", "url"];
+    readonly solve: readonly ["ip", "ms", "locale", "game", "tiles", "blanks", "rack", "results"];
+    readonly verify: readonly ["ip", "ms", "locale", "game", "tiles", "blanks", "valid", "invalid"];
+    readonly download: readonly ["ip", "ms", "locale", "status", "encoding", "bytes"];
+    readonly definition: readonly ["ip", "ms", "locale", "words", "found"];
+    readonly build: readonly ["locale", "words", "download_ms", "build_ms"];
+    readonly error: readonly ["level", "operation", "locale", "ip", "ua", "message", "stack", "input"];
+};
+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>;
+export {};

package/packages/logger/build/events.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_FIELDS = void 0;
+// Field order is the column order of the exported CSV files - append only, never reorder.
+exports.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'],
+};

package/packages/logger/build/formatCsvRow.d.ts

@@ -0,0 +1,2 @@
+import { type EventValue } from './events';
+export declare function formatCsvRow(values: EventValue[]): string;

package/packages/logger/build/formatCsvRow.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCsvRow = formatCsvRow;
+const FORMULA_PREFIX = /^[=+\-@\t\r]/;
+function formatCsvRow(values) {
+    return `${values.map(formatCsvField).join(',')}\n`;
+}
+function formatCsvField(value) {
+    if (typeof value === 'undefined') {
+        return '';
+    }
+    const text = typeof value === 'string' ? escapeFormula(value) : String(value);
+    return needsQuoting(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+function escapeFormula(text) {
+    return FORMULA_PREFIX.test(text) ? `'${text}` : text;
+}
+function needsQuoting(text) {
+    return /[",\n\r]/.test(text) || text !== text.trim();
+}

package/packages/logger/build/index.d.ts

@@ -1 +1,5 @@
-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/build/index.js

@@ -1,5 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logger = void 0;
-var logger_1 = require("./logger");
-Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_1.logger; } });
+exports.logEvent = exports.logError = exports.formatCsvRow = exports.EVENT_FIELDS = exports.OUTPUT_DIRECTORY = exports.EVENTS_FILEPATH = exports.CSV_DIRECTORY = void 0;
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "CSV_DIRECTORY", { enumerable: true, get: function () { return constants_1.CSV_DIRECTORY; } });
+Object.defineProperty(exports, "EVENTS_FILEPATH", { enumerable: true, get: function () { return constants_1.EVENTS_FILEPATH; } });
+Object.defineProperty(exports, "OUTPUT_DIRECTORY", { enumerable: true, get: function () { return constants_1.OUTPUT_DIRECTORY; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "EVENT_FIELDS", { enumerable: true, get: function () { return events_1.EVENT_FIELDS; } });
+var formatCsvRow_1 = require("./formatCsvRow");
+Object.defineProperty(exports, "formatCsvRow", { enumerable: true, get: function () { return formatCsvRow_1.formatCsvRow; } });
+var logError_1 = require("./logError");
+Object.defineProperty(exports, "logError", { enumerable: true, get: function () { return logError_1.logError; } });
+var logEvent_1 = require("./logEvent");
+Object.defineProperty(exports, "logEvent", { enumerable: true, get: function () { return logEvent_1.logEvent; } });

package/packages/logger/build/logError.d.ts

@@ -0,0 +1,4 @@
+import { type EventOf, type Operation } from './events';
+type ErrorContext = Partial<Pick<EventOf<'error'>, 'level' | 'input' | 'ip' | 'locale' | 'ua'>>;
+export declare function logError(operation: Operation, error: unknown, { level, ...context }?: ErrorContext): void;
+export {};

package/packages/logger/build/logError.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logError = logError;
+const constants_1 = require("./constants");
+const describeError_1 = require("./describeError");
+const logEvent_1 = require("./logEvent");
+function logError(operation, error, { level = 'error', ...context } = {}) {
+    const description = (0, describeError_1.describeError)(error);
+    (0, logEvent_1.logEvent)({ type: 'error', level, operation, ...description, ...context });
+    if (level === 'error' && !constants_1.IS_TEST_RUN) {
+        process.stderr.write(formatStderrEntry(operation, description));
+    }
+}
+function formatStderrEntry(operation, { message, stack }) {
+    const frames = stack?.split('\n').filter((line) => line.startsWith('    at ')) ?? [];
+    return `${[`${operation}: ${message}`, ...frames].join('\n')}\n`;
+}

package/packages/logger/build/logEvent.d.ts

@@ -0,0 +1,3 @@
+import { type Event } from './events';
+export declare function logEvent(event: Event): void;
+export declare function formatEventLine(event: Event, now: Date): string;

package/packages/logger/build/logEvent.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logEvent = logEvent;
+exports.formatEventLine = formatEventLine;
+const fs_1 = __importDefault(require("fs"));
+const constants_1 = require("./constants");
+const events_1 = require("./events");
+function logEvent(event) {
+    if (constants_1.IS_TEST_RUN) {
+        return;
+    }
+    try {
+        fs_1.default.mkdirSync(constants_1.OUTPUT_DIRECTORY, { recursive: true });
+        fs_1.default.appendFileSync(constants_1.EVENTS_FILEPATH, formatEventLine(event, new Date()));
+    }
+    catch (error) {
+        process.stderr.write(`Could not append to ${constants_1.EVENTS_FILEPATH}: ${String(error)}\n`);
+    }
+}
+function formatEventLine(event, now) {
+    const line = { timestamp: formatTimestamp(now), ...event };
+    return `${JSON.stringify(line, ['timestamp', 'type', ...events_1.EVENT_FIELDS[event.type]])}\n`;
+}
+function formatTimestamp(date) {
+    return `${date.toISOString().slice(0, 19)}Z`;
+}

package/packages/logger/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@scrabble-solver/logger",
-  "version": "2.18.2",
-  "description": "Winston-based JSON file logger for Scrabble Solver.",
+  "version": "2.18.4",
+  "description": "JSON-lines event log for Scrabble Solver, with CSV export.",
   "keywords": [
     "logger",
-    "winston",
+    "events",
+    "csv",
     "scrabble"
   ],
   "main": "build/index.js",
@@ -24,12 +25,10 @@
   },
   "homepage": "https://scrabble-solver.org",
   "scripts": {
-    "build": "tsc --project .",
+    "build": "tsc --project . && tsc --project scripts",
     "clean": "rimraf build/",
-    "stats": "node scripts/stats.js"
-  },
-  "dependencies": {
-    "winston": "^3.19.0"
+    "export": "bun scripts/export-csv.ts",
+    "test": "bun test src"
   },
   "gitHead": "1e2d1ad49a288d4a44196d8e3336740da132c637"
 }

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');
+  });
+});