ts-codemod-lib 4.0.0 → 4.1.0

package/src/functions/functions/has-disable-next-line-comment.mts

@@ -84,9 +84,9 @@ export const hasDisableNextLineComment = (
         }
       }
 
-      // If we found *any* comment on the preceding line, but it wasn't
-      // the correct ignore comment, then the node is not ignored by
-      // a comment on the *immediately* preceding line. Stop checking further back.
+      // If we found *any* comment on the preceding line, but it wasn't the
+      // correct ignore comment, then the node is not ignored by a comment on
+      // the *immediately* preceding line. Stop checking further back.
       return false;
     }
 
@@ -99,38 +99,6 @@ export const hasDisableNextLineComment = (
   return false;
 };
 
-/**
- * The 1-based line number of a position in `sourceFile`, counted the way
- * ts-morph's `getStartLineNumber` and `getLineAndColumnAtPos` count it: one
- * plus the number of `\n` before the position (a lone `\r` starts no line,
- * unlike in the compiler's own line map).
- *
- * ts-morph scans the text from its start on every call, which made this
- * check, asked of every node a transformer visits, quadratic in the size of
- * the file. The newline positions are collected once per compiler source file
- * instead. ts-morph replaces that object whenever the file is edited, so an
- * entry never outlives the text it was collected from.
- */
-const lineNumberLookup = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  sourceFile: tsm.ts.SourceFile,
-): ((pos: number) => number) => {
-  const cached = newlinePositionsCache.get(sourceFile);
-
-  const newlinePositions = cached ?? newlinePositionsOf(sourceFile.text);
-
-  if (cached === undefined) {
-    newlinePositionsCache.set(sourceFile, newlinePositions);
-  }
-
-  return (pos) => countLessThan(newlinePositions, pos) + 1;
-};
-
-const newlinePositionsCache = new WeakMap<
-  tsm.ts.SourceFile,
-  readonly number[]
->();
-
 const newlinePositionsOf = (text: string): readonly number[] => {
   const mut_positions: number[] = [];
 
@@ -164,3 +132,35 @@ const countLessThan = (sorted: readonly number[], value: number): number => {
 
   return mut_low;
 };
+
+/**
+ * The 1-based line number of a position in `sourceFile`, counted the way
+ * ts-morph's `getStartLineNumber` and `getLineAndColumnAtPos` count it: one
+ * plus the number of `\n` before the position (a lone `\r` starts no line,
+ * unlike in the compiler's own line map).
+ *
+ * ts-morph scans the text from its start on every call, which made this
+ * check, asked of every node a transformer visits, quadratic in the size of the
+ * file. The newline positions are collected once per compiler source file
+ * instead. ts-morph replaces that object whenever the file is edited, so an
+ * entry never outlives the text it was collected from.
+ */
+const lineNumberLookup = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceFile: tsm.ts.SourceFile,
+): ((pos: number) => number) => {
+  const cached = newlinePositionsCache.get(sourceFile);
+
+  const newlinePositions = cached ?? newlinePositionsOf(sourceFile.text);
+
+  if (cached === undefined) {
+    newlinePositionsCache.set(sourceFile, newlinePositions);
+  }
+
+  return (pos) => countLessThan(newlinePositions, pos) + 1;
+};
+
+const newlinePositionsCache = new WeakMap<
+  tsm.ts.SourceFile,
+  readonly number[]
+>();

package/src/functions/functions/is-readonly-node.mts

@@ -30,6 +30,31 @@ export const isReadonlyArrayTypeNode = (
   node.getOperator() === tsm.SyntaxKind.ReadonlyKeyword &&
   node.getTypeNode().isKind(tsm.SyntaxKind.ArrayType);
 
+export const isReadonlyTupleTypeNode = (
+  node: DeepReadonly<tsm.Node>,
+): node is ReadonlyTupleTypeNode =>
+  node.isKind(tsm.SyntaxKind.TypeOperator) &&
+  node.getOperator() === tsm.SyntaxKind.ReadonlyKeyword &&
+  node.getTypeNode().isKind(tsm.SyntaxKind.TupleType);
+
+export const isReadonlyTypeReferenceNode = (
+  node: DeepReadonly<tsm.Node>,
+): node is ReadonlyTypeReferenceNode => {
+  if (!node.isKind(tsm.SyntaxKind.TypeReference)) {
+    return false;
+  }
+
+  const typeName = node.getTypeName();
+
+  const typeArguments = node.getTypeArguments();
+
+  return (
+    typeName.isKind(tsm.SyntaxKind.Identifier) &&
+    typeName.getText() === 'Readonly' &&
+    Arr.isFixedLengthArray(1, typeArguments)
+  );
+};
+
 // Helper to get a specific type node from source code
 const getTypeNodeFromSource = (
   sourceCode: string,
@@ -97,13 +122,6 @@ export type ReadonlyTupleTypeNode = tsm.TypeNode &
     getTypeNode: () => tsm.TupleTypeNode;
   }>;
 
-export const isReadonlyTupleTypeNode = (
-  node: DeepReadonly<tsm.Node>,
-): node is ReadonlyTupleTypeNode =>
-  node.isKind(tsm.SyntaxKind.TypeOperator) &&
-  node.getOperator() === tsm.SyntaxKind.ReadonlyKeyword &&
-  node.getTypeNode().isKind(tsm.SyntaxKind.TupleType);
-
 if (import.meta.vitest !== undefined) {
   describe('isReadonlyTupleTypeNode', () => {
     test('should return true for readonly tuple type', () => {
@@ -162,24 +180,6 @@ export type ReadonlyTypeReferenceNode = tsm.TypeNode &
     getTypeArguments: () => readonly [tsm.TypeNode];
   }>;
 
-export const isReadonlyTypeReferenceNode = (
-  node: DeepReadonly<tsm.Node>,
-): node is ReadonlyTypeReferenceNode => {
-  if (!node.isKind(tsm.SyntaxKind.TypeReference)) {
-    return false;
-  }
-
-  const typeName = node.getTypeName();
-
-  const typeArguments = node.getTypeArguments();
-
-  return (
-    typeName.isKind(tsm.SyntaxKind.Identifier) &&
-    typeName.getText() === 'Readonly' &&
-    Arr.isFixedLengthArray(1, typeArguments)
-  );
-};
-
 if (import.meta.vitest !== undefined) {
   describe('isReadonlyTypeReferenceNode', () => {
     test('should return true for Readonly<T>', () => {

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

@@ -1,21 +1,107 @@
-import { asUint32, range } from 'ts-data-forge';
+import * as tsm from 'ts-morph';
 
-const parenDepthDelta = (char: string | undefined): number => {
-  switch (char) {
-    case '(':
-      return 1;
-
-    case ')':
-      return -1;
+/**
+ * Wraps a string with parentheses if not already wrapped.
+ * Avoids adding redundant parentheses when the expression is already fully
+ * wrapped with balanced parentheses.
+ *
+ * @example
+ *
+ * ```ts
+ * assert.strictEqual(wrapWithParentheses('A'), '(A)');
+ *
+ * // already wrapped, so not '((A))'
+ * assert.strictEqual(wrapWithParentheses('(A)'), '(A)');
+ *
+ * assert.strictEqual(wrapWithParentheses('A | B'), '(A | B)');
+ *
+ * assert.strictEqual(wrapWithParentheses('(A | B)'), '(A | B)');
+ *
+ * // the outer parentheses do not span everything, so a pair is added
+ * assert.strictEqual(wrapWithParentheses('(A) | (B)'), '((A) | (B))');
+ * ```
+ */
+export const wrapWithParentheses = (nodeStr: string): string => {
+  const trimmed = nodeStr.trim();
 
-    // `at` returns `undefined` past the end of the string. The loop below
-    // never asks for such an index, but the type says it can.
-    case undefined:
-    default:
-      return 0;
-  }
+  return isWrappedWithParentheses(trimmed)
+    ? trimmed
+    : (`(${trimmed})` as const);
 };
 
+/**
+ * What {@link isWrappedWithParentheses} tracks while scanning. `parenDepth` is
+ * the only verdict; `openBraces` tells the `}` that closes a template
+ * substitution from one that closes a type literal.
+ */
+type ScanState = Readonly<{
+  parenDepth: number;
+  /**
+   * One character per brace still open, innermost last: `{` for a type
+   * literal's, `$` for a template substitution's (`${`).
+   */
+  openBraces: string;
+}>;
+
+type ScanStep = (state: ScanState, scanner: tsm.ts.Scanner) => ScanState;
+
+const initialScanState: ScanState = {
+  parenDepth: 0,
+  openBraces: '',
+} as const;
+
+/**
+ * Tokens after which the scan cannot be trusted. The scanner reads without a
+ * parser, so it cannot tell a regular expression literal from a division: a
+ * quote or parenthesis inside `/"/` or `/\(/` would be read as a string or a
+ * parenthesis, and could balance by accident. No type contains one of these.
+ */
+const untrustedTokens: ReadonlySet<tsm.ts.SyntaxKind> =
+  new Set<tsm.ts.SyntaxKind>([
+    tsm.ts.SyntaxKind.SlashToken,
+    tsm.ts.SyntaxKind.SlashEqualsToken,
+    tsm.ts.SyntaxKind.Unknown,
+  ]);
+
+/**
+ * How each token that matters moves the state; every other token leaves it as
+ * is. A map rather than a `switch`, which would have to name every
+ * `SyntaxKind`.
+ */
+const scanStep: ReadonlyMap<tsm.ts.SyntaxKind, ScanStep> = new Map<
+  tsm.ts.SyntaxKind,
+  ScanStep
+>([
+  [
+    tsm.ts.SyntaxKind.OpenParenToken,
+    (state) => ({ ...state, parenDepth: state.parenDepth + 1 }),
+  ],
+  [
+    tsm.ts.SyntaxKind.CloseParenToken,
+    (state) => ({ ...state, parenDepth: state.parenDepth - 1 }),
+  ],
+  [
+    tsm.ts.SyntaxKind.OpenBraceToken,
+    (state) => ({ ...state, openBraces: `${state.openBraces}{` }),
+  ],
+  [
+    tsm.ts.SyntaxKind.TemplateHead,
+    (state) => ({ ...state, openBraces: `${state.openBraces}$` }),
+  ],
+  [
+    tsm.ts.SyntaxKind.CloseBraceToken,
+    (state, scanner) =>
+      // A `}` that closes a substitution resumes the template's text, which the
+      // scanner reads only when asked to re-scan; the substitution stays open
+      // when that text ends in another `${` (a `TemplateMiddle`).
+      state.openBraces.endsWith('$') &&
+      scanner.reScanTemplateToken(/* isTaggedTemplate */ false) !==
+        tsm.ts.SyntaxKind.TemplateTail
+        ? state
+        : { ...state, openBraces: state.openBraces.slice(0, -1) },
+  ],
+]);
+
 /**
  * Checks if a string is already wrapped with a single pair of balanced
  * parentheses that encompasses the entire expression.
@@ -24,10 +110,17 @@ const parenDepthDelta = (char: string | undefined): number => {
  * everything — while `'A'` is not, and neither is `'(A) | (B)'`, whose first
  * parenthesis closes before the end.
  *
+ * Only parenthesis tokens count: the text is read with TypeScript's scanner, so
+ * a parenthesis inside a string literal, a template literal's text or a comment
+ * (`(A | '(') | (B)`) does not. Text the scanner cannot read with certainty — a
+ * `/` that may start a regular expression (so `(a / b)` too), an unterminated
+ * string or template literal, unbalanced parentheses — is reported as not
+ * wrapped, so that it gets a pair.
+ *
  * 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.
+ * {@link wrapWithParentheses}, the exported form, whose example covers the same
+ * cases.
  */
 const isWrappedWithParentheses = (str: string): boolean => {
   const trimmed = str.trim();
@@ -36,47 +129,40 @@ const isWrappedWithParentheses = (str: string): boolean => {
     return false;
   }
 
-  // Check if the opening and closing parentheses are balanced
-  // and the opening parenthesis corresponds to the closing one
-  let mut_depth = 0;
+  const scanner = tsm.ts.createScanner(
+    tsm.ts.ScriptTarget.Latest,
+    /* skipTrivia */ true,
+    tsm.ts.LanguageVariant.Standard,
+    trimmed,
+  );
 
-  for (const mut_i of range(0, asUint32(trimmed.length))) {
-    mut_depth += parenDepthDelta(trimmed.at(mut_i));
+  let mut_state: ScanState = initialScanState;
 
-    // If we reach depth 0 before the end, the outer parentheses don't wrap everything
-    if (mut_depth === 0 && mut_i < trimmed.length - 1) {
+  for (
+    let mut_token = scanner.scan();
+    mut_token !== tsm.ts.SyntaxKind.EndOfFileToken;
+    mut_token = scanner.scan()
+  ) {
+    // Wrapping is the safe answer: a redundant pair costs nothing, a missing
+    // one changes the meaning.
+    if (untrustedTokens.has(mut_token)) {
       return false;
     }
-  }
 
-  return true;
-};
+    mut_state = scanStep.get(mut_token)?.(mut_state, scanner) ?? mut_state;
 
-/**
- * Wraps a string with parentheses if not already wrapped.
- * Avoids adding redundant parentheses when the expression is already
- * fully wrapped with balanced parentheses.
- *
- * @example
- *
- * ```ts
- * assert.strictEqual(wrapWithParentheses('A'), '(A)');
- *
- * // already wrapped, so not '((A))'
- * assert.strictEqual(wrapWithParentheses('(A)'), '(A)');
- *
- * assert.strictEqual(wrapWithParentheses('A | B'), '(A | B)');
- *
- * assert.strictEqual(wrapWithParentheses('(A | B)'), '(A | B)');
- *
- * // the outer parentheses do not span everything, so a pair is added
- * assert.strictEqual(wrapWithParentheses('(A) | (B)'), '((A) | (B))');
- * ```
- */
-export const wrapWithParentheses = (nodeStr: string): string => {
-  const trimmed = nodeStr.trim();
+    // Read after the step, which may have re-scanned a template's text.
+    if (scanner.isUnterminated()) {
+      return false;
+    }
 
-  return isWrappedWithParentheses(trimmed)
-    ? trimmed
-    : (`(${trimmed})` as const);
+    // If we reach depth 0 before the end, the outer parentheses don't wrap
+    // everything
+    if (mut_state.parenDepth === 0 && scanner.getTokenEnd() < trimmed.length) {
+      return false;
+    }
+  }
+
+  // Unbalanced text is wrapped too.
+  return mut_state.parenDepth === 0;
 };

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

@@ -0,0 +1,115 @@
+// `dedent` keeps these fixtures template literals: as plain strings, a `${` in
+// them reads as a forgotten substitution (no-template-curly-in-string).
+import dedent from 'dedent';
+import { wrapWithParentheses } from './wrap-with-parentheses.mjs';
+
+describe(wrapWithParentheses, () => {
+  test.each([
+    { name: 'a bare name', source: 'A', expected: '(A)' },
+    { name: 'a wrapped name', source: '(A)', expected: '(A)' },
+    { name: 'a doubly wrapped name', source: '((A))', expected: '((A))' },
+    { name: 'a bare union', source: 'A | B', expected: '(A | B)' },
+    {
+      name: 'outer parentheses that close before the end',
+      source: '(A) | (B)',
+      expected: '((A) | (B))',
+    },
+    {
+      name: 'surrounding whitespace',
+      source: '  (A | B)\n',
+      expected: '(A | B)',
+    },
+    {
+      name: 'an opening parenthesis inside a string literal type',
+      source: "(A | '(') | (B)",
+      expected: "((A | '(') | (B))",
+    },
+    {
+      name: 'a closing parenthesis inside a string literal type',
+      source: "(A | ')' | B)",
+      expected: "(A | ')' | B)",
+    },
+    {
+      name: 'an escaped quote before a parenthesis in a string literal type',
+      source: String.raw`(A | '\'(') | (B)`,
+      expected: String.raw`((A | '\'(') | (B))`,
+    },
+    {
+      name: 'a parenthesis inside a block comment',
+      source: '(A /* ( */) | (B)',
+      expected: '((A /* ( */) | (B))',
+    },
+    {
+      name: 'a parenthesis inside a line comment',
+      source: '(A // (\n) | (B)',
+      expected: '((A // (\n) | (B))',
+    },
+    {
+      name: 'a parenthesis inside a template literal type without substitutions',
+      source: '(`(`) | (B)',
+      expected: '((`(`) | (B))',
+    },
+    {
+      name: 'parentheses inside the text spans of a template literal type',
+      source: dedent`(\`(\${A}(\${B})\`) | (C)`,
+      expected: dedent`((\`(\${A}(\${B})\`) | (C))`,
+    },
+    {
+      name: 'a type literal with braces inside a template literal substitution',
+      source: dedent`(\`\${{ a: \`(\` }['a']}\`) | (B)`,
+      expected: dedent`((\`\${{ a: \`(\` }['a']}\`) | (B))`,
+    },
+    {
+      name: 'parentheses inside a template literal substitution still count',
+      source: dedent`(\`\${(A)}\`)`,
+      expected: dedent`(\`\${(A)}\`)`,
+    },
+    {
+      name: 'a quote left open by a regular expression literal',
+      source: "(/'/.test(a)) || (b)",
+      expected: "((/'/.test(a)) || (b))",
+    },
+    {
+      name: 'a parenthesis in a regular expression literal',
+      source: '(/[(]/.test(a)) || (b)',
+      expected: '((/[(]/.test(a)) || (b))',
+    },
+    {
+      name: 'quotes that close inside a later regular expression literal',
+      source: '(/"/.test(a)) || (/"/.test(b))',
+      expected: '((/"/.test(a)) || (/"/.test(b)))',
+    },
+    {
+      name: 'escaped parentheses in regular expression literals that balance',
+      source: String.raw`(/\(/.test(a)) || (/\)/.test(b))`,
+      expected: String.raw`((/\(/.test(a)) || (/\)/.test(b)))`,
+    },
+    {
+      name: 'a division inside wrapped parentheses',
+      source: '(a / b)',
+      expected: '((a / b))',
+    },
+    {
+      name: 'an unterminated string literal that runs to the end',
+      source: "(A | ') | (B)",
+      expected: "((A | ') | (B))",
+    },
+    {
+      name: 'an unterminated string literal that a line break ends',
+      source: "(A | '(\n)",
+      expected: "((A | '(\n))",
+    },
+    {
+      name: 'an unterminated template literal after a substitution',
+      source: dedent`(\`\${A}) | (B)`,
+      expected: dedent`((\`\${A}) | (B))`,
+    },
+    {
+      name: 'an unterminated block comment',
+      source: '(A /* ) | (B)',
+      expected: '((A /* ) | (B))',
+    },
+  ] as const)('$name', ({ source, expected }) => {
+    expect(wrapWithParentheses(source)).toBe(expected);
+  });
+});

package/src/functions/utils/replace-node-with-text.mts

@@ -4,19 +4,18 @@ import type * as tsm from 'ts-morph';
  * `node.replaceWithText(newNodeText)`, sparing a one-line text the indentation
  * lookup.
  *
- * `replaceWithText` writes the text through a writer whose indentation it
- * looks up first, for the lines after the first one, and the lookup reparses
- * the whole file in the language service: on top of the reparse every
- * replacement makes anyway, once per replacement, so it is quadratic in the
- * size of the file. A text with no `\n` has no line after the first, the
- * indentation is never applied, and a plain writer from the same project
- * writes the same text — so the lookup is skipped. A multi-line text takes
- * the original path.
+ * `replaceWithText` writes the text through a writer whose indentation it looks
+ * up first, for the lines after the first one, and the lookup reparses the
+ * whole file in the language service: on top of the reparse every replacement
+ * makes anyway, once per replacement, so it is quadratic in the size of the
+ * file. A text with no `\n` has no line after the first, the indentation is
+ * never applied, and a plain writer from the same project writes the same text
+ * — so the lookup is skipped. A multi-line text takes the original path.
  *
  * The writer is passed as `replaceWithText`'s second argument, which its
- * declaration leaves out and ts-morph passes itself when it sets an
- * expression. Were it ever dropped, the method would look the indentation up
- * as before: slower, never different.
+ * declaration leaves out and ts-morph passes itself when it sets an expression.
+ * Were it ever dropped, the method would look the indentation up as before:
+ * slower, never different.
  */
 export const replaceNodeWithText = (
   node: tsm.Node,