wrec 0.29.3 → 0.29.4

package/package.json

@@ -2,7 +2,7 @@
   "name": "wrec",
   "description": "a small library that greatly simplifies building web components",
   "author": "R. Mark Volkmann",
-  "version": "0.29.3",
+  "version": "0.29.4",
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/lint.js

@@ -31,7 +31,6 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
 import ts from 'typescript';
 import {parse} from 'node-html-parser';
 
@@ -1869,20 +1868,7 @@ function walkHtmlNode(
   }
 }
 
-const isCliEntry = (() => {
-  if (!process.argv[1]) return false;
-
-  try {
-    return (
-      fs.realpathSync(process.argv[1]) ===
-      fs.realpathSync(fileURLToPath(import.meta.url))
-    );
-  } catch {
-    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
-  }
-})();
-
-if (isCliEntry) {
+if (import.meta.main) {
   try {
     main();
   } catch (error) {

package/scripts/used-by.js

@@ -3,7 +3,8 @@
 // determines the proper values for property config `usedBy` properties.
 // Each value is a list of methods that use the property
 // or a single method name.
-// It uses the TypeScript compiler to parse the file,
+//
+// This uses the TypeScript compiler to parse the source file,
 // discover which expressions call which methods,
 // trace property usage through those call chains, and
 // output or update the `usedBy` properties`.
@@ -17,12 +18,201 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
 import ts from 'typescript';
 
+const cwd = process.cwd();
+
+// Records property names introduced by
+// an identifier or object binding pattern.
+// An object binding pattern is destructuring syntax
+// used in a binding position, like a variable declaration,
+// parameter list, or assignment target.
+function addBindingName(props, name) {
+  if (ts.isIdentifier(name)) {
+    props.add(name.text);
+  } else if (ts.isObjectBindingPattern(name)) {
+    addObjectBindingProps(props, name);
+  }
+}
+
+// Adds property names referenced by an object binding pattern.
+function addObjectBindingProps(props, bindingPattern) {
+  for (const element of bindingPattern.elements) {
+    if (element.dotDotDotToken) continue;
+
+    if (element.propertyName) {
+      const name = getNameText(element.propertyName);
+      if (name) props.add(name);
+      continue;
+    }
+
+    addBindingName(props, element.name);
+  }
+}
+
+// Analyzes a parsed source file and returns any proposed `usedBy` edits.
+// This is the heart of the functionality in this script.
+function analyzeSourceFile(sourceFile) {
+  const edits = [];
+  const {names: wrecNames, quote} = getWrecImportInfo(sourceFile);
+  const suggestions = [];
+  let foundWrecSubclass = false;
+
+  // Find the statement that defines a class that extends Wrec.
+  for (const node of sourceFile.statements) {
+    if (!ts.isClassDeclaration(node) || !extendsWrec(node, wrecNames)) continue;
+    foundWrecSubclass = true;
+
+    let propertiesObject = null;
+    // Find the static property named "properties".
+    for (const member of node.members) {
+      if (
+        ts.isPropertyDeclaration(member) &&
+        hasStaticModifier(member) &&
+        getNameText(member.name) === 'properties' &&
+        member.initializer &&
+        ts.isObjectLiteralExpression(member.initializer)
+      ) {
+        propertiesObject = member.initializer;
+        break;
+      }
+    }
+
+    // Bail out if no static property named "properties" was found.
+    if (!propertiesObject) continue;
+
+    // Get a Set of the defined property names.
+    const propertyNames = new Set(
+      propertiesObject.properties
+        .filter(ts.isPropertyAssignment)
+        .map(property => getNameText(property.name))
+        .filter(name => name !== null)
+    );
+
+    // Get a map where the keys are property names and
+    // the values are Sets of public methods that use it transitively.
+    const propToMethods = getMethodUsages(node, propertyNames);
+
+    // For each member that represents a component property ...
+    for (const member of propertiesObject.properties) {
+      // Skip the member if not a property assignment.
+      if (!ts.isPropertyAssignment(member)) continue;
+
+      // Skip the member if we can't gets its name
+      // or if its value isn't an object literal.
+      const propName = getNameText(member.name);
+      if (!propName || !ts.isObjectLiteralExpression(member.initializer))
+        continue;
+
+      // Convert the Set of methods that use the property into a sorted array.
+      const methodNames = [
+        ...(propToMethods.get(propName) ?? new Set())
+      ].sort();
+
+      // Get an array of all the NodeObjects that represent
+      // properties in the configuration object, except the one for "usedBy".
+      const configObject = member.initializer;
+      const existingMembers = configObject.properties.filter(
+        property =>
+          !(
+            ts.isPropertyAssignment(property) &&
+            getNameText(property.name) === 'usedBy'
+          )
+      );
+
+      // If the property is used by any methods ...
+      if (methodNames.length > 0) {
+        suggestions.push({
+          propName,
+          suggestion: createUsedByProperty(methodNames, quote)
+        });
+      } else {
+        // Determine if the configuration object already had a "usedBy" property.
+        const hadUsedBy =
+          existingMembers.length !== configObject.properties.length;
+        if (hadUsedBy) {
+          suggestions.push({propName, suggestion: 'remove usedBy'});
+        } else {
+          continue;
+        }
+      }
+
+      // Build the new text for the property configuration object.
+      const nextText = buildConfigText(sourceFile, member, methodNames, quote);
+      // Get the existing text for the property configuration object.
+      const currentText = sourceFile.text.slice(
+        configObject.getStart(sourceFile),
+        configObject.end
+      );
+      // If they differ, add an object describing
+      // the desired edit to the edits array.
+      if (nextText !== currentText) {
+        edits.push({
+          start: configObject.getStart(sourceFile),
+          end: configObject.end,
+          propName,
+          oldText: currentText,
+          text: nextText
+        });
+      }
+    }
+  }
+
+  // If we didn't find a Wrec subclass, then there are no changes to make.
+  if (!foundWrecSubclass) {
+    return {
+      changed: false,
+      edits: [],
+      foundWrecSubclass: false,
+      suggestions,
+      text: sourceFile.text
+    };
+  }
+
+  // If we found a Wrec subclass,
+  // but no edits for usedBy properties are needed ...
+  if (edits.length === 0) {
+    return {
+      changed: false,
+      edits: [],
+      foundWrecSubclass: true,
+      suggestions,
+      text: sourceFile.text
+    };
+  }
+
+  // Get the current text in the source file.
+  let nextSource = sourceFile.text;
+
+  // Sort the edits to be made from last to first.
+  edits.sort((a, b) => b.start - a.start);
+
+  // Make each of the edits to the source file.
+  for (const edit of edits) {
+    nextSource =
+      nextSource.slice(0, edit.start) + edit.text + nextSource.slice(edit.end);
+  }
+
+  return {
+    changed: true,
+    edits,
+    foundWrecSubclass: true,
+    suggestions,
+    text: nextSource
+  };
+}
+
+// Builds a new property config object
+// with an updated `usedBy` entry if needed.
+// - member is an AST node for the initialization of a property
+//   inside the "static properties" object.
+// - methodsNames is an array of the methods that use the property.
+// - quote is either a single or double quote.
 function buildConfigText(sourceFile, member, methodNames, quote) {
-  const {text} = sourceFile;
   const configObject = member.initializer;
+
+  // Get an array of AST nodes for all the config object properties
+  // except `usedBy`.
   const existingMembers = configObject.properties.filter(
     property =>
       !(
@@ -30,67 +220,169 @@ function buildConfigText(sourceFile, member, methodNames, quote) {
         getNameText(property.name) === 'usedBy'
       )
   );
-  const existingTexts = existingMembers.map(property =>
+
+  // Create property assignment strings from the AST nodes.
+  const {text} = sourceFile;
+  const propertyStrings = existingMembers.map(property =>
     text.slice(property.getStart(sourceFile), property.end).trim()
   );
-  if (methodNames.length > 0)
-    existingTexts.push(createUsedByProperty(methodNames, quote));
 
-  const original = text.slice(
+  // If this property is used by any methods,
+  // add a usedBy property that lists them.
+  if (methodNames.length > 0) {
+    propertyStrings.push(createUsedByProperty(methodNames, quote));
+  }
+
+  const existingPropertiesString = text.slice(
     configObject.getStart(sourceFile),
     configObject.end
   );
-  const multiline = original.includes('\n');
-  if (!multiline) {
-    const openMatch = original.match(/^\{(\s*)/);
-    const closeMatch = original.match(/(\s*)\}$/);
-    const openSpacing = openMatch ? openMatch[1] : ' ';
-    const closeSpacing = closeMatch ? closeMatch[1] : ' ';
-    return `{${openSpacing}${existingTexts.join(', ')}${closeSpacing}}`;
+
+  const multiline = existingPropertiesString.includes('\n');
+  if (multiline) {
+    // Build and return a multi-line config object string
+    // that preserves the existing indentation.
+    const memberIndent = getIndent(text, member.getStart(sourceFile));
+    const [firstMember] = existingMembers;
+    const propertyIndent = firstMember
+      ? getIndent(text, firstMember.getStart(sourceFile))
+      : memberIndent + '  ';
+    const content = propertyStrings
+      .map(part => `${propertyIndent}${part}`)
+      .join(',\n');
+    return `{\n${content}\n${memberIndent}}`;
   }
 
-  // Preserve the surrounding formatting style so the update feels like a
-  // minimal edit instead of reformatting the whole object.
-  const memberIndent = getIndent(text, member.getStart(sourceFile));
-  const firstExisting = existingMembers[0];
-  const innerIndent = firstExisting
-    ? getIndent(text, firstExisting.getStart(sourceFile))
-    : memberIndent + '  ';
-  return `{\n${existingTexts.map(part => `${innerIndent}${part}`).join(',\n')}\n${memberIndent}}`;
+  // Build and return a single line config object string
+  // that preserves the existing spacing around curly braces.
+  const openMatch = existingPropertiesString.match(/^\{(\s*)/);
+  const closeMatch = existingPropertiesString.match(/(\s*)\}$/);
+  const openSpacing = openMatch ? openMatch[1] : ' ';
+  const closeSpacing = closeMatch ? closeMatch[1] : ' ';
+  return `{${openSpacing}${propertyStrings.join(', ')}${closeSpacing}}`;
 }
 
-function collectFiles(startPath, files = []) {
-  if (!fs.existsSync(startPath)) return files;
-
-  const stat = fs.statSync(startPath);
-  if (stat.isFile()) {
-    if (isSupportedSourceFile(startPath)) files.push(startPath);
-    return files;
-  }
-
-  for (const entry of fs.readdirSync(startPath, {withFileTypes: true})) {
-    const fullPath = path.join(startPath, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === 'node_modules' || entry.name === 'dist') continue;
-      collectFiles(fullPath, files);
-    } else if (entry.isFile() && isSupportedSourceFile(entry.name, true)) {
-      files.push(fullPath);
+// Walks a method body to collect component property reads
+// and method calls made through `this`.
+// This is only called by getMethodUsages.
+function collectMethodBodyUsage(node, props, calledMethods) {
+  if (
+    ts.isPropertyAccessExpression(node) &&
+    node.expression.kind === ts.SyntaxKind.ThisKeyword
+  ) {
+    // Handles direct property access like `this.foo`
+    // and records method calls like `this.foo()`.
+    recordThisAccess(props, calledMethods, node, node.name.text);
+  } else if (
+    ts.isElementAccessExpression(node) &&
+    node.expression.kind === ts.SyntaxKind.ThisKeyword &&
+    node.argumentExpression &&
+    ts.isStringLiteralLike(node.argumentExpression)
+  ) {
+    // Handles string-based element access like `this['foo']`
+    // and records method calls like `this['foo']()`.
+    recordThisAccess(props, calledMethods, node, node.argumentExpression.text);
+  } else if (
+    ts.isVariableDeclaration(node) &&
+    node.initializer &&
+    node.initializer.kind === ts.SyntaxKind.ThisKeyword
+  ) {
+    // Handles variable declarations initialized from `this`,
+    // such as `const {foo} = this` or `const self = this`.
+    addBindingName(props, node.name);
+  } else if (
+    ts.isBinaryExpression(node) &&
+    node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+    node.right.kind === ts.SyntaxKind.ThisKeyword
+  ) {
+    // Handles assignments from `this`, such as destructuring
+    // or object-literal patterns that pull named properties from it.
+    if (ts.isObjectLiteralExpression(node.left)) {
+      for (const property of node.left.properties) {
+        if (
+          ts.isShorthandPropertyAssignment(property) ||
+          ts.isPropertyAssignment(property)
+        ) {
+          const name = getNameText(property.name);
+          if (name) props.add(name);
+        }
+      }
+    } else if (ts.isObjectBindingPattern(node.left)) {
+      addObjectBindingProps(props, node.left);
     }
   }
 
-  return files;
+  ts.forEachChild(node, child =>
+    collectMethodBodyUsage(child, props, calledMethods)
+  );
 }
 
+// Returns a string for a usedBy property.
 function createUsedByProperty(methodNames, quote) {
-  if (methodNames.length === 1) {
-    return `usedBy: ${quote}${methodNames[0]}${quote}`;
+  const value =
+    methodNames.length === 1
+      ? `${quote}${methodNames[0]}${quote}`
+      : `[${methodNames.map(name => `${quote}${name}${quote}`).join(', ')}]`;
+  return `usedBy: ${value}`;
+}
+
+// Determines what changes, if any, should be made in
+// the usedBy properties in property configuration objects
+// found in the file at a given relative path.
+export function evaluateSourceFile(filePath, options = {}) {
+  const {dry = false} = options;
+  const absFilePath = path.resolve(cwd, filePath);
+  validateFile(absFilePath);
+
+  // The file is read in this function instead of in evaluateSourceText
+  // so unit tests can pass hard-coded text to that function.
+  const text = fs.readFileSync(absFilePath, 'utf8');
+  let {
+    changed,
+    foundWrecSubclass,
+    suggestions,
+    text: nextText
+  } = evaluateSourceText(absFilePath, text);
+
+  // If we didn't find the definition of a class that extends Wrec ...
+  if (!foundWrecSubclass) {
+    throw new Error('No class extending Wrec was found.');
+  }
+
+  // If this isn't a dry run and changes were made,
+  // write the modified source code back to the file.
+  if (!dry && changed) {
+    fs.writeFileSync(absFilePath, nextText);
+    suggestions = []; // all the suggestions have been applied
   }
-  return `usedBy: [${methodNames.map(name => `${quote}${name}${quote}`).join(', ')}]`;
+
+  return {changed, foundWrecSubclass, suggestions, text: nextText};
+}
+
+// Determines what changes, if any, should be made in
+// the usedBy properties in property configuration objects
+// found in source file text.
+// This function was factored out of evaluateSourceFile
+// to support unit tests.
+export function evaluateSourceText(filePath, text) {
+  const scriptKind = filePath.endsWith('.ts')
+    ? ts.ScriptKind.TS
+    : ts.ScriptKind.JS;
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKind
+  );
+  return analyzeSourceFile(sourceFile);
 }
 
-function extendsWrec(node, wrecNames) {
+// Determines whether a class declaration extends one of the known Wrec imports.
+// This is only called by analyzeSourceFile.
+function extendsWrec(classNode, wrecNames) {
   return Boolean(
-    node.heritageClauses?.some(
+    classNode.heritageClauses?.some(
       clause =>
         clause.token === ts.SyntaxKind.ExtendsKeyword &&
         clause.types.some(
@@ -103,42 +395,103 @@ function extendsWrec(node, wrecNames) {
   );
 }
 
+// Gets the names of all methods that are called from
+// JavaScript expressions in the component's static CSS template.
+// This is only called by getMethodUsages.
+function getCssCalledMethods(classNode) {
+  const methodNames = new Set();
+  const CALL_RE = /this\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+  let template;
+
+  for (const member of classNode.members) {
+    // If this member isn't the AST node for "static css = ..."
+    // then skip it.
+    if (
+      ts.isPropertyDeclaration(member) &&
+      hasStaticModifier(member) &&
+      getNameText(member.name) === 'css' &&
+      member.initializer &&
+      ts.isTaggedTemplateExpression(member.initializer) &&
+      ts.isIdentifier(member.initializer.tag) &&
+      member.initializer.tag.text === 'css'
+    ) {
+      // Keep the last matching declaration because
+      // JavaScript class fields use last-one-wins semantics
+      // when the same static field is declared twice.
+      template = member.initializer.template;
+    }
+  }
+
+  // If no matching declaration was found, return an empty Set.
+  if (!template) return methodNames;
+
+  // Finds all method names called in CSS property value expressions
+  // matching `this.method()`.
+  const text = template.getText();
+  for (const match of text.matchAll(CALL_RE)) {
+    methodNames.add(match[1]);
+  }
+
+  return methodNames;
+}
+
+// Gets the names of all methods that are called from
+// the "computed" JavaScript expression of an component property.
+// This is only called by getMethodUsages.
 function getComputedCalledMethods(classNode) {
   const methodNames = new Set();
   const CALL_RE = /this\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+  let propertiesNode;
 
   for (const member of classNode.members) {
+    // If this member isn't the AST node for "static properties = ..."
+    // then skip it.
     if (
-      !ts.isPropertyDeclaration(member) ||
-      !hasStaticModifier(member) ||
-      getNameText(member.name) !== 'properties' ||
-      !member.initializer ||
-      !ts.isObjectLiteralExpression(member.initializer)
+      ts.isPropertyDeclaration(member) &&
+      hasStaticModifier(member) &&
+      getNameText(member.name) === 'properties' &&
+      member.initializer &&
+      ts.isObjectLiteralExpression(member.initializer)
+    ) {
+      // Keep the last matching declaration because
+      // JavaScript class fields use last-one-wins semantics
+      // when the same static field is declared twice.
+      propertiesNode = member.initializer;
+    }
+  }
+
+  // If no matching declaration was found, return an empty Set.
+  if (!propertiesNode) return methodNames;
+
+  // For each property in the last "static properties" object ...
+  for (const property of propertiesNode.properties) {
+    // If it isn't a property assignment or
+    // the property value isn't an object literal then skip it.
+    if (
+      !ts.isPropertyAssignment(property) ||
+      !ts.isObjectLiteralExpression(property.initializer)
     ) {
       continue;
     }
 
-    for (const property of member.initializer.properties) {
+    // For each property in the configuration object ...
+    for (const configProperty of property.initializer.properties) {
+      // If it isn't a property assignment or
+      // the property name isn't "computed" then skip it.
       if (
-        !ts.isPropertyAssignment(property) ||
-        !ts.isObjectLiteralExpression(property.initializer)
+        !ts.isPropertyAssignment(configProperty) ||
+        getNameText(configProperty.name) !== 'computed'
       ) {
         continue;
       }
 
-      for (const configProperty of property.initializer.properties) {
-        if (
-          !ts.isPropertyAssignment(configProperty) ||
-          getNameText(configProperty.name) !== 'computed'
-        ) {
-          continue;
-        }
+      // If the property value isn't a string then skip it.
+      if (!ts.isStringLiteralLike(configProperty.initializer)) continue;
 
-        if (!ts.isStringLiteralLike(configProperty.initializer)) continue;
-        const computed = configProperty.initializer.text;
-        for (const match of computed.matchAll(CALL_RE)) {
-          methodNames.add(match[1]);
-        }
+      // Find all the method calls in the string JavaScript expression.
+      const computed = configProperty.initializer.text;
+      for (const match of computed.matchAll(CALL_RE)) {
+        methodNames.add(match[1]);
       }
     }
   }
@@ -146,161 +499,53 @@ function getComputedCalledMethods(classNode) {
   return methodNames;
 }
 
+// Returns the leading indentation in the line
+// that begins at a given position (`pos`) inside `text`.
 function getIndent(text, pos) {
   const lineStart = text.lastIndexOf('\n', pos - 1) + 1;
   const match = /^[ \t]*/.exec(text.slice(lineStart));
   return match ? match[0] : '';
 }
 
+// Returns a map where the keys are property names and
+// the values are Sets of public methods that use it transitively.
 function getMethodUsages(classNode, propertyNames) {
   const methodInfo = new Map();
-  for (const member of classNode.members) {
-    if (hasStaticModifier(member)) continue;
 
-    if (
-      (ts.isMethodDeclaration(member) ||
-        ts.isGetAccessorDeclaration(member) ||
-        ts.isSetAccessorDeclaration(member)) &&
-      member.body
-    ) {
-      const methodName = getNameText(member.name);
-      if (!methodName) continue;
-
-      const props = new Set();
-      const calledMethods = new Set();
-      const isPrivate = ts.isPrivateIdentifier(member.name);
-
-      function addBindingName(name) {
-        if (ts.isIdentifier(name)) {
-          props.add(name.text);
-        } else if (ts.isObjectBindingPattern(name)) {
-          addObjectBindingProps(name);
-        }
-      }
-
-      function addObjectBindingProps(bindingPattern) {
-        for (const element of bindingPattern.elements) {
-          if (element.dotDotDotToken) continue;
-
-          if (element.propertyName) {
-            const name = getNameText(element.propertyName);
-            if (name) props.add(name);
-            continue;
-          }
-
-          if (ts.isIdentifier(element.name)) {
-            props.add(element.name.text);
-          } else if (ts.isObjectBindingPattern(element.name)) {
-            addObjectBindingProps(element.name);
-          }
-        }
-      }
-
-      function visit(child) {
-        // Record both direct property reads like `this.foo` and method calls
-        // like `this.renderFoo()` so we can later propagate property usage
-        // through method-to-method call chains.
-        if (
-          ts.isPropertyAccessExpression(child) &&
-          child.expression.kind === ts.SyntaxKind.ThisKeyword
-        ) {
-          const name = child.name.text;
-          props.add(name);
-          if (
-            ts.isCallExpression(child.parent) &&
-            child.parent.expression === child
-          ) {
-            calledMethods.add(name);
-          }
-        } else if (
-          ts.isElementAccessExpression(child) &&
-          child.expression.kind === ts.SyntaxKind.ThisKeyword &&
-          child.argumentExpression &&
-          ts.isStringLiteralLike(child.argumentExpression)
-        ) {
-          const name = child.argumentExpression.text;
-          props.add(name);
-          if (
-            ts.isCallExpression(child.parent) &&
-            child.parent.expression === child
-          ) {
-            calledMethods.add(name);
-          }
-        } else if (
-          ts.isVariableDeclaration(child) &&
-          child.initializer &&
-          child.initializer.kind === ts.SyntaxKind.ThisKeyword
-        ) {
-          if (ts.isObjectBindingPattern(child.name)) {
-            addObjectBindingProps(child.name);
-          } else {
-            addBindingName(child.name);
-          }
-        } else if (
-          ts.isBinaryExpression(child) &&
-          child.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
-          child.right.kind === ts.SyntaxKind.ThisKeyword
-        ) {
-          if (ts.isObjectLiteralExpression(child.left)) {
-            for (const property of child.left.properties) {
-              if (
-                ts.isShorthandPropertyAssignment(property) ||
-                ts.isPropertyAssignment(property)
-              ) {
-                const name = getNameText(property.name);
-                if (name) props.add(name);
-              }
-            }
-          } else if (ts.isObjectBindingPattern(child.left)) {
-            addObjectBindingProps(child.left);
-          }
-        }
-
-        ts.forEachChild(child, visit);
-      }
-
-      ts.forEachChild(member.body, visit);
-      methodInfo.set(methodName, {calledMethods, isPrivate, props});
-    }
+  for (const member of classNode.members) {
+    // If the member doesn't represent an instance method, skip it.
+    if (!isInstanceMethodMember(member)) continue;
+
+    // If the member doesn't have a string name, skip it.
+    const methodName = getNameText(member.name);
+    if (!methodName) continue;
+
+    const props = new Set();
+    const calledMethods = new Set();
+    collectMethodBodyUsage(member.body, props, calledMethods);
+    methodInfo.set(methodName, {
+      calledMethods,
+      isPrivate: ts.isPrivateIdentifier(member.name),
+      props
+    });
   }
 
+  // Build a Set of method names that are called from
+  // the "static html" template, the "static css" template,
+  // or computed property expressions.
   const entryMethods = new Set([
+    ...getCssCalledMethods(classNode),
     ...getTemplateCalledMethods(classNode),
     ...getComputedCalledMethods(classNode)
   ]);
   const memo = new Map();
 
-  function getTransitiveProps(methodName, seen = new Set()) {
-    // Starting from methods that are reachable from the template/computed
-    // properties, walk through nested method calls and accumulate every
-    // component property touched along the way.
-    if (memo.has(methodName)) return memo.get(methodName);
-    if (seen.has(methodName)) return new Set();
-
-    seen.add(methodName);
-    const info = methodInfo.get(methodName);
-    const props = new Set(info?.props ?? []);
-
-    if (info) {
-      for (const calledMethod of info.calledMethods) {
-        const calledProps = getTransitiveProps(calledMethod, seen);
-        for (const propName of calledProps) props.add(propName);
-      }
-    }
-
-    seen.delete(methodName);
-    memo.set(methodName, props);
-    return props;
-  }
-
   const propToMethods = new Map();
   for (const methodName of entryMethods) {
     const info = methodInfo.get(methodName);
     if (!info || info.isPrivate) continue;
 
-    if (info.isPrivate) continue;
-
-    for (const propName of getTransitiveProps(methodName)) {
+    for (const propName of getTransitiveProps(methodInfo, memo, methodName)) {
       if (!propertyNames.has(propName)) continue;
 
       let methods = propToMethods.get(propName);
@@ -315,72 +560,100 @@ function getMethodUsages(classNode, propertyNames) {
   return propToMethods;
 }
 
-function getNameText(name) {
-  if (
-    ts.isIdentifier(name) ||
-    ts.isStringLiteral(name) ||
-    ts.isPrivateIdentifier(name)
-  ) {
-    return name.text;
-  }
-  return null;
-}
-
+// Gets the text value of an AST name node.
+const getNameText = name =>
+  ts.isIdentifier(name) ||
+  ts.isStringLiteral(name) ||
+  ts.isPrivateIdentifier(name)
+    ? name.text
+    : null;
+
+// Gets the names of all methods that are called
+// from the component's static HTML template.
+// This is only called by getMethodUsages.
 function getTemplateCalledMethods(classNode) {
-  const methodNames = new Set();
-  const CALL_RE = /this\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
-
-  function visit(node) {
-    if (
-      ts.isPropertyAccessExpression(node) &&
-      node.expression.kind === ts.SyntaxKind.ThisKeyword &&
-      ts.isCallExpression(node.parent) &&
-      node.parent.expression === node
-    ) {
-      methodNames.add(node.name.text);
-    }
-
-    ts.forEachChild(node, visit);
-  }
-
-  function addTemplateTextMethods(template) {
-    // Template expressions can hide method calls inside raw template text,
-    // so use a regex in addition to AST traversal to catch those names.
-    const text = template.getText();
-    for (const match of text.matchAll(CALL_RE)) {
-      methodNames.add(match[1]);
-    }
-  }
-
+  // Find the last `static html = html\`...\`` declaration
+  // because duplicate static class fields use last-one-wins semantics.
+  let template;
   for (const member of classNode.members) {
+    // If it's a "static html =" property assignment node ...
     if (
       ts.isPropertyDeclaration(member) &&
       hasStaticModifier(member) &&
       getNameText(member.name) === 'html' &&
       member.initializer
     ) {
+      // If the value is a tagged template literal with the "html" tag ...
       if (
         ts.isTaggedTemplateExpression(member.initializer) &&
         ts.isIdentifier(member.initializer.tag) &&
         member.initializer.tag.text === 'html'
       ) {
-        addTemplateTextMethods(member.initializer.template);
+        template = member.initializer.template;
       }
-      ts.forEachChild(member.initializer, visit);
     }
   }
 
+  const methodNames = new Set();
+  if (template) {
+    // Finds all method names called in the HTML template
+    // matching `this.method()`.
+    const text = template.getText();
+    const CALL_RE = /this\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+    for (const match of text.matchAll(CALL_RE)) {
+      methodNames.add(match[1]);
+    }
+  }
   return methodNames;
 }
 
+// Recursively follow method-call chains to accumulate all accessed properties.
+// This is only called by getMethodUsages.
+function getTransitiveProps(methodInfo, memo, methodName, seen = new Set()) {
+  // Starting from methods that are reachable from
+  // css/template/computed properties, walk through nested method calls
+  // and accumulate every component property touched along the way.
+  if (memo.has(methodName)) return memo.get(methodName);
+  if (seen.has(methodName)) return new Set();
+
+  seen.add(methodName);
+  const info = methodInfo.get(methodName);
+  const props = new Set(info?.props ?? []);
+
+  if (info) {
+    for (const calledMethod of info.calledMethods) {
+      const calledProps = getTransitiveProps(
+        methodInfo,
+        memo,
+        calledMethod,
+        seen
+      );
+      for (const propName of calledProps) props.add(propName);
+    }
+  }
+
+  seen.delete(methodName);
+  memo.set(methodName, props);
+  return props;
+}
+
+// Collects imported Wrec class names. For example,
+// the following line would treat "MyWrec" as a class
+// that can be extended in order to implement a wrec component:
+//   import { Wrec as MyWrec } from 'wrec`
+// This also determines the quote character (single or double)
+// used for those imports.
 function getWrecImportInfo(sourceFile) {
+  // Start with the unaliased class name and a default quote style
+  // in case the file imports Wrec later or not at all.
   const names = new Set(['Wrec']);
   let quote = "'";
 
   // Support aliased imports such as `import {Wrec as Base} from 'wrec'`
-  // so subclass detection still works and generated text matches the
-  // file's existing quote style.
+  // so subclass detection still works.
   for (const statement of sourceFile.statements) {
+    // Ignore anything that is not an import declaration
+    // with a string module path.
     if (
       !ts.isImportDeclaration(statement) ||
       !statement.importClause ||
@@ -389,26 +662,28 @@ function getWrecImportInfo(sourceFile) {
       continue;
     }
 
+    // Only inspect imports that come from Wrec itself or its supported variants.
     const moduleName = statement.moduleSpecifier.text;
-    const isWrecModule =
-      moduleName === 'wrec' ||
-      moduleName === 'wrec/ssr' ||
-      moduleName.endsWith('/wrec') ||
-      moduleName.endsWith('/wrec-ssr');
+    const isWrecModule = moduleName === 'wrec' || moduleName.endsWith('/wrec');
     if (!isWrecModule) continue;
 
+    // Skip default or namespace imports
+    // because we only care about named imports.
     const namedBindings = statement.importClause.namedBindings;
     if (!namedBindings || !ts.isNamedImports(namedBindings)) continue;
 
     for (const element of namedBindings.elements) {
+      // Resolve the original imported name so aliased imports
+      // like `Wrec as Base` still count as Wrec imports.
       const importedName = element.propertyName?.text ?? element.name.text;
       if (importedName === 'Wrec') {
+        // Store the local identifier that this file uses to refer to Wrec.
         names.add(element.name.text);
 
+        // Capture whether the source file uses single or double quotes
+        // so generated code can follow the file's existing style.
         const moduleText = statement.moduleSpecifier.getText(sourceFile);
-        if (moduleText.startsWith('"') || moduleText.startsWith("'")) {
-          quote = moduleText[0];
-        }
+        quote = moduleText[0];
       }
     }
   }
@@ -416,12 +691,26 @@ function getWrecImportInfo(sourceFile) {
   return {names, quote};
 }
 
-function hasStaticModifier(node) {
+// Determines if a class member is static.
+function hasStaticModifier(member) {
   return Boolean(
-    node.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword)
+    member.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword)
+  );
+}
+
+// Determines if a class member represents an instance method.
+// This is only called by getMethodUsages.
+function isInstanceMethodMember(member) {
+  return (
+    !hasStaticModifier(member) &&
+    (ts.isMethodDeclaration(member) ||
+      ts.isGetAccessorDeclaration(member) ||
+      ts.isSetAccessorDeclaration(member)) &&
+    member.body
   );
 }
 
+// Determines if a path refers to a JavaScript or TypeScript source file.
 function isSupportedSourceFile(filePath, excludeTests = false) {
   return (
     /\.(js|ts)$/.test(filePath) &&
@@ -430,235 +719,61 @@ function isSupportedSourceFile(filePath, excludeTests = false) {
   );
 }
 
-function transformSourceFile(sourceFile) {
-  const edits = [];
-  const {names: wrecNames, quote} = getWrecImportInfo(sourceFile);
-  const suggestions = [];
-  let foundWrecSubclass = false;
-
-  // Each matching class contributes text replacements for the specific
-  // property config objects that need `usedBy` added, updated, or removed.
-  for (const node of sourceFile.statements) {
-    if (!ts.isClassDeclaration(node) || !extendsWrec(node, wrecNames)) continue;
-    foundWrecSubclass = true;
-
-    let propertiesObject = null;
-    for (const member of node.members) {
-      if (
-        ts.isPropertyDeclaration(member) &&
-        hasStaticModifier(member) &&
-        getNameText(member.name) === 'properties' &&
-        member.initializer &&
-        ts.isObjectLiteralExpression(member.initializer)
-      ) {
-        propertiesObject = member.initializer;
-        break;
-      }
-    }
-
-    if (!propertiesObject) continue;
-
-    const propertyNames = new Set(
-      propertiesObject.properties
-        .filter(ts.isPropertyAssignment)
-        .map(property => getNameText(property.name))
-        .filter(Boolean)
-    );
-
-    const propToMethods = getMethodUsages(node, propertyNames);
-    for (const member of propertiesObject.properties) {
-      if (!ts.isPropertyAssignment(member)) continue;
-
-      const propName = getNameText(member.name);
-      if (!propName || !ts.isObjectLiteralExpression(member.initializer))
-        continue;
-
-      const methodNames = [
-        ...(propToMethods.get(propName) ?? new Set())
-      ].sort();
-      const configObject = member.initializer;
-      const existingMembers = configObject.properties.filter(
-        property =>
-          !(
-            ts.isPropertyAssignment(property) &&
-            getNameText(property.name) === 'usedBy'
-          )
-      );
-      const hadUsedBy =
-        existingMembers.length !== configObject.properties.length;
-      if (methodNames.length > 0 || hadUsedBy) {
-        suggestions.push({
-          propName,
-          suggestion:
-            methodNames.length > 0
-              ? createUsedByProperty(methodNames, quote)
-              : 'remove usedBy'
-        });
-      }
-      const needsUsedBy = methodNames.length > 0;
-      if (!hadUsedBy && !needsUsedBy) continue;
-
-      const nextText = buildConfigText(sourceFile, member, methodNames, quote);
-      const currentText = sourceFile.text.slice(
-        configObject.getStart(sourceFile),
-        configObject.end
-      );
-      if (nextText !== currentText) {
-        edits.push({
-          start: configObject.getStart(sourceFile),
-          end: configObject.end,
-          propName,
-          oldText: currentText,
-          text: nextText
-        });
-      }
-    }
-  }
-
-  if (!foundWrecSubclass) {
-    return {
-      changed: false,
-      edits: [],
-      foundWrecSubclass: false,
-      suggestions,
-      text: sourceFile.text
-    };
-  }
-
-  if (edits.length === 0) {
-    return {
-      changed: false,
-      edits: [],
-      foundWrecSubclass: true,
-      suggestions,
-      text: sourceFile.text
-    };
-  }
-
-  let nextSource = sourceFile.text;
-  edits.sort((a, b) => b.start - a.start);
-  for (const edit of edits) {
-    nextSource =
-      nextSource.slice(0, edit.start) + edit.text + nextSource.slice(edit.end);
-  }
-
-  return {
-    changed: true,
-    edits,
-    foundWrecSubclass: true,
-    suggestions,
-    text: nextSource
-  };
-}
-
-function validateTargetFile(target, cwd = process.cwd()) {
-  if (!fs.existsSync(target)) {
-    throw new Error(`File not found: ${path.relative(cwd, target)}`);
-  }
-
-  const stat = fs.statSync(target);
-  if (!stat.isFile()) {
-    throw new Error(`Not a file: ${path.relative(cwd, target)}`);
-  }
-
-  if (!/\.(js|ts)$/.test(target) || /\.d\.ts$/.test(target)) {
-    throw new Error(`Unsupported file type: ${path.relative(cwd, target)}`);
-  }
-}
-
-export function updateUsedBySource(filePath, text) {
-  const scriptKind = filePath.endsWith('.ts')
-    ? ts.ScriptKind.TS
-    : ts.ScriptKind.JS;
-  const sourceFile = ts.createSourceFile(
-    filePath,
-    text,
-    ts.ScriptTarget.Latest,
-    true,
-    scriptKind
-  );
-
-  return transformSourceFile(sourceFile);
-}
-
-export function updateUsedByFile(filePath, options = {}) {
-  const {dry = false, quiet = false} = options;
-  const cwd = process.cwd();
-  const resolved = path.resolve(cwd, filePath);
-  validateTargetFile(resolved, cwd);
-
-  const text = fs.readFileSync(resolved, 'utf8');
-  const {
-    changed,
-    foundWrecSubclass,
-    suggestions,
-    text: nextText
-  } = updateUsedBySource(resolved, text);
-  if (!foundWrecSubclass) {
-    throw new Error('No class extending Wrec was found.');
-  }
-  if (dry) {
-    return {changed, foundWrecSubclass, suggestions, text: nextText};
-  }
-
-  if (changed) {
-    // Otherwise, apply the rewritten source text back to disk.
-    fs.writeFileSync(resolved, nextText);
-  }
-  return {changed, foundWrecSubclass, suggestions: [], text: nextText, quiet};
-}
-
-function fail(message) {
-  console.error(message);
-  process.exit(1);
-}
-
+// Handles CLI arguments and runs the script.
 function main() {
   const args = process.argv.slice(2);
-  const dry = args.includes('--dry');
-  const quiet = args.includes('--quiet');
   const inputPaths = args.filter(arg => !arg.startsWith('--'));
 
-  if (args.includes('--check')) {
-    throw new Error('Use --dry instead of --check.');
-  }
-
   if (inputPaths.length !== 1) {
-    throw new Error(
-      'Specify a single source file, e.g. npx wrec-usedby src/examples/radio-group.js'
-    );
+    throw new Error('Specify a single source file');
   }
 
-  const result = updateUsedByFile(inputPaths[0], {dry, quiet});
+  const dry = args.includes('--dry');
+  const result = evaluateSourceFile(inputPaths[0], {dry});
   if (dry) {
-    // In dry mode, report the inferred change and exit non-zero when at
-    // least one update would be needed so the script can be used in checks.
+    // Report the proposed changes.
     for (const {propName, suggestion} of result.suggestions) {
-      console.log(`${propName} - ${suggestion}`);
+      console.info(`${propName} - ${suggestion}`);
     }
-    if (!result.changed) return;
-    process.exit(1);
+
+    // Exit with a non-zero when there is at least one change
+    // so that condition can be checked.
+    if (result.changed) process.exit(1);
+  } else if (result.changed) {
+    console.info('updated source file');
+  } else {
+    console.info('no changes needed');
   }
+}
 
-  if (result.changed) console.log('updated');
+// Records a `this` property access and
+// tracks it as a method call when applicable.
+function recordThisAccess(props, calledMethods, node, name) {
+  props.add(name);
+  if (ts.isCallExpression(node.parent) && node.parent.expression === node) {
+    calledMethods.add(name);
+  }
 }
 
-const isCliEntry = (() => {
-  if (!process.argv[1]) return false;
-  try {
-    return (
-      fs.realpathSync(process.argv[1]) ===
-      fs.realpathSync(fileURLToPath(import.meta.url))
-    );
-  } catch {
-    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+// Validates that a source file exists and has a supported extension.
+function validateFile(absFilePath) {
+  if (!fs.existsSync(absFilePath)) throw new Error('File not found');
+
+  const stat = fs.statSync(absFilePath);
+  if (!stat.isFile()) throw new Error('Not a file');
+
+  if (!/\.(js|ts)$/.test(absFilePath) || /\.d\.ts$/.test(absFilePath)) {
+    throw new Error('Unsupported file type');
   }
-})();
+}
 
-if (isCliEntry) {
+// If this is being run as a script,
+// versus being imported (likely by test code) ...
+if (import.meta.main) {
   try {
     main();
   } catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
   }
 }