wrec 0.29.3 → 0.30.0

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,432 +18,60 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
 import ts from 'typescript';
-
-function buildConfigText(sourceFile, member, methodNames, quote) {
-  const {text} = sourceFile;
-  const configObject = member.initializer;
-  const existingMembers = configObject.properties.filter(
-    property =>
-      !(
-        ts.isPropertyAssignment(property) &&
-        getNameText(property.name) === 'usedBy'
-      )
-  );
-  const existingTexts = existingMembers.map(property =>
-    text.slice(property.getStart(sourceFile), property.end).trim()
-  );
-  if (methodNames.length > 0)
-    existingTexts.push(createUsedByProperty(methodNames, quote));
-
-  const original = 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}}`;
-  }
-
-  // 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}}`;
-}
-
-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);
-    }
-  }
-
-  return files;
-}
-
-function createUsedByProperty(methodNames, quote) {
-  if (methodNames.length === 1) {
-    return `usedBy: ${quote}${methodNames[0]}${quote}`;
+import {
+  extendsWrec,
+  getNameText,
+  getPropertyAssignmentNames,
+  getWrecImportInfo,
+  hasStaticModifier
+} from './ast-utils.js';
+
+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);
   }
-  return `usedBy: [${methodNames.map(name => `${quote}${name}${quote}`).join(', ')}]`;
-}
-
-function extendsWrec(node, wrecNames) {
-  return Boolean(
-    node.heritageClauses?.some(
-      clause =>
-        clause.token === ts.SyntaxKind.ExtendsKeyword &&
-        clause.types.some(
-          type =>
-            ts.isExpressionWithTypeArguments(type) &&
-            ts.isIdentifier(type.expression) &&
-            wrecNames.has(type.expression.text)
-        )
-    )
-  );
 }
 
-function getComputedCalledMethods(classNode) {
-  const methodNames = new Set();
-  const CALL_RE = /this\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+// Adds property names referenced by an object binding pattern.
+function addObjectBindingProps(props, bindingPattern) {
+  for (const element of bindingPattern.elements) {
+    if (element.dotDotDotToken) continue;
 
-  for (const member of classNode.members) {
-    if (
-      !ts.isPropertyDeclaration(member) ||
-      !hasStaticModifier(member) ||
-      getNameText(member.name) !== 'properties' ||
-      !member.initializer ||
-      !ts.isObjectLiteralExpression(member.initializer)
-    ) {
+    if (element.propertyName) {
+      const name = getNameText(element.propertyName);
+      if (name) props.add(name);
       continue;
     }
 
-    for (const property of member.initializer.properties) {
-      if (
-        !ts.isPropertyAssignment(property) ||
-        !ts.isObjectLiteralExpression(property.initializer)
-      ) {
-        continue;
-      }
-
-      for (const configProperty of property.initializer.properties) {
-        if (
-          !ts.isPropertyAssignment(configProperty) ||
-          getNameText(configProperty.name) !== 'computed'
-        ) {
-          continue;
-        }
-
-        if (!ts.isStringLiteralLike(configProperty.initializer)) continue;
-        const computed = configProperty.initializer.text;
-        for (const match of computed.matchAll(CALL_RE)) {
-          methodNames.add(match[1]);
-        }
-      }
-    }
+    addBindingName(props, element.name);
   }
-
-  return methodNames;
-}
-
-function getIndent(text, pos) {
-  const lineStart = text.lastIndexOf('\n', pos - 1) + 1;
-  const match = /^[ \t]*/.exec(text.slice(lineStart));
-  return match ? match[0] : '';
 }
 
-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});
-    }
-  }
-
-  const entryMethods = new Set([
-    ...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)) {
-      if (!propertyNames.has(propName)) continue;
-
-      let methods = propToMethods.get(propName);
-      if (!methods) {
-        methods = new Set();
-        propToMethods.set(propName, methods);
-      }
-      methods.add(methodName);
-    }
-  }
-
-  return propToMethods;
-}
-
-function getNameText(name) {
-  if (
-    ts.isIdentifier(name) ||
-    ts.isStringLiteral(name) ||
-    ts.isPrivateIdentifier(name)
-  ) {
-    return name.text;
-  }
-  return null;
-}
-
-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]);
-    }
-  }
-
-  for (const member of classNode.members) {
-    if (
-      ts.isPropertyDeclaration(member) &&
-      hasStaticModifier(member) &&
-      getNameText(member.name) === 'html' &&
-      member.initializer
-    ) {
-      if (
-        ts.isTaggedTemplateExpression(member.initializer) &&
-        ts.isIdentifier(member.initializer.tag) &&
-        member.initializer.tag.text === 'html'
-      ) {
-        addTemplateTextMethods(member.initializer.template);
-      }
-      ts.forEachChild(member.initializer, visit);
-    }
-  }
-
-  return methodNames;
-}
-
-function getWrecImportInfo(sourceFile) {
-  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.
-  for (const statement of sourceFile.statements) {
-    if (
-      !ts.isImportDeclaration(statement) ||
-      !statement.importClause ||
-      !ts.isStringLiteral(statement.moduleSpecifier)
-    ) {
-      continue;
-    }
-
-    const moduleName = statement.moduleSpecifier.text;
-    const isWrecModule =
-      moduleName === 'wrec' ||
-      moduleName === 'wrec/ssr' ||
-      moduleName.endsWith('/wrec') ||
-      moduleName.endsWith('/wrec-ssr');
-    if (!isWrecModule) continue;
-
-    const namedBindings = statement.importClause.namedBindings;
-    if (!namedBindings || !ts.isNamedImports(namedBindings)) continue;
-
-    for (const element of namedBindings.elements) {
-      const importedName = element.propertyName?.text ?? element.name.text;
-      if (importedName === 'Wrec') {
-        names.add(element.name.text);
-
-        const moduleText = statement.moduleSpecifier.getText(sourceFile);
-        if (moduleText.startsWith('"') || moduleText.startsWith("'")) {
-          quote = moduleText[0];
-        }
-      }
-    }
-  }
-
-  return {names, quote};
-}
-
-function hasStaticModifier(node) {
-  return Boolean(
-    node.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword)
-  );
-}
-
-function isSupportedSourceFile(filePath, excludeTests = false) {
-  return (
-    /\.(js|ts)$/.test(filePath) &&
-    !/\.d\.ts$/.test(filePath) &&
-    (!excludeTests || !filePath.includes('.test.'))
-  );
-}
-
-function transformSourceFile(sourceFile) {
+// 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;
 
-  // Each matching class contributes text replacements for the specific
-  // property config objects that need `usedBy` added, updated, or removed.
+  // 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) &&
@@ -456,26 +85,34 @@ function transformSourceFile(sourceFile) {
       }
     }
 
+    // Bail out if no static property named "properties" was found.
     if (!propertiesObject) continue;
 
-    const propertyNames = new Set(
-      propertiesObject.properties
-        .filter(ts.isPropertyAssignment)
-        .map(property => getNameText(property.name))
-        .filter(Boolean)
-    );
+    // Get a Set of the defined property names.
+    const propertyNames = new Set(getPropertyAssignmentNames(propertiesObject));
 
+    // 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 =>
@@ -484,25 +121,33 @@ function transformSourceFile(sourceFile) {
             getNameText(property.name) === 'usedBy'
           )
       );
-      const hadUsedBy =
-        existingMembers.length !== configObject.properties.length;
-      if (methodNames.length > 0 || hadUsedBy) {
+
+      // If the property is used by any methods ...
+      if (methodNames.length > 0) {
         suggestions.push({
           propName,
-          suggestion:
-            methodNames.length > 0
-              ? createUsedByProperty(methodNames, quote)
-              : 'remove usedBy'
+          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;
+        }
       }
-      const needsUsedBy = methodNames.length > 0;
-      if (!hadUsedBy && !needsUsedBy) 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),
@@ -515,6 +160,7 @@ function transformSourceFile(sourceFile) {
     }
   }
 
+  // If we didn't find a Wrec subclass, then there are no changes to make.
   if (!foundWrecSubclass) {
     return {
       changed: false,
@@ -525,6 +171,8 @@ function transformSourceFile(sourceFile) {
     };
   }
 
+  // If we found a Wrec subclass,
+  // but no edits for usedBy properties are needed ...
   if (edits.length === 0) {
     return {
       changed: false,
@@ -535,8 +183,13 @@ function transformSourceFile(sourceFile) {
     };
   }
 
+  // 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);
@@ -551,22 +204,169 @@ function transformSourceFile(sourceFile) {
   };
 }
 
-function validateTargetFile(target, cwd = process.cwd()) {
-  if (!fs.existsSync(target)) {
-    throw new Error(`File not found: ${path.relative(cwd, target)}`);
+// 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 configObject = member.initializer;
+
+  // Get an array of AST nodes for all the config object properties
+  // except `usedBy`.
+  const existingMembers = configObject.properties.filter(
+    property =>
+      !(
+        ts.isPropertyAssignment(property) &&
+        getNameText(property.name) === 'usedBy'
+      )
+  );
+
+  // 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 this property is used by any methods,
+  // add a usedBy property that lists them.
+  if (methodNames.length > 0) {
+    propertyStrings.push(createUsedByProperty(methodNames, quote));
   }
 
-  const stat = fs.statSync(target);
-  if (!stat.isFile()) {
-    throw new Error(`Not a file: ${path.relative(cwd, target)}`);
+  const existingPropertiesString = text.slice(
+    configObject.getStart(sourceFile),
+    configObject.end
+  );
+
+  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}}`;
   }
 
-  if (!/\.(js|ts)$/.test(target) || /\.d\.ts$/.test(target)) {
-    throw new Error(`Unsupported file type: ${path.relative(cwd, target)}`);
+  // 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}}`;
+}
+
+// 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);
+    }
   }
+
+  ts.forEachChild(node, child =>
+    collectMethodBodyUsage(child, props, calledMethods)
+  );
+}
+
+// Returns a string for a usedBy property.
+function createUsedByProperty(methodNames, quote) {
+  const value =
+    methodNames.length === 1
+      ? `${quote}${methodNames[0]}${quote}`
+      : `[${methodNames.map(name => `${quote}${name}${quote}`).join(', ')}]`;
+  return `usedBy: ${value}`;
 }
 
-export function updateUsedBySource(filePath, text) {
+// 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 {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;
@@ -577,88 +377,319 @@ export function updateUsedBySource(filePath, text) {
     true,
     scriptKind
   );
+  return analyzeSourceFile(sourceFile);
+}
+
+// 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;
 
-  return transformSourceFile(sourceFile);
+  // 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;
 }
 
-export function updateUsedByFile(filePath, options = {}) {
-  const {dry = false, quiet = false} = options;
-  const cwd = process.cwd();
-  const resolved = path.resolve(cwd, filePath);
-  validateTargetFile(resolved, cwd);
+// 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;
 
-  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.');
+  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)
+    ) {
+      // 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 (dry) {
-    return {changed, foundWrecSubclass, suggestions, text: nextText};
+
+  // 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 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(configProperty) ||
+        getNameText(configProperty.name) !== 'computed'
+      ) {
+        continue;
+      }
+
+      // If the property value isn't a string then skip it.
+      if (!ts.isStringLiteralLike(configProperty.initializer)) continue;
+
+      // 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]);
+      }
+    }
+  }
+
+  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 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();
+
+  const propToMethods = new Map();
+  for (const methodName of entryMethods) {
+    const info = methodInfo.get(methodName);
+    if (!info || info.isPrivate) continue;
+
+    for (const propName of getTransitiveProps(methodInfo, memo, methodName)) {
+      if (!propertyNames.has(propName)) continue;
+
+      let methods = propToMethods.get(propName);
+      if (!methods) {
+        methods = new Set();
+        propToMethods.set(propName, methods);
+      }
+      methods.add(methodName);
+    }
+  }
+
+  return propToMethods;
+}
+
+// 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) {
+  // 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'
+      ) {
+        template = member.initializer.template;
+      }
+    }
   }
 
-  if (changed) {
-    // Otherwise, apply the rewritten source text back to disk.
-    fs.writeFileSync(resolved, nextText);
+  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 {changed, foundWrecSubclass, suggestions: [], text: nextText, quiet};
+  return methodNames;
 }
 
-function fail(message) {
-  console.error(message);
-  process.exit(1);
+// 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;
 }
 
+// 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) &&
+    !/\.d\.ts$/.test(filePath) &&
+    (!excludeTests || !filePath.includes('.test.'))
+  );
+}
+
+// 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);
   }
 }