@hardlydifficult/text 1.0.7 → 1.0.9

package/README.md

@@ -149,3 +149,45 @@ formatWithLineNumbers("line 1\nline 2\n...\nline 100", 98);
 ```
 
 This is useful for displaying code snippets, file contents, or log output with line numbers for reference.
+
+### `createLinker(rules?)`
+
+Create a reusable linker that turns matched text patterns into platform-specific links.
+
+Supports:
+
+- plain strings
+- idempotent re-runs (won't double-link existing linked text)
+- skipping code spans/backticks and existing links by default
+- deterministic conflict handling (priority, then longest match, then rule order)
+
+```typescript
+import { createLinker } from "@hardlydifficult/text";
+
+const linker = createLinker()
+  .linear("fairmint")
+  .githubPr("Fairmint/api")
+  .custom(/\bINC-\d+\b/g, ({ match }) => `https://incident.io/${match}`);
+
+const slack = 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>"
+```
+
+You can also pass rules up front:
+
+```typescript
+const linker = createLinker([
+  {
+    pattern: /\b([A-Z]{2,6}-\d+)\b/g,
+    href: "https://linear.app/fairmint/issue/$1",
+  },
+]);
+```
+
+Formats:
+
+- `slack` → `<url|text>`
+- `markdown` / `discord` → `[text](url)`
+- `plaintext` → raw `url`
+
+`linker.apply(text, options)` is an alias of `linker.linkText(text, options)`.

package/dist/healYaml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Heal common YAML formatting issues from LLM output.
+ *
+ * Fixes applied:
+ * - Strips markdown code fences (```yaml ... ```)
+ * - Quotes plain scalar values that contain colons (prevents "nested mappings" parse errors)
+ */
+export declare function healYaml(yaml: string): string;
+//# sourceMappingURL=healYaml.d.ts.map

package/dist/healYaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healYaml.d.ts","sourceRoot":"","sources":["../src/healYaml.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA0B7C"}

package/dist/healYaml.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.healYaml = healYaml;
+/**
+ * Heal common YAML formatting issues from LLM output.
+ *
+ * Fixes applied:
+ * - Strips markdown code fences (```yaml ... ```)
+ * - Quotes plain scalar values that contain colons (prevents "nested mappings" parse errors)
+ */
+function healYaml(yaml) {
+    let cleaned = yaml.trim();
+    // Strip markdown code fences
+    if (cleaned.startsWith("```")) {
+        const firstNewline = cleaned.indexOf("\n");
+        cleaned = cleaned.slice(firstNewline + 1);
+    }
+    if (cleaned.endsWith("```")) {
+        cleaned = cleaned.slice(0, cleaned.lastIndexOf("```"));
+    }
+    cleaned = cleaned.trim();
+    // Quote plain scalar values that contain `: ` (colon-space).
+    // Pattern matches `key: value` where value is a plain scalar containing a colon.
+    // Skips values already quoted (`"`), single-quoted (`'`), block scalars (`|`, `>`),
+    // or flow collections (`[`, `{`).
+    cleaned = cleaned.replace(/^(\s*\w+:[ \t]+)(?!["'|>[{])(.+:.+)$/gm, (_, prefix, value) => {
+        const escaped = value.replace(/"/g, '\\"');
+        return `${prefix}"${escaped}"`;
+    });
+    return cleaned;
+}
+//# sourceMappingURL=healYaml.js.map

package/dist/healYaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healYaml.js","sourceRoot":"","sources":["../src/healYaml.ts"],"names":[],"mappings":";;AAOA,4BA0BC;AAjCD;;;;;;GAMG;AACH,SAAgB,QAAQ,CAAC,IAAY;IACnC,IAAI,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE1B,6BAA6B;IAC7B,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAEzB,6DAA6D;IAC7D,iFAAiF;IACjF,oFAAoF;IACpF,kCAAkC;IAClC,OAAO,GAAG,OAAO,CAAC,OAAO,CACvB,wCAAwC,EACxC,CAAC,CAAC,EAAE,MAAc,EAAE,KAAa,EAAE,EAAE;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,GAAG,MAAM,IAAI,OAAO,GAAG,CAAC;IACjC,CAAC,CACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export type { BuildTreeOptions } from "./buildFileTree.js";
 export { convertFormat } from "./convertFormat.js";
 export type { TextFormat } from "./convertFormat.js";
 export { formatWithLineNumbers } from "./formatWithLineNumbers.js";
+export { healYaml } from "./healYaml.js";
+export { Linker, createLinker, type LinkRule, type LinkHrefBuilder, type LinkMatchContext, type LinkerApplyOptions, type LinkerPlatform, } from "./linker.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatWithLineNumbers = exports.convertFormat = exports.FILE_TREE_DEFAULTS = exports.buildFileTree = exports.formatDuration = exports.slugify = exports.chunkText = exports.extractPlaceholders = exports.replaceTemplate = exports.formatErrorForLog = exports.formatError = exports.getErrorMessage = void 0;
+exports.createLinker = exports.Linker = exports.healYaml = exports.formatWithLineNumbers = exports.convertFormat = exports.FILE_TREE_DEFAULTS = exports.buildFileTree = exports.formatDuration = exports.slugify = exports.chunkText = exports.extractPlaceholders = exports.replaceTemplate = exports.formatErrorForLog = exports.formatError = exports.getErrorMessage = void 0;
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "getErrorMessage", { enumerable: true, get: function () { return errors_js_1.getErrorMessage; } });
 Object.defineProperty(exports, "formatError", { enumerable: true, get: function () { return errors_js_1.formatError; } });
@@ -21,4 +21,9 @@ var convertFormat_js_1 = require("./convertFormat.js");
 Object.defineProperty(exports, "convertFormat", { enumerable: true, get: function () { return convertFormat_js_1.convertFormat; } });
 var formatWithLineNumbers_js_1 = require("./formatWithLineNumbers.js");
 Object.defineProperty(exports, "formatWithLineNumbers", { enumerable: true, get: function () { return formatWithLineNumbers_js_1.formatWithLineNumbers; } });
+var healYaml_js_1 = require("./healYaml.js");
+Object.defineProperty(exports, "healYaml", { enumerable: true, get: function () { return healYaml_js_1.healYaml; } });
+var linker_js_1 = require("./linker.js");
+Object.defineProperty(exports, "Linker", { enumerable: true, get: function () { return linker_js_1.Linker; } });
+Object.defineProperty(exports, "createLinker", { enumerable: true, get: function () { return linker_js_1.createLinker; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAA8E;AAArE,4GAAA,eAAe,OAAA;AAAE,wGAAA,WAAW,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AACxD,6CAAqE;AAA5D,8GAAA,eAAe,OAAA;AAAE,kHAAA,mBAAmB,OAAA;AAC7C,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAClB,2CAAuC;AAA9B,qGAAA,OAAO,OAAA;AAChB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AACvB,uDAAuE;AAA9D,iHAAA,aAAa,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAE1C,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AAEtB,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAA8E;AAArE,4GAAA,eAAe,OAAA;AAAE,wGAAA,WAAW,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AACxD,6CAAqE;AAA5D,8GAAA,eAAe,OAAA;AAAE,kHAAA,mBAAmB,OAAA;AAC7C,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAClB,2CAAuC;AAA9B,qGAAA,OAAO,OAAA;AAChB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA;AACvB,uDAAuE;AAA9D,iHAAA,aAAa,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAE1C,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AAEtB,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAC9B,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,yCAQqB;AAPnB,mGAAA,MAAM,OAAA;AACN,yGAAA,YAAY,OAAA"}

package/dist/linker.d.ts

@@ -0,0 +1,90 @@
+export type LinkerPlatform = "slack" | "discord" | "markdown" | "plaintext";
+export interface LinkerApplyOptions {
+    /**
+     * Target output format.
+     * Alias: `platform`.
+     * Default: "markdown"
+     */
+    format?: LinkerPlatform;
+    platform?: LinkerPlatform;
+    /**
+     * When true (default), skips linkification inside inline/fenced code spans.
+     */
+    skipCode?: boolean;
+    /**
+     * When true (default), skips linkification inside existing links.
+     */
+    skipExistingLinks?: boolean;
+}
+export interface LinkMatchContext {
+    /** Full regex match text. */
+    match: string;
+    /** Positional capture groups. */
+    groups: string[];
+    /** Rule name assigned at registration time. */
+    ruleName: string;
+    /** Match start index in the original input. */
+    index: number;
+    /** Original input string. */
+    input: string;
+}
+export type LinkHrefBuilder = (context: LinkMatchContext) => string;
+export interface LinkRule {
+    /** Optional stable name for diagnostics and conflict visibility. */
+    name?: string;
+    /** Match pattern. Global matching is enforced automatically. */
+    pattern: RegExp;
+    /**
+     * URL template string (supports $0/$& for full match, $1..$N for groups).
+     * Convenience alias for `toHref`.
+     */
+    href?: string;
+    /**
+     * Either a URL template string or a callback that builds an href from match context.
+     * If both `href` and `toHref` are provided, `toHref` wins.
+     */
+    toHref?: string | LinkHrefBuilder;
+    /**
+     * Higher priority wins for overlapping matches that start at the same index.
+     * Default: 0
+     */
+    priority?: number;
+}
+/**
+ * Stateful linker utility that applies configured rules to text.
+ *
+ * Behavior highlights:
+ * - idempotent by default (skips existing links)
+ * - skips code spans by default
+ * - deterministic overlap resolution (priority, length, then declaration order)
+ */
+export declare class Linker {
+    private readonly rules;
+    constructor(initialRules?: LinkRule[]);
+    private addRule;
+    rule(rule: LinkRule): this;
+    rule(name: string, rule: Omit<LinkRule, "name">): this;
+    custom(pattern: RegExp, toHref: string | LinkHrefBuilder, options?: {
+        name?: string;
+        priority?: number;
+    }): this;
+    linear(workspace: string, options?: {
+        name?: string;
+        priority?: number;
+    }): this;
+    githubPr(repository: string, options?: {
+        name?: string;
+        priority?: number;
+    }): this;
+    apply(input: string, options?: LinkerApplyOptions): string;
+    linkText(input: string, options?: LinkerApplyOptions): string;
+}
+/**
+ * Create a linker with optional initial rules.
+ *
+ * - `href` accepts template substitutions (`$0`/`$&`, `$1..$N`)
+ * - `toHref` callback, when provided, takes precedence over `href`
+ * - omitted `priority` defaults to `0`
+ */
+export declare function createLinker(initialRules?: LinkRule[]): Linker;
+//# sourceMappingURL=linker.d.ts.map

package/dist/linker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linker.d.ts","sourceRoot":"","sources":["../src/linker.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAE5E,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CAAC;AAEpE,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2JD;;;;;;;GAOG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;gBAEhC,YAAY,GAAE,QAAQ,EAAO;IAMzC,OAAO,CAAC,OAAO;IAKf,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,IAAI;IActD,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,eAAe,EAChC,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GACjD,IAAI;IASP,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GACjD,IAAI;IAQP,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GACjD,IAAI;IASP,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM;IAI9D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM;CAqFlE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,YAAY,GAAE,QAAQ,EAAO,GAAG,MAAM,CAElE"}

package/dist/linker.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Linker = void 0;
+exports.createLinker = createLinker;
+function ensureGlobal(pattern) {
+    if (pattern.flags.includes("g")) {
+        return new RegExp(pattern.source, pattern.flags);
+    }
+    return new RegExp(pattern.source, `${pattern.flags}g`);
+}
+function templateToHref(template) {
+    return ({ match, groups }) => template.replace(/\$\$|\$(\d+|&|0)/g, (token, capture) => {
+        if (token === "$$") {
+            return "$";
+        }
+        if (capture === "&" || capture === "0") {
+            return match;
+        }
+        const index = Number(capture);
+        if (!Number.isInteger(index) || index < 0) {
+            return "";
+        }
+        return groups[index - 1] ?? "";
+    });
+}
+function compileRule(rule, index) {
+    const source = rule.toHref ?? rule.href;
+    if (source === undefined) {
+        throw new Error(`Invalid linker rule "${rule.name ?? `rule-${String(index + 1)}`}": missing href/toHref`);
+    }
+    const toHref = typeof source === "string" ? templateToHref(source) : source;
+    return {
+        name: rule.name ?? `rule-${String(index + 1)}`,
+        pattern: ensureGlobal(rule.pattern),
+        priority: rule.priority ?? 0,
+        toHref,
+    };
+}
+function pushSpans(source, pattern, spans) {
+    const matcher = ensureGlobal(pattern);
+    let match = matcher.exec(source);
+    while (match !== null) {
+        if (match[0].length === 0) {
+            matcher.lastIndex += 1;
+            match = matcher.exec(source);
+            continue;
+        }
+        spans.push({
+            start: match.index,
+            end: match.index + match[0].length,
+        });
+        match = matcher.exec(source);
+    }
+}
+function normalizeSpans(spans) {
+    if (spans.length <= 1) {
+        return spans;
+    }
+    spans.sort((a, b) => a.start - b.start || a.end - b.end);
+    const merged = [spans[0]];
+    for (let i = 1; i < spans.length; i++) {
+        const current = spans[i];
+        const previous = merged[merged.length - 1];
+        if (current.start <= previous.end) {
+            previous.end = Math.max(previous.end, current.end);
+            continue;
+        }
+        merged.push(current);
+    }
+    return merged;
+}
+function getProtectedSpans(input, options) {
+    const spans = [];
+    if (options.skipCode) {
+        // Fenced code blocks first, then inline spans.
+        pushSpans(input, /```[\s\S]*?```/g, spans);
+        pushSpans(input, /`[^`\n]+`/g, spans);
+    }
+    if (options.skipExistingLinks) {
+        // Slack and angle-bracket links/mentions.
+        pushSpans(input, /<[^>\n]+>/g, spans);
+        // Markdown links.
+        pushSpans(input, /\[[^\]]+\]\([^)]+\)/g, spans);
+        // Plain URLs.
+        pushSpans(input, /https?:\/\/[^\s<>()]+/g, spans);
+    }
+    return normalizeSpans(spans);
+}
+function overlapsProtected(spans, start, end) {
+    for (const span of spans) {
+        if (span.end <= start) {
+            continue;
+        }
+        if (span.start >= end) {
+            return false;
+        }
+        return true;
+    }
+    return false;
+}
+function formatLink(href, text, platform) {
+    switch (platform) {
+        case "slack":
+            return `<${href}|${text}>`;
+        case "discord":
+        case "markdown":
+            return `[${text}](${href})`;
+        case "plaintext":
+            return href;
+        default:
+            return text;
+    }
+}
+function resolvePlatform(options) {
+    return options.format ?? options.platform ?? "markdown";
+}
+/**
+ * Stateful linker utility that applies configured rules to text.
+ *
+ * Behavior highlights:
+ * - idempotent by default (skips existing links)
+ * - skips code spans by default
+ * - deterministic overlap resolution (priority, length, then declaration order)
+ */
+class Linker {
+    rules = [];
+    constructor(initialRules = []) {
+        for (const rule of initialRules) {
+            this.addRule(rule);
+        }
+    }
+    addRule(rule) {
+        this.rules.push(compileRule(rule, this.rules.length));
+        return this;
+    }
+    rule(ruleOrName, maybeRule) {
+        if (typeof ruleOrName === "string") {
+            if (maybeRule === undefined) {
+                throw new Error(`Missing rule config for "${ruleOrName}"`);
+            }
+            return this.addRule({ ...maybeRule, name: ruleOrName });
+        }
+        return this.addRule(ruleOrName);
+    }
+    custom(pattern, toHref, options = {}) {
+        return this.addRule({
+            name: options.name,
+            pattern,
+            toHref,
+            priority: options.priority,
+        });
+    }
+    linear(workspace, options = {}) {
+        return this.custom(/\b([A-Z]{2,6}-\d+)\b/g, ({ match }) => `https://linear.app/${workspace}/issue/${match}`, { name: options.name ?? "linear", priority: options.priority });
+    }
+    githubPr(repository, options = {}) {
+        return this.custom(/\bPR#(\d+)\b/g, ({ groups }) => `https://github.com/${repository}/pull/${groups[0] ?? ""}`, { name: options.name ?? "github-pr", priority: options.priority });
+    }
+    apply(input, options = {}) {
+        return this.linkText(input, options);
+    }
+    linkText(input, options = {}) {
+        if (this.rules.length === 0 || input === "") {
+            return input;
+        }
+        const platform = resolvePlatform(options);
+        const protectedSpans = getProtectedSpans(input, {
+            skipCode: options.skipCode ?? true,
+            skipExistingLinks: options.skipExistingLinks ?? true,
+        });
+        const candidates = [];
+        for (let ruleOrder = 0; ruleOrder < this.rules.length; ruleOrder++) {
+            const rule = this.rules[ruleOrder];
+            const matcher = rule.pattern;
+            matcher.lastIndex = 0;
+            let match = matcher.exec(input);
+            while (match !== null) {
+                const matchedText = match[0];
+                if (matchedText.length === 0) {
+                    matcher.lastIndex += 1;
+                    match = matcher.exec(input);
+                    continue;
+                }
+                const start = match.index;
+                const end = start + matchedText.length;
+                if (!overlapsProtected(protectedSpans, start, end)) {
+                    candidates.push({
+                        start,
+                        end,
+                        text: matchedText,
+                        groups: match.slice(1),
+                        ruleOrder,
+                        ruleName: rule.name,
+                        priority: rule.priority,
+                    });
+                }
+                match = matcher.exec(input);
+            }
+        }
+        if (candidates.length === 0) {
+            return input;
+        }
+        candidates.sort((a, b) => a.start - b.start ||
+            b.priority - a.priority ||
+            b.end - b.start - (a.end - a.start) ||
+            b.ruleOrder - a.ruleOrder);
+        const selected = [];
+        let cursorEnd = -1;
+        for (const candidate of candidates) {
+            if (candidate.start < cursorEnd) {
+                continue;
+            }
+            selected.push(candidate);
+            cursorEnd = candidate.end;
+        }
+        let output = "";
+        let inputCursor = 0;
+        for (const candidate of selected) {
+            output += input.slice(inputCursor, candidate.start);
+            const rule = this.rules[candidate.ruleOrder];
+            const href = rule.toHref({
+                match: candidate.text,
+                groups: candidate.groups,
+                ruleName: candidate.ruleName,
+                index: candidate.start,
+                input,
+            });
+            if (href === "") {
+                output += candidate.text;
+            }
+            else {
+                output += formatLink(href, candidate.text, platform);
+            }
+            inputCursor = candidate.end;
+        }
+        output += input.slice(inputCursor);
+        return output;
+    }
+}
+exports.Linker = Linker;
+/**
+ * Create a linker with optional initial rules.
+ *
+ * - `href` accepts template substitutions (`$0`/`$&`, `$1..$N`)
+ * - `toHref` callback, when provided, takes precedence over `href`
+ * - omitted `priority` defaults to `0`
+ */
+function createLinker(initialRules = []) {
+    return new Linker(initialRules);
+}
+//# sourceMappingURL=linker.js.map

package/dist/linker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linker.js","sourceRoot":"","sources":["../src/linker.ts"],"names":[],"mappings":"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"}

package/package.json

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