@nac3/forge-cli 0.2.0-alpha.1

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

@@ -0,0 +1,118 @@
+/**
+ * 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 type { Verb } from './verb-inference.js';
+export interface JsTemplateCandidate {
+    /** Stable identifier of this candidate across reruns. */
+    fingerprint: string;
+    /** File path the candidate was discovered in. */
+    filePath: string;
+    /** Index of the opening tag's `<` in the source (UTF-16 code units). */
+    offset: number;
+    /** 1-based line + col, computed lazily by the orchestrator if needed. */
+    line: number;
+    /** Tag name (lowercase): button / input / textarea / etc. */
+    tag: string;
+    /** Static attributes literal-extracted from the opening tag. */
+    static_attrs: string;
+    /** Heuristic: which JS expression is interpolated in aria-label. */
+    dynamic_id_expr: string | null;
+    /** Inferred role + verb. */
+    role: 'action' | 'field' | 'tab' | 'region' | 'option';
+    verb: Verb | null;
+    /** Whether the element already carries data-nac-id (regex hit). */
+    already_decorated: boolean;
+    /** Plugin slug -- derived from file path or surrounding function name. */
+    plugin: string;
+    /** Proposed nac_id template (may contain '+ EXPR +' for dynamic parts). */
+    proposed_id_template: string;
+    /** Confidence in [0, 1]. */
+    confidence: number;
+    /** Plain text content of the element (when it sits between open + close
+       in the same string and is not interpolated). */
+    text_static: string | null;
+    /** aria-label, if literal (interpolations replaced by '*'). */
+    aria_label_static: string | null;
+    /** The full text of the opening tag, for diagnostics. */
+    opening_tag_text: string;
+}
+export interface JsTemplateScanResult {
+    filePath: string;
+    candidates: JsTemplateCandidate[];
+}
+/**
+ * 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 declare function scanJsTemplates(filePath: string, source: string): JsTemplateScanResult;
+export interface AppliedJsDecision {
+    fingerprint: string;
+    nac_id_template: string;
+    role: string;
+    verb: string | null;
+    plugin: string;
+    /** Position to insert at (offset of the opening tag's `<` in the source). */
+    offset: number;
+    /** Original opening tag text to use as anchor. */
+    opening_tag_text: string;
+}
+/**
+ * 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 declare function applyJsDecisions(source: string, decisions: AppliedJsDecision[]): string;
+export declare function scanJsFile(filePath: string): Promise<JsTemplateScanResult>;
+export declare function applyJsDecisionsToFile(filePath: string, decisions: AppliedJsDecision[], options?: {
+    dryRun?: boolean;
+}): Promise<{
+    source: string;
+    wrote: boolean;
+}>;
+//# sourceMappingURL=js-template-walker.d.ts.map

package/dist/migrate/js-template-walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"js-template-walker.d.ts","sourceRoot":"","sources":["../../src/migrate/js-template-walker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAGhD,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,4BAA4B;IAC5B,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACvD,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,mEAAmE;IACnE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB;sDACkD;IAClD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAmEtF;AAuZD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,iBAAiB,EAAE,GAC7B,MAAM,CAwBR;AAgDD,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAGhF;AAED,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,iBAAiB,EAAE,EAC9B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAQ7C"}