Semantic Analysis

Semantic analysis enables your codemods to understand symbol relationships in code—finding where variables are defined, tracking all references to a function, or discovering cross-file dependencies. This goes beyond pattern matching to provide IDE-like intelligence for your transformations.

Supported Languages

Language	Provider	Features
JavaScript/TypeScript	oxc	Definitions, references, cross-file resolution
Python	ruff	Definitions, references, cross-file resolution
Other languages	Codemod	Enterprise features available. For JSSG open-source, it returns no-op results.

Enterprise customers can get semantic analysis for Go, Rust, Java, C, C++, C Sharp, Ruby, PHP, Swift, Kotlin, Haskell, and Elixir. Contact us to learn more.

Analysis Modes

Semantic analysis operates in two modes, each with different performance and accuracy trade-offs:

File Scope (Default)

Single-file analysis that processes symbols within the current file only. This mode is fast and requires no additional configuration. Best for:

Quick analysis of local variables
Single-file transformations
Dry runs and exploratory analysis

Limitations:

Cannot resolve cross-file imports
Cannot find references in other files

Workspace Scope

Workspace-wide analysis that resolves cross-file imports and finds references across your entire project. This mode requires specifying a workspace root. Best for:

Renaming symbols across files
Finding all usages of exported functions
Dependency analysis and migration codemods

Requirements:

Workspace root path must be specified
Files must be processed (indexed) before cross-file queries work

API Reference

`node.definition(options?)`

Get the definition location for the symbol at this node’s position.

DefinitionResult | null

Returns an object containing the definition node, its root, and the kind of definition, or null if not found.

interface DefinitionOptions {
  /** If false, stop at import statements without resolving. Default: true (in workspace scope mode) */
  resolveExternal?: boolean;
}

interface DefinitionResult<M> {
  /** The AST node at the definition location */
  node: SgNode<M>;
  /** The SgRoot for the file containing the definition */
  root: SgRoot<M>;
  /** The kind of definition: 'local', 'import', or 'external' */
  kind: "local" | "import" | "external";
}

Definition kinds:

'local' — Definition is in the same file (local variable, function, class, etc.)
'import' — Definition traced to an import statement, but module couldn’t be resolved (e.g., external package)
'external' — Definition resolved to a different file in the workspace

Returns null when:

No semantic provider is configured
No symbol is found at this position

When a symbol comes from an unresolved import (e.g., import x from "some-external-module"), definition() now returns the import statement with kind: 'import' instead of returning null. This allows you to at least trace the symbol back to where it was imported.

`node.references()`

Find all references to the symbol at this node’s position.

Array<FileReferences>

Returns an array of file references, grouped by file.

interface FileReferences<M> {
  /** The SgRoot for the file containing references */
  root: SgRoot<M>;
  /** Array of SgNode objects for each reference in this file */
  nodes: Array<SgNode<M>>;
}

Returns empty array when:

No semantic provider is configured
No symbol is found at this position

In file scope mode, references() only searches the current file. In workspace scope mode, it searches all indexed files in the workspace.

`root.write(content)`

Write content to a file obtained via definition() or references(). This method allows cross-file editing within a single codemod execution.

void

Writes the provided content to the file and updates the semantic provider’s cache.

// Write to a file obtained from definition() or references()
const def = node.definition();
if (def && def.root.filename() !== root.filename()) {
  const edits = [def.node.replace("newName")];
  const newContent = def.root.root().commitEdits(edits);
  def.root.write(newContent);
}

Throws an error when:

Called on the current file being processed (use return instead)
The file has no path
The write operation fails

You cannot call write() on the current file. For the current file, return the modified content from transform() instead.

Using Semantic Analysis

Via Workflow Configuration (Recommended)

The recommended way to use semantic analysis is through workflow files. Create a workflow.yaml that references your codemod script:

version: "1"
nodes:
  transform:
    js-ast-grep:
      js_file: scripts/codemod.ts
      semantic_analysis: file

version: "1"
nodes:
  transform:
    js-ast-grep:
      js_file: scripts/codemod.ts
      semantic_analysis: workspace

version: "1"
nodes:
  transform:
    js-ast-grep:
      js_file: scripts/codemod.ts
      semantic_analysis:
        mode: workspace
        root: ./path/to/workspace

string | object

Configure semantic analysis mode. Can be:

"file" — Single-file analysis (default)
"workspace" — Workspace-wide analysis using the target path
{ mode: "workspace", root: "./path" } — Workspace-wide with custom root

Run the workflow:

npx codemod workflow run -w /path/to/codemod/workflow.yaml -t /path/to/target

PATH

Path to the workflow YAML file.

PATH

Path to the target directory containing files to transform.

When semantic analysis returns an SgRoot for another file, you can use root.relativeFilename() to get that file’s path relative to the active target directory.

Via CLI Commands

For quick testing or simple use cases, you can also use the JSSG CLI directly:

jssg run
jssg test

# File scope (default)
npx codemod jssg run ./scripts/codemod.ts \
  --language tsx \
  --target /path/to/target

# Workspace scope

npx codemod jssg run ./scripts/codemod.ts \
 --language tsx \
 --target /path/to/target \
 --semantic-workspace /path/to/target

PATH

Enable workspace-wide semantic analysis using the provided path as the workspace root.

# File scope (default)
npx codemod jssg test ./scripts/codemod.ts --language tsx

# Workspace scope
npx codemod jssg test ./scripts/codemod.ts \
  --language tsx \
  --semantic-workspace /path/to/project

Examples

Renaming a Utility Function Across Files (TypeScript)

This example renames formatDate to formatDateTime across a multi-file TypeScript project. Source codebase:

export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}

export function parseDate(str: string): Date {
  return new Date(str);
}

import { formatDate } from "../utils/date";

interface Event {
  title: string;
  date: Date;
}

export function EventCard({ title, date }: Event) {
  return (
    <div className="event-card">
      <h3>{title}</h3>
      <span>{formatDate(date)}</span>
    </div>
  );
}

import { formatDate } from "../utils/date";

export function Dashboard({ events }) {
  return (
    <div>
      <h1>Upcoming Events</h1>
      {events.map((event) => (
        <p key={event.id}>
          {event.name} - {formatDate(event.scheduledAt)}
        </p>
      ))}
    </div>
  );
}

Codemod and workflow:

export default function transform(root) {
  const rootNode = root.root();
  const currentFile = root.filename();

  // Find the function declaration we want to rename
  const funcDeclName = rootNode.find({
    rule: {
      pattern: "formatDate",
      inside: {
        pattern: "export function formatDate($$$PARAMS) { $$$BODY }",
        stopBy: {
          kind: "export_statement",
        },
      },
    },
  });

  if (!funcDeclName) return null;

  // Find all references across the workspace
  const refs = funcDeclName.references();
  const currentFileEdits = [];

  for (const fileRef of refs) {
    const edits = fileRef.nodes.map((node) => node.replace("formatDateTime"));

    if (fileRef.root.filename() === currentFile) {
      currentFileEdits.push(...edits);
    } else {
      // Write changes to other files
      const newContent = fileRef.root.root().commitEdits(edits);
      fileRef.root.write(newContent);
    }
  }

  return rootNode.commitEdits(currentFileEdits);
}

version: "1"
nodes:
  rename-format-date:
    js-ast-grep:
      js_file: scripts/rename-format-date.ts
      semantic_analysis: workspace

Run the workflow:

npx codemod workflow run -w /path/to/codemod/workflow.yaml -t ./src

Result:

export function formatDateTime(date: Date): string {
  return date.toISOString().split('T')[0];
}

export function parseDate(str: string): Date {
  return new Date(str);
}

import { formatDateTime } from "../utils/date";

interface Event {
  title: string;
  date: Date;
}

export function EventCard({ title, date }: Event) {
  return (
    <div className="event-card">
      <h3>{title}</h3>
      <span>{formatDateTime(date)}</span>
    </div>
  );
}

import { formatDateTime } from "../utils/date";

export function Dashboard({ events }) {
  return (
    <div>
      <h1>Upcoming Events</h1>
      {events.map((event) => (
        <p key={event.id}>
          {event.name} - {formatDateTime(event.scheduledAt)}
        </p>
      ))}
    </div>
  );
}

Finding Usages of a Python Class

Analyze how a class is used across a Python project without making changes. Source codebase:

class User:
    def __init__(self, name: str, email: str):
        self.name = name
        self.email = email
    
    def display_name(self) -> str:
        return f"{self.name} <{self.email}>"

from models.user import User

def authenticate(username: str, password: str) -> User | None:
    # Verify credentials
    if verify_password(username, password):
        return User(name=username, email=f"{username}@example.com")
    return None

def create_guest() -> User:
    return User(name="Guest", email="guest@example.com")

from models.user import User
from services.auth import authenticate

def get_current_user(request) -> User:
    user = authenticate(request.username, request.password)
    if not user:
        raise AuthError("Invalid credentials")
    return user

Codemod and workflow:

export default function transform(root) {
  const rootNode = root.root();

  // Find the User class definition
  const classDefName = rootNode.find({
    rule: { pattern: "User", inside: { pattern: "class User: $$$BODY" } },
  });

  if (!classDefName) return null;

  const refs = classDefName.references();

  // Log usage analysis
  console.log("=== User class usage analysis ===\n");

  let totalUsages = 0;
  for (const fileRef of refs) {
    const filename = fileRef.root.filename();
    console.log(`📄 ${filename}:`);
    for (const node of fileRef.nodes) {
      const line = node.range().start.line + 1;
      const context = node.parent()?.text().slice(0, 50) || node.text();
      console.log(`   Line ${line}: ${context}...`);
      totalUsages++;
    }
    console.log("");
  }

  console.log(`Total: ${totalUsages} usages across ${refs.length} files`);

  return null; // Analysis only, no changes
}

version: "1"
nodes:
  analyze-user-class:
    js-ast-grep:
      js_file: scripts/analyze-user-class.ts
      semantic_analysis: workspace

Run the workflow:

npx codemod workflow run -w /path/to/codemod/workflow.yaml -t ./

Output:

=== User class usage analysis ===

📄 models/user.py:
   Line 1: class User:...

📄 services/auth.py:
   Line 1: from models.user import User...
   Line 6: return User(name=username, email=f"{userna...
   Line 10: return User(name="Guest", email="guest@exa...

📄 api/routes.py:
   Line 1: from models.user import User...
   Line 4: def get_current_user(request) -> User:...

Total: 6 usages across 3 files

Tracing External Module Imports

Find where external dependencies are imported when node_modules isn’t available. Source codebase:

import axios from 'axios';
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
});

export async function fetchUser(id: string) {
  const response = await axios.get(`/api/users/${id}`);
  return UserSchema.parse(response.data);
}

import { useQuery } from "@tanstack/react-query";
import { fetchUser } from "../api/client";

export function useUser(userId: string) {
  return useQuery({
    queryKey: ["user", userId],
    queryFn: () => fetchUser(userId),
  });
}

Codemod and workflow:

export default function transform(root) {
  const rootNode = root.root();

  // Find all identifiers that might be external imports
  const identifiers = ["axios", "z", "useQuery"];

  for (const name of identifiers) {
    const node = rootNode.find({ rule: { pattern: name } });
    for (const node of nodes) {
      const def = node.definition();

      if (def) {
        if (def.kind === "import") {
          // External module - couldn't resolve, but we have the import
          console.log(`${name}: External import`);
          console.log(`  Import statement: ${def.node.text()}`);
        } else if (def.kind === "local") {
          console.log(
            `${name}: Defined locally at line ${
              def.node.range().start.line + 1
            }`
          );
        } else if (def.kind === "external") {
          console.log(`${name}: Defined in ${def.root.filename()}`);
        }
      }
    }
  }

return null;
}

version: "1"
nodes:
  trace-imports:
    js-ast-grep:
      js_file: scripts/trace-external-imports.ts
      semantic_analysis: workspace

Run the workflow:

npx codemod workflow run -w /path/to/codemod/workflow.yaml -t ./src

Output:

axios: External import
  Import statement: import axios from 'axios'
z: External import
  Import statement: import { z } from 'zod'
useQuery: External import
  Import statement: import { useQuery } from '@tanstack/react-query'

When a symbol comes from an unresolved import (e.g., import x from "some-external-module"), definition() returns the import statement with kind: 'import'. This allows you to trace symbols back to their import source even when the module can’t be resolved or the semantic mode is set to file scope.

Cross-File Editing with Definition Lookup

Rename a constant and update all files that import it. Source codebase:

export const API_BASE_URL = "https://api.example.com";
export const API_TIMEOUT = 5000;
export const MAX_RETRIES = 3;

import { API_BASE_URL, API_TIMEOUT } from "../constants";

export const client = {
  baseURL: API_BASE_URL,
  timeout: API_TIMEOUT,
};

import { API_BASE_URL } from "../constants";

export const config = {
  apiUrl: API_BASE_URL,
  debug: process.env.NODE_ENV === "development",
};

Codemod and workflow:

export default function transform(root) {
  const rootNode = root.root();
  const currentFile = root.filename();

  // Find the constant declaration
  const constDeclName = rootNode.find({
    rule: {
      pattern: "API_BASE_URL",
      inside: {
        pattern: "export const API_BASE_URL = $VALUE",
        stopBy: {
          kind: "export_statement",
        },
      },
    },
  });

  if (!constDeclName) return null;

  // Find all references to API_BASE_URL
  const refs = constDeclName.references();
  const currentFileEdits = [];

  for (const fileRef of refs) {
    const edits = fileRef.nodes.map((node) => node.replace("API_ENDPOINT"));

    if (fileRef.root.filename() === currentFile) {
      currentFileEdits.push(...edits);
    } else {
      const newContent = fileRef.root.root().commitEdits(edits);
      fileRef.root.write(newContent);
    }
  }

  return rootNode.commitEdits(currentFileEdits);
}

version: "1"
nodes:
  rename-constant:
    js-ast-grep:
      js_file: scripts/rename-constant.ts
      semantic_analysis: workspace

Run the workflow:

npx codemod workflow run -w /path/to/codemod/workflow.yaml -t ./src

Result:

export const API_ENDPOINT = "https://api.example.com";
export const API_TIMEOUT = 5000;
export const MAX_RETRIES = 3;

import { API_ENDPOINT, API_TIMEOUT } from "../constants";

export const client = {
  baseURL: API_ENDPOINT,
  timeout: API_TIMEOUT,
};

import { API_ENDPOINT } from "../constants";

export const config = {
  apiUrl: API_ENDPOINT,
  debug: process.env.NODE_ENV === "development",
};

You cannot call write() on the current file being processed. For the current file, return the modified content from transform() instead. This ensures the engine properly tracks and applies changes.

When you call write() on an SgRoot obtained from definition() or references(), the semantic provider’s cache is automatically updated. This ensures subsequent semantic queries reflect the changes.

Best Practices

Use file scope for single-file transformations

File scope analysis is faster and doesn’t require workspace configuration. Use it when your codemod only needs to understand symbols within a single file.

workflow.yaml

version: "1"
nodes:
  transform:
    js-ast-grep:
      js_file: scripts/codemod.ts
      semantic_analysis: file # Fast, single-file analysis

Handle null/empty results gracefully

Semantic analysis may return null or empty results for various reasons. Always check return values:

const def = node.definition();
if (!def) {
  // Definition not found - could be external, unresolved, or no provider
  return null;
}

const refs = node.references();
if (refs.length === 0) {
  // No references found
  return null;
}

Check file ownership before editing

When processing references across files, verify you’re editing the correct file:

for (const fileRef of refs) {
  // Only edit the current file
  if (fileRef.root.filename() === root.filename()) {
    for (const node of fileRef.nodes) {
      edits.push(node.replace("newText"));
    }
  }
}

Troubleshooting

Semantic methods return null/empty

Possible causes:

No semantic analysis configured in workflow (add semantic_analysis: workspace)
The language isn’t supported (only JavaScript/TypeScript and Python)
The symbol couldn’t be resolved (external library, syntax error)

Debug steps:

const def = node.definition();
console.log("Definition:", def);
console.log("Node text:", node.text());
console.log("Node kind:", node.kind());

Cross-file references not found

Possible causes:

Using file scope mode instead of workspace scope
The target file hasn’t been indexed yet
Import resolution failed

Solution: Ensure you’re using workspace scope mode in your workflow:

workflow.yaml

version: "1"
nodes:
  transform:
    js-ast-grep:
      js_file: scripts/codemod.ts
      semantic_analysis: workspace

Then run:

npx codemod workflow run -w /path/to/codemod/workflow.yaml -t /path/to/target

Performance issues with large workspaces

Tips:

Start with file scope for initial development
Use workspace scope only when cross-file analysis is needed
Consider running workflows on subsets of your codebase by targeting specific directories

Next Steps

API Reference

Complete API documentation for SgNode and SgRoot methods.

Advanced Patterns

Learn advanced transformation techniques and best practices.

Testing

Test your codemods with fixtures and the test runner.

Security

Understand JSSG’s security model and capabilities.

First steps

Community

Enterprise

Other Resources

Supported Languages

Analysis Modes

File Scope (Default)

Workspace Scope

API Reference

`node.definition(options?)`

`node.references()`

`root.write(content)`

Using Semantic Analysis

Via Workflow Configuration (Recommended)

Via CLI Commands

Examples

Renaming a Utility Function Across Files (TypeScript)

Finding Usages of a Python Class

Tracing External Module Imports

Cross-File Editing with Definition Lookup

Best Practices

Troubleshooting

Next Steps

API Reference

Advanced Patterns

Testing

Security

​Supported Languages

​Analysis Modes

​File Scope (Default)

​Workspace Scope

​API Reference

​node.definition(options?)

​node.references()

​root.write(content)

​Using Semantic Analysis

​Via Workflow Configuration (Recommended)

​Via CLI Commands

​Examples

​Renaming a Utility Function Across Files (TypeScript)

​Finding Usages of a Python Class

​Tracing External Module Imports

​Cross-File Editing with Definition Lookup

​Best Practices

​Troubleshooting

​Next Steps

API Reference

Advanced Patterns

Testing

Security

Supported Languages

Analysis Modes

File Scope (Default)

Workspace Scope

API Reference

`node.definition(options?)`

`node.references()`

`root.write(content)`

Using Semantic Analysis

Via Workflow Configuration (Recommended)

Via CLI Commands

Examples

Renaming a Utility Function Across Files (TypeScript)

Finding Usages of a Python Class

Tracing External Module Imports

Cross-File Editing with Definition Lookup

Best Practices

Troubleshooting

Next Steps