@nac3/forge-cli 0.2.0-alpha.1

package/dist/migrate/js-template-walker.js

@@ -0,0 +1,644 @@
+/**
+ * Yujin Forge -- JS-template walker.
+ *
+ * Many real-world apps render HTML via JS string templates rather
+ * than authoring it in static HTML. Common patterns:
+ *
+ *   var html = '<button class="cta save" aria-label="Save invoice '
+ *            + escapeHtml(inv.id) + '">Save</button>';
+ *
+ *   var html = `<tr data-id="${row.id}">
+ *                 <td>${row.name}</td>
+ *                 <td><button class="del" aria-label="Delete row ${row.id}">Delete</button></td>
+ *               </tr>`;
+ *
+ * The HTML walker (html-walker.ts) operates on parsed DOM trees and
+ * misses these because the elements only materialise at runtime when
+ * the JS executes. This walker scans .js / .ts source as text, finds
+ * HTML opening tags inside string literals (single-quote concat OR
+ * template literal), classifies each one, identifies the *dynamic
+ * id expression* (typically the JS expression that wraps the row's
+ * unique identifier and appears inside the aria-label), and rewrites
+ * the source by inserting `data-nac-id=` / `data-nac-role=` /
+ * `data-nac-action=` attributes -- with the same JS expression
+ * woven into the nac_id so each rendered row gets a unique id.
+ *
+ * The walker is deliberately scoped to recognise patterns we see in
+ * production codebases. Patterns we cannot decode (heavily computed
+ * tags, dynamic role assignment, JSX in .js without typescript
+ * tooling) are flagged low-confidence and reported -- never
+ * silently mis-decorated.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { inferVerb } from './verb-inference.js';
+import { parse } from 'node-html-parser';
+/** Convert UTF-16 offset to {line, col} (both 1-based). */
+function offsetToLineCol(source, off) {
+    let line = 1, col = 1;
+    for (let i = 0; i < off && i < source.length; i++) {
+        if (source.charCodeAt(i) === 10) {
+            line++;
+            col = 1;
+        }
+        else
+            col++;
+    }
+    return { line, col };
+}
+const ELIGIBLE_TAGS = new Set([
+    'button', 'input', 'textarea', 'select', 'a', 'form',
+    'main', 'section', 'aside', 'nav', 'article', 'header', 'footer',
+]);
+/**
+ * Find every <tag ...> opening that appears inside a JS string
+ * literal (single, double, or template). Returns the structural
+ * extraction with whatever we could parse statically.
+ *
+ * The matcher is tolerant: it does not require a closing tag in the
+ * same string (real templates often split a single element across
+ * many concatenations). It looks at the opening tag + the immediate
+ * concatenation neighbourhood for the dynamic-id expression.
+ */
+export function scanJsTemplates(filePath, source) {
+    const candidates = [];
+    /* Regex: opening tag inside ANY string-quote context. We find the
+       tag via opening `<word` and then capture attributes up to `>`. */
+    /* tag: alpha, 1+; attrs: anything up to a closing `>` that is not
+       inside a string. We accept multi-line tags (the `s` flag). */
+    const tagRe = /<([a-zA-Z][a-zA-Z0-9]*)(\s[^>]*?)?(\/?)\s*>/gs;
+    /* JS string literal detector: we want to skip tags that appear in
+       code (outside strings) and only consider those inside a quote.
+       Heuristic: walk back to the nearest UNCLOSED quote on the same
+       enclosed scope. We use a lightweight state machine. */
+    const inString = computeStringScopes(source);
+    let m;
+    while ((m = tagRe.exec(source)) !== null) {
+        const offset = m.index;
+        const stringScope = inString[offset];
+        if (!stringScope)
+            continue;
+        const tagName = m[1] ?? '';
+        if (!tagName)
+            continue;
+        const tag = tagName.toLowerCase();
+        if (!ELIGIBLE_TAGS.has(tag))
+            continue;
+        const attrsRaw = (m[2] ?? '');
+        const openingTagText = m[0];
+        /* Skip elements that ALREADY carry data-nac-id literal in the
+           attrs region of THIS opening tag. We check the literal text;
+           interpolated decoration is rare. */
+        const alreadyDecorated = /data-nac-id\s*=/.test(attrsRaw);
+        /* Skip <a> without onclick / role=button -- bare navigation. */
+        if (tag === 'a' && !/onclick=|role\s*=\s*['"]button['"]/.test(attrsRaw))
+            continue;
+        /* Skip <input type="hidden"> */
+        if (tag === 'input' && /type\s*=\s*['"]hidden['"]/.test(attrsRaw))
+            continue;
+        const role = classifyRole(tag, attrsRaw);
+        const ariaStatic = extractStaticAriaLabel(attrsRaw);
+        const textStatic = extractStaticText(source, offset, openingTagText, m[3] === '/');
+        const verb = inferVerbFromAttrs(role, tag, ariaStatic, textStatic, attrsRaw);
+        const dynamicIdExpr = detectDynamicIdExpr(source, offset, openingTagText);
+        const plugin = derivePluginSlug(filePath, source, offset);
+        const proposedId = buildProposedIdTemplate(plugin, role, verb, tag, dynamicIdExpr, ariaStatic, textStatic);
+        const conf = computeConfidence({
+            role, verb, ariaStatic, textStatic, dynamicIdExpr,
+        });
+        const { line } = offsetToLineCol(source, offset);
+        const fp = computeFingerprint(filePath, tag, role, ariaStatic, textStatic, dynamicIdExpr);
+        candidates.push({
+            fingerprint: fp,
+            filePath,
+            offset,
+            line,
+            tag,
+            static_attrs: attrsRaw,
+            dynamic_id_expr: dynamicIdExpr,
+            role,
+            verb,
+            already_decorated: alreadyDecorated,
+            plugin,
+            proposed_id_template: proposedId,
+            confidence: conf,
+            text_static: textStatic,
+            aria_label_static: ariaStatic,
+            opening_tag_text: openingTagText,
+        });
+    }
+    return { filePath, candidates };
+}
+/* ----------------------------------------------------------------
+   JS string-scope detection.
+
+   We classify every character offset as "inside a string?" yes/no.
+   The marker is conservative: we only flag clear string regions
+   (single / double / backtick quoted) and treat anything we are
+   unsure about as NOT a string. The tradeoff is occasional missed
+   decoration vs accidentally rewriting non-string code; we always
+   prefer the safe side.
+
+   Caveat: template literals can contain ${expr} which is JS code.
+   We treat the entire template literal as a string scope for the
+   purpose of "is this a string?" -- the resulting HTML attr
+   injection inside a ${} would be syntactically wrong, but in
+   practice template literals carry the entire HTML in the literal
+   region, not in ${}.
+   ---------------------------------------------------------------- */
+function computeStringScopes(source) {
+    const len = source.length;
+    const inStr = new Uint8Array(len);
+    /* Track the last non-whitespace, non-comment token to disambiguate
+       `/` as division vs regex literal. After certain tokens (= ( , [
+       { ; ! & | ? : return etc.) a `/` starts a regex; after others
+       (identifier, ) ] number, etc.) it's division. */
+    let lastSignificant = '';
+    const regexPreceders = new Set([
+        '', '=', '(', ',', '[', '{', ';', '!', '&', '|', '?', ':', '+',
+        '-', '*', '/', '%', '<', '>', '~', '^',
+        'return', 'typeof', 'delete', 'void', 'in', 'of', 'new', 'throw',
+        'instanceof', 'yield', 'await', 'else', 'do', 'case',
+    ]);
+    let i = 0;
+    while (i < len) {
+        const c = source.charCodeAt(i);
+        /* Skip single-line comments */
+        if (c === 47 /* / */ && i + 1 < len && source.charCodeAt(i + 1) === 47) {
+            while (i < len && source.charCodeAt(i) !== 10)
+                i++;
+            continue;
+        }
+        /* Skip block comments */
+        if (c === 47 && i + 1 < len && source.charCodeAt(i + 1) === 42) {
+            i += 2;
+            while (i < len - 1 && !(source.charCodeAt(i) === 42 && source.charCodeAt(i + 1) === 47))
+                i++;
+            i += 2;
+            continue;
+        }
+        /* Regex literal? `/` not part of `//` or `/*` -- already
+           handled above. Disambiguate by the last significant token. */
+        if (c === 47 && regexPreceders.has(lastSignificant)) {
+            /* Walk forward until the closing `/` (not in a char class,
+               not escaped). */
+            i++;
+            let inClass = false;
+            while (i < len) {
+                const cc = source.charCodeAt(i);
+                if (cc === 92 /* \ */) {
+                    i += 2;
+                    continue;
+                }
+                if (cc === 91 /* [ */) {
+                    inClass = true;
+                    i++;
+                    continue;
+                }
+                if (cc === 93 /* ] */) {
+                    inClass = false;
+                    i++;
+                    continue;
+                }
+                if (cc === 47 && !inClass) {
+                    i++;
+                    break;
+                }
+                if (cc === 10 /* newline */)
+                    break; /* regex can't span lines */
+                i++;
+            }
+            /* Optional flags */
+            while (i < len && /[gimsuy]/.test(source[i] || ''))
+                i++;
+            lastSignificant = '/regex/';
+            continue;
+        }
+        /* String quote? */
+        if (c === 34 /* " */ || c === 39 /* ' */ || c === 96 /* ` */) {
+            const quote = c;
+            const start = i;
+            i++;
+            while (i < len) {
+                const cc = source.charCodeAt(i);
+                if (cc === 92 /* \ */) {
+                    i += 2;
+                    continue;
+                }
+                if (cc === quote) {
+                    i++;
+                    break;
+                }
+                if (quote === 96 && cc === 36 /* $ */ && i + 1 < len && source.charCodeAt(i + 1) === 123 /* { */) {
+                    let depth = 1;
+                    i += 2;
+                    while (i < len && depth > 0) {
+                        const cd = source.charCodeAt(i);
+                        if (cd === 123)
+                            depth++;
+                        else if (cd === 125)
+                            depth--;
+                        i++;
+                    }
+                    continue;
+                }
+                i++;
+            }
+            for (let k = start; k < i; k++)
+                inStr[k] = 1;
+            lastSignificant = 'string';
+            continue;
+        }
+        /* Track the last significant token for regex disambiguation.
+           Whitespace + newlines do NOT reset it. */
+        if (c > 32) {
+            /* Identifier or keyword? Walk to capture full word. */
+            if ((c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c === 95 || c === 36) {
+                let j = i;
+                while (j < len) {
+                    const cj = source.charCodeAt(j);
+                    if ((cj >= 65 && cj <= 90) || (cj >= 97 && cj <= 122) ||
+                        (cj >= 48 && cj <= 57) || cj === 95 || cj === 36)
+                        j++;
+                    else
+                        break;
+                }
+                lastSignificant = source.slice(i, j);
+                i = j;
+                continue;
+            }
+            /* Number? */
+            if (c >= 48 && c <= 57) {
+                while (i < len) {
+                    const ci = source.charCodeAt(i);
+                    if ((ci >= 48 && ci <= 57) || ci === 46)
+                        i++;
+                    else
+                        break;
+                }
+                lastSignificant = '0';
+                continue;
+            }
+            /* Punctuation: record the single char. */
+            lastSignificant = source[i] || '';
+        }
+        i++;
+    }
+    return inStr;
+}
+/* ---- classification + inference helpers ---- */
+function classifyRole(tag, attrsRaw) {
+    if (tag === 'input' || tag === 'textarea' || tag === 'select')
+        return 'field';
+    if (['main', 'section', 'aside', 'nav', 'article', 'header', 'footer', 'form'].includes(tag))
+        return 'region';
+    const role = /(?:^|\s)role\s*=\s*["']([^"']+)["']/.exec(attrsRaw)?.[1]?.toLowerCase();
+    if (role === 'tab')
+        return 'tab';
+    if (role === 'option')
+        return 'option';
+    return 'action';
+}
+function extractStaticAriaLabel(attrsRaw) {
+    /* Grab the aria-label value as a literal string up to the first
+       interpolation marker. We accept aria-label="..." and
+       aria-label='...'. */
+    const m = /aria-label\s*=\s*(["'])((?:\\.|(?!\1).)*)\1/.exec(attrsRaw);
+    if (!m || typeof m[2] !== 'string')
+        return null;
+    return m[2].trim() || null;
+}
+function extractStaticText(source, openTagOffset, openingTagText, isSelfClosing) {
+    if (isSelfClosing)
+        return null;
+    /* Find the matching `</tag>` in the rest of the source. We only
+       pull the LITERAL text between the open + close tags if the
+       close tag exists in the same string scope and no interpolation
+       splits the inner. This is best-effort. */
+    const tagMatch = /^<([a-zA-Z][a-zA-Z0-9]*)/.exec(openingTagText);
+    if (!tagMatch || !tagMatch[1])
+        return null;
+    const tag = tagMatch[1].toLowerCase();
+    const start = openTagOffset + openingTagText.length;
+    const closeRe = new RegExp('</' + tag + '\\s*>', 'gi');
+    closeRe.lastIndex = start;
+    const cm = closeRe.exec(source);
+    if (!cm)
+        return null;
+    const innerRaw = source.slice(start, cm.index);
+    /* If inner has unbalanced quotes or string-boundary chars + JS
+       concatenation operators, bail. */
+    if (/['"`]\s*\+|\+\s*['"`]/.test(innerRaw)) {
+        /* Has concatenation -- the text is dynamic. Extract the
+           leading literal portion only. */
+        const leading = innerRaw.split(/['"`]\s*\+/)[0] ?? '';
+        return leading.replace(/[<>]/g, '').trim().slice(0, 80) || null;
+    }
+    return innerRaw.replace(/[<>]/g, '').trim().slice(0, 80) || null;
+}
+function inferVerbFromAttrs(role, tag, aria, text, attrsRaw) {
+    if (role !== 'action' && role !== 'tab')
+        return null;
+    /* Build a minimal DOM stub so we can reuse the same L1-L5
+       classifier the HTML walker uses. */
+    const stub = parse('<' + tag + ' '
+        + (attrsRaw.replace(/\$\{[^}]*\}/g, '*').replace(/['"]\s*\+\s*[^+]*\+\s*['"]/g, '*'))
+        + '>' + (text ?? aria ?? '') + '</' + tag + '>');
+    const el = stub.firstChild;
+    if (!el)
+        return null;
+    const hit = inferVerb(el);
+    return hit?.verb ?? null;
+}
+function detectDynamicIdExpr(source, openTagOffset, openingTagText) {
+    /* Layered detection. Each layer scans the opening tag (+ a bit
+       of slack) for an interpolation pattern. First hit wins.
+       Layers in priority order:
+         L1  aria-label="...${EXPR}..."         (strongest signal)
+         L2  data-*-id / data-*-key="...EXPR..."
+         L3  id="...EXPR..."
+         L4  most-frequent expression in opening tag (fallback) */
+    /* L1: aria-label interpolation */
+    const fromAria = extractInterpolationInAttr(source, openTagOffset, openingTagText, /aria-label/);
+    if (fromAria)
+        return fromAria;
+    /* L2: data-*-id / data-key / data-row-id / etc. */
+    const fromDataId = extractInterpolationInAttr(source, openTagOffset, openingTagText, /data-([a-z0-9_-]*)(id|key|row-id|item-id|line-id|invoice-id|order-id|user-id)/i);
+    if (fromDataId)
+        return fromDataId;
+    /* L3: id="...EXPR..." */
+    const fromId = extractInterpolationInAttr(source, openTagOffset, openingTagText, /\bid\b/);
+    if (fromId)
+        return fromId;
+    /* L4: most-frequent JS interpolation in the opening tag.
+       If the row identity isn't tagged in any attr, we look at every
+       `'..' + EXPR + '..'` chunk inside the opening tag and pick the
+       EXPR that appears most often. Tied counts break in favour of
+       the shortest expression (heuristic: `inv.id` beats
+       `escapeHtml(inv.client_name)`).
+  
+       CRITICAL: window stays WITHIN the opening tag. Going past the
+       `>` includes interpolations from sibling tags and ends up
+       picking the wrong dynamic id. */
+    const exprs = collectInterpolations(openingTagText);
+    if (exprs.length > 0) {
+        const counts = new Map();
+        for (const e of exprs)
+            counts.set(e, (counts.get(e) || 0) + 1);
+        const ranked = [...counts.entries()].sort((a, b) => {
+            if (b[1] !== a[1])
+                return b[1] - a[1];
+            return a[0].length - b[0].length;
+        });
+        const winner = ranked[0];
+        if (winner && winner[1] >= 1)
+            return winner[0];
+    }
+    return null;
+}
+/**
+ * Find the first JS expression interpolated inside the value of the
+ * first attribute whose name matches `attrPattern`. Returns null if
+ * the attribute is absent or has no interpolation.
+ *
+ * The interpolation can be either string-concat (`'..' + EXPR + '..'`
+ * OR `".." + EXPR + ".."`, possibly with mismatched HTML/JS quotes)
+ * or template-literal (`${EXPR}`).
+ *
+ * Critical detail: the HTML attribute quote and the JS-string quote
+ * may differ. Common case: JS string uses `'` (single) and HTML
+ * attribute uses `"` (double). The detector must not assume they
+ * match.
+ */
+function extractInterpolationInAttr(source, openTagOffset, openingTagText, attrPattern) {
+    const re = new RegExp(`(${attrPattern.source})\\s*=\\s*['"]`, attrPattern.flags || 'i');
+    const m = re.exec(openingTagText);
+    if (!m)
+        return null;
+    const attrStartRel = m.index;
+    const valStartRel = attrStartRel + m[0].length - 1; /* index of the opening HTML-attr quote */
+    const htmlQuote = openingTagText[valStartRel] || '"';
+    /* Find the matching closing HTML-attr quote in openingTagText.
+       We do NOT respect JS-string boundaries here -- we just look
+       for the next char === htmlQuote that is not preceded by `\`. */
+    let valEndRel = valStartRel + 1;
+    while (valEndRel < openingTagText.length) {
+        const ch = openingTagText[valEndRel];
+        if (ch === htmlQuote && openingTagText[valEndRel - 1] !== '\\')
+            break;
+        valEndRel++;
+    }
+    if (valEndRel >= openingTagText.length)
+        return null;
+    /* The attribute value region spans [valStartRel+1, valEndRel)
+       in openingTagText. Within this region, look for any concat
+       or template interpolation. */
+    const valRegion = openingTagText.slice(valStartRel + 1, valEndRel);
+    /* concat interpolation: '<quote> + EXPR + <quote>' where
+       <quote> is either ' or ". The JS string could have been
+       opened with EITHER. We accept either inside the value. */
+    const concatRe = /(['"`])\s*\+\s*([^+]+?)\s*\+\s*\1/;
+    const cm = concatRe.exec(valRegion);
+    if (cm && cm[2])
+        return cm[2].trim();
+    /* template literal interpolation */
+    const tplRe = /\$\{([^}]+)\}/;
+    const tm = tplRe.exec(valRegion);
+    if (tm && tm[1])
+        return tm[1].trim();
+    return null;
+}
+/**
+ * Collect every JS expression that appears as an interpolation
+ * (either `' + EXPR + '` style concat OR `${EXPR}` template) within
+ * the given source slice. Used by the L4 fallback heuristic to
+ * pick the row identity by frequency.
+ */
+function collectInterpolations(slice) {
+    const out = [];
+    /* concat pattern */
+    const concatRe = /['"]\s*\+\s*([^+'"]+?)\s*\+\s*['"]/g;
+    let cm;
+    while ((cm = concatRe.exec(slice)) !== null) {
+        const e = (cm[1] ?? '').trim();
+        if (e && e.length < 100)
+            out.push(e);
+    }
+    /* template literal pattern */
+    const tplRe = /\$\{([^}]+)\}/g;
+    let tm;
+    while ((tm = tplRe.exec(slice)) !== null) {
+        const e = (tm[1] ?? '').trim();
+        if (e && e.length < 100)
+            out.push(e);
+    }
+    return out;
+}
+function derivePluginSlug(filePath, source, openTagOffset) {
+    /* Look backward for a function name + try to derive a slug from
+       it OR from filename. */
+    const fnRe = /function\s+(render[A-Z][a-zA-Z0-9_]*)\s*\(/g;
+    let lastFn = null;
+    let fm;
+    while ((fm = fnRe.exec(source)) !== null) {
+        if (fm.index >= openTagOffset)
+            break;
+        lastFn = fm[1] ?? null;
+    }
+    if (lastFn) {
+        const slug = lastFn
+            .replace(/^render/, '')
+            .replace(/([A-Z])/g, '_$1')
+            .toLowerCase()
+            .replace(/^_+/, '');
+        if (slug)
+            return slug;
+    }
+    return path.basename(filePath)
+        .replace(/\.(js|jsx|ts|tsx|mjs)$/, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '') || 'page';
+}
+function buildProposedIdTemplate(plugin, role, verb, tag, dynamicIdExpr, aria, text) {
+    const stem = (aria ?? text ?? verb ?? tag)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 24);
+    const base = plugin + '.' + role + '_' + (verb ?? tag);
+    if (dynamicIdExpr) {
+        /* Encode the dynamic id as a template marker {{EXPR}}. The
+           rewriter weaves it back into the source as a real JS concat. */
+        return base + '.{{' + dynamicIdExpr + '}}';
+    }
+    if (stem && stem !== (verb ?? tag))
+        return base + '.' + stem;
+    return base;
+}
+function computeConfidence(args) {
+    let conf = 0.4; // base
+    if (args.role === 'field' || args.role === 'region')
+        conf += 0.35;
+    if (args.verb)
+        conf += 0.25;
+    if (args.ariaStatic)
+        conf += 0.15;
+    if (args.dynamicIdExpr)
+        conf += 0.10; // unique-per-row
+    return Math.min(1, conf);
+}
+function computeFingerprint(filePath, tag, role, aria, text, dynamicIdExpr) {
+    const seed = JSON.stringify({
+        file: filePath, tag, role,
+        aria: (aria ?? '').slice(0, 60),
+        text: (text ?? '').slice(0, 60),
+        dyn: dynamicIdExpr ?? '',
+    });
+    return crypto.createHash('sha256').update(seed).digest('hex').slice(0, 16);
+}
+/**
+ * Rewrite a JS source string by injecting NAC attrs into the
+ * opening tags identified by `decisions`. Decisions must reference
+ * the SAME source you read (offsets are absolute).
+ *
+ * For dynamic id templates of the form "<base>.{{EXPR}}", the
+ * inserted attrs use JS string-concatenation that weaves EXPR back
+ * into the rendered HTML:
+ *
+ *   ' data-nac-id="<base>.' + escapeHtml(EXPR) + '" '
+ *
+ * (We use escapeHtml when the source defines such a helper; we
+ * fall back to inline `String(...)` otherwise. The detection runs
+ * once per file.)
+ */
+export function applyJsDecisions(source, decisions) {
+    if (decisions.length === 0)
+        return source;
+    /* Determine helper name */
+    const hasEscapeHtml = /\bfunction\s+escapeHtml\b|escapeHtml\s*=/.test(source);
+    const escape = hasEscapeHtml ? 'escapeHtml' : 'String';
+    /* Sort decisions DESC by offset so earlier injections do not
+       shift later positions. */
+    const sorted = [...decisions].sort((a, b) => b.offset - a.offset);
+    let out = source;
+    for (const d of sorted) {
+        const opening = out.slice(d.offset, d.offset + d.opening_tag_text.length);
+        if (opening !== d.opening_tag_text) {
+            /* The source has changed under us -- skip this decision. */
+            continue;
+        }
+        /* The opening text ends with `>` (or `/>`). Insert before that. */
+        const last = opening.lastIndexOf('>');
+        const isSelfClose = opening[last - 1] === '/';
+        const insertAt = d.offset + (isSelfClose ? last - 1 : last);
+        /* Compose the attr injection. */
+        const inj = composeAttrInjection(d, escape);
+        out = out.slice(0, insertAt) + inj + out.slice(insertAt);
+    }
+    return out;
+}
+function composeAttrInjection(d, escape) {
+    /* Detect the JS-string kind of the surrounding context by
+       inspecting the opening_tag_text. */
+    const inConcatString = /['"]\s*\+\s*[^+]+\+\s*['"]/.test(d.opening_tag_text);
+    const inTemplateString = /\$\{[^}]+\}/.test(d.opening_tag_text);
+    const idTemplate = d.nac_id_template;
+    const m = /^(.+?)\.\{\{(.+)\}\}$/.exec(idTemplate);
+    if (m) {
+        const base = m[1] ?? '';
+        const expr = m[2] ?? '';
+        /* If the expression already includes a function call (looks like
+           `escapeHtml(...)`, `String(...)`, `Number(...)`, etc.), do NOT
+           wrap again -- double-wrapping produces nonsense like
+           `escapeHtml(escapeHtml(x))`. We detect a leading identifier
+           followed by `(`. */
+        const exprIsCall = /^[A-Za-z_$][\w$]*\s*\(/.test(expr);
+        const safeExpr = exprIsCall ? expr : `${escape}(${expr})`;
+        if (inTemplateString || (!inConcatString && /`/.test(d.opening_tag_text))) {
+            /* Template literal form: ` data-nac-id="<base>.${EXPR}" data-nac-role="<role>"...` */
+            let inj = ` data-nac-id="${base}.\${${expr}}" data-nac-role="${d.role}"`;
+            if (d.verb)
+                inj += ` data-nac-action="${d.verb}"`;
+            return inj;
+        }
+        /* Default: single-quote string concat. Detect the surrounding
+           JS-quote (the JS-string this opening tag lives in) by
+           inspecting how the existing string is composed. We use `'`
+           by default since invoice-app + most jQuery-era code uses
+           single-quoted JS strings. */
+        let inj = ' data-nac-id="' + base + '.\' + ' + safeExpr + ' + \'" data-nac-role="' + d.role + '"';
+        if (d.verb)
+            inj += ' data-nac-action="' + d.verb + '"';
+        return inj;
+    }
+    /* Static id */
+    if (inTemplateString) {
+        let inj = ` data-nac-id="${idTemplate}" data-nac-role="${d.role}"`;
+        if (d.verb)
+            inj += ` data-nac-action="${d.verb}"`;
+        return inj;
+    }
+    let inj = ' data-nac-id="' + idTemplate + '" data-nac-role="' + d.role + '"';
+    if (d.verb)
+        inj += ' data-nac-action="' + d.verb + '"';
+    return inj;
+}
+/* ---- File-level helpers ---- */
+export async function scanJsFile(filePath) {
+    const source = await fs.readFile(filePath, 'utf-8');
+    return scanJsTemplates(filePath, source);
+}
+export async function applyJsDecisionsToFile(filePath, decisions, options = {}) {
+    const source = await fs.readFile(filePath, 'utf-8');
+    const out = applyJsDecisions(source, decisions);
+    if (!options.dryRun && out !== source) {
+        await fs.writeFile(filePath, out, 'utf-8');
+        return { source: out, wrote: true };
+    }
+    return { source: out, wrote: false };
+}
+//# sourceMappingURL=js-template-walker.js.map