@spintax/core 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 All notable changes to `@spintax/core` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.1.4 — 2026-07-13
+
+A post-process bug fix (hit in production) plus docs. No API change.
+
+### Fixed
+
+- **`postProcess` no longer mangles `mailto:` / `tel:` URIs.** They carry no `//` authority,
+  so the URL shield missed them; the email shield then carved the address out from under the
+  prefix, and the "space after a colon" rule split the leftover into a malformed
+  `mailto: contact@example.com` href. They are now shielded as whole tokens (with the same
+  trailing-punctuation handling as URLs) before the email/domain passes. Mirrored into the PHP
+  engine and covered by 4 golden-corpus fixtures, so the post-process parity contract holds
+  in both engines. Reported in [#41](https://github.com/investblog/spintax-js/issues/41).
+
+### Changed
+
+- Docs: a **Use Cases** section (cold email, notifications, chatbots, A/B copy, programmatic
+  SEO, spinning LLM-drafted templates locally) and the N-variants recipe — call `render` N
+  times with different seeds — with the caveat that distinct seeds are *independent draws, not
+  distinct results*, so a low-cardinality template will repeat. Batching stays a host concern.
+- npm keywords broadened (`text-spinner`, `email-template`, `placeholders`, `variables`,
+  `conditionals`) to match how people actually search for this.
+
+## 0.1.3 — 2026-07-08
+
+Precise diagnostic positions. Backward-compatible — `validate()` verdicts (pass/fail),
+codes, and severities are unchanged (still not parity-gated per §3.1); only the
+best-effort position fields are improved. No render/parse behavior change.
+
+### Added
+
+- **`validate()` diagnostics now carry accurate `line`/`column` for every code**, not just
+  brackets. Previously `plural.*`, `permutation.*`, `set.malformed`, and `include.*` reported
+  a line with `column: 1`, and `variable.*` had no position at all (defaulted to `1:1`). All
+  now point at the offending token.
+- **`endLine`/`endColumn`** are populated so a consumer can underline the exact span (e.g. the
+  whole `%name%` reference or `{plural …}` block).
+- **Structured `data`** on diagnostics: `variable.undefined` → `{ name }`; `plural.arity` →
+  `{ expected, got }`; `permutation.*` → `{ key }` / `{ value }`; `bracket.*` → `{ bracket }` /
+  `{ open, close }`; `include.unknown-target` → `{ target }`. Lets a bot/editor build UI without
+  parsing the (non-parity-gated) `message`.
+- `PluralBlock.end` (internal) — exclusive end offset, so validation can span the full block.
+
+### Notes
+
+- `variable.undefined` still reports **once per unique name**, now anchored at its first
+  occurrence. Consumers that want to highlight every occurrence can expand via `data.name`.
+
 ## 0.1.2 — 2026-07-08
 
 Docs. No engine or API changes.

package/README.md

@@ -1,7 +1,6 @@
 # @spintax/core
 
 [![npm](https://img.shields.io/npm/v/@spintax/core.svg)](https://www.npmjs.com/package/@spintax/core)
-[![npm downloads](https://img.shields.io/npm/dm/@spintax/core.svg)](https://www.npmjs.com/package/@spintax/core)
 [![CI](https://github.com/investblog/spintax-js/actions/workflows/ci.yml/badge.svg)](https://github.com/investblog/spintax-js/actions/workflows/ci.yml)
 [![types](https://img.shields.io/npm/types/@spintax/core.svg)](https://www.npmjs.com/package/@spintax/core)
 [![license](https://img.shields.io/npm/l/@spintax/core.svg)](https://github.com/investblog/spintax-js/blob/main/LICENSE)
@@ -44,6 +43,33 @@ validate('{a|b');          // → [{ severity: 'error', code: 'bracket.unclosed'
 extract('%title% {?promo?Sale}'); // → { refs: ['title', 'promo'], sets: [], includes: [] }
 ```
 
+## Use cases
+
+Anywhere one message has to go out many times without reading like a form letter:
+
+- **Cold email & outreach** — one template, a distinct body per recipient, personalized through `context`.
+- **SMS / push / notifications** — deterministic output in a few kilobytes, no API call per send.
+- **Chatbots & agents** — vary canned replies so a bot doesn't repeat itself verbatim.
+- **A/B and multivariate testing** — enumerate copy variants in the template instead of in application code.
+- **Programmatic SEO / content generation** — thousands of pages from one authored source.
+- **LLM output at scale** — have a model draft the template once, then spin it locally, forever, for free.
+
+The core renders a **single** string per call — batching is a host concern. To emit N variants, call
+`render` N times with different seeds; a seeded call is reproducible, so any variant can be
+regenerated later from its seed alone:
+
+```ts
+const template = '{Hi|Hello|Hey} %name%, {quick|short|small} question about {pricing|billing}';
+const variants = [1, 2, 3].map((seed) => render(template, { context: { name: 'Ada' }, seed }));
+// → [ 'Hello Ada, quick question about billing',
+//     'Hey Ada, quick question about pricing',
+//     'Hey Ada, quick question about pricing' ]   ← same as seed 2; see the caveat below
+```
+
+Distinct seeds are **independent draws, not distinct results** — like any sampling they can repeat,
+and the fewer combinations a template has, the more often they will. If you need N *unique* variants,
+dedupe in the host and cap the retries: a template may simply not have N combinations to give.
+
 ## Spintax syntax
 
 | Construct | Example | Meaning |
@@ -131,6 +157,7 @@ plural buckets, conditional truthiness, `#set` collapse, post-process output) is
 ## Links
 
 - 📦 npm — [`@spintax/core`](https://www.npmjs.com/package/@spintax/core)
+- 🤖 Try it — [@spintaxnetbot](https://t.me/spintaxnetbot) (Telegram: validate + preview + AI `/draft`)
 - 🧩 Source — [investblog/spintax-js](https://github.com/investblog/spintax-js)
 - 🌐 Product — [spintax.net](https://spintax.net)
 - 🏠 Maintainer — [301.st](https://301.st)

package/dist/index.cjs

@@ -330,7 +330,7 @@ function findPluralBlocks(text) {
       i = j + 1;
       continue;
     }
-    blocks.push({ start, countSlot: inner.slice(0, colon), formsRaw: inner.slice(colon + 1) });
+    blocks.push({ start, end: j + 1, countSlot: inner.slice(0, colon), formsRaw: inner.slice(colon + 1) });
     i = j + 1;
   }
   return blocks;
@@ -381,11 +381,28 @@ function validateTemplate(src, opts = {}) {
   }
   return diagnostics;
 }
-function err(code, message, line = 1, column = 1) {
-  return { severity: "error", code, message, line, column };
+function err(code, message, pos) {
+  return { severity: "error", code, message, ...pos };
 }
-function warn(code, message, line = 1, column = 1) {
-  return { severity: "warning", code, message, line, column };
+function warn(code, message, pos) {
+  return { severity: "warning", code, message, ...pos };
+}
+function offsetToLineCol(text, offset) {
+  let line = 1;
+  let lineStart = 0;
+  const end = Math.min(Math.max(offset, 0), text.length);
+  for (let i = 0; i < end; i += 1) {
+    if (text.charAt(i) === "\n") {
+      line += 1;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: end - lineStart + 1 };
+}
+function span(text, offset, length) {
+  const s = offsetToLineCol(text, offset);
+  const e = offsetToLineCol(text, offset + length);
+  return { line: s.line, column: s.column, endLine: e.line, endColumn: e.column };
 }
 function checkBrackets(text, out) {
   const close = { "{": "}", "[": "]" };
@@ -403,15 +420,15 @@ function checkBrackets(text, out) {
     } else if (ch === "}" || ch === "]") {
       const top = stack.pop();
       if (top === void 0) {
-        out.push(err("bracket.unexpected-closing", `Unexpected closing '${ch}'.`, line, column));
+        out.push(err("bracket.unexpected-closing", `Unexpected closing '${ch}'.`, { line, column, endLine: line, endColumn: column + 1, data: { bracket: ch } }));
       } else if (top.expect !== ch) {
-        out.push(err("bracket.mismatched", `'${top.char}' closed by '${ch}'.`, line, column));
+        out.push(err("bracket.mismatched", `'${top.char}' closed by '${ch}'.`, { line, column, endLine: line, endColumn: column + 1, data: { open: top.char, close: ch } }));
       }
     }
     column += 1;
   }
   for (const unclosed of stack) {
-    out.push(err("bracket.unclosed", `Unclosed '${unclosed.char}'.`, unclosed.line, unclosed.column));
+    out.push(err("bracket.unclosed", `Unclosed '${unclosed.char}'.`, { line: unclosed.line, column: unclosed.column, endLine: unclosed.line, endColumn: unclosed.column + 1, data: { bracket: unclosed.char } }));
   }
 }
 function checkSetDirectives(text, out) {
@@ -420,7 +437,9 @@ function checkSetDirectives(text, out) {
     const trimmed = lineText.replace(/^[ \t]+/, "");
     if (!trimmed.startsWith("#set ") && !trimmed.startsWith("#set	")) return;
     if (!/^#set\s+%(\w+)%\s*=\s*(.+)$/u.test(trimmed)) {
-      out.push(err("set.malformed", "Malformed #set. Expected: #set %name% = value", idx + 1));
+      const column = lineText.length - trimmed.length + 1;
+      const line = idx + 1;
+      out.push(err("set.malformed", "Malformed #set. Expected: #set %name% = value", { line, column, endLine: line, endColumn: lineText.length + 1 }));
     }
   });
 }
@@ -428,20 +447,32 @@ function checkPermutationConfigs(text, out) {
   for (const m of text.matchAll(/\[<([^>]*?)>/gu)) {
     const configStr = m[1] ?? "";
     if (!/\w+\s*=/.test(configStr)) continue;
-    const line = countLines(text, m.index ?? 0);
+    const configBase = (m.index ?? 0) + 2;
     for (const km of configStr.matchAll(/(\w+)\s*=/gu)) {
       const key = (km[1] ?? "").toLowerCase();
       if (!KNOWN_CONFIG_KEYS.has(key)) {
-        out.push(err("permutation.unknown-key", `Unknown permutation config key: '${km[1]}'.`, line));
+        out.push(err(
+          "permutation.unknown-key",
+          `Unknown permutation config key: '${km[1]}'.`,
+          { ...span(text, configBase + (km.index ?? 0), (km[1] ?? "").length), data: { key: km[1] } }
+        ));
       }
     }
     const min = /minsize\s*=\s*([^;>\s]+)/i.exec(configStr);
     if (min && !/^\d+$/.test(min[1] ?? "")) {
-      out.push(err("permutation.minsize-not-integer", `minsize must be a positive integer, got '${min[1]}'.`, line));
+      out.push(err(
+        "permutation.minsize-not-integer",
+        `minsize must be a positive integer, got '${min[1]}'.`,
+        { ...span(text, configBase + min.index, min[0].length), data: { value: min[1] } }
+      ));
     }
     const max = /maxsize\s*=\s*([^;>\s]+)/i.exec(configStr);
     if (max && !/^\d+$/.test(max[1] ?? "")) {
-      out.push(err("permutation.maxsize-not-integer", `maxsize must be a positive integer, got '${max[1]}'.`, line));
+      out.push(err(
+        "permutation.maxsize-not-integer",
+        `maxsize must be a positive integer, got '${max[1]}'.`,
+        { ...span(text, configBase + max.index, max[0].length), data: { value: max[1] } }
+      ));
     }
   }
 }
@@ -449,15 +480,19 @@ function checkPlurals(text, locale, out) {
   const base = locale && locale !== "" ? normalizeBaseLang(locale) : "";
   const arity = base !== "" ? pluralArity(base) : 0;
   for (const block of findPluralBlocks(text)) {
-    const line = countLines(text, block.start);
+    const at = span(text, block.start, block.end - block.start);
     if (/[{}[\]]/.test(block.formsRaw)) {
-      out.push(err("plural.nested-brackets", "{plural ...}: forms must not contain nested spintax brackets.", line));
+      out.push(err("plural.nested-brackets", "{plural ...}: forms must not contain nested spintax brackets.", at));
       continue;
     }
     if (arity > 0) {
       const count = block.formsRaw.split("|").length;
       if (count !== arity) {
-        out.push(err("plural.arity", `{plural ...}: expected ${arity} forms, got ${count}.`, line));
+        out.push(err(
+          "plural.arity",
+          `{plural ...}: expected ${arity} forms, got ${count}.`,
+          { ...at, data: { expected: arity, got: count } }
+        ));
       }
     }
   }
@@ -465,37 +500,49 @@ function checkPlurals(text, locale, out) {
 function checkVariableReferences(text, known, out) {
   const knownSet = new Set((known ?? []).map((n) => n.toLowerCase()));
   const defs = /* @__PURE__ */ new Map();
+  const defPos = /* @__PURE__ */ new Map();
   for (const m of text.matchAll(/^[ \t]*#set[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)$/gmu)) {
-    defs.set((m[1] ?? "").toLowerCase(), m[2] ?? "");
+    const name = (m[1] ?? "").toLowerCase();
+    defs.set(name, m[2] ?? "");
+    const nameOffset = (m.index ?? 0) + m[0].indexOf("%");
+    defPos.set(name, span(text, nameOffset, name.length + 2));
   }
+  const somewhere = { line: 1, column: 1 };
   for (const [name, value] of defs) {
     if (value.toLowerCase().includes(`%${name}%`)) {
-      out.push(err("variable.self-reference", `Variable '${name}' references itself.`));
+      out.push(err("variable.self-reference", `Variable '${name}' references itself.`, defPos.get(name) ?? somewhere));
     }
   }
   for (const name of defs.keys()) {
-    detectCycle(name, defs, [name], out);
+    detectCycle(name, defs, [name], defPos.get(name) ?? somewhere, out);
   }
-  const body = text.replace(/^[ \t]*#set[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, "");
-  const refs = /* @__PURE__ */ new Set();
-  for (const m of body.matchAll(/%(\w+)%/gu)) refs.add((m[1] ?? "").toLowerCase());
-  for (const m of body.matchAll(/\{\?!?([A-Za-z_]\w*)\?/gu)) refs.add((m[1] ?? "").toLowerCase());
-  for (const ref of refs) {
-    if (!defs.has(ref) && !knownSet.has(ref)) {
-      out.push(warn("variable.undefined", `Variable '${ref}' is not defined \u2014 may be a runtime variable.`));
-    }
+  const body = text.replace(/^[ \t]*#set[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, (m) => m.replace(/[^\n]/g, " "));
+  const seen = /* @__PURE__ */ new Set();
+  const undefinedAt = (name, offset, length) => {
+    const key = name.toLowerCase();
+    if (defs.has(key) || knownSet.has(key) || seen.has(key)) return;
+    seen.add(key);
+    out.push(warn(
+      "variable.undefined",
+      `Variable '${name}' is not defined \u2014 may be a runtime variable.`,
+      { ...span(text, offset, length), data: { name } }
+    ));
+  };
+  for (const m of body.matchAll(/%(\w+)%/gu)) undefinedAt(m[1] ?? "", m.index ?? 0, m[0].length);
+  for (const m of body.matchAll(/\{\?!?([A-Za-z_]\w*)\?/gu)) {
+    undefinedAt(m[1] ?? "", (m.index ?? 0) + m[0].indexOf(m[1] ?? ""), (m[1] ?? "").length);
   }
 }
-function detectCycle(current, defs, visited, out) {
+function detectCycle(current, defs, visited, rootPos, out) {
   const value = defs.get(current) ?? "";
   for (const m of value.matchAll(/%(\w+)%/gu)) {
     const ref = (m[1] ?? "").toLowerCase();
     if (ref === current) continue;
     if (visited.includes(ref)) {
-      out.push(err("variable.circular-reference", `Circular variable reference: ${[...visited, ref].join(" \u2192 ")}.`));
+      out.push(err("variable.circular-reference", `Circular variable reference: ${[...visited, ref].join(" \u2192 ")}.`, rootPos));
       return;
     }
-    if (defs.has(ref)) detectCycle(ref, defs, [...visited, ref], out);
+    if (defs.has(ref)) detectCycle(ref, defs, [...visited, ref], rootPos, out);
   }
 }
 function checkIncludeTargets(text, known, out) {
@@ -504,19 +551,15 @@ function checkIncludeTargets(text, known, out) {
   for (const m of text.matchAll(INCLUDE_RE)) {
     const ref = m[1] ?? "";
     if (!set.has(ref)) {
-      out.push(
-        err("include.unknown-target", `#include target '${ref}' does not match any known template.`, countLines(text, m.index ?? 0))
-      );
+      const refOffset = (m.index ?? 0) + m[0].indexOf('"') + 1;
+      out.push(err(
+        "include.unknown-target",
+        `#include target '${ref}' does not match any known template.`,
+        { ...span(text, refOffset, ref.length), data: { target: ref } }
+      ));
     }
   }
 }
-function countLines(text, offset) {
-  let n = 1;
-  for (let i = 0; i < offset && i < text.length; i += 1) {
-    if (text.charAt(i) === "\n") n += 1;
-  }
-  return n;
-}
 
 // src/internal/extract.ts
 var SET_DEF_RE = /^[ \t]*#set[ \t]+%(\w+)%[ \t]*=/gmu;
@@ -863,6 +906,7 @@ var WS = " \\t\\r\\n\\f\\x0B";
 var S = `[${WS}]`;
 var DOMAIN_PART = "(?:(?:(?:xn--)?[\\p{L}\\p{N}]+(?:-[\\p{L}\\p{N}]+)*)\\.)+(?:xn--[a-z0-9\\-]{2,59}|[\\p{L}][\\p{L}\\p{N}-]{1,62})";
 var URL_RE = new RegExp(`(?:https?|ftp):\\/\\/[^${WS}<>"')\\]]+`, "giu");
+var MAILTEL_RE = new RegExp(`(?:mailto|tel):[^${WS}<>"')\\]]+`, "giu");
 var EMAIL_RE = new RegExp(`[a-z0-9._%+\\-]+@${DOMAIN_PART}\\b`, "giu");
 var DOMAIN_RE = new RegExp(`\\b${DOMAIN_PART}\\b`, "giu");
 var DECIMAL_RE = /\b\d+\.\d+\b/gu;
@@ -897,6 +941,7 @@ function postProcess(input) {
   };
   let text = input;
   text = text.replace(URL_RE, (m) => storeWithTrailingPunct(m, "URL"));
+  text = text.replace(MAILTEL_RE, (m) => storeWithTrailingPunct(m, "URI"));
   text = text.replace(EMAIL_RE, (m) => store(m, "EMAIL"));
   text = text.replace(DOMAIN_RE, (m) => store(m, "DOM"));
   text = text.replace(DECIMAL_RE, (m) => store(m, "NUM"));