@hardlydifficult/text 1.0.17 → 1.0.19

package/README.md

@@ -11,154 +11,199 @@ npm install @hardlydifficult/text
 ## Quick Start
 
 ```typescript
-import * as text from "@hardlydifficult/text";
+import {
+  replaceTemplate,
+  chunkText,
+  slugify,
+  formatDuration,
+  buildFileTree,
+  convertFormat,
+  createLinker,
+} from "@hardlydifficult/text";
 
 // Template replacement
-const greeting = text.replaceTemplate("Hello {{name}}!", { name: "World" });
-console.log(greeting); // "Hello World!"
+const greeting = replaceTemplate("Hello {{name}}!", { name: "Alice" });
+// "Hello Alice!"
 
-// Text chunking
-const chunks = text.chunkText("Line 1\nLine 2\nLong line", 15);
-console.log(chunks); // ["Line 1\nLine 2", "Long line"]
+// Split long text into chunks
+const chunks = chunkText("Line 1\nLine 2\nLine 3", 10);
+// ["Line 1\nLine 2", "Line 3"]
 
-// Slugification
-console.log(text.slugify("My Feature Name!")); // "my-feature-name"
+// Convert to URL-safe slug
+const slug = slugify("My Feature Name!", 10);
+// "my-feature"
 
-// Duration formatting
-console.log(text.formatDuration(125_000)); // "2m 5s"
-```
-
-## Error Handling
-
-### `getErrorMessage(err: unknown): string`
+// Format duration in ms
+const formatted = formatDuration(125_000);
+// "2m 5s"
 
-Extract a message string from an unknown error.
-
-```typescript
-import { getErrorMessage } from "@hardlydifficult/text";
+// Build a file tree
+const tree = buildFileTree(["src/index.ts", "src/utils.ts", "README.md"]);
+// src/
+//   index.ts
+//   utils.ts
+//
+// README.md
 
-try {
-  throw new Error("Something went wrong");
-} catch (err) {
-  console.error(getErrorMessage(err)); // "Something went wrong"
-}
+// Convert between JSON/YAML
+const yaml = convertFormat('{"name":"Alice"}', "yaml");
+// name: Alice
 ```
 
-### `formatError(err: unknown, context?: string): string`
+## Error Handling
 
-Format an error with an optional context prefix.
+Consistent error extraction and formatting utilities.
 
 ```typescript
-import { formatError } from "@hardlydifficult/text";
-
-formatError(new Error("not found"), "User lookup"); // "User lookup: not found"
-formatError(new Error("not found")); // "not found"
-```
+import { getErrorMessage, formatError, formatErrorForLog } from "@hardlydifficult/text";
 
-### `formatErrorForLog(err: unknown): string`
+const err = new Error("disk full");
 
-Format an error for logging. Returns `err.message` for `Error` instances, `String(err)` otherwise.
+getErrorMessage(err); // "disk full"
+formatError(err, "Failed to save"); // "Failed to save: disk full"
+formatErrorForLog(err); // "disk full"
+```
 
-```typescript
-import { formatErrorForLog } from "@hardlydifficult/text";
+### Functions
 
-formatErrorForLog(new Error("Database error")); // "Database error"
-```
+| Function | Description |
+|----------|-------------|
+| `getErrorMessage(err)` | Extract message string from unknown error |
+| `formatError(err, context?)` | Format error with optional context prefix |
+| `formatErrorForLog(err)` | Format error for logging (non-Error → string) |
 
 ## Template Replacement
 
-### `replaceTemplate(template: string, values: Record<string, string>): string`
-
-Replace `{{variable}}` placeholders with provided values.
+Simple string interpolation using `{{variable}}` syntax.
 
 ```typescript
-import { replaceTemplate } from "@hardlydifficult/text";
+import { replaceTemplate, extractPlaceholders } from "@hardlydifficult/text";
 
-replaceTemplate("Hello {{name}}, welcome to {{place}}!", {
+const text = replaceTemplate("Hello {{name}}! You are {{age}}.", {
   name: "Alice",
-  place: "Wonderland",
+  age: "30",
 });
-// "Hello Alice, welcome to Wonderland!"
-```
-
-### `extractPlaceholders(template: string): string[]`
-
-Extract all unique placeholder names from a template string.
+// "Hello Alice! You are 30."
 
-```typescript
-import { extractPlaceholders } from "@hardlydifficult/text";
-
-extractPlaceholders("{{name}} is in {{place}}"); // ["name", "place"]
+const vars = extractPlaceholders("{{greeting}}, {{name}}!");
+// ["greeting", "name"]
 ```
 
-## Text Processing
+### Functions
 
-### `chunkText(text: string, maxLength: number): string[]`
+| Function | Description |
+|----------|-------------|
+| `replaceTemplate(template, values)` | Replace all `{{variable}}` placeholders |
+| `extractPlaceholders(template)` | Return unique placeholder names |
 
-Split text into chunks of at most `maxLength` characters, preferring line breaks and spaces for natural breaks.
+## Text Chunking
+
+Split long text into manageable chunks respecting natural breaks.
 
 ```typescript
 import { chunkText } from "@hardlydifficult/text";
 
-const text = "Line 1\nLine 2\nThis is a very long line that needs to be chunked.";
-const chunks = chunkText(text, 20);
-// ["Line 1\nLine 2", "This is a very", "long line that", "needs to be", "chunked."]
+const text = "line one\nline two\nline three";
+chunkText(text, 18);
+// ["line one\nline two", "line three"]
 ```
 
-### `slugify(input: string, maxLength?: number): string`
+### Behavior
+
+- Breaks on newlines first, then spaces
+- Falls back to hard breaks when no natural break point exists
+- Trims leading whitespace from subsequent chunks
 
-Convert a string to a URL/filename-safe slug by lowercasing, replacing non-alphanumeric characters with hyphens, and optionally truncating at hyphen boundaries.
+## Slugification
+
+Convert strings to URL/filename-safe slugs.
 
 ```typescript
 import { slugify } from "@hardlydifficult/text";
 
 slugify("My Feature Name!"); // "my-feature-name"
 slugify("My Feature Name!", 10); // "my-feature"
-slugify("  spaces & symbols!  "); // "spaces-symbols"
 ```
 
-### `formatWithLineNumbers(content: string, startLine?: number): string`
+### Features
 
-Format text content with right-aligned line numbers.
+- Lowercases and replaces non-alphanumeric runs with single hyphens
+- Trims leading/trailing hyphens
+- Optional `maxLength` truncates at hyphen boundary when possible
 
-```typescript
-import { formatWithLineNumbers } from "@hardlydifficult/text";
+## Duration Formatting
 
-formatWithLineNumbers("foo\nbar\nbaz");
-// " 1: foo\n 2: bar\n 3: baz"
+Format milliseconds as human-readable duration strings.
 
-formatWithLineNumbers("hello\nworld", 10);
-// "10: hello\n11: world"
+```typescript
+import { formatDuration } from "@hardlydifficult/text";
+
+formatDuration(125_000); // "2m 5s"
+formatDuration(3_600_000); // "1h"
+formatDuration(500); // "<1s"
 ```
 
-### `formatDuration(ms: number): string`
+### Format Rules
 
-Format milliseconds as a human-readable duration string, showing up to two units and using "<1s" for sub-second values.
+| Duration | Output |
+|----------|--------|
+| < 1000ms | `<1s` |
+| 1–59 seconds | `<seconds>s` |
+| 1–59 minutes | `<minutes>m` or `<minutes>m <seconds>s` |
+| 1–23 hours | `<hours>h` or `<hours>h <minutes>m` |
+| ≥ 1 day | `<days>d` or `<days>d <hours>h` |
+
+## File Tree Rendering
+
+Build and render hierarchical file trees with depth-based truncation and annotations.
 
 ```typescript
-import { formatDuration } from "@hardlydifficult/text";
+import { buildFileTree, FILE_TREE_DEFAULTS } from "@hardlydifficult/text";
+import type { BuildTreeOptions } from "@hardlydifficult/text";
 
-formatDuration(125_000);   // "2m 5s"
-formatDuration(3_600_000); // "1h"
-formatDuration(500);       // "<1s"
-formatDuration(90_000_000); // "1d 1h"
+const paths = [
+  "src/index.ts",
+  "test/unit/a.test.ts",
+  "test/unit/b.test.ts",
+];
+
+const options: BuildTreeOptions = {
+  maxLevel2: 2,
+  annotations: new Map([["src/index.ts", "Entry point"]]),
+  collapseDirs: ["test"],
+};
+
+buildFileTree(paths, options);
+// src/
+//   index.ts — Entry point
+//
+// test/
+//   (2 files across 1 dir)
 ```
 
-## Format Conversion
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxLevel2` | `number` | 10 | Max children to show at depth 2 (top-level dirs) |
+| `maxLevel3` | `number` | 3 | Max children to show at depth 3 (files/dirs inside top dirs) |
+| `annotations` | `Map<string, string>` | `undefined` | File/dir descriptions |
+| `details` | `Map<string, string[]>` | `undefined` | Extra lines to show under file entries |
+| `collapseDirs` | `string[]` | `undefined` | Directory names to collapse and summarize |
 
-### `convertFormat(content: string, to: "json" | "yaml"): string`
+## Format Conversion
 
-Convert between JSON and YAML string formats with automatic input format detection.
+Convert text between JSON and YAML with auto-detection.
 
 ```typescript
 import { convertFormat } from "@hardlydifficult/text";
+import type { TextFormat } from "@hardlydifficult/text";
 
 // JSON to YAML
-convertFormat('{"name": "Alice", "age": 30}', "yaml");
+convertFormat('{"name":"Alice"}', "yaml");
 // name: Alice
-// age: 30
 
-// YAML to JSON
+// YAML to JSON (pretty-printed with 2-space indent)
 convertFormat("name: Alice\nage: 30", "json");
 // {
 //   "name": "Alice",
@@ -166,212 +211,136 @@ convertFormat("name: Alice\nage: 30", "json");
 // }
 ```
 
-### `formatYaml(data: unknown): string`
+### Functions
 
-Serialize data to clean YAML, using block literals for long strings containing colons.
+| Function | Description |
+|----------|-------------|
+| `convertFormat(content, to)` | Parse input and re-serialize to `json` or `yaml` |
 
-```typescript
-import { formatYaml } from "@hardlydifficult/text";
+## YAML Formatting
 
-formatYaml({ message: "Hello: World" });
-// "message: >\n  Hello: World"
-```
-
-### `healYaml(dirtyYaml: string): string`
-
-Clean malformed YAML by stripping markdown code fences and quoting problematic scalar values containing colons.
+Serialize data to clean YAML, using block literals for long strings containing `: `.
 
 ```typescript
-import { healYaml } from "@hardlydifficult/text";
+import { formatYaml } from "@hardlydifficult/text";
 
-healYaml('```yaml\nmessage: Hello: World\n```');
-// "message: >\n  Hello: World"
+formatYaml({
+  purpose:
+    "Core AI SDK: LLM integrations (Anthropic, Ollama) and streaming support.",
+});
+// purpose: |
+//   Core AI SDK: LLM integrations (Anthropic, Ollama) and streaming support.
 ```
 
-## Link Generation
+### Behavior
 
-### `createLinker(initialRules?: LinkRule[]): Linker`
+- Long strings (`>60 chars`) containing `: ` render as block literals (`|`)
+- Short strings and safe scalars remain plain or quoted as needed
+- Preserves round-trip parseability
 
-Create a configurable linker to transform text patterns into platform-specific links. The linker is idempotent by default, skips code spans and existing links, and resolves overlapping matches deterministically.
+## YAML Healing
+
+Sanitize malformed YAML from LLMs by stripping code fences and quoting scalar values containing colons.
 
 ```typescript
-import { createLinker } from "@hardlydifficult/text";
+import { healYaml } from "@hardlydifficult/text";
+import { parse } from "yaml";
 
-const linker = createLinker()
-  .linear("fairmint")
-  .githubPr("Fairmint/api");
+const badYaml = `\`\`\`yaml
+purpose: |
+  Core AI: LLM integrations (Anthropic, Ollama)
+description: Main deps: Node, TypeScript, Vitest.
+\`\`\``;
 
-linker.linkText("Fix ENG-533 and PR#42", { format: "slack" });
-// "Fix <https://linear.app/fairmint/issue/ENG-533|ENG-533> and <https://github.com/Fairmint/api/pull/42|PR#42>"
+const cleaned = healYaml(badYaml);
+// purpose: |
+//   Core AI: LLM integrations (Anthropic, Ollama)
+// description: "Main deps: Node, TypeScript, Vitest."
 
-linker.linkText("Fix ENG-533 and PR#42", { format: "markdown" });
-// "[ENG-533](https://linear.app/fairmint/issue/ENG-533) and [PR#42](https://github.com/Fairmint/api/pull/42)"
+parse(cleaned); // Parses successfully
 ```
 
-#### Linker Methods
+### Fixes Applied
 
-**`.linear(workspace: string, options?: { name?: string; priority?: number }): Linker`**
+- Strips markdown code fences (` ```yaml ` or ` ``` `)
+- Quotes plain scalar values containing `: ` to avoid parse errors
 
-Add a rule for Linear issue references (e.g., `ENG-533`).
+## Linkification
 
-```typescript
-const linker = createLinker().linear("fairmint");
-linker.linkText("Fix ENG-533", { format: "markdown" });
-// "[ENG-533](https://linear.app/fairmint/issue/ENG-533)"
-```
-
-**`.githubPr(repository: string, options?: { name?: string; priority?: number }): Linker`**
-
-Add a rule for GitHub pull request references (e.g., `PR#42`).
+Transform text with issue/PR references into formatted links.
 
 ```typescript
-const linker = createLinker().githubPr("Fairmint/api");
-linker.linkText("Merge PR#42", { format: "markdown" });
-// "[PR#42](https://github.com/Fairmint/api/pull/42)"
-```
-
-**`.custom(pattern: RegExp, toHref: string | LinkHrefBuilder, options?: { name?: string; priority?: number }): Linker`**
+import { createLinker } from "@hardlydifficult/text";
 
-Add a custom rule with a regex pattern and URL template or callback.
+const linker = createLinker()
+  .linear("fairmint")
+  .githubPr("Fairmint/api");
 
-```typescript
-const linker = createLinker().custom(
-  /\bINC-\d+\b/g,
-  ({ match }) => `https://incident.io/${match}`
-);
-linker.linkText("Resolve INC-99", { format: "markdown" });
-// "[INC-99](https://incident.io/INC-99)"
+const output = linker.apply("Fix ENG-533 and PR#42", { platform: "slack" });
+// Fix <https://linear.app/fairmint/issue/ENG-533|ENG-533> <https://github.com/Fairmint/api/pull/42|PR#42>
 ```
 
-**`.linkText(input: string, options?: LinkerApplyOptions): string`**
+### Platforms
 
-Apply all configured rules to the input text and return formatted links.
+| Platform | Output Format |
+|----------|---------------|
+| `slack` | `<href\|text>` |
+| `discord` | `[text](href)` |
+| `markdown` | `[text](href)` |
+| `plaintext` | `href` (raw URL) |
 
-**`.apply(input: string, options?: LinkerApplyOptions): string`**
+### Linker Methods
 
-Alias for `linkText()`.
+| Method | Description |
+|--------|-------------|
+| `custom(pattern, toHref, options)` | Register a new rule with regex pattern and href builder |
+| `linear(workspace, options)` | Match `PROJECT-123` and link to Linear |
+| `githubPr(repository, options)` | Match `PR#123` and link to GitHub Pull Request |
+| `apply(text, options)` | Transform text with configured rules |
 
-#### Link Options
+### Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `format` | `"slack" \| "discord" \| "markdown" \| "plaintext"` | `"markdown"` | Target output format |
-| `platform` | `"slack" \| "discord" \| "markdown" \| "plaintext"` | `"markdown"` | Alias for `format` |
-| `skipCode` | `boolean` | `true` | Skip linkification inside code spans (backticks and fenced blocks) |
-| `skipExistingLinks` | `boolean` | `true` | Skip linkification inside existing links (Slack, Markdown, and plain URLs) |
-
-#### URL Template Syntax
-
-When using a string template for `href` or `toHref`, the following substitutions are available:
-
-- `$0` or `$&` — Full regex match
-- `$1`, `$2`, etc. — Capture groups
-- `$$` — Literal `$`
+| `format` / `platform` | `LinkerPlatform` | `"markdown"` | Output format |
+| `skipCode` | `boolean` | `true` | Skip linkification inside code blocks/inline code |
+| `skipExistingLinks` | `boolean` | `true` | Skip linkification inside existing links |
 
-```typescript
-const linker = createLinker().custom(
-  /\b([A-Z]{2,6})-(\d+)\b/g,
-  "https://example.com/issues/$1/$2"
-);
-linker.linkText("ENG-533", { format: "markdown" });
-// "[ENG-533](https://example.com/issues/ENG/533)"
-```
+### LinkRule Options
 
-## File Tree Rendering
+| Property | Type | Description |
+|----------|------|-------------|
+| `pattern` | `RegExp` | Match pattern (global matching enforced) |
+| `href` / `toHref` | `string` or `LinkHrefBuilder` | URL template (supports `$0`/`$&`, `$1`..`$N`) or callback |
+| `priority` | `number` | `0` | Higher priority wins overlapping matches |
 
-### `buildFileTree(files: string[], options?: BuildTreeOptions): string`
+## Text with Line Numbers
 
-Build and render a hierarchical file tree with depth-based truncation and optional annotations.
+Format text content with right-aligned line numbers.
 
 ```typescript
-import { buildFileTree } from "@hardlydifficult/text";
-
-const files = [
-  "src/index.ts",
-  "src/utils.ts",
-  "src/components/Button.tsx",
-  "README.md",
-];
-
-buildFileTree(files);
-// src/
-//   index.ts
-//   utils.ts
-//   components/
-//     Button.tsx
-//
-// README.md
-```
-
-#### Tree Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `maxLevel2` | `number` | `10` | Maximum children to show at depth 2 |
-| `maxLevel3` | `number` | `3` | Maximum children to show at depth 3+ |
-| `annotations` | `Map<string, string>` | — | Descriptions to append to entries (e.g., `"src/index.ts" → "Main entry point"`) |
-| `details` | `Map<string, string[]>` | — | Extra indented lines to show under file entries (e.g., key sections) |
-| `collapseDirs` | `string[]` | — | Directory names to collapse with a summary instead of expanding |
+import { formatWithLineNumbers } from "@hardlydifficult/text";
 
-#### Annotations Example
+formatWithLineNumbers("foo\nbar\nbaz");
+// 1: foo
+// 2: bar
+// 3: baz
 
-```typescript
-const annotations = new Map([
-  ["src", "Source code"],
-  ["src/index.ts", "Main entry point"],
-]);
-
-buildFileTree(["src/index.ts", "src/utils.ts"], { annotations });
-// src/ — Source code
-//   index.ts — Main entry point
-//   utils.ts
+formatWithLineNumbers("hello\nworld", 10);
+// 10: hello
+// 11: world
 ```
 
-#### Details Example
-
-```typescript
-const details = new Map([
-  [
-    "src/index.ts",
-    [
-      "> main (5-20): App entry point.",
-      "> shutdown (22-35): Cleanup handler.",
-    ],
-  ],
-]);
-
-buildFileTree(["src/index.ts"], { details });
-// src/
-//   index.ts
-//     > main (5-20): App entry point.
-//     > shutdown (22-35): Cleanup handler.
-```
+## Markdown Fence Escaping
 
-#### Collapsed Directories Example
+Escape content by wrapping with more backticks than contained in the content.
 
 ```typescript
-buildFileTree(
-  [
-    "node_modules/package-a/index.js",
-    "node_modules/package-b/index.js",
-    "src/index.ts",
-  ],
-  { collapseDirs: ["node_modules"] }
-);
-// node_modules/
-//   (2 files across 2 dirs)
-//
-// src/
-//   index.ts
-```
+import { escapeFence } from "@hardlydifficult/text";
 
-### `FILE_TREE_DEFAULTS`
-
-Default truncation limits for file tree rendering.
-
-```typescript
-import { FILE_TREE_DEFAULTS } from "@hardlydifficult/text";
+const result = escapeFence("content with ``` triple backticks");
+// { fence: "````", content: "content with ``` triple backticks" }
 
-console.log(FILE_TREE_DEFAULTS.maxLevel2); // 10
-console.log(FILE_TREE_DEFAULTS.maxLevel3); // 3
+// Use as:
+// ${result.fence}${result.content}${result.fence}
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/text",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [