@jsenv/ast 6.9.1 → 6.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/ast",
-  "version": "6.9.1",
+  "version": "6.9.3",
   "type": "module",
   "description": "Parse and transform HTML, CSS and JS",
   "repository": {

package/src/js/import_meta.js

@@ -0,0 +1,16 @@
+// "import.meta.<name>" as parsed by acorn: a member expression whose object
+// is the "import.meta" meta property. Returns <name>, or null for any other node.
+export const getImportMetaPropertyName = (node) => {
+  if (node.type !== "MemberExpression" || node.computed) {
+    return null;
+  }
+  const { object, property } = node;
+  if (
+    object.type !== "MetaProperty" ||
+    object.meta.name !== "import" ||
+    object.property.name !== "meta"
+  ) {
+    return null;
+  }
+  return property.name;
+};

package/src/js/js_static_analysis/css_template_substitutions.js

@@ -0,0 +1,241 @@
+// A "${}" inside a css template hides the whole css from the build: nothing can
+// be parsed, so nothing can be checked, rewritten or stripped.
+// It can be kept readable when the expression stands exactly where a css value
+// stands: "var(--jsenv-css-substitution-0)" is a value the css parser accepts
+// anywhere a value is expected, so the css around it stays css, and the
+// expression takes the placeholder's place back once the css is transformed.
+// Anywhere else — a selector, an at-rule prelude, a property name, inside a
+// string or inside url() — nothing can stand for the expression, and the
+// template is left alone.
+
+const PLACEHOLDER = (index) => `var(--jsenv-css-substitution-${index})`;
+
+/**
+ * @param {Object} templateLiteralNode a TemplateLiteral acorn node
+ * @param {string} js the source the node comes from
+ * @returns {{ content: string, substitutions: Array<{placeholder: string, expression: string}> }|null}
+ *          null when at least one expression is not in a css value position
+ */
+export const buildCssTemplateSubstitutions = (templateLiteralNode, js) => {
+  const { quasis, expressions } = templateLiteralNode;
+  const parts = [];
+  for (const quasi of quasis) {
+    const { cooked } = quasi.value;
+    if (cooked === undefined) {
+      // an escape sequence acorn could not cook: what the css is cannot be told
+      return null;
+    }
+    parts.push(cooked);
+  }
+  const substitutions = [];
+  let content = parts[0];
+  const positions = [];
+  for (let i = 0; i < expressions.length; i++) {
+    const placeholder = PLACEHOLDER(i);
+    positions.push(content.length);
+    substitutions.push({
+      placeholder,
+      expression: js.slice(expressions[i].start, expressions[i].end),
+    });
+    content += placeholder + parts[i + 1];
+  }
+  for (const position of positions) {
+    if (!isCssValuePosition(content, position)) {
+      return null;
+    }
+  }
+  return { content, substitutions };
+};
+
+// Reads the css from its start up to "position", keeping just enough state to
+// tell what the placeholder sitting there would be part of.
+const isCssValuePosition = (css, position) => {
+  let braceDepth = 0;
+  let stringQuote = null;
+  let inComment = false;
+  // the functions the position is nested in, innermost last ("" for a plain
+  // parenthesis); only url() has to be told apart, its argument is not a value
+  const functionStack = [];
+  // what has been read since the last "{", "}" or ";": a declaration value
+  // starts after a ":", and an at-rule prelude starts with "@"
+  let statementStart = 0;
+  let colonSeen = false;
+  let i = 0;
+  while (i < position) {
+    const char = css[i];
+    if (inComment) {
+      if (char === "*" && css[i + 1] === "/") {
+        inComment = false;
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (stringQuote) {
+      if (char === "\\") {
+        i += 2;
+        continue;
+      }
+      if (char === stringQuote) {
+        stringQuote = null;
+      }
+      i++;
+      continue;
+    }
+    if (char === "/" && css[i + 1] === "*") {
+      inComment = true;
+      i += 2;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      stringQuote = char;
+      i++;
+      continue;
+    }
+    if (char === "(") {
+      functionStack.push(readFunctionNameBefore(css, i));
+      i++;
+      continue;
+    }
+    if (char === ")") {
+      functionStack.pop();
+      i++;
+      continue;
+    }
+    if (char === "{") {
+      braceDepth++;
+      statementStart = i + 1;
+      colonSeen = false;
+      i++;
+      continue;
+    }
+    if (char === "}") {
+      braceDepth--;
+      statementStart = i + 1;
+      colonSeen = false;
+      i++;
+      continue;
+    }
+    if (char === ";") {
+      statementStart = i + 1;
+      colonSeen = false;
+      i++;
+      continue;
+    }
+    if (char === ":" && functionStack.length === 0) {
+      colonSeen = true;
+      i++;
+      continue;
+    }
+    i++;
+  }
+  if (inComment || stringQuote) {
+    return false;
+  }
+  if (braceDepth === 0) {
+    // outside any rule: a selector, or an at-rule prelude
+    return false;
+  }
+  if (!colonSeen) {
+    // a property name, or a nested selector
+    return false;
+  }
+  if (css.slice(statementStart, position).trimStart().startsWith("@")) {
+    // an at-rule prelude nested in a rule, "@media (min-width: ...)"
+    return false;
+  }
+  if (functionStack[functionStack.length - 1] === "url") {
+    // url() takes an url, and an url built at runtime is not one the build
+    // can follow to a file
+    return false;
+  }
+  // A ":" also opens a pseudo class, so what looks like a value here can still
+  // be the end of a nested selector; that is settled by what closes it.
+  return closedByDeclarationEnd(css, position);
+};
+
+const readFunctionNameBefore = (css, parenthesisIndex) => {
+  let start = parenthesisIndex;
+  while (start > 0 && /[a-zA-Z0-9_-]/.test(css[start - 1])) {
+    start--;
+  }
+  return css.slice(start, parenthesisIndex).toLowerCase();
+};
+
+// A declaration ends on ";" or "}"; reaching "{" first means what was read is
+// a selector.
+const closedByDeclarationEnd = (css, position) => {
+  let stringQuote = null;
+  let inComment = false;
+  let i = position;
+  while (i < css.length) {
+    const char = css[i];
+    if (inComment) {
+      if (char === "*" && css[i + 1] === "/") {
+        inComment = false;
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (stringQuote) {
+      if (char === "\\") {
+        i += 2;
+        continue;
+      }
+      if (char === stringQuote) {
+        stringQuote = null;
+      }
+      i++;
+      continue;
+    }
+    if (char === "/" && css[i + 1] === "*") {
+      inComment = true;
+      i += 2;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      stringQuote = char;
+      i++;
+      continue;
+    }
+    if (char === ";" || char === "}") {
+      return true;
+    }
+    if (char === "{") {
+      return false;
+    }
+    i++;
+  }
+  // the last declaration of the template may end without ";"
+  return true;
+};
+
+/**
+ * Puts the expressions back where their placeholder stands and renders the
+ * template literal to write in place of the original one.
+ * @returns {string|null} null when a placeholder did not survive the css
+ *          transformation as it was written: what would be given back would
+ *          not be what the source said
+ */
+export const renderCssTemplateLiteral = (content, substitutions) => {
+  for (const { placeholder } of substitutions) {
+    const index = content.indexOf(placeholder);
+    if (index === -1) {
+      return null;
+    }
+    if (content.indexOf(placeholder, index + placeholder.length) !== -1) {
+      return null;
+    }
+  }
+  let escaped = content
+    .replace(/\\/g, "\\\\")
+    .replace(/`/g, "\\`")
+    .replace(/\$/g, "\\$");
+  for (const { placeholder, expression } of substitutions) {
+    escaped = escaped.replace(placeholder, () => `\${${expression}}`);
+  }
+  return `\`${escaped}\``;
+};

package/src/js/js_static_analysis/import_meta_css.js

@@ -0,0 +1,198 @@
+import { getImportMetaPropertyName } from "../import_meta.js";
+import { buildCssTemplateSubstitutions } from "./css_template_substitutions.js";
+import { extractContentInfo } from "./helpers.js";
+
+export const isImportMetaCssAssignment = (node) => {
+  return (
+    node.type === "AssignmentExpression" &&
+    node.operator === "=" &&
+    getImportMetaPropertyName(node.left) === "css"
+  );
+};
+
+export const analyzeImportMetaCssAssignment = (
+  node,
+  { js, ast, ancestors, onInlineContent },
+) => {
+  // "import.meta.css = [css, url]": the array form a pre-built file ships
+  // (see jsenv:import_meta_css); the css is the first element.
+  const assignedNode =
+    node.right.type === "ArrayExpression" ? node.right.elements[0] : node.right;
+  if (!assignedNode) {
+    return;
+  }
+  // "const css = `...`; import.meta.css = css;" — the css is where the constant
+  // is declared, and that is where it is read and rewritten.
+  const nodeHoldingContent =
+    assignedNode.type === "Identifier"
+      ? findModuleConstantValue(assignedNode.name, { ast, ancestors })
+      : assignedNode;
+  if (!nodeHoldingContent) {
+    return;
+  }
+  const position = {
+    start: nodeHoldingContent.start,
+    end: nodeHoldingContent.end,
+    line: nodeHoldingContent.loc.start.line,
+    column: nodeHoldingContent.loc.start.column,
+    lineEnd: nodeHoldingContent.loc.end.line,
+    columnEnd: nodeHoldingContent.loc.end.column,
+  };
+  const contentInfo = extractContentInfo(nodeHoldingContent);
+  if (contentInfo) {
+    onInlineContent({
+      type: "import_meta_css_assignment",
+      contentType: "text/css",
+      ...position,
+      nodeType: contentInfo.nodeType,
+      quote: contentInfo.quote,
+      content: contentInfo.content,
+      astInfo: { node: nodeHoldingContent },
+    });
+    return;
+  }
+  if (nodeHoldingContent.type !== "TemplateLiteral") {
+    return;
+  }
+  const substitutionInfo = buildCssTemplateSubstitutions(
+    nodeHoldingContent,
+    js,
+  );
+  if (!substitutionInfo) {
+    return;
+  }
+  onInlineContent({
+    type: "import_meta_css_assignment",
+    contentType: "text/css",
+    ...position,
+    nodeType: "TemplateLiteral",
+    quote: "`",
+    content: substitutionInfo.content,
+    substitutions: substitutionInfo.substitutions,
+    astInfo: { node: nodeHoldingContent },
+  });
+};
+
+const findModuleConstantValue = (name, { ast, ancestors }) => {
+  if (isShadowed(name, ancestors)) {
+    // the name stands for something declared closer than the module
+    return null;
+  }
+  for (const node of ast.body) {
+    const declaration =
+      node.type === "ExportNamedDeclaration" ? node.declaration : node;
+    if (!declaration || declaration.type !== "VariableDeclaration") {
+      continue;
+    }
+    if (declaration.kind !== "const") {
+      // the value read at assignment time is not the one written here
+      continue;
+    }
+    for (const declarator of declaration.declarations) {
+      if (declarator.id.type === "Identifier" && declarator.id.name === name) {
+        return declarator.init;
+      }
+    }
+  }
+  return null;
+};
+
+// Walks out from the assignment towards the module: a name declared on the way
+// is not the module constant, whatever the module declares under it.
+const isShadowed = (name, ancestors) => {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const node = ancestors[i];
+    if (node.type === "Program") {
+      return false;
+    }
+    if (
+      node.type === "FunctionDeclaration" ||
+      node.type === "FunctionExpression" ||
+      node.type === "ArrowFunctionExpression"
+    ) {
+      for (const param of node.params) {
+        if (patternDeclares(param, name)) {
+          return true;
+        }
+      }
+      continue;
+    }
+    if (node.type === "CatchClause") {
+      if (node.param && patternDeclares(node.param, name)) {
+        return true;
+      }
+      continue;
+    }
+    if (node.type === "BlockStatement" || node.type === "StaticBlock") {
+      if (bodyDeclares(node.body, name)) {
+        return true;
+      }
+      continue;
+    }
+    if (
+      node.type === "ForStatement" ||
+      node.type === "ForInStatement" ||
+      node.type === "ForOfStatement"
+    ) {
+      const init = node.init || node.left;
+      if (init && init.type === "VariableDeclaration") {
+        for (const declarator of init.declarations) {
+          if (patternDeclares(declarator.id, name)) {
+            return true;
+          }
+        }
+      }
+      continue;
+    }
+  }
+  return false;
+};
+
+const bodyDeclares = (body, name) => {
+  for (const node of body) {
+    if (node.type === "VariableDeclaration") {
+      for (const declarator of node.declarations) {
+        if (patternDeclares(declarator.id, name)) {
+          return true;
+        }
+      }
+      continue;
+    }
+    if (
+      (node.type === "FunctionDeclaration" ||
+        node.type === "ClassDeclaration") &&
+      node.id &&
+      node.id.name === name
+    ) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const patternDeclares = (pattern, name) => {
+  if (!pattern) {
+    return false;
+  }
+  if (pattern.type === "Identifier") {
+    return pattern.name === name;
+  }
+  if (pattern.type === "AssignmentPattern") {
+    return patternDeclares(pattern.left, name);
+  }
+  if (pattern.type === "RestElement") {
+    return patternDeclares(pattern.argument, name);
+  }
+  if (pattern.type === "ArrayPattern") {
+    return pattern.elements.some((element) => patternDeclares(element, name));
+  }
+  if (pattern.type === "ObjectPattern") {
+    return pattern.properties.some((property) =>
+      patternDeclares(
+        property.type === "RestElement" ? property.argument : property.value,
+        name,
+      ),
+    );
+  }
+  return false;
+};

package/src/js/parse_js_urls.js

@@ -6,6 +6,10 @@ import {
   analyzeImportDeclaration,
   analyzeImportExpression,
 } from "./js_static_analysis/import_export.js";
+import {
+  analyzeImportMetaCssAssignment,
+  isImportMetaCssAssignment,
+} from "./js_static_analysis/import_meta_css.js";
 import {
   analyzeImportMetaResolveCall,
   isImportMetaResolveCall,
@@ -130,6 +134,16 @@ export const parseJsUrls = ({
     ExportAllDeclaration: (node) => {
       analyzeExportAllDeclaration(node, { onUrl });
     },
+    AssignmentExpression: (node, ancestors) => {
+      if (inlineContent && isJsModule && isImportMetaCssAssignment(node)) {
+        analyzeImportMetaCssAssignment(node, {
+          js,
+          ast,
+          ancestors,
+          onInlineContent,
+        });
+      }
+    },
     CallExpression: (node) => {
       if (isJsModule && isImportMetaResolveCall(node)) {
         analyzeImportMetaResolveCall(node, { onUrl });

package/src/js/visit_js_ast.js

@@ -0,0 +1,5 @@
+import { simple } from "acorn-walk";
+
+export const visitJsAst = (ast, visitors) => {
+  simple(ast, visitors);
+};

package/src/main.js

@@ -49,6 +49,9 @@ export { injectJsImport } from "./js/babel_utils.js";
 export { parseJsWithAcorn } from "./js/parse_js_with_acorn.js";
 export { parseJsUrls } from "./js/parse_js_urls.js";
 export { visitJsAstUntil } from "./js/visit_js_ast_until.js";
+export { visitJsAst } from "./js/visit_js_ast.js";
+export { getImportMetaPropertyName } from "./js/import_meta.js";
 export { getUrlForContentInsideJs } from "./js/js_inline_content_url.js";
+export { renderCssTemplateLiteral } from "./js/js_static_analysis/css_template_substitutions.js";
 
 export { generateUrlForInlineContent } from "./inline_content_url.js";