punctilio 1.2.10 → 1.4.0

package/src/tests/utils.test.ts

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs"
+import { tmpdir } from "node:os"
+
+import { countSeparators, assertSeparatorCountPreserved, formatErrorString } from "../utils.js"
+import { DEFAULT_SEPARATOR } from "../constants.js"
+
+describe("countSeparators", () => {
+  it.each([
+    ["empty string", "", DEFAULT_SEPARATOR, 0],
+    ["no separators", "hello world", DEFAULT_SEPARATOR, 0],
+    ["single separator", `a${DEFAULT_SEPARATOR}b`, DEFAULT_SEPARATOR, 1],
+    ["multiple separators", `${DEFAULT_SEPARATOR}a${DEFAULT_SEPARATOR}b${DEFAULT_SEPARATOR}`, DEFAULT_SEPARATOR, 3],
+    ["consecutive separators", `${DEFAULT_SEPARATOR}${DEFAULT_SEPARATOR}${DEFAULT_SEPARATOR}`, DEFAULT_SEPARATOR, 3],
+    ["custom separator", "a|b|c", "|", 2],
+  ])("%s: counts correctly", (_desc, input, separator, expected) => {
+    expect(countSeparators(input, separator)).toBe(expected)
+  })
+
+  it.each([
+    [`a${DEFAULT_SEPARATOR}b`, 1],
+    ["no separators", 0],
+    [`${DEFAULT_SEPARATOR}${DEFAULT_SEPARATOR}`, 2],
+  ])("uses DEFAULT_SEPARATOR when omitted: %s -> %i", (input, expected) => {
+    expect(countSeparators(input)).toBe(expected)
+  })
+})
+
+describe("assertSeparatorCountPreserved", () => {
+  describe("does not throw when count preserved", () => {
+    it.each([
+      ["same count", `a${DEFAULT_SEPARATOR}b`, `x${DEFAULT_SEPARATOR}y`],
+      ["zero count", "ab", "xy"],
+      ["multiple preserved", `${DEFAULT_SEPARATOR}a${DEFAULT_SEPARATOR}b${DEFAULT_SEPARATOR}`, `${DEFAULT_SEPARATOR}x${DEFAULT_SEPARATOR}y${DEFAULT_SEPARATOR}`],
+    ])("%s", (_desc, original, transformed) => {
+      expect(() => assertSeparatorCountPreserved(original, transformed, DEFAULT_SEPARATOR, "test")).not.toThrow()
+    })
+  })
+
+  describe("throws when count changes", () => {
+    it.each([
+      ["separator removed", `a${DEFAULT_SEPARATOR}b`, "ab", 1, 0],
+      ["separator added", "ab", `a${DEFAULT_SEPARATOR}b`, 0, 1],
+      ["multiple removed", `${DEFAULT_SEPARATOR}${DEFAULT_SEPARATOR}`, "", 2, 0],
+    ])("%s: expected %i, got %i", (_desc, original, transformed, expectedCount, actualCount) => {
+      expect(() => assertSeparatorCountPreserved(original, transformed, DEFAULT_SEPARATOR, "testFn"))
+        .toThrow(`testFn altered separator count: expected ${expectedCount}, got ${actualCount}`)
+    })
+  })
+
+  describe("default parameters", () => {
+    it.each([
+      ["throws when separator lost", `a${DEFAULT_SEPARATOR}b`, "ab", true],
+      ["does not throw when preserved", `a${DEFAULT_SEPARATOR}b`, `x${DEFAULT_SEPARATOR}y`, false],
+    ])("%s", (_desc, original, transformed, shouldThrow) => {
+      if (shouldThrow) {
+        expect(() => assertSeparatorCountPreserved(original, transformed)).toThrow()
+      } else {
+        expect(() => assertSeparatorCountPreserved(original, transformed)).not.toThrow()
+      }
+    })
+  })
+})
+
+describe("formatErrorString", () => {
+  it("returns JSON-stringified content for short strings", () => {
+    const result = formatErrorString("short text", "test")
+    expect(result).toBe('"short text"')
+  })
+
+  it("writes to temp file for strings over 500 chars", () => {
+    const longText = "x".repeat(501)
+    const result = formatErrorString(longText, "long-test")
+
+    expect(result).toMatch(/^\[written to .+punctilio-error-long-test-\d+\.txt\]$/)
+
+    // Extract filepath and verify file contents
+    const match = result.match(/\[written to (?<path>.+)\]/)
+    const filepath = match?.groups?.path ?? ""
+    expect(filepath).not.toBe("")
+    expect(existsSync(filepath)).toBe(true)
+    expect(readFileSync(filepath, "utf-8")).toBe(longText)
+
+    // Cleanup
+    unlinkSync(filepath)
+  })
+
+  it("writes to temp directory", () => {
+    const longText = "y".repeat(600)
+    const result = formatErrorString(longText, "tmpdir")
+
+    const match = result.match(/\[written to (?<path>.+)\]/)
+    const filepath = match?.groups?.path ?? ""
+    expect(filepath).not.toBe("")
+    expect(filepath.startsWith(tmpdir())).toBe(true)
+
+    unlinkSync(filepath)
+  })
+})

package/src/utils.ts

@@ -0,0 +1,65 @@
+/**
+ * Utility functions for text transformation validation.
+ *
+ * @module utils
+ */
+
+import { writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { DEFAULT_SEPARATOR } from "./constants.js"
+
+/** Threshold above which strings are written to temp files in error messages. */
+const ERROR_STRING_THRESHOLD = 500
+
+/**
+ * Formats a string for error messages. If the string exceeds the threshold,
+ * writes it to a temp file and returns a reference to the file path.
+ */
+export function formatErrorString(content: string, label: string): string {
+  if (content.length <= ERROR_STRING_THRESHOLD) {
+    return JSON.stringify(content)
+  }
+
+  const timestamp = Date.now()
+  const filename = `punctilio-error-${label}-${timestamp}.txt`
+  const filepath = join(tmpdir(), filename)
+  writeFileSync(filepath, content, "utf-8")
+  return `[written to ${filepath}]`
+}
+
+export function countSeparators(text: string, separator: string = DEFAULT_SEPARATOR): number {
+  let count = 0
+  for (const char of text) {
+    if (char === separator) count++
+  }
+  return count
+}
+
+/**
+ * Validates that a transformation preserved the separator count.
+ * Throws an error if separators were added or removed.
+ *
+ * @param original - The original text before transformation
+ * @param transformed - The text after transformation
+ * @param separator - The separator character to check (default: DEFAULT_SEPARATOR)
+ * @param transformName - Name of the transform for error messages (default: "transform")
+ * @throws Error if separator count changed
+ */
+export function assertSeparatorCountPreserved(
+  original: string,
+  transformed: string,
+  separator: string = DEFAULT_SEPARATOR,
+  transformName: string = "transform"
+): void {
+  const originalCount = countSeparators(original, separator)
+  const transformedCount = countSeparators(transformed, separator)
+  if (originalCount !== transformedCount) {
+    throw new Error(
+      `${transformName} altered separator count: expected ${originalCount}, got ${transformedCount}.\n` +
+      `This is a bug in punctilio. Please file an issue at https://github.com/alexander-turner/punctilio/issues\n` +
+      `Include the input text that caused this error.`
+    )
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}