@spintax/core 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 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.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.
+
+### Changed
+
+- **Cross-engine parity is now machine-verified.** The shared golden corpus was executed against
+  the actual PHP Spintax plugin engine (via the new `packages/conformance/php` runner) — 88 cases,
+  no divergence. Upgraded the README claim from "TS side; PHP execution pending" to parity-verified
+  against both engines.
+
 ## 0.1.1 — 2026-07-08
 
 Docs + metadata. First release published from CI with **provenance** (npm Trusted Publishing).

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)
@@ -15,15 +14,16 @@ parse, render, validate, extract, analyze, and neutralize spintax templates.
 
 - **Zero runtime dependencies.** Runs unchanged on Cloudflare Workers, Node 18+, and in the browser.
 - **ESM-first, dual CJS.** Ships `.d.ts` types for both.
-- **Built to the [Spintax WordPress plugin](https://wordpress.org/plugins/spintax/)'s behavior
-  contract** via a shared golden corpus — an *independent* TypeScript implementation, not a
-  line-by-line port. The TS suite passes the full deterministic corpus; cross-engine execution
-  of that corpus by the PHP plugin is pending.
+- **Parity-verified against the [Spintax WordPress plugin](https://wordpress.org/plugins/spintax/).**
+  An *independent* TypeScript implementation (not a line-by-line port) held to the plugin's behavior
+  contract by a shared golden corpus — the **same** fixtures pass against both this engine and the
+  PHP plugin (deterministic verdicts, plural buckets, conditionals, `#set` collapse, post-process),
+  with no divergence.
 - **MIT** licensed.
 
-> **Status: `0.1.0`** — first public release. Feature-complete; passes the full deterministic
-> golden corpus (encoding the plugin's contract, TS side); the §9.2 API is proven by a reference
-> Cloudflare Worker (`examples/worker`).
+> **Status: released & stable.** Feature-complete — parse / render / validate / extract / analyze /
+> neutralize. The deterministic golden corpus passes against **both** this engine and the PHP
+> plugin, and the §9.2 API is proven by a reference Cloudflare Worker (`examples/worker`).
 
 ## Install
 
@@ -130,6 +130,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;