ts-codemod-lib 3.3.1 → 3.3.3

package/src/functions/ast-transformers/transform-source-code.mts

@@ -2,80 +2,179 @@ import { Arr } from 'ts-data-forge';
 import * as tsm from 'ts-morph';
 import { type TsMorphTransformer } from './types.mjs';
 
-const extractFileIgnoreTransformers = (code: string): readonly string[] => {
-  // Try to find any of the supported file-level ignore comment prefixes
-  const patterns = [
-    {
-      prefix: 'transformer-ignore',
-      regex: /\/\*\s*transformer-ignore\s*(.*?)\s*\*\//u,
-    },
-    {
-      prefix: 'ts-codemod-ignore',
-      regex: /\/\*\s*ts-codemod-ignore\s*(.*?)\s*\*\//u,
-    },
-    {
-      prefix: 'codemod-ignore',
-      regex: /\/\*\s*codemod-ignore\s*(.*?)\s*\*\//u,
-    },
-    {
-      prefix: 'transform-ignore',
-      regex: /\/\*\s*transform-ignore\s*(.*?)\s*\*\//u,
-    },
-  ] as const;
+const fileIgnorePrefixes = [
+  'transformer-ignore',
+  'ts-codemod-ignore',
+  'codemod-ignore',
+  'transform-ignore',
+] as const;
+
+/**
+ * Finds the file-level ignore comment `/* <prefix> name, name *\/` and returns
+ * the transformer names it lists (empty for all transformers), or `undefined`
+ * when the file has none. Whitespace, line breaks included, may surround the
+ * prefix and the names, but the names themselves must stay on one line. The
+ * prefixes are tried in order, each against the whole file.
+ *
+ * The scan runs in time linear in the length of `code`, whatever it contains.
+ */
+const findFileIgnoreTransformers = (
+  code: string,
+): readonly string[] | undefined => {
+  for (const prefix of fileIgnorePrefixes) {
+    const names = findFileIgnoreComment(code, prefix);
+
+    if (names !== undefined) {
+      return names;
+    }
+  }
 
-  for (const { regex } of patterns) {
-    const match = regex.exec(code);
+  return undefined;
+};
 
-    if (match !== null) {
-      const targetTransformers = match[1]?.trim() ?? '';
+const findFileIgnoreComment = (
+  code: string,
+  prefix: string,
+): readonly string[] | undefined => {
+  // Queries into these searches only move forward, so each part of `code` is
+  // scanned a bounded number of times.
+  const findCommentEnd = createForwardSearch((from) =>
+    code.indexOf('*/', from),
+  );
 
-      // Empty means ignore all transformers
-      if (targetTransformers === '') {
-        return [];
-      }
+  const findLineTerminator = createForwardSearch((from) =>
+    indexOfLineTerminator(code, from),
+  );
+
+  const trimEndBefore = createLastValueCache((commentEnd: number) =>
+    skipWhitespaceBackward(code, commentEnd),
+  );
+
+  for (
+    let mut_open = code.indexOf('/*');
+    mut_open !== -1;
+    mut_open = code.indexOf('/*', mut_open + 2)
+  ) {
+    const prefixStart = skipWhitespace(code, mut_open + 2);
+
+    if (!code.startsWith(prefix, prefixStart)) {
+      continue;
+    }
+
+    const namesStart = skipWhitespace(code, prefixStart + prefix.length);
+
+    const commentEnd = findCommentEnd(namesStart);
+
+    // Nothing after this point is closed, so no later comment can match.
+    if (commentEnd === -1) {
+      return undefined;
+    }
+
+    const namesEnd = Math.max(namesStart, trimEndBefore(commentEnd));
 
-      // Parse comma-separated transformer names
-      return targetTransformers.split(',').map((name) => name.trim());
+    const lineTerminator = findLineTerminator(namesStart);
+
+    if (lineTerminator === -1 || lineTerminator >= namesEnd) {
+      const names = code.slice(namesStart, namesEnd);
+
+      // Empty means ignore all transformers; otherwise parse comma-separated
+      // transformer names
+      return names === '' ? [] : names.split(',').map((name) => name.trim());
     }
   }
 
-  return [];
+  return undefined;
 };
 
 const shouldSkipFile = (
-  code: string,
-  transformerName: string | undefined,
-): boolean => {
-  const ignoredTransformers = extractFileIgnoreTransformers(code);
-
-  // If no file-level ignore comment found, don't skip
-  const patterns = [
-    /\/\*\s*transformer-ignore\s*.*?\s*\*\//u,
-    /\/\*\s*ts-codemod-ignore\s*.*?\s*\*\//u,
-    /\/\*\s*codemod-ignore\s*.*?\s*\*\//u,
-    /\/\*\s*transform-ignore\s*.*?\s*\*\//u,
-  ] as const;
-
-  const hasFileIgnoreComment = patterns.some((regex) => regex.test(code));
-
-  if (!hasFileIgnoreComment && Arr.isEmpty(ignoredTransformers)) {
-    return false;
+  ignoredTransformers: readonly string[] | undefined,
+  transformerName: string,
+): boolean =>
+  ignoredTransformers !== undefined &&
+  // Empty array means ignore all transformers (file-level ignore without
+  // specific transformers); otherwise check if the transformer is in the
+  // ignore list
+  (Arr.isEmpty(ignoredTransformers) ||
+    ignoredTransformers.includes(transformerName));
+
+/**
+ * Wraps a search returning the first index at or after `from` (or -1), reusing
+ * the previous answer while it still holds for a later `from`.
+ */
+const createForwardSearch = (
+  search: (from: number) => number,
+): ((from: number) => number) => {
+  let mut_from = Number.POSITIVE_INFINITY;
+
+  let mut_found = -1;
+
+  return (from) => {
+    if (from < mut_from || (mut_found !== -1 && from > mut_found)) {
+      mut_from = from;
+
+      mut_found = search(from);
+    }
+
+    return mut_found;
+  };
+};
+
+const createLastValueCache = (
+  fn: (arg: number) => number,
+): ((arg: number) => number) => {
+  let mut_arg: number | undefined = undefined;
+
+  let mut_value = 0;
+
+  return (arg) => {
+    if (arg !== mut_arg) {
+      mut_arg = arg;
+
+      mut_value = fn(arg);
+    }
+
+    return mut_value;
+  };
+};
+
+const skipWhitespace = (code: string, from: number): number => {
+  let mut_index = from;
+
+  while (mut_index < code.length && isWhitespace(code[mut_index])) {
+    mut_index += 1;
   }
 
-  // Empty array means ignore all transformers (file-level ignore without specific transformers)
-  if (Arr.isEmpty(ignoredTransformers)) {
-    return true;
+  return mut_index;
+};
+
+const skipWhitespaceBackward = (code: string, end: number): number => {
+  let mut_index = end;
+
+  while (mut_index > 0 && isWhitespace(code[mut_index - 1])) {
+    mut_index -= 1;
   }
 
-  // If transformer name is not specified, don't skip
-  if (transformerName === undefined) {
-    return false;
+  return mut_index;
+};
+
+const indexOfLineTerminator = (code: string, from: number): number => {
+  let mut_index = from;
+
+  while (mut_index < code.length && !isLineTerminator(code[mut_index])) {
+    mut_index += 1;
   }
 
-  // Check if the transformer is in the ignore list
-  return ignoredTransformers.includes(transformerName);
+  return mut_index < code.length ? mut_index : -1;
 };
 
+// Same set as `\s` and `String.prototype.trim`
+const isWhitespace = (char: string | undefined): boolean =>
+  char !== undefined && /^\s$/u.test(char);
+
+// The characters `.` does not match
+const isLineTerminator = (char: string | undefined): boolean =>
+  char !== undefined && /^[\n\r\u{2028}\u{2029}]$/u.test(char);
+
 export const transformSourceCode = (
   code: string,
   isTsx: boolean,
@@ -96,10 +195,12 @@ export const transformSourceCode = (
     code,
   );
 
+  const ignoredTransformers = findFileIgnoreTransformers(code);
+
   for (const transformer of transformers) {
     const transformerName = transformer.name;
 
-    if (shouldSkipFile(code, transformerName)) {
+    if (shouldSkipFile(ignoredTransformers, transformerName)) {
       if (debug) {
         console.debug(
           `skipped by ignore-file comment for transformer: ${transformerName}`,

package/src/functions/ast-transformers/transform-source-code.test.mts

@@ -0,0 +1,123 @@
+import { replaceAnyWithUnknownTransformer } from './replace-any-with-unknown.mjs';
+import { transformSourceCode } from './transform-source-code.mjs';
+
+const body = 'export const x: any = 1;\n';
+
+const transformedBody = 'export const x: unknown = 1;\n';
+
+const transform = (code: string): string =>
+  transformSourceCode(code, false, [replaceAnyWithUnknownTransformer()]);
+
+describe('transformSourceCode file-level ignore comments', () => {
+  test.each([
+    {
+      name: 'no ignore comment',
+      header: '',
+      skipped: false,
+    },
+    {
+      name: 'ignore all transformers',
+      header: '/* transformer-ignore */\n',
+      skipped: true,
+    },
+    {
+      name: 'ignore all transformers without spaces',
+      header: '/*transformer-ignore*/\n',
+      skipped: true,
+    },
+    {
+      name: 'ignore the running transformer',
+      header: '/* transformer-ignore replace-any-with-unknown */\n',
+      skipped: true,
+    },
+    {
+      name: 'ignore the running transformer among others',
+      header:
+        '/* transformer-ignore append-as-const, replace-any-with-unknown */\n',
+      skipped: true,
+    },
+    {
+      name: 'ignore another transformer only',
+      header: '/* transformer-ignore append-as-const */\n',
+      skipped: false,
+    },
+    {
+      name: 'ts-codemod-ignore prefix',
+      header: '/* ts-codemod-ignore */\n',
+      skipped: true,
+    },
+    {
+      name: 'codemod-ignore prefix',
+      header: '/* codemod-ignore replace-any-with-unknown */\n',
+      skipped: true,
+    },
+    {
+      name: 'transform-ignore prefix',
+      header: '/* transform-ignore */\n',
+      skipped: true,
+    },
+    {
+      name: 'names on the first line and the terminator on the next',
+      header: '/* transformer-ignore replace-any-with-unknown\n */\n',
+      skipped: true,
+    },
+    {
+      name: 'prefix on the first line and names on the next',
+      header: '/*\n  transformer-ignore\n  replace-any-with-unknown */\n',
+      skipped: true,
+    },
+    {
+      name: 'names spanning several lines are not an ignore comment',
+      header: '/* transformer-ignore append-as-const\n  note */\n',
+      skipped: false,
+    },
+    {
+      name: 'an unterminated comment is not an ignore comment',
+      header: '// /* transformer-ignore\n',
+      skipped: false,
+    },
+    {
+      name: 'a later well-formed comment is found after a malformed one',
+      header:
+        '/* transformer-ignore a\n b */\n/* transformer-ignore replace-any-with-unknown */\n',
+      skipped: true,
+    },
+    {
+      name: 'prefixes are tried in order, not by position',
+      header:
+        '/* codemod-ignore */\n/* transformer-ignore append-as-const */\n',
+      skipped: false,
+    },
+  ] as const)('$name', ({ header, skipped }) => {
+    assert.strictEqual(
+      transform(`${header}${body}`),
+      `${header}${skipped ? body : transformedBody}`,
+    );
+  });
+
+  test(
+    'finishes in linear time on long whitespace runs in unterminated comments',
+    { timeout: 2000 },
+    () => {
+      const header = `/* transformer-ignore${' '.repeat(2000)}x\nnote */\n`;
+
+      assert.strictEqual(
+        transform(`${header}${body}`),
+        `${header}${transformedBody}`,
+      );
+    },
+  );
+
+  test(
+    'finishes in linear time on many unterminated comments in one line',
+    { timeout: 2000 },
+    () => {
+      const header = `export const s = \`${'/* transformer-ignore x '.repeat(10_000)}\`;\n`;
+
+      assert.strictEqual(
+        transform(`${header}${body}`),
+        `${header}${transformedBody}`,
+      );
+    },
+  );
+});

package/src/functions/functions/has-call-or-construct-signature.mts

@@ -0,0 +1,120 @@
+import * as tsm from 'ts-morph';
+
+/**
+ * Determines whether a node is a type literal or an interface that declares a
+ * call or construct signature.
+ *
+ * `Readonly<T>` is a mapped type over `keyof T`, and neither signature kind is a
+ * property, so neither survives the mapping: wrapping `{ (x: string): void }`
+ * with `Readonly` produces a type that is no longer callable. A type mixing
+ * properties with a call signature is worse still — the properties come through
+ * and only the signature disappears. So a type literal carrying one must not be
+ * wrapped; its members are marked `readonly` in place instead.
+ *
+ * @param node - The node to check
+ * @returns true if the node declares at least one call or construct signature,
+ *   false for any other node kind
+ */
+export const hasCallOrConstructSignature = (node: tsm.Node): boolean =>
+  (node.isKind(tsm.SyntaxKind.TypeLiteral) ||
+    node.isKind(tsm.SyntaxKind.InterfaceDeclaration)) &&
+  node
+    .getMembers()
+    .some(
+      (member) =>
+        member.isKind(tsm.SyntaxKind.CallSignature) ||
+        member.isKind(tsm.SyntaxKind.ConstructSignature),
+    );
+
+if (import.meta.vitest !== undefined) {
+  const getFirstNodeOfKind = (
+    sourceCode: string,
+    kind: tsm.SyntaxKind,
+  ): tsm.Node => {
+    const project = new tsm.Project({ useInMemoryFileSystem: true });
+
+    const sourceFile = project.createSourceFile('test.ts', sourceCode);
+
+    return sourceFile.getFirstDescendantByKindOrThrow(kind);
+  };
+
+  const getTypeLiteral = (sourceCode: string): tsm.Node =>
+    getFirstNodeOfKind(sourceCode, tsm.SyntaxKind.TypeLiteral);
+
+  describe('hasCallOrConstructSignature', () => {
+    test.each([
+      { name: 'call signature', code: 'type T = { (a: string): void };' },
+      { name: 'construct signature', code: 'type T = { new (a: string): X };' },
+      {
+        name: 'call signature mixed with a property',
+        code: 'type T = { (a: string): void; b: number };',
+      },
+      {
+        name: 'overloaded call signatures',
+        code: 'type T = { (a: string): void; (a: number): void };',
+      },
+    ])('is true for a type literal with a $name', ({ code }) => {
+      assert.isTrue(hasCallOrConstructSignature(getTypeLiteral(code)));
+    });
+
+    test.each([
+      { name: 'properties only', code: 'type T = { a: number; b: string };' },
+      { name: 'an index signature', code: 'type T = { [k: string]: number };' },
+      {
+        name: 'a method signature',
+        code: 'type T = { a(b: string): void };',
+      },
+      {
+        name: 'a function-typed property',
+        code: 'type T = { a: (b: string) => void };',
+      },
+      { name: 'no members', code: 'type T = {};' },
+    ])('is false for a type literal with $name', ({ code }) => {
+      assert.isFalse(hasCallOrConstructSignature(getTypeLiteral(code)));
+    });
+
+    test('is true for an interface with a call signature', () => {
+      assert.isTrue(
+        hasCallOrConstructSignature(
+          getFirstNodeOfKind(
+            'interface I { (a: string): void }',
+            tsm.SyntaxKind.InterfaceDeclaration,
+          ),
+        ),
+      );
+    });
+
+    test('is false for an interface without one', () => {
+      assert.isFalse(
+        hasCallOrConstructSignature(
+          getFirstNodeOfKind(
+            'interface I { a: string }',
+            tsm.SyntaxKind.InterfaceDeclaration,
+          ),
+        ),
+      );
+    });
+
+    test.each([
+      {
+        name: 'a function type',
+        code: 'type T = (a: string) => void;',
+        kind: tsm.SyntaxKind.FunctionType,
+      },
+      {
+        name: 'a constructor type',
+        code: 'type T = new (a: string) => X;',
+        kind: tsm.SyntaxKind.ConstructorType,
+      },
+      {
+        name: 'a class declaration',
+        code: 'class C { constructor(a: string) {} }',
+        kind: tsm.SyntaxKind.ClassDeclaration,
+      },
+    ])('is false for $name', ({ code, kind }) => {
+      assert.isFalse(
+        hasCallOrConstructSignature(getFirstNodeOfKind(code, kind)),
+      );
+    });
+  });
+}

package/src/functions/functions/index.mts

@@ -1,3 +1,4 @@
+export * from './has-call-or-construct-signature.mjs';
 export * from './has-disable-next-line-comment.mjs';
 export * from './is-as-const-node.mjs';
 export * from './is-atomic-type-node.mjs';

package/src/functions/functions/should-avoid-parentheses-for-readonly.mts

@@ -16,13 +16,9 @@ import * as tsm from 'ts-morph';
 export const shouldAvoidParenthesesForReadonly = (node: tsm.Node): boolean => {
   const parent = node.getParent();
 
-  if (parent === undefined) {
-    return false;
-  }
-
   // Check if parent is TypePredicate: x is T
   // In this case, we MUST avoid parentheses: x is readonly T (not x is (readonly T))
   // because `x is (readonly T)` is a syntax error
   // For all other cases, keep parentheses for safety
-  return parent.isKind(tsm.SyntaxKind.TypePredicate);
+  return parent?.isKind(tsm.SyntaxKind.TypePredicate) ?? false;
 };

package/src/functions/functions/wrap-with-parentheses.mts

@@ -1,13 +1,3 @@
-/**
- * Checks if a string is already wrapped with a single pair of balanced parentheses
- * that encompasses the entire expression.
- *
- * @example
- * isWrappedWithParentheses('(A)') // true
- * isWrappedWithParentheses('((A))') // true (outer pair wraps everything)
- * isWrappedWithParentheses('(A) | (B)') // false (outer parens don't wrap everything)
- * isWrappedWithParentheses('A') // false
- */
 import { asUint32, range } from 'ts-data-forge';
 
 const parenDepthDelta = (char: string | undefined): number => {
@@ -26,6 +16,19 @@ const parenDepthDelta = (char: string | undefined): number => {
   }
 };
 
+/**
+ * Checks if a string is already wrapped with a single pair of balanced
+ * parentheses that encompasses the entire expression.
+ *
+ * `'(A)'` and `'((A))'` are wrapped — in the second the outer pair still spans
+ * everything — while `'A'` is not, and neither is `'(A) | (B)'`, whose first
+ * parenthesis closes before the end.
+ *
+ * Module-local, so `samples/` — which imports the package the way a consumer
+ * does — cannot reach it, and it therefore carries no `@example`. See
+ * {@link wrapWithParentheses}, the exported form, whose example covers the
+ * same cases.
+ */
 const isWrappedWithParentheses = (str: string): boolean => {
   const trimmed = str.trim();
 
@@ -55,18 +58,25 @@ const isWrappedWithParentheses = (str: string): boolean => {
  * fully wrapped with balanced parentheses.
  *
  * @example
- * wrapWithParentheses('A') // '(A)'
- * wrapWithParentheses('(A)') // '(A)' (not '((A))')
- * wrapWithParentheses('A | B') // '(A | B)'
- * wrapWithParentheses('(A | B)') // '(A | B)' (not '((A | B))')
- * wrapWithParentheses('(A) | (B)') // '((A) | (B))' (needs outer parens)
+ *
+ * ```ts
+ * assert.deepStrictEqual(wrapWithParentheses('A'), '(A)');
+ *
+ * // already wrapped, so not '((A))'
+ * assert.deepStrictEqual(wrapWithParentheses('(A)'), '(A)');
+ *
+ * assert.deepStrictEqual(wrapWithParentheses('A | B'), '(A | B)');
+ *
+ * assert.deepStrictEqual(wrapWithParentheses('(A | B)'), '(A | B)');
+ *
+ * // the outer parentheses do not span everything, so a pair is added
+ * assert.deepStrictEqual(wrapWithParentheses('(A) | (B)'), '((A) | (B))');
+ * ```
  */
 export const wrapWithParentheses = (nodeStr: string): string => {
   const trimmed = nodeStr.trim();
 
-  if (isWrappedWithParentheses(trimmed)) {
-    return trimmed;
-  }
-
-  return `(${trimmed})` as const;
+  return isWrappedWithParentheses(trimmed)
+    ? trimmed
+    : (`(${trimmed})` as const);
 };