@glubean/scanner 0.2.2 → 0.2.4

package/dist/template-sentinel.js

@@ -0,0 +1,149 @@
+/**
+ * Template-id sentinel helpers — match runtime row ids back to the static
+ * template id emitted by `extractFromSource` for `test.each` / `test.pick`.
+ *
+ * ## Background
+ *
+ * Static parsing produces ONE `ExportMeta` per data-driven export, with an
+ * id that contains `$placeholder` markers — e.g. `test.each(rows)({ id:
+ * "case-$id" })` is extracted as id `"case-$id"`. At runtime, the harness
+ * substitutes the placeholders against each row, emitting concrete ids
+ * like `"case-101"`, `"case-202"`. Downstream consumers (CLI run output,
+ * MCP discover/run, etc.) need to map the concrete event ids back to the
+ * static meta — that's what these helpers do.
+ *
+ * ## Placeholder syntax
+ *
+ * - Marker is `$<word>` — a `$` followed by a JS identifier-start character
+ *   followed by zero or more identifier characters (letters, digits, `_`).
+ * - Each placeholder matches `.*` (greedy) at runtime — there is no
+ *   typed/numeric variant. Multi-placeholder ids (`case-$a-$b`) match
+ *   greedily left-to-right; ambiguous splits are not resolved.
+ * - Matching is **case-insensitive** (the runner's harness id substitution
+ *   may lowercase row keys).
+ *
+ * ## Variant prefix
+ *
+ * VSCode prefixes ids with `each:` / `pick:` for routing. These helpers
+ * strip the prefix before matching so a `each:case-$id` template still
+ * matches a runtime `case-101`.
+ *
+ * ## Limitations
+ *
+ * - Two static templates whose runtime ids could collide (e.g.
+ *   `case-$x` and `case-$y` in the same file) get first-match-wins
+ *   semantics from `findTemplateMatch` — there's no warning.
+ * - The shape `case-$a-$b` matching `case-x-y-z` has multiple valid
+ *   splits; this helper returns *some* match without disambiguating.
+ *   Document your runtime ids to avoid placeholder ambiguity.
+ */
+const TEMPLATE_RE = /\$[A-Za-z_]\w*/g;
+const VARIANT_PREFIX_RE = /^(?:each|pick):/;
+/**
+ * Strip the VSCode variant prefix (`each:` / `pick:`) from an id, leaving
+ * the bare template / concrete id. Returns the input unchanged if no
+ * prefix is present.
+ */
+export function stripVariantPrefix(id) {
+    return id.replace(VARIANT_PREFIX_RE, "");
+}
+/**
+ * Returns `true` if the id contains at least one `$placeholder` marker
+ * (after stripping any variant prefix). Use this to detect "this is a
+ * template, not a concrete id" — concrete runtime ids never contain `$`.
+ */
+export function hasTemplatePlaceholders(id) {
+    TEMPLATE_RE.lastIndex = 0;
+    return TEMPLATE_RE.test(stripVariantPrefix(id));
+}
+/**
+ * Build a regex that matches concrete runtime ids against a template id.
+ * Internal — exposed via `matchesTemplateId` and `findTemplateMatch`. If
+ * the input has no placeholders, returns `undefined` (caller should do an
+ * exact-string compare instead).
+ *
+ * Each `$word` placeholder becomes `.*` (greedy). The regex is anchored
+ * (`^...$`) and case-insensitive (`/i`).
+ */
+function templateIdToRegExp(id) {
+    const normalized = stripVariantPrefix(id);
+    TEMPLATE_RE.lastIndex = 0;
+    if (!TEMPLATE_RE.test(normalized))
+        return undefined;
+    TEMPLATE_RE.lastIndex = 0;
+    let lastIndex = 0;
+    let pattern = "^";
+    let match;
+    while ((match = TEMPLATE_RE.exec(normalized)) !== null) {
+        pattern += escapeRegExp(normalized.slice(lastIndex, match.index));
+        pattern += ".*";
+        lastIndex = match.index + match[0].length;
+    }
+    pattern += escapeRegExp(normalized.slice(lastIndex));
+    pattern += "$";
+    return new RegExp(pattern, "i");
+}
+/**
+ * Returns `true` if `concreteId` is a substituted instance of `templateId`.
+ *
+ * Both inputs are normalised (variant prefix stripped, lowercased before
+ * exact compare). For `test.each([{id: "alpha"}])({ id: "case-$id" })`
+ * the runtime emits `"case-alpha"` — `matchesTemplateId("case-$id",
+ * "case-alpha")` returns `true`.
+ *
+ * Exact-id ties pass through unchanged: `matchesTemplateId("health",
+ * "health")` is `true` even though `"health"` has no placeholders.
+ */
+export function matchesTemplateId(templateId, concreteId) {
+    const normalizedTemplate = stripVariantPrefix(templateId).toLowerCase();
+    const normalizedConcrete = stripVariantPrefix(concreteId).toLowerCase();
+    if (normalizedTemplate === normalizedConcrete)
+        return true;
+    return templateIdToRegExp(templateId)?.test(stripVariantPrefix(concreteId)) ?? false;
+}
+/**
+ * Permissive filter match — used by CLI / MCP `--filter <id>` so the user
+ * can target a row by its concrete id while only the template appears in
+ * static meta. Acceptance order:
+ *   1. Empty filter → match (caller wants everything).
+ *   2. Filter substring of the template (template `case-$id` matches filter
+ *      `case`).
+ *   3. Filter is a substituted instance (template `case-$id`, filter
+ *      `case-101`).
+ *   4. Filter starts with the template's literal prefix (template
+ *      `case-$id`, filter `case-101-extra`).
+ *
+ * Slightly more permissive than `matchesTemplateId` — designed for human
+ * `--filter` input, not strict harness event matching.
+ */
+export function matchesTemplateFilter(templateId, filter) {
+    const normalizedFilter = stripVariantPrefix(filter).toLowerCase().trim();
+    if (!normalizedFilter)
+        return true;
+    const normalizedTemplate = stripVariantPrefix(templateId).toLowerCase();
+    if (normalizedTemplate.includes(normalizedFilter))
+        return true;
+    if (matchesTemplateId(templateId, normalizedFilter))
+        return true;
+    const prefix = normalizedTemplate.split(TEMPLATE_RE)[0] ?? "";
+    return prefix.length > 0 && normalizedFilter.startsWith(prefix);
+}
+/**
+ * Find the static meta entry whose id matches `concreteId`. Prefers exact
+ * matches over template matches — so if both `case-$id` and `case-101`
+ * exist statically (rare but possible), the concrete row event for
+ * `case-101` resolves to the concrete entry, not the template.
+ *
+ * If multiple template entries could match (e.g. two overlapping
+ * placeholders), returns the first one in array order — no warning. Avoid
+ * collisions by namespacing template ids per file.
+ */
+export function findTemplateMatch(items, concreteId) {
+    const normalizedConcrete = stripVariantPrefix(concreteId).toLowerCase();
+    const exact = items.find((item) => stripVariantPrefix(item.id).toLowerCase() === normalizedConcrete);
+    return exact ?? items.find((item) => matchesTemplateId(item.id, concreteId));
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=template-sentinel.js.map

package/dist/template-sentinel.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glubean/scanner",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "exports": {
     ".": {