@nuvio/ast-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Nuvio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# `@nuvio/ast-engine`
+
+Parses TSX/JSX, locates `data-nuvio-id` hosts, applies patch ops (`setText`, `mergeTailwindClassName`, `moveSibling`, `setHidden`, `duplicateHost`) with whitelist + `tailwind-merge`, formats with Prettier. Golden tests in `src/apply-patch.test.ts`.
+
+See the [Nuvio README](../../README.md) and [CHANGELOG](../../CHANGELOG.md).

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { PatchOp } from '@nuvio/shared';
+
+type ApplyPatchToSourceResult = {
+    ok: true;
+    source: string;
+    diffSummary: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Apply Phase 2 patch operations to TSX/JSX source for a single `data-nuvio-id` host.
+ */
+declare function applyPatchToSource(source: string, filePath: string, hostId: string, ops: readonly PatchOp[]): Promise<ApplyPatchToSourceResult>;
+
+/**
+ * Phase 2 — conservative Tailwind v3-style allowlist for `mergeTailwindClassName`.
+ * Expand intentionally; unknown tokens are rejected before `tailwind-merge`.
+ */
+declare function validateTailwindFragment(fragment: string): void;
+
+export { type ApplyPatchToSourceResult, applyPatchToSource, validateTailwindFragment };

package/dist/index.js

@@ -0,0 +1,328 @@
+// src/apply-patch.ts
+import { createRequire } from "module";
+import path from "path";
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+import prettier from "prettier";
+import { twMerge } from "tailwind-merge";
+
+// src/tailwind-whitelist.ts
+var SPACING = /^(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(0|px|auto|0\.5|1|1\.5|2|2\.5|3|3\.5|4|5|6|7|8|9|10|11|12|14|16|20|24|28|32|36|40|44|48|52|56|60|64|72|80|96)$/;
+var TEXT_SIZE = /^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)$/;
+var FONT_WEIGHT = /^font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)$/;
+var LEADING = /^leading-(none|tight|snug|normal|relaxed|loose|[0-9]+)$/;
+var COLOR_SOLID = /^(text|bg|border)-(inherit|current|transparent|black|white)$/;
+var COLOR_SCALE = /^(text|bg|border)-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(50|100|200|300|400|500|600|700|800|900|950)$/;
+var BG_COLOR_OPACITY = /^bg-(slate|sky|neutral)-(800|900|950)\/(50|75|80)$/;
+var ROUNDED = /^rounded$|^rounded-(none|sm|md|lg|xl|2xl|3xl|full)$/;
+var LAYOUT = /^(flex|inline-flex|block|inline|inline-block|grid|inline-grid|hidden|contents)$/;
+var FLEX = /^(flex-row|flex-col|flex-wrap|flex-1|grow|shrink|basis-0|items-(start|end|center|baseline|stretch)|justify-(start|end|center|between|around|evenly))$/;
+var BORDER_W = /^border(-(0|2|4|8))?$/;
+var TEXT_ALIGN = /^text-(left|center|right|justify|start|end)$/;
+var OPACITY = /^opacity-(0|5|10|15|20|25|30|40|50|60|70|75|80|90|95|100)$/;
+var SHADOW = /^shadow$|^shadow-(sm|md|lg|xl|2xl|inner|none)$/;
+var W_WIDTH = /^w-(auto|full|screen|min|max|fit|px|0|0\.5|1|1\.5|2|2\.5|3|3\.5|4|5|6|7|8|9|10|11|12|14|16|20|24|28|32|36|40|44|48|52|56|60|64|72|80|96|1\/2|1\/3|2\/3|1\/4|3\/4)$/;
+var H_HEIGHT = /^h-(auto|full|screen|min|max|fit|px|0|0\.5|1|1\.5|2|2\.5|3|3\.5|4|5|6|7|8|9|10|11|12|14|16|20|24|28|32|36|40|44|48|52|56|60|64|72|80|96)$/;
+var MAX_W = /^max-w-(none|xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full|min|max|fit|prose)$/;
+var MIN_H = /^min-h-(0|full|screen|min|max|fit|px|0\.5|1|1\.5|2|2\.5|3|3\.5|4|5|6|7|8|9|10|11|12|14|16|20|24|28|32|36|40|44|48|52|56|60|64|72|80|96)$/;
+function normalizeTailwindToken(raw) {
+  return raw.trim().replace(/[\u200B-\u200D\uFEFF]/g, "").replace(/[\u00AD\u2010\u2011\u2012\u2013\u2014\u2212]/g, "-");
+}
+function validateTailwindFragment(fragment) {
+  const tokens = fragment.trim().split(/\s+/).filter(Boolean);
+  for (const raw of tokens) {
+    const t2 = normalizeTailwindToken(raw);
+    if (!t2) {
+      continue;
+    }
+    if (SPACING.test(t2) || TEXT_SIZE.test(t2) || FONT_WEIGHT.test(t2) || LEADING.test(t2) || COLOR_SOLID.test(t2) || COLOR_SCALE.test(t2) || BG_COLOR_OPACITY.test(t2) || ROUNDED.test(t2) || LAYOUT.test(t2) || FLEX.test(t2) || BORDER_W.test(t2) || TEXT_ALIGN.test(t2) || OPACITY.test(t2) || SHADOW.test(t2) || W_WIDTH.test(t2) || H_HEIGHT.test(t2) || MAX_W.test(t2) || MIN_H.test(t2)) {
+      continue;
+    }
+    throw new Error(`Unknown or disallowed Tailwind utility: ${t2}`);
+  }
+}
+
+// src/apply-patch.ts
+var require2 = createRequire(import.meta.url);
+var traverse = require2("@babel/traverse").default;
+var generate = require2("@babel/generator").default;
+function findHostOpening(ast, hostId) {
+  let found = null;
+  traverse(ast, {
+    JSXOpeningElement(path2) {
+      for (const attr of path2.node.attributes) {
+        if (!t.isJSXAttribute(attr)) {
+          continue;
+        }
+        if (!t.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
+          continue;
+        }
+        if (t.isStringLiteral(attr.value) && attr.value.value === hostId) {
+          found = path2;
+          path2.stop();
+          return;
+        }
+      }
+    }
+  });
+  return found;
+}
+function applySetText(openingPath, text) {
+  const parent = openingPath.parentPath;
+  if (!parent?.isJSXElement()) {
+    throw new Error("Host is not a JSX element");
+  }
+  const jsx = parent;
+  const { children } = jsx.node;
+  if (children.length === 0) {
+    jsx.node.children = [t.jsxText(text)];
+    return;
+  }
+  if (children.length === 1 && t.isJSXText(children[0])) {
+    children[0].value = text;
+    return;
+  }
+  if (children.length === 1 && t.isJSXExpressionContainer(children[0]) && t.isStringLiteral(children[0].expression)) {
+    children[0].expression.value = text;
+    return;
+  }
+  jsx.node.children = [t.jsxText(text)];
+}
+function readStringLiteralClassName(opening) {
+  for (const attr of opening.attributes) {
+    if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: "className" })) {
+      if (t.isStringLiteral(attr.value)) {
+        return attr.value.value;
+      }
+      return null;
+    }
+  }
+  return "";
+}
+function parentSupportsLayoutMoves(parentOpening) {
+  const cls = readStringLiteralClassName(parentOpening);
+  if (cls === null) {
+    return false;
+  }
+  return /\b(flex|inline-flex|grid|inline-grid)\b/.test(cls) || /\b(flex-|grid-)/.test(cls);
+}
+function collectJsxElementChildIndices(parent) {
+  const indices = [];
+  parent.children.forEach((child, i) => {
+    if (t.isJSXElement(child)) {
+      indices.push(i);
+    }
+  });
+  return indices;
+}
+function applyMoveSibling(openingPath, direction) {
+  const hostPath = openingPath.parentPath;
+  if (!hostPath?.isJSXElement()) {
+    throw new Error("Host is not a JSX element");
+  }
+  const parentPath = hostPath.parentPath;
+  if (!parentPath?.isJSXElement()) {
+    throw new Error("Move requires a JSX element parent (same flex/grid container)");
+  }
+  const parentOpening = parentPath.node.openingElement;
+  if (!parentSupportsLayoutMoves(parentOpening)) {
+    throw new Error(
+      "Parent must use flex or grid layout (string-literal className with flex/grid utilities)"
+    );
+  }
+  const parent = parentPath.node;
+  const jsxIndices = collectJsxElementChildIndices(parent);
+  const hostIndex = parent.children.indexOf(hostPath.node);
+  if (hostIndex < 0) {
+    throw new Error("Host not found in parent children");
+  }
+  const pos = jsxIndices.indexOf(hostIndex);
+  if (pos < 0) {
+    throw new Error("Host must be a direct JSX element child of the layout parent");
+  }
+  if (direction === "up" && pos === 0) {
+    throw new Error("Already the first sibling");
+  }
+  if (direction === "down" && pos === jsxIndices.length - 1) {
+    throw new Error("Already the last sibling");
+  }
+  const swapIndex = direction === "up" ? jsxIndices[pos - 1] : jsxIndices[pos + 1];
+  const hostNode = parent.children[hostIndex];
+  parent.children[hostIndex] = parent.children[swapIndex];
+  parent.children[swapIndex] = hostNode;
+}
+function applySetHidden(openingPath, hidden) {
+  if (hidden) {
+    applyMergeClassName(openingPath, "hidden");
+    return;
+  }
+  const opening = openingPath.node;
+  let clsAttr;
+  for (const attr of opening.attributes) {
+    if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: "className" })) {
+      clsAttr = attr;
+      break;
+    }
+  }
+  if (!clsAttr || !t.isStringLiteral(clsAttr.value)) {
+    return;
+  }
+  const tokens = clsAttr.value.value.split(/\s+/).filter((tok) => tok && tok !== "hidden");
+  clsAttr.value = t.stringLiteral(twMerge(tokens.join(" ")));
+}
+function collectNuvioIds(ast) {
+  const ids = /* @__PURE__ */ new Set();
+  traverse(ast, {
+    JSXOpeningElement(path2) {
+      for (const attr of path2.node.attributes) {
+        if (!t.isJSXAttribute(attr) || !t.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
+          continue;
+        }
+        if (t.isStringLiteral(attr.value)) {
+          ids.add(attr.value.value);
+        }
+      }
+    }
+  });
+  return ids;
+}
+function setNuvioIdOnOpening(opening, id) {
+  for (const attr of opening.attributes) {
+    if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
+      if (t.isStringLiteral(attr.value)) {
+        attr.value.value = id;
+        return;
+      }
+    }
+  }
+  opening.attributes.push(
+    t.jsxAttribute(t.jsxIdentifier("data-nuvio-id"), t.stringLiteral(id))
+  );
+}
+function uniqueDuplicateId(baseId, taken) {
+  const candidate = `${baseId}.copy`;
+  if (!taken.has(candidate)) {
+    return candidate;
+  }
+  let n = 2;
+  while (taken.has(`${baseId}.copy${n}`)) {
+    n += 1;
+  }
+  return `${baseId}.copy${n}`;
+}
+function applyDuplicateHost(ast, openingPath, hostId) {
+  const hostPath = openingPath.parentPath;
+  if (!hostPath?.isJSXElement()) {
+    throw new Error("Host is not a JSX element");
+  }
+  const parentPath = hostPath.parentPath;
+  if (!parentPath?.isJSXElement()) {
+    throw new Error("Duplicate requires a JSX element parent");
+  }
+  const taken = collectNuvioIds(ast);
+  const newId = uniqueDuplicateId(hostId, taken);
+  const clone = t.cloneNode(hostPath.node, true);
+  if (!t.isJSXElement(clone)) {
+    throw new Error("Failed to clone host element");
+  }
+  setNuvioIdOnOpening(clone.openingElement, newId);
+  const parent = parentPath.node;
+  const hostIndex = parent.children.indexOf(hostPath.node);
+  if (hostIndex < 0) {
+    throw new Error("Host not found in parent children");
+  }
+  parent.children.splice(hostIndex + 1, 0, clone);
+  return newId;
+}
+function applyMergeClassName(openingPath, fragment) {
+  validateTailwindFragment(fragment);
+  const opening = openingPath.node;
+  let clsAttr;
+  for (const attr of opening.attributes) {
+    if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: "className" })) {
+      clsAttr = attr;
+      break;
+    }
+  }
+  if (!clsAttr) {
+    opening.attributes.push(
+      t.jsxAttribute(t.jsxIdentifier("className"), t.stringLiteral(fragment.trim()))
+    );
+    return;
+  }
+  if (!t.isStringLiteral(clsAttr.value)) {
+    throw new Error("className must be a string literal for Phase 2 patches");
+  }
+  const current = clsAttr.value.value;
+  clsAttr.value = t.stringLiteral(twMerge(current, fragment.trim()));
+}
+async function applyPatchToSource(source, filePath, hostId, ops) {
+  let ast;
+  try {
+    ast = parse(source, {
+      sourceType: "module",
+      plugins: ["typescript", "jsx"],
+      sourceFilename: filePath
+    });
+  } catch (e) {
+    return { ok: false, code: "parse_error", message: String(e) };
+  }
+  const openingPath = findHostOpening(ast, hostId);
+  if (!openingPath) {
+    return { ok: false, code: "host_not_found", message: `No JSX host with data-nuvio-id="${hostId}"` };
+  }
+  let duplicateNewId;
+  try {
+    for (const op of ops) {
+      if (op.kind === "setText") {
+        applySetText(openingPath, op.text);
+      } else if (op.kind === "mergeTailwindClassName") {
+        applyMergeClassName(openingPath, op.classNameFragment);
+      } else if (op.kind === "moveSibling") {
+        applyMoveSibling(openingPath, op.direction);
+      } else if (op.kind === "setHidden") {
+        applySetHidden(openingPath, op.hidden);
+      } else if (op.kind === "duplicateHost") {
+        duplicateNewId = applyDuplicateHost(ast, openingPath, hostId);
+      }
+    }
+  } catch (e) {
+    return { ok: false, code: "patch_rejected", message: String(e) };
+  }
+  let raw;
+  try {
+    raw = generate(ast, { retainLines: false, comments: true }).code;
+  } catch (e) {
+    return { ok: false, code: "generate_error", message: String(e) };
+  }
+  let formatted;
+  try {
+    formatted = await prettier.format(raw, {
+      parser: "typescript",
+      filepath: filePath
+    });
+  } catch (e) {
+    return { ok: false, code: "format_error", message: String(e) };
+  }
+  const base = path.basename(filePath);
+  const opBits = ops.map((op) => {
+    switch (op.kind) {
+      case "setText":
+        return `set text (${op.text.length} char${op.text.length === 1 ? "" : "s"})`;
+      case "mergeTailwindClassName":
+        return `merge className (${op.classNameFragment.trim()})`;
+      case "moveSibling":
+        return `move sibling ${op.direction}`;
+      case "setHidden":
+        return op.hidden ? "hide element" : "show element";
+      case "duplicateHost":
+        return duplicateNewId ? `duplicate host \u2192 ${duplicateNewId}` : "duplicate host";
+    }
+  });
+  const diffSummary = `${base}: ${opBits.join("; ")}`;
+  return { ok: true, source: formatted, diffSummary };
+}
+export {
+  applyPatchToSource,
+  validateTailwindFragment
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@nuvio/ast-engine",
+  "version": "0.1.0",
+  "description": "Nuvio AST patch engine: parse TSX/JSX, apply whitelist Tailwind merges and text edits, format with Prettier.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ehah/Nuvio.git",
+    "directory": "packages/ast-engine"
+  },
+  "keywords": [
+    "nuvio",
+    "ast",
+    "tsx",
+    "tailwind",
+    "babel"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.26.9",
+    "@babel/parser": "^7.26.9",
+    "@babel/traverse": "^7.26.9",
+    "@babel/types": "^7.26.9",
+    "prettier": "^3.5.1",
+    "tailwind-merge": "^2.6.0",
+    "@nuvio/shared": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.20.7",
+    "@types/node": "^22.13.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.6"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}