@atlaskit/codemod-cli 0.27.2 → 0.27.3

package/dist/es2019/presets/remove-token-fallbacks/utils/reporter.js

@@ -0,0 +1,118 @@
+/* eslint-disable no-console */
+import fs from 'fs/promises';
+import path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+async function writeToCsv(filePath, data) {
+  await fs.writeFile(filePath, data.join('\n'), 'utf-8');
+}
+async function readCsv(filePath) {
+  const data = await fs.readFile(filePath, 'utf-8');
+  return data.split('\n').filter(line => line.trim() !== '');
+}
+function escapeCsvValue(value) {
+  if (!value) {
+    return value;
+  }
+  if (value.includes('"')) {
+    // Escape double quotes by doubling them
+    value = value.replace(/"/g, '""');
+  }
+  if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+    // Surround the value with double quotes if it contains a comma, double quotes, or newlines
+    value = `"${value}"`;
+  }
+  return value;
+}
+export async function clearFolder(reportFolder) {
+  console.log('Clearing report folder:', reportFolder);
+  const filesToDelete = await fs.readdir(reportFolder);
+  for (const file of filesToDelete) {
+    const filePath = path.join(reportFolder, file);
+    await fs.unlink(filePath);
+  }
+}
+async function saveFilePaths(reportFolder, files) {
+  const filesTxtPath = path.join(reportFolder, 'files.txt');
+  await fs.writeFile(filesTxtPath, Array.from(files).map(filePath => `"${filePath}"`).join(' '), 'utf-8');
+}
+export async function combineReports(reportFolder) {
+  console.log('Combining reports in folder:', reportFolder);
+  const files = await fs.readdir(reportFolder);
+  let totalReplaced = 0;
+  let totalNotReplaced = 0;
+  const combinedReplacements = [];
+  const combinedNonReplacements = [];
+  const affectedPaths = new Set();
+  for (const file of files) {
+    const filePath = path.join(reportFolder, file);
+    if (file.endsWith('_success.csv')) {
+      const replacements = await readCsv(filePath);
+      const codeFilePaths = replacements.map(x => x.split(',')[2]);
+      for (const codeFilePath of codeFilePaths) {
+        affectedPaths.add(codeFilePath);
+      }
+      totalReplaced += replacements.length;
+      combinedReplacements.push(...replacements);
+    } else if (file.endsWith('_failed.csv')) {
+      const nonReplacements = await readCsv(filePath);
+      totalNotReplaced += nonReplacements.length;
+      combinedNonReplacements.push(...nonReplacements);
+    }
+  }
+  const totalTokens = totalReplaced + totalNotReplaced;
+  const percentageReplaced = totalTokens > 0 ? totalReplaced / totalTokens * 100 : 0;
+  await clearFolder(reportFolder);
+
+  // Write combined summary as JSON
+  const combinedSummaryPath = path.join(reportFolder, 'summary.json');
+  const summaryData = {
+    totalReplaced,
+    totalNotReplaced,
+    percentageReplaced
+  };
+  await fs.writeFile(combinedSummaryPath, JSON.stringify(summaryData, null, 2), 'utf-8');
+
+  // Sort the combined arrays
+  const sortCsvLines = lines => {
+    return lines.sort((a, b) => {
+      const aCols = a.split(',');
+      const bCols = b.split(',');
+      for (let i = 0; i < 4; i++) {
+        const comparison = aCols[i].localeCompare(bCols[i]);
+        if (comparison !== 0) {
+          return comparison;
+        }
+      }
+      return 0;
+    });
+  };
+  const sortedReplacements = sortCsvLines(combinedReplacements);
+  const sortedNonReplacements = sortCsvLines(combinedNonReplacements);
+
+  // Write combined replacements
+  const combinedReplacementsPath = path.join(reportFolder, 'success.csv');
+  const header = 'Team,Package,File,Line Number,Raw Token Key,Raw Fallback Value,Resolved Token Value,Resolved Fallback Value,Difference %';
+  await fs.writeFile(combinedReplacementsPath, [header, ...sortedReplacements].join('\n'), 'utf-8');
+
+  // Write combined non-replacements
+  const combinedNonReplacementsPath = path.join(reportFolder, 'failed.csv');
+  await fs.writeFile(combinedNonReplacementsPath, [header, ...sortedNonReplacements].join('\n'), 'utf-8');
+  // Extract unique file paths
+  await saveFilePaths(reportFolder, affectedPaths);
+}
+function prepareCsvData(items) {
+  return items.map(item => {
+    var _item$difference$toFi, _item$difference;
+    return [escapeCsvValue(item.teamInfo.teamName), escapeCsvValue(item.teamInfo.packageName), escapeCsvValue(item.filePath), escapeCsvValue(String(item.lineNumber)), escapeCsvValue(item.tokenKey), escapeCsvValue(item.rawFallbackValue), escapeCsvValue(item.resolvedTokenValue), escapeCsvValue(item.resolvedFallbackValue), escapeCsvValue((_item$difference$toFi = (_item$difference = item.difference) === null || _item$difference === void 0 ? void 0 : _item$difference.toFixed(1)) !== null && _item$difference$toFi !== void 0 ? _item$difference$toFi : '')].join(',');
+  });
+}
+export async function writeReports(details, reportFolder) {
+  const replacementsFilePath = path.join(reportFolder, `${uuidv4()}_success.csv`);
+  const nonReplacementsFilePath = path.join(reportFolder, `${uuidv4()}_failed.csv`);
+  await fs.mkdir(reportFolder, {
+    recursive: true
+  });
+  const replacementData = prepareCsvData(details.replaced);
+  const nonReplacementData = prepareCsvData(details.notReplaced);
+  await Promise.all([writeToCsv(replacementsFilePath, replacementData), writeToCsv(nonReplacementsFilePath, nonReplacementData)]);
+}

package/dist/es2019/presets/remove-token-fallbacks/utils/token-processor.js

@@ -0,0 +1,377 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+/* eslint-disable no-console */
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import { normalizeValues } from './normalize-values';
+import { addOrUpdateEslintIgnoreComment } from './update-comments';
+export class TokenProcessor {
+  constructor(j, options, fileInfo, source, rootDir, details, tokenMap, teamInfo) {
+    _defineProperty(this, "logMessages", []);
+    _defineProperty(this, "possibleExtensions", ['.ts', '.tsx', '.js', '.jsx']);
+    this.j = j;
+    this.options = options;
+    this.fileInfo = fileInfo;
+    this.source = source;
+    this.rootDir = rootDir;
+    this.details = details;
+    this.tokenMap = tokenMap;
+    this.teamInfo = teamInfo;
+  }
+  async processAndLogSingleToken(callPath) {
+    var _callPath$node$loc;
+    const line = (_callPath$node$loc = callPath.node.loc) === null || _callPath$node$loc === void 0 ? void 0 : _callPath$node$loc.start.line;
+    const {
+      shouldLog,
+      ...rest
+    } = await this.processSingleToken(callPath);
+    if (this.options.silent || !shouldLog) {
+      return rest;
+    }
+    const coloredPath = chalk.blue(this.fileInfo.path);
+    const coloredLine = line ? `: ${chalk.green(line)}` : '';
+    console.log(`${coloredPath}${coloredLine}: ${this.logMessages.join(' | ')}
+----------------------------------------`);
+    return rest;
+  }
+  logVerbose(message) {
+    if (this.options.verbose) {
+      this.log(message);
+    }
+  }
+  log(message) {
+    this.logMessages.push(message);
+  }
+  logError(message) {
+    this.log(chalk.red(message));
+  }
+  async processSingleToken(callPath) {
+    var _callPath$node$loc2;
+    const args = callPath.node.arguments;
+    const line = (_callPath$node$loc2 = callPath.node.loc) === null || _callPath$node$loc2 === void 0 ? void 0 : _callPath$node$loc2.start.line;
+    if (args.length < 2) {
+      this.logVerbose(chalk.yellow('Skipped token call without fallback'));
+      return {
+        shouldLog: false,
+        fallbackRemoved: false,
+        resolvedImportDeclaration: undefined,
+        resolvedLocalVarDeclaration: undefined
+      };
+    }
+    const tokenKey = this.getTokenKey(args[0]);
+    if (!tokenKey) {
+      return {
+        shouldLog: true,
+        fallbackRemoved: false,
+        resolvedImportDeclaration: undefined,
+        resolvedLocalVarDeclaration: undefined
+      };
+    }
+    const isSkipped = tokenKey.startsWith('elevation.shadow') || tokenKey.startsWith('font.body') || tokenKey.startsWith('font.heading');
+    const tokenValue = isSkipped ? '' : this.tokenMap[tokenKey];
+    this.logVerbose(`Token value from tokenMap: ${chalk.magenta(tokenValue)} for key: ${chalk.yellow(tokenKey)}`);
+    const {
+      rawFallbackValue,
+      fallbackValue,
+      resolvedImportDeclaration,
+      resolvedLocalVarDeclaration
+    } = isSkipped ? {
+      rawFallbackValue: 'N/A',
+      fallbackValue: undefined,
+      resolvedImportDeclaration: undefined,
+      resolvedLocalVarDeclaration: undefined
+    } : await this.getFallbackValue(args[1]);
+    const {
+      difference,
+      isAcceptableDifference,
+      tokenLogValue,
+      fallbackLogValue,
+      normalizedTokenValue,
+      normalizedFallbackValue
+    } = normalizeValues(tokenKey, tokenValue, fallbackValue);
+    const areEqual = normalizedTokenValue === normalizedFallbackValue;
+    const logData = {
+      teamInfo: this.teamInfo,
+      filePath: this.fileInfo.path,
+      lineNumber: line || -1,
+      tokenKey,
+      rawFallbackValue,
+      resolvedTokenValue: tokenValue,
+      resolvedFallbackValue: fallbackValue !== null && fallbackValue !== void 0 ? fallbackValue : '',
+      difference
+    };
+    let fallbackRemoved = false;
+    let importDeclaration;
+    let localVarDeclaration;
+    if (areEqual || isAcceptableDifference || this.options.forceUpdate) {
+      this.log(chalk.green(areEqual ? 'Token value and fallback value are equal, removing fallback' : 'Token value and fallback value are within acceptable difference threshold, removing fallback'));
+      args.pop();
+      this.details.replaced.push(logData);
+      fallbackRemoved = true;
+      importDeclaration = resolvedImportDeclaration;
+      localVarDeclaration = resolvedLocalVarDeclaration;
+    } else {
+      const message = normalizedFallbackValue === undefined ? `Fallback value could not be resolved` : `Values mismatched significantly`;
+      this.logError(message);
+      if (this.options.addEslintComments) {
+        addOrUpdateEslintIgnoreComment(this.j, tokenValue, fallbackValue, callPath);
+      }
+      this.details.notReplaced.push(logData);
+    }
+    this.log(`Token: ${chalk.yellow(tokenKey)}, Raw fallback: ${chalk.yellow(rawFallbackValue)}, Resolved token value: ${tokenLogValue}, Resolved fallback value: ${fallbackLogValue}`);
+    return {
+      shouldLog: true,
+      fallbackRemoved,
+      resolvedImportDeclaration: importDeclaration,
+      resolvedLocalVarDeclaration: localVarDeclaration
+    };
+  }
+  getTokenKey(arg) {
+    if (arg.type === 'StringLiteral') {
+      const tokenKey = arg.value;
+      this.logVerbose(`Determined token key as literal: ${chalk.yellow(tokenKey)}`);
+      return tokenKey;
+    } else {
+      this.logError(`The first argument of token function is not a string literal`);
+      return undefined;
+    }
+  }
+  async getFallbackValue(fallbackValueNode) {
+    switch (fallbackValueNode.type) {
+      case 'StringLiteral':
+        return this.processFallbackAsStringLiteral(fallbackValueNode);
+      case 'Identifier':
+        return this.processFallbackAsIdentifier(fallbackValueNode);
+      case 'MemberExpression':
+        return this.processFallbackAsMemberExpression(fallbackValueNode);
+      case 'TemplateLiteral':
+        return this.processFallbackAsTemplateLiteral(fallbackValueNode);
+      default:
+        return {
+          fallbackValue: undefined,
+          rawFallbackValue: '',
+          resolvedImportDeclaration: undefined,
+          resolvedLocalVarDeclaration: undefined
+        };
+    }
+  }
+  processFallbackAsStringLiteral(fallbackValueNode) {
+    const fallbackValue = fallbackValueNode.value;
+    this.logVerbose(`Fallback value is a literal: ${chalk.yellow(fallbackValue)}`);
+    return {
+      fallbackValue,
+      rawFallbackValue: fallbackValue,
+      resolvedImportDeclaration: undefined,
+      resolvedLocalVarDeclaration: undefined
+    };
+  }
+  async processFallbackAsIdentifier(fallbackValueNode) {
+    const variableName = fallbackValueNode.name;
+    const variableNameForLog = `${chalk.yellow(variableName)}`;
+    let fallbackValue;
+    this.logVerbose(`Fallback is an identifier: ${chalk.yellow(variableName)}, attempting to resolve...`);
+
+    // Check for local variable declaration
+    const localVarDeclaration = this.source.find(this.j.VariableDeclarator, {
+      id: {
+        name: variableName
+      }
+    }).at(0);
+    let resolvedImportDeclaration;
+    let resolvedLocalVarDeclaration;
+    if (localVarDeclaration.size()) {
+      const init = localVarDeclaration.get().value.init;
+      if (init.type === 'Literal' || init.type === 'StringLiteral') {
+        fallbackValue = init.value;
+        resolvedLocalVarDeclaration = localVarDeclaration.paths()[0];
+        this.logVerbose(`Resolved fallback value from local variable: ${chalk.yellow(fallbackValue)} for identifier: ${variableNameForLog}`);
+      }
+    } else {
+      // Check for named import
+      const importDeclaration = this.source.find(this.j.ImportDeclaration).filter(this.createImportFilter(variableName)).at(0);
+      if (importDeclaration.size()) {
+        const importSource = importDeclaration.get().value.source.value;
+        fallbackValue = await this.resolveValueFromImport(this.rootDir, importSource, undefined, variableName);
+        if (fallbackValue !== undefined) {
+          this.logVerbose(`Resolved fallback value from import: ${chalk.yellow(fallbackValue)} for identifier: ${variableNameForLog}`);
+          resolvedImportDeclaration = importDeclaration.paths()[0];
+        }
+      } else {
+        this.logVerbose(chalk.red(`Could not resolve fallback value for identifier: ${variableNameForLog}: it's neither a local variable nor an import`));
+      }
+    }
+    return {
+      rawFallbackValue: variableName,
+      fallbackValue,
+      resolvedImportDeclaration,
+      resolvedLocalVarDeclaration
+    };
+  }
+  async processFallbackAsMemberExpression(fallbackValueNode) {
+    let objectName;
+    let propertyName;
+    let fallbackValue;
+    if (fallbackValueNode.object.type === 'Identifier') {
+      objectName = fallbackValueNode.object.name;
+    }
+    if (fallbackValueNode.property.type === 'Identifier') {
+      propertyName = fallbackValueNode.property.name;
+    } else if (fallbackValueNode.property.type === 'Literal' && typeof fallbackValueNode.property.value === 'string') {
+      propertyName = fallbackValueNode.property.value;
+    }
+    if (!objectName || !propertyName) {
+      this.logError(`Could not determine object and property names from member expression: ${chalk.yellow(fallbackValueNode)}`);
+      return {
+        rawFallbackValue: '',
+        fallbackValue,
+        resolvedImportDeclaration: undefined,
+        resolvedLocalVarDeclaration: undefined
+      };
+    }
+    const rawFallbackValue = `${objectName}.${propertyName}`;
+    this.logVerbose(`Fallback is a member expression: ${chalk.yellow(rawFallbackValue)}, attempting to resolve...`);
+    let resolvedImportDeclaration;
+
+    // Find the import statement for the object
+    const importDeclaration = this.source.find(this.j.ImportDeclaration).filter(this.createImportFilter(objectName)).at(0);
+    if (importDeclaration.size()) {
+      const importSource = importDeclaration.get().value.source.value;
+      fallbackValue = await this.resolveValueFromImport(this.rootDir, importSource, objectName, propertyName);
+      if (fallbackValue !== undefined) {
+        resolvedImportDeclaration = importDeclaration.paths()[0];
+        this.logVerbose(`Resolved fallback value from member expression: ${chalk.yellow(fallbackValue)}`);
+      }
+    } else {
+      this.logError(`Could not find import for member expression: ${chalk.yellow(rawFallbackValue)}`);
+    }
+    return {
+      rawFallbackValue,
+      fallbackValue,
+      resolvedImportDeclaration,
+      resolvedLocalVarDeclaration: undefined
+    };
+  }
+  async processFallbackAsTemplateLiteral(fallbackValueNode) {
+    const expressions = fallbackValueNode.expressions;
+    let rawFallbackValue = '';
+    let fallbackValue;
+    const quasis = fallbackValueNode.quasis;
+    if (expressions.length !== 1 || quasis.length !== 2) {
+      this.logError(`Unsupported template literal structure`);
+      return {
+        rawFallbackValue,
+        fallbackValue,
+        resolvedImportDeclaration: undefined,
+        resolvedLocalVarDeclaration: undefined
+      };
+    }
+    let exprValue;
+    const expression = expressions[0];
+    let resolvedImportDeclaration;
+    let resolvedLocalVarDeclaration;
+    if (expression.type === 'Identifier') {
+      const result = await this.processFallbackAsIdentifier(expression);
+      exprValue = result.fallbackValue;
+      resolvedImportDeclaration = result.resolvedImportDeclaration;
+      resolvedLocalVarDeclaration = result.resolvedLocalVarDeclaration;
+    } else if (expression.type === 'MemberExpression') {
+      const result = await this.processFallbackAsMemberExpression(expression);
+      exprValue = result.fallbackValue;
+      resolvedImportDeclaration = result.resolvedImportDeclaration;
+    }
+    if (exprValue !== undefined) {
+      rawFallbackValue = `${quasis[0].value.raw}\${${exprValue}}${quasis[1].value.raw}`;
+      fallbackValue = `${quasis[0].value.cooked}${exprValue}${quasis[1].value.cooked}`;
+      this.logVerbose(`Resolved fallback value from template literal: ${chalk.yellow(fallbackValue)}`);
+    }
+    return {
+      rawFallbackValue,
+      fallbackValue,
+      resolvedImportDeclaration,
+      resolvedLocalVarDeclaration
+    };
+  }
+  tryResolveModulePath(moduleName) {
+    try {
+      const resolvedPath = require.resolve(moduleName, {
+        paths: [this.rootDir]
+      });
+      this.logVerbose(`Resolved module path: ${chalk.green(resolvedPath)} for ${chalk.cyan(moduleName)}`);
+      return resolvedPath;
+    } catch (error) {
+      return null;
+    }
+  }
+  async tryResolveLocalPath(currentDir, importPath) {
+    for (const ext of this.possibleExtensions) {
+      const potentialPath = path.resolve(currentDir, `${importPath}${ext}`);
+      try {
+        await fs.access(potentialPath);
+        this.logVerbose(`Resolved file path locally: ${chalk.green(potentialPath)}`);
+        return potentialPath;
+      } catch {
+        // Continue if the file is not found
+      }
+    }
+    return null;
+  }
+  async resolveValueFromImport(currentDir, importPath, objectName, propertyOrVariableName) {
+    let filePath = this.tryResolveModulePath(importPath);
+    if (!filePath) {
+      filePath = await this.tryResolveLocalPath(currentDir, importPath);
+    }
+    if (!filePath) {
+      this.logError(`File not found for import path: ${chalk.cyan(importPath)} in directory: ${chalk.blue(this.rootDir)}`);
+      return undefined;
+    }
+    this.logVerbose(`Reading file: ${chalk.green(filePath)}`);
+    const fileContent = await fs.readFile(filePath, 'utf-8');
+    const source = this.j(fileContent);
+    if (objectName) {
+      // Check if the object is imported from another module
+      const imports = source.find(this.j.ImportDeclaration);
+      const matchingImport = imports.filter(this.createImportFilter(objectName)).at(0);
+      if (matchingImport.size()) {
+        var _importDecl$source$va;
+        const importDecl = matchingImport.get().node;
+        const newImportPath = (_importDecl$source$va = importDecl.source.value) === null || _importDecl$source$va === void 0 ? void 0 : _importDecl$source$va.toString();
+        return this.resolveValueFromImport(path.dirname(filePath), newImportPath, objectName, propertyOrVariableName);
+      }
+    }
+    // If not imported, check for variable declaration
+    const varDeclaration = source.find(this.j.VariableDeclarator, {
+      id: {
+        name: propertyOrVariableName
+      }
+    }).at(0);
+    if (!varDeclaration.size()) {
+      this.logError(`Variable declaration not found for ${chalk.yellow(propertyOrVariableName)} in file: ${chalk.green(filePath)}`);
+      return undefined;
+    }
+    const init = varDeclaration.get().value.init;
+    if (init.type === 'Literal' || init.type === 'StringLiteral' || init.type === 'NumericLiteral') {
+      return init.value;
+    } else {
+      this.logError(`Unhandled init type ${init.type} for variable: ${chalk.yellow(propertyOrVariableName)} in file: ${chalk.green(filePath)}`);
+      return undefined;
+    }
+  }
+  createImportFilter(targetName) {
+    return path => {
+      var _path$node$specifiers;
+      return ((_path$node$specifiers = path.node.specifiers) === null || _path$node$specifiers === void 0 ? void 0 : _path$node$specifiers.some(specifier => {
+        var _specifier$local, _specifier$local2, _specifier$local3;
+        switch (specifier.type) {
+          case 'ImportNamespaceSpecifier':
+            return ((_specifier$local = specifier.local) === null || _specifier$local === void 0 ? void 0 : _specifier$local.name) === targetName;
+          case 'ImportDefaultSpecifier':
+            return ((_specifier$local2 = specifier.local) === null || _specifier$local2 === void 0 ? void 0 : _specifier$local2.name) === targetName;
+          case 'ImportSpecifier':
+            return ((_specifier$local3 = specifier.local) === null || _specifier$local3 === void 0 ? void 0 : _specifier$local3.name) === targetName || specifier.imported.name === targetName;
+          default:
+            return false;
+        }
+      })) === true;
+    };
+  }
+}

package/dist/es2019/presets/remove-token-fallbacks/utils/update-comments.js

@@ -0,0 +1,46 @@
+export function addOrUpdateEslintIgnoreComment(j, tokenValue, fallbackValue, callPath) {
+  const commentText = `eslint-disable-next-line @atlaskit/design-system/no-unsafe-design-token-usage -- The token value "${tokenValue}" and fallback "${fallbackValue}" do not match and can't be replaced automatically.`;
+  // first see if we can add the comment to the parent object property
+  const updatedCommentInObjectExpression = addOrUpdateEslintIgnoreCommentForParentInObjectExpression(j, commentText, callPath);
+  // if the comment was not added to the parent object property, add it to the node itself
+  if (!updatedCommentInObjectExpression) {
+    addOrUpdateEslintIgnoreCommentForNodeItself(j, commentText, callPath);
+  }
+}
+function addOrUpdateEslintIgnoreCommentForNodeItself(j, commentText, callPath) {
+  const leadingComments = callPath.node.leadingComments || [];
+  const existingCommentIndex = leadingComments.findIndex(comment => comment.value.includes('eslint-disable-next-line @atlaskit/design-system/no-unsafe-design-token-usage'));
+  const commentLine = j.commentLine(commentText, true);
+  if (existingCommentIndex !== -1) {
+    // Replace the existing comment
+    // Note: in order to modify the comment, it's fine to update it in the `leadingComments` array
+    leadingComments[existingCommentIndex] = commentLine;
+  } else {
+    // Add a new comment if none exists
+    // Note: Adding new comment to 'leadingComments' doesn't affect anything, we need to add it to 'comments' property
+    callPath.node.comments = [commentLine];
+  }
+}
+function addOrUpdateEslintIgnoreCommentForParentInObjectExpression(j, commentText, callPath) {
+  const parent = callPath.parentPath;
+  // Check if the parent node is an ObjectProperty
+  if (parent && parent.node.type === 'ObjectProperty') {
+    const grandparent = parent.parentPath;
+    // Check if the grandparent is an ObjectExpression
+    if (grandparent && grandparent.node.type === 'ObjectExpression') {
+      // Check for existing leading comments
+      const leadingComments = parent.node.leadingComments || [];
+      const existingCommentIndex = leadingComments.findIndex(comment => comment.value.includes('eslint-disable-next-line @atlaskit/design-system/no-unsafe-design-token-usage'));
+      const commentLine = j.commentLine(commentText, true);
+      if (existingCommentIndex !== -1) {
+        // Replace the existing comment
+        leadingComments[existingCommentIndex] = commentLine;
+      } else {
+        // Add a new comment if none exists
+        parent.node.comments = [commentLine, ...(parent.node.comments || [])];
+      }
+      return true;
+    }
+  }
+  return false;
+}