#!/usr/bin/env node

/**

* Scans the Rust codebase to find unused turbo-tasks items:

* - #[turbo_tasks::function] → fn definitions

* - #[turbo_tasks::value] → struct/enum definitions

* - #[turbo_tasks::value_trait] → trait definitions

*

* Exit code 0: no unused items found

* Exit code 1: unused items found

*

* Usage: node scripts/check-unused-turbo-tasks.mjs

*/

import { readdir, readFile } from 'node:fs/promises'

import { join, relative } from 'node:path'

import { fileURLToPath } from 'node:url'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

const ROOT = join(__dirname, '..')

const SCAN_DIRS = [join(ROOT, 'turbopack/crates'), join(ROOT, 'crates')]

const EXCLUDE_DIRS = ['turbo-tasks-macros-tests']

// After seeing an attribute, give up looking for the item it annotates

// if we haven't found it within this many lines.

const MAX_ANNOTATION_DISTANCE = 10

// ---------------------------------------------------------------------------

// Regexes

// ---------------------------------------------------------------------------

// Attribute detection (applied to trimmed lines)

const TT_FUNCTION_RE = /^#\[turbo_tasks::function/

const TT_VALUE_RE = /^#\[turbo_tasks::value(?![_a-zA-Z0-9])/ // not value_impl or value_trait

const TT_VALUE_IMPL_RE = /^#\[turbo_tasks::value_impl/

const TT_VALUE_TRAIT_RE = /^#\[turbo_tasks::value_trait/

// Item-header extraction

const FN_NAME_RE = /\bfn\s+([a-zA-Z_][a-zA-Z0-9_]*)/

const STRUCT_ENUM_RE =

/^\s*(?:pub(?:\([^)]*\))?\s+)?(?:struct|enum)\s+([A-Za-z_][A-Za-z0-9_]*)/

const TRAIT_RE = /^\s*(?:pub\s+)?trait\s+([A-Za-z_][A-Za-z0-9_]*)/

const IMPL_TRAIT_FOR_RE =

/^\s*impl\s*(?:<[^>]*>\s*)?([A-Za-z_][A-Za-z0-9_:]*(?:<[^>]*>)?)\s+for\s+([A-Za-z_][A-Za-z0-9_:]*)/

const IMPL_INHERENT_RE = /^\s*impl\s*(?:<[^>]*>\s*)?([A-Za-z_][A-Za-z0-9_:]*)/

// Usage scanning

const IDENT_RE = /\b([a-zA-Z_][a-zA-Z0-9_]*)\b/g

// ---------------------------------------------------------------------------

// Types

// ---------------------------------------------------------------------------

/**

* @typedef {{

* name: string,

* kind: 'function' | 'value' | 'value_trait',

* filePath: string,

* line: number,

* context: 'free' | 'inherent_impl' | 'trait_impl' | 'trait_def',

* typeName?: string,

* traitName?: string,

* }} Definition

*/

// ---------------------------------------------------------------------------

// Helpers

// ---------------------------------------------------------------------------

/**

* Tracks a "pending annotation": an attribute was seen on some line and we are

* scanning forward to find the item it annotates (a fn, struct, enum, or trait).

*

* Returns null when a match is found or the search window expires, along with

* the matched name (or null).

*/

function resolvePending(pending, currentLine, trimmed, itemRe) {

if (pending < 0) return { pending, match: null }

const m = itemRe.exec(trimmed)

if (m) return { pending: -1, match: m[1] }

if (currentLine - pending > MAX_ANNOTATION_DISTANCE)

return { pending: -1, match: null }

return { pending, match: null }

}

/**

* Count unbalanced braces on a line, ignoring string literals and comments.

*/

function countBraces(line) {

let depth = 0

let inString = false

let escape = false

let inChar = false

for (let i = 0; i < line.length; i++) {

const ch = line[i]

if (escape) {

escape = false

continue

}

if (ch === '\\') {

escape = true

continue

}

// Line comment — stop processing

if (!inString && !inChar && ch === '/' && line[i + 1] === '/') break

if (inString) {

if (ch === '"') inString = false

continue

}

if (inChar) {

if (ch === "'") inChar = false

continue

}

if (ch === '"') {

inString = true

continue

}

// Simplified char literal detection ('x')

if (ch === "'" && i + 2 < line.length && line[i + 2] === "'") {

i += 2

continue

}

if (ch === '{') depth++

if (ch === '}') depth--

}

return depth

}

/**

* Format a Definition for display.

*/

function formatDefinition(def, relPath) {

const loc = `${relPath}:${def.line}`

if (def.kind === 'value') return ` ${loc} - value ${def.name}`

if (def.kind === 'value_trait') return ` ${loc} - value_trait ${def.name}`

const contextLabels = {

free: 'free function',

inherent_impl: `method on ${def.typeName}`,

trait_impl: `impl ${def.traitName} for ${def.typeName}`,

trait_def: `trait ${def.traitName} default method`,

}

const ctx = contextLabels[def.context] ?? def.context

return ` ${loc} - fn ${def.name} (${ctx})`

}

// ---------------------------------------------------------------------------

// Phase 0: Discover all .rs files

// ---------------------------------------------------------------------------

async function discoverRsFiles(dirs) {

const files = []

for (const dir of dirs) {

let entries

try {

entries = await readdir(dir, { recursive: true, withFileTypes: false })

} catch {

continue

}

for (const entry of entries) {

if (entry.endsWith('.rs')) {

const parts = entry.split('/')

if (parts.some((p) => EXCLUDE_DIRS.includes(p))) continue

files.push(join(dir, entry))

}

}

}

return files

}

// ---------------------------------------------------------------------------

// Phase 1: Extract definitions

// ---------------------------------------------------------------------------

/**

* Parse a single .rs file for turbo-tasks definitions.

*

* Tracks three kinds of pending annotations:

* - #[turbo_tasks::function] → expects `fn <name>`

* - #[turbo_tasks::value] → expects `struct <name>` or `enum <name>`

* - #[turbo_tasks::value_trait] → expects `trait <name>`

*

* Also maintains a block stack to determine whether a function lives inside a

* #[turbo_tasks::value_impl] or #[turbo_tasks::value_trait] block, which gives

* the function its context (inherent method, trait impl, trait default method).

*/

function parseDefinitions(filePath, content) {

const lines = content.split('\n')

/** @type {Definition[]} */

const definitions = []

let braceDepth = 0

/**

* Stack of impl/trait blocks we're inside (for function context).

* @type {Array<{ startDepth: number, typeName?: string, traitName?: string, implKind: 'inherent' | 'trait' | 'trait_def' }>}

*/

const blockStack = []

// Pending attribute state: line index where the attribute was seen, or -1.

let pendingFn = -1

let pendingValue = -1

let pendingValueTrait = -1

let pendingBlockType = null // 'value_impl' | 'value_trait'

for (let i = 0; i < lines.length; i++) {

const line = lines[i]

const trimmed = line.trimStart()

const isComment = trimmed.startsWith('//')

if (!isComment) {

// --- Detect attributes ---

if (TT_VALUE_IMPL_RE.test(trimmed)) pendingBlockType = 'value_impl'

if (TT_VALUE_TRAIT_RE.test(trimmed)) {

pendingBlockType = 'value_trait'

pendingValueTrait = i

}

if (TT_VALUE_RE.test(trimmed)) pendingValue = i

if (TT_FUNCTION_RE.test(trimmed)) pendingFn = i

// --- Resolve pending value/value_trait annotations into definitions ---

{

const r = resolvePending(pendingValue, i, trimmed, STRUCT_ENUM_RE)

pendingValue = r.pending

if (r.match) {

definitions.push({

name: r.match,

kind: 'value',

filePath,

line: i + 1,

context: 'free',

})

}

}

{

const r = resolvePending(pendingValueTrait, i, trimmed, TRAIT_RE)

pendingValueTrait = r.pending

if (r.match) {

definitions.push({

name: r.match,

kind: 'value_trait',

filePath,

line: i + 1,

context: 'free',

})

}

}

// --- Resolve pending function annotations ---

{

const r = resolvePending(pendingFn, i, trimmed, FN_NAME_RE)

pendingFn = r.pending

if (r.match) {

const block =

blockStack.length > 0 ? blockStack[blockStack.length - 1] : null

let context = 'free'

let typeName, traitName

if (block) {

if (block.implKind === 'inherent') {

context = 'inherent_impl'

typeName = block.typeName

} else if (block.implKind === 'trait') {

context = 'trait_impl'

typeName = block.typeName

traitName = block.traitName

} else if (block.implKind === 'trait_def') {

context = 'trait_def'

traitName = block.traitName

}

}

definitions.push({

name: r.match,

kind: 'function',

filePath,

line: i + 1,

context,

...(typeName && { typeName }),

...(traitName && { traitName }),

})

}

}

// --- Resolve pending block headers (value_impl / value_trait) ---

if (pendingBlockType === 'value_impl') {

const traitImplMatch = IMPL_TRAIT_FOR_RE.exec(trimmed)

if (traitImplMatch) {

blockStack.push({

startDepth: braceDepth,

traitName: traitImplMatch[1],

typeName: traitImplMatch[2],

implKind: 'trait',

})

pendingBlockType = null

} else {

const inherentMatch = IMPL_INHERENT_RE.exec(trimmed)

if (inherentMatch && trimmed.includes('{')) {

blockStack.push({

startDepth: braceDepth,

typeName: inherentMatch[1],

implKind: 'inherent',

})

pendingBlockType = null

}

// else: impl line without opening brace yet — keep waiting

}

} else if (pendingBlockType === 'value_trait') {

const traitMatch = TRAIT_RE.exec(trimmed)

if (traitMatch) {

blockStack.push({

startDepth: braceDepth,

traitName: traitMatch[1],

implKind: 'trait_def',

})

pendingBlockType = null

}

}

}

// Track brace depth (even for comment lines — countBraces skips //)

braceDepth += countBraces(line)

// Pop blocks that have closed

while (

blockStack.length > 0 &&

braceDepth <= blockStack[blockStack.length - 1].startDepth

) {

blockStack.pop()

}

}

return definitions

}

// ---------------------------------------------------------------------------

// Phase 2: Find used names

// ---------------------------------------------------------------------------

/**

* Scan all file contents and return the set of definition names that appear

* at least once outside their definition site.

*

* @param {Map<string, string>} fileContents

* @param {Set<string>} names

* @param {Map<string, Set<string>>} definitionLocations name → Set<"path:line">

* @returns {Set<string>}

*/

function findUsedNames(fileContents, names, definitionLocations) {

const used = new Set()

for (const [filePath, content] of fileContents) {

const lines = content.split('\n')

for (let i = 0; i < lines.length; i++) {

const line = lines[i]

if (line.trimStart().startsWith('//')) continue

let match

IDENT_RE.lastIndex = 0

while ((match = IDENT_RE.exec(line)) !== null) {

const name = match[1]

if (used.has(name) || !names.has(name)) continue

// Skip the definition site itself

const defLocs = definitionLocations.get(name)

if (defLocs && defLocs.has(`${filePath}:${i + 1}`)) continue

used.add(name)

if (used.size === names.size) return used

}

}

}

return used

}

// ---------------------------------------------------------------------------

// Main

// ---------------------------------------------------------------------------

async function main() {

const rsFiles = await discoverRsFiles(SCAN_DIRS)

/** @type {Map<string, string>} */

const fileContents = new Map()

await Promise.all(

rsFiles.map(async (filePath) => {

try {

fileContents.set(filePath, await readFile(filePath, 'utf-8'))

} catch {

/* skip unreadable files */

}

})

)

// Parse definitions from all files

/** @type {Definition[]} */

const allDefinitions = []

for (const [filePath, content] of fileContents) {

allDefinitions.push(...parseDefinitions(filePath, content))

}

// Build indexes

const allNames = new Set(allDefinitions.map((d) => d.name))

/** @type {Map<string, Set<string>>} */

const definitionLocations = new Map()

for (const def of allDefinitions) {

const key = `${def.filePath}:${def.line}`

if (!definitionLocations.has(def.name)) {

definitionLocations.set(def.name, new Set())

}

definitionLocations.get(def.name).add(key)

}

// Find which names have external usage

const usedNames = findUsedNames(fileContents, allNames, definitionLocations)

// Collect and sort unused definitions

const unused = allDefinitions

.filter((d) => !usedNames.has(d.name))

.sort((a, b) => a.filePath.localeCompare(b.filePath) || a.line - b.line)

// Report

if (unused.length === 0) {

console.log(

`No unused turbo-tasks items found (${allDefinitions.length} total checked).`

)

process.exit(0)

}

console.log('Unused turbo-tasks items:\n')

for (const def of unused) {

console.log(formatDefinition(def, relative(ROOT, def.filePath)))

}

console.log(

`\nFound ${unused.length} unused turbo-tasks item(s) out of ${allDefinitions.length} total.`

)

process.exit(1)

}

main().catch((err) => {

console.error(err)

process.exit(2)

})