@opensip-tools/lang-typescript 1.0.4

package/src/__tests__/ast-utilities.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  countUnescapedBackticks,
+  findBinaryExpressions,
+  findCallExpressions,
+  findTemplateLiterals,
+  getColumn,
+  getIdentifierName,
+  getLineNumber,
+  getPropertyChain,
+  getSharedSourceFile,
+  isInComment,
+  isInStringLiteral,
+  isLiteral,
+  isPropertyAccess,
+  parseSource,
+  ts,
+  walkNodes,
+} from '../ast-utilities.js';
+
+const parse = (content: string) => parseSource(content, 'x.ts');
+
+describe('parseSource', () => {
+  it('parses valid TypeScript', () => {
+    expect(parse('const x = 1;')).not.toBeNull();
+  });
+
+  it('returns null on parse failure', () => {
+    // Note: TS parser is permissive — try with a sentinel call that throws.
+    // Most invalid syntax still produces a tree; instead exercise the catch
+    // path by passing a non-string.
+    // Cast to any to bypass the type guard for this test.
+    const result = parseSource(undefined as unknown as string, 'x.ts');
+    expect(result).toBeNull();
+  });
+});
+
+describe('getSharedSourceFile', () => {
+  it('returns a parsed source file', () => {
+    expect(getSharedSourceFile('shared.ts', 'export const x = 1;')).not.toBeNull();
+  });
+});
+
+describe('walkNodes', () => {
+  it('visits every descendant node', () => {
+    const sf = parse('const x = 1; const y = 2;');
+    if (!sf) throw new Error('parse failed');
+    let count = 0;
+    walkNodes(sf, () => count++);
+    expect(count).toBeGreaterThan(2);
+  });
+});
+
+describe('getIdentifierName / getPropertyChain', () => {
+  it('returns the leaf identifier from an Identifier', () => {
+    const sf = parse('foo;');
+    if (!sf) throw new Error('parse failed');
+    let leaf = '';
+    walkNodes(sf, (n) => {
+      if (ts.isIdentifier(n) && leaf === '') leaf = getIdentifierName(n);
+    });
+    expect(leaf).toBe('foo');
+  });
+
+  it('returns the property name from a PropertyAccessExpression', () => {
+    const sf = parse('a.b.c;');
+    if (!sf) throw new Error('parse failed');
+    let result = '';
+    walkNodes(sf, (n) => {
+      if (ts.isPropertyAccessExpression(n) && result === '') result = getPropertyChain(n);
+    });
+    expect(result).toBe('a.b.c');
+  });
+
+  it('returns empty string for non-identifier non-property nodes', () => {
+    const sf = parse('1 + 2;');
+    if (!sf) throw new Error('parse failed');
+    let found = '';
+    walkNodes(sf, (n) => {
+      if (ts.isBinaryExpression(n)) found = getIdentifierName(n);
+    });
+    expect(found).toBe('');
+  });
+
+  it('getPropertyChain returns empty for non-identifier non-property', () => {
+    const sf = parse('1 + 2;');
+    if (!sf) throw new Error('parse failed');
+    let found = '';
+    walkNodes(sf, (n) => {
+      if (ts.isBinaryExpression(n) && found === '') found = getPropertyChain(n);
+    });
+    expect(found).toBe('');
+  });
+});
+
+describe('getLineNumber / getColumn', () => {
+  it('returns 1-based line and 0-based column', () => {
+    const sf = parse('\n\nconst x = 1;');
+    if (!sf) throw new Error('parse failed');
+    let line = 0;
+    let col = 0;
+    walkNodes(sf, (n) => {
+      if (ts.isVariableDeclaration(n)) {
+        line = getLineNumber(n, sf);
+        col = getColumn(n, sf);
+      }
+    });
+    expect(line).toBe(3);
+    expect(col).toBe(6); // "const " (6 chars)
+  });
+});
+
+describe('isPropertyAccess', () => {
+  it('matches when the property name is the right one', () => {
+    const sf = parse('foo.bar();');
+    if (!sf) throw new Error('parse failed');
+    let matched = false;
+    walkNodes(sf, (n) => {
+      if (ts.isPropertyAccessExpression(n) && isPropertyAccess(n, 'bar')) matched = true;
+    });
+    expect(matched).toBe(true);
+  });
+
+  it('does not match when the property name differs', () => {
+    const sf = parse('foo.bar();');
+    if (!sf) throw new Error('parse failed');
+    let matched = false;
+    walkNodes(sf, (n) => {
+      if (ts.isPropertyAccessExpression(n) && isPropertyAccess(n, 'baz')) matched = true;
+    });
+    expect(matched).toBe(false);
+  });
+});
+
+describe('isLiteral', () => {
+  it.each([
+    ['"hi"', true],
+    ['42', true],
+    ['true', true],
+    ['false', true],
+    ['null', true],
+    ['undefined', true],
+    ['x', false],
+  ])('isLiteral(%s) === %s', (src, expected) => {
+    const sf = parse(`(${src});`);
+    if (!sf) throw new Error('parse failed');
+    let result: boolean | null = null;
+    walkNodes(sf, (n) => {
+      if (ts.isParenthesizedExpression(n) && result === null) result = isLiteral(n.expression);
+    });
+    expect(result).toBe(expected);
+  });
+});
+
+describe('isInStringLiteral', () => {
+  it('returns true for nodes inside a string template', () => {
+    const sf = parse('const x = `${foo}`;');
+    if (!sf) throw new Error('parse failed');
+    let found = false;
+    walkNodes(sf, (n) => {
+      if (ts.isIdentifier(n) && n.text === 'foo' && isInStringLiteral(n)) found = true;
+    });
+    expect(found).toBe(true);
+  });
+
+  it('returns false for nodes outside string literals', () => {
+    const sf = parse('const x = 1; const y = x;');
+    if (!sf) throw new Error('parse failed');
+    let foundOutside = false;
+    walkNodes(sf, (n) => {
+      if (ts.isIdentifier(n) && n.text === 'y' && !isInStringLiteral(n)) foundOutside = true;
+    });
+    expect(foundOutside).toBe(true);
+  });
+});
+
+describe('findCallExpressions', () => {
+  it('finds matching call sites by object + method name', () => {
+    const sf = parse('console.log(1); foo(); console.log(2);');
+    if (!sf) throw new Error('parse failed');
+    const calls = findCallExpressions(sf, 'console', 'log');
+    expect(calls.length).toBe(2);
+  });
+
+  it('matches when objectName is a suffix of the property chain', () => {
+    const sf = parse('a.b.console.log(1);');
+    if (!sf) throw new Error('parse failed');
+    const calls = findCallExpressions(sf, 'console', 'log');
+    expect(calls.length).toBe(1);
+  });
+
+  it('returns empty when no matches', () => {
+    const sf = parse('foo();');
+    if (!sf) throw new Error('parse failed');
+    expect(findCallExpressions(sf, 'console', 'log')).toEqual([]);
+  });
+});
+
+describe('findBinaryExpressions', () => {
+  it('finds binary expressions of the given operator kind', () => {
+    const sf = parse('a + b; c - d; a + e;');
+    if (!sf) throw new Error('parse failed');
+    expect(findBinaryExpressions(sf, ts.SyntaxKind.PlusToken).length).toBe(2);
+  });
+});
+
+describe('findTemplateLiterals', () => {
+  it('finds template expressions with interpolations', () => {
+    const sf = parse('const x = `${a}${b}`;');
+    if (!sf) throw new Error('parse failed');
+    expect(findTemplateLiterals(sf).length).toBe(1);
+  });
+
+  it('skips no-substitution templates', () => {
+    const sf = parse('const x = `static`;');
+    if (!sf) throw new Error('parse failed');
+    expect(findTemplateLiterals(sf)).toEqual([]);
+  });
+});
+
+describe('isInComment', () => {
+  it('returns false for a position outside a comment', () => {
+    const src = 'const x = 1;\nconst y = 2;';
+    const sf = parse(src);
+    if (!sf) throw new Error('parse failed');
+    const xIdx = src.indexOf('const x');
+    expect(isInComment(xIdx, sf)).toBe(false);
+  });
+
+  it('returns true for a position inside a leading block comment', () => {
+    const src = '/* block\n   comment\n*/\nconst x = 1;';
+    const sf = parse(src);
+    if (!sf) throw new Error('parse failed');
+    const insideIdx = src.indexOf('block');
+    expect(isInComment(insideIdx, sf)).toBe(true);
+  });
+});
+
+describe('countUnescapedBackticks', () => {
+  it('counts unescaped backticks', () => {
+    expect(countUnescapedBackticks('a `b` c')).toBe(2);
+  });
+
+  it('does not count escaped backticks', () => {
+    expect(countUnescapedBackticks('a \\` b')).toBe(0);
+  });
+
+  it('returns 0 when there are none', () => {
+    expect(countUnescapedBackticks('plain text')).toBe(0);
+  });
+});

package/src/adapter.ts

@@ -0,0 +1,21 @@
+
+
+import { parseSource } from './parse.js'
+import { typescriptQuery } from './query.js'
+import { stripComments, stripStrings } from './strip.js'
+
+import type { LanguageAdapter } from '@opensip-tools/core/languages/adapter.js'
+import type ts from 'typescript'
+
+export const typescriptAdapter: LanguageAdapter<ts.SourceFile, ts.Node> = {
+  id: 'typescript',
+  fileExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+  aliases: ['javascript', 'tsx', 'jsx', 'js'],
+  parse: parseSource,
+  stripStrings,
+  stripComments,
+  query: typescriptQuery,
+}
+
+/** Plugin contract — exported as the lang plugin's `adapters` array. */
+export const adapters = [typescriptAdapter] as const

package/src/ast-utilities.ts

@@ -0,0 +1,238 @@
+// @fitness-ignore-file batch-operation-limits -- iterates bounded collections (config entries, registry items, or small analysis results)
+/**
+ * @fileoverview Shared AST utilities for fitness checks.
+ *
+ * Common TypeScript AST operations for source parsing, tree walking,
+ * and node inspection. Used by AST-based fitness checks. Lives in
+ * @opensip-tools/lang-typescript so the dependency on `typescript` is
+ * isolated to the language pack.
+ */
+
+import { getParseTree } from '@opensip-tools/core/languages/parse-cache.js'
+import * as ts from 'typescript'
+
+
+import { typescriptAdapter } from './adapter.js'
+
+// =============================================================================
+// SOURCE PARSING
+// =============================================================================
+
+/**
+ * Parse TypeScript/JavaScript source into an AST SourceFile.
+ * Returns null on parse failure.
+ */
+export function parseSource(content: string, filePath: string): ts.SourceFile | null {
+  try {
+    return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Cached parse — uses the language-aware parse cache via the registered
+ * TS adapter. Falls back to a direct parse when no cache is active.
+ */
+export function getSharedSourceFile(filePath: string, content: string): ts.SourceFile | null {
+  return getParseTree(typescriptAdapter, filePath, content)
+}
+
+// =============================================================================
+// TREE WALKING
+// =============================================================================
+
+/**
+ * Depth-first walk of all nodes in a SourceFile or subtree.
+ */
+export function walkNodes(root: ts.Node, visitor: (node: ts.Node) => void): void {
+  function visit(node: ts.Node): void {
+    visitor(node)
+    ts.forEachChild(node, visit)
+  }
+  ts.forEachChild(root, visit)
+}
+
+// =============================================================================
+// NODE INSPECTION
+// =============================================================================
+
+/**
+ * Get the leaf identifier text from an expression node.
+ */
+export function getIdentifierName(node: ts.Node): string {
+  if (ts.isIdentifier(node)) return node.text
+  if (ts.isPropertyAccessExpression(node)) return node.name.text
+  return ''
+}
+
+/**
+ * Get the full dotted path of a property access chain.
+ */
+export function getPropertyChain(node: ts.Node): string {
+  if (ts.isIdentifier(node)) return node.text
+  if (ts.isPropertyAccessExpression(node)) {
+    return `${getPropertyChain(node.expression)}.${node.name.text}`
+  }
+  return ''
+}
+
+/**
+ * Get the 1-indexed line number for a node.
+ */
+export function getLineNumber(node: ts.Node, sourceFile: ts.SourceFile): number {
+  const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
+  return line + 1
+}
+
+/**
+ * Get the column number (0-indexed) for a node.
+ */
+export function getColumn(node: ts.Node, sourceFile: ts.SourceFile): number {
+  const { character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
+  return character
+}
+
+/**
+ * Check if a node is a property access matching a specific property name.
+ */
+export function isPropertyAccess(node: ts.Node, propertyName: string): boolean {
+  return ts.isPropertyAccessExpression(node) && node.name.text === propertyName
+}
+
+/**
+ * Check if a node is a literal value.
+ */
+export function isLiteral(node: ts.Node): boolean {
+  if (ts.isStringLiteral(node) || ts.isNumericLiteral(node)) return true
+  if (ts.isNoSubstitutionTemplateLiteral(node)) return true
+  if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword)
+    return true
+  if (node.kind === ts.SyntaxKind.NullKeyword) return true
+  if (ts.isIdentifier(node) && node.text === 'undefined') return true
+  return false
+}
+
+/**
+ * Check if a node is inside a string literal or template literal.
+ */
+export function isInStringLiteral(node: ts.Node): boolean {
+  let current = node.parent
+  while (!ts.isSourceFile(current)) {
+    if (
+      ts.isStringLiteral(current) ||
+      ts.isNoSubstitutionTemplateLiteral(current) ||
+      ts.isTemplateExpression(current)
+    ) {
+      return true
+    }
+    current = current.parent
+  }
+  return false
+}
+
+// =============================================================================
+// NODE FINDERS
+// =============================================================================
+
+/**
+ * Find all call expressions matching `object.method()` pattern.
+ */
+export function findCallExpressions(
+  root: ts.Node,
+  objectName: string,
+  methodName: string,
+): ts.CallExpression[] {
+  const results: ts.CallExpression[] = []
+  walkNodes(root, (node) => {
+    if (!ts.isCallExpression(node)) return
+    const expr = node.expression
+    if (!ts.isPropertyAccessExpression(expr)) return
+    if (expr.name.text !== methodName) return
+    const chain = getPropertyChain(expr.expression)
+    if (chain === objectName || chain.endsWith(`.${objectName}`)) {
+      results.push(node)
+    }
+  })
+  return results
+}
+
+/**
+ * Find all binary expressions with a specific operator.
+ */
+export function findBinaryExpressions(
+  root: ts.Node,
+  operator: ts.SyntaxKind,
+): ts.BinaryExpression[] {
+  const results: ts.BinaryExpression[] = []
+  walkNodes(root, (node) => {
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === operator) {
+      results.push(node)
+    }
+  })
+  return results
+}
+
+/**
+ * Find all template literal expressions (with substitutions).
+ */
+export function findTemplateLiterals(root: ts.Node): ts.TemplateExpression[] {
+  const results: ts.TemplateExpression[] = []
+  walkNodes(root, (node) => {
+    if (ts.isTemplateExpression(node)) {
+      results.push(node)
+    }
+  })
+  return results
+}
+
+// =============================================================================
+// COMMENT DETECTION
+// =============================================================================
+
+function isPositionInRanges(position: number, ranges: ts.CommentRange[] | undefined): boolean {
+  if (!ranges) return false
+  for (const range of ranges) {
+    if (position >= range.pos && position < range.end) return true
+  }
+  return false
+}
+
+/**
+ * Check if a position in the source falls inside a comment.
+ */
+export function isInComment(position: number, sourceFile: ts.SourceFile): boolean {
+  const text = sourceFile.getFullText()
+  const lineStarts = sourceFile.getLineStarts()
+
+  for (let i = 0; i < lineStarts.length; i++) {
+    const lineStart = lineStarts[i] ?? 0
+    const lineEnd = i + 1 < lineStarts.length ? (lineStarts[i + 1] ?? text.length) : text.length
+
+    if (position < lineStart || position >= lineEnd) continue
+
+    if (isPositionInRanges(position, ts.getLeadingCommentRanges(text, lineStart))) return true
+    if (isPositionInRanges(position, ts.getTrailingCommentRanges(text, lineStart))) return true
+  }
+
+  return false
+}
+
+// =============================================================================
+// STRING UTILITIES
+// =============================================================================
+
+/**
+ * Count unescaped backtick characters in a line.
+ */
+export function countUnescapedBackticks(line: string): number {
+  let count = 0
+  for (let ci = 0; ci < line.length; ci++) {
+    if (line[ci] === '`' && (ci === 0 || line[ci - 1] !== '\\')) count++
+  }
+  return count
+}
+
+/** Re-export TypeScript namespace for check authors */
+// eslint-disable-next-line unicorn/prefer-export-from -- `export * as from 'typescript'` is invalid (typescript uses `export =`); the namespace import + named export form is the only working shape
+export { ts }

package/src/index.ts

@@ -0,0 +1,26 @@
+// TypeScript LanguageAdapter for opensip-tools
+export { typescriptAdapter, adapters } from './adapter.js'
+export { parseSource } from './parse.js'
+export { typescriptQuery } from './query.js'
+export { stripStrings, stripComments, filterContent, clearFilterCache } from './strip.js'
+export type { FilteredContent } from './strip.js'
+
+// Legacy AST helpers — re-exported so existing TS checks can keep their imports
+// pointing at @opensip-tools/lang-typescript instead of @opensip-tools/core/framework/*
+export {
+  getSharedSourceFile,
+  walkNodes,
+  getIdentifierName,
+  getPropertyChain,
+  getLineNumber,
+  getColumn,
+  isPropertyAccess,
+  isLiteral,
+  isInStringLiteral,
+  findCallExpressions,
+  findBinaryExpressions,
+  findTemplateLiterals,
+  isInComment,
+  countUnescapedBackticks,
+  ts,
+} from './ast-utilities.js'

package/src/parse.ts

@@ -0,0 +1,22 @@
+import ts from 'typescript'
+
+/**
+ * Parse TypeScript/JavaScript source into a SourceFile.
+ * Returns null on parse failure.
+ *
+ * Uses ts.ScriptKind.TSX so the same parse path handles .ts and .tsx
+ * (and is permissive enough for .js / .jsx).
+ */
+export function parseSource(content: string, filePath: string): ts.SourceFile | null {
+  try {
+    return ts.createSourceFile(
+      filePath,
+      content,
+      ts.ScriptTarget.Latest,
+      /* setParentNodes */ true,
+      ts.ScriptKind.TSX,
+    )
+  } catch {
+    return null
+  }
+}

package/src/query.ts

@@ -0,0 +1,76 @@
+import ts from 'typescript'
+
+import type { LanguageQueryAPI } from '@opensip-tools/core/languages/adapter.js'
+import type { GenericFunction, Import, Location } from '@opensip-tools/core/languages/generic-types.js'
+
+function locationOf(sourceFile: ts.SourceFile, node: ts.Node): Location {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
+  return { file: sourceFile.fileName, line: line + 1, column: character }
+}
+
+function walk(node: ts.Node, visit: (n: ts.Node) => void): void {
+  visit(node)
+  ts.forEachChild(node, (child) => walk(child, visit))
+}
+
+export const typescriptQuery: LanguageQueryAPI<ts.SourceFile, ts.Node> = {
+  findFunctions(tree) {
+    const out: GenericFunction<ts.Node>[] = []
+    walk(tree, (n) => {
+      if (
+        ts.isFunctionDeclaration(n) ||
+        ts.isFunctionExpression(n) ||
+        ts.isArrowFunction(n) ||
+        ts.isMethodDeclaration(n)
+      ) {
+        const name = (n as ts.FunctionDeclaration).name?.text ?? null
+        out.push({ name, location: locationOf(tree, n), node: n })
+      }
+    })
+    return out
+  },
+  findImports(tree) {
+    const out: Import[] = []
+    walk(tree, (n) => {
+      if (ts.isImportDeclaration(n) && ts.isStringLiteral(n.moduleSpecifier)) {
+        const specifier = n.moduleSpecifier.text
+        const names: string[] = []
+        const clause = n.importClause
+        if (clause?.name) names.push(clause.name.text)
+        if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+          for (const elem of clause.namedBindings.elements) names.push(elem.name.text)
+        }
+        out.push({ specifier, names, location: locationOf(tree, n) })
+      }
+    })
+    return out
+  },
+  findCallsTo(tree, name) {
+    const out: ts.Node[] = []
+    walk(tree, (n) => {
+      if (ts.isCallExpression(n)) {
+        const expr = n.expression
+        let target = ''
+        if (ts.isIdentifier(expr)) target = expr.text
+        else if (ts.isPropertyAccessExpression(expr)) target = expr.name.text
+        if (target === name) out.push(n)
+      }
+    })
+    return out
+  },
+  findStringLiterals(tree) {
+    const out: { value: string; location: Location }[] = []
+    walk(tree, (n) => {
+      if (ts.isStringLiteralLike(n)) {
+        out.push({ value: n.text, location: locationOf(tree, n) })
+      }
+    })
+    return out
+  },
+  getLocation(tree, node) {
+    return locationOf(tree, node)
+  },
+  getText(tree, node) {
+    return node.getText(tree)
+  },
+}

package/src/strip.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview TypeScript string and comment stripping.
+ *
+ * Implements the LanguageAdapter contract methods stripStrings/stripComments
+ * by re-using the rich filterContent implementation in core. Both functions
+ * preserve byte length so line/column positions remain stable.
+ */
+
+import { filterContent } from '@opensip-tools/fitness'
+
+/**
+ * Replace string literal content with whitespace of equal length.
+ * Quote/backtick delimiters are preserved; only the inside is blanked.
+ */
+export function stripStrings(content: string): string {
+  return filterContent(content).code
+}
+
+/**
+ * Replace string literals AND comments with whitespace of equal length.
+ */
+export function stripComments(content: string): string {
+  return filterContent(content).codeNoComments
+}
+
+// Re-export filterContent and the FilteredContent type for richer
+// position-aware needs. The clearFilterCache helper is also re-exported
+// for compatibility with any callers that managed it directly.
+export { filterContent, clearFilterCache } from '@opensip-tools/fitness'
+export type { FilteredContent } from '@opensip-tools/fitness'

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}