@electric-sql/client 1.5.11 → 1.5.13

package/bin/lib/shape-stream-static-analysis.mjs

@@ -0,0 +1,1067 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+
+const PACKAGE_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  `..`,
+  `..`
+)
+const GIT_ROOT = resolveGitRoot()
+
+const CLIENT_FILE = path.join(PACKAGE_DIR, `src`, `client.ts`)
+const STATE_MACHINE_FILE = path.join(
+  PACKAGE_DIR,
+  `src`,
+  `shape-stream-state.ts`
+)
+const ANALYSIS_DIRS = [`src`, `test`, `bin`]
+const ANALYSIS_EXTENSIONS = new Set([`.ts`, `.tsx`, `.js`, `.mjs`])
+const ANALYSIS_EXCLUDED_DIRS = new Set([
+  `dist`,
+  `node_modules`,
+  `junit`,
+  `coverage`,
+  `fixtures`,
+])
+const PROTOCOL_LITERAL_METHODS = new Set([
+  `get`,
+  `set`,
+  `has`,
+  `append`,
+  `delete`,
+])
+const PROTOCOL_LITERAL_CANONICAL_VALUES = [
+  `electric-cursor`,
+  `electric-handle`,
+  `electric-offset`,
+  `electric-schema`,
+  `electric-up-to-date`,
+  `cursor`,
+  `expired_handle`,
+  `handle`,
+  `live`,
+  `offset`,
+  `table`,
+  `where`,
+  `replica`,
+  `params`,
+  `experimental_live_sse`,
+  `live_sse`,
+  `log`,
+  `subset__where`,
+  `subset__limit`,
+  `subset__offset`,
+  `subset__order_by`,
+  `subset__params`,
+  `subset__where_expr`,
+  `subset__order_by_expr`,
+  `cache-buster`,
+]
+const PROTOCOL_LITERAL_BY_NORMALIZED = new Map(
+  PROTOCOL_LITERAL_CANONICAL_VALUES.map((value) => [
+    normalizeLiteral(value),
+    value,
+  ])
+)
+
+const SHARED_FIELD_IGNORE = new Set([
+  `#syncState`,
+  `#started`,
+  `#connected`,
+  `#error`,
+  `#messageChain`,
+  `#onError`,
+  `#mode`,
+  `#pauseLock`,
+  `#subscribers`,
+  `#snapshotTracker`,
+  `#snapshotCounter`,
+  `#unsubscribeFromVisibilityChanges`,
+  `#unsubscribeFromWakeDetection`,
+  `#transformer`,
+  `#currentFetchUrl`,
+  `#tickPromise`,
+])
+
+const ALLOWED_IGNORED_ACTION_CLASSES = new Set([`ErrorState`, `PausedState`])
+
+export function analyzeTypeScriptClient(options = {}) {
+  const packageDir = options.packageDir ?? PACKAGE_DIR
+  const clientFile = path.join(packageDir, `src`, `client.ts`)
+  const stateMachineFile = path.join(packageDir, `src`, `shape-stream-state.ts`)
+
+  const clientAnalysis = analyzeShapeStreamClient(clientFile)
+  const stateMachineAnalysis = analyzeStateMachine(stateMachineFile)
+  const protocolLiteralAnalysis = analyzeProtocolLiterals(
+    listAnalysisFiles(packageDir),
+    {
+      requireConstantsInFiles: (filePath) =>
+        filePath.includes(`${path.sep}src${path.sep}`),
+    }
+  )
+
+  const findings = clientAnalysis.findings
+    .concat(stateMachineAnalysis.findings)
+    .concat(protocolLiteralAnalysis.findings)
+    .sort(compareFindings)
+
+  return {
+    packageDir,
+    clientFile,
+    stateMachineFile,
+    findings,
+    reports: {
+      recursiveMethods: clientAnalysis.recursiveMethods,
+      sharedFieldReport: clientAnalysis.sharedFieldReport,
+      ignoredActionReport: stateMachineAnalysis.ignoredActionReport,
+      protocolLiteralReport: protocolLiteralAnalysis.report,
+    },
+  }
+}
+
+export function analyzeShapeStreamClient(filePath = CLIENT_FILE) {
+  const sourceFile = readSourceFile(filePath)
+  const classDecl = sourceFile.statements.find(
+    (statement) =>
+      ts.isClassDeclaration(statement) && statement.name?.text === `ShapeStream`
+  )
+
+  if (!classDecl) {
+    throw new Error(`Could not find ShapeStream class in ${filePath}`)
+  }
+
+  const classInfo = buildClassInfo(sourceFile, classDecl)
+  const recursiveMethods = buildRecursiveMethodReport(classInfo)
+  const sharedFieldReport = buildSharedFieldReport(classInfo)
+  const findings = sharedFieldReport
+    .filter((report) => report.risky)
+    .map((report) => ({
+      kind: `shared-instance-field`,
+      severity: `warning`,
+      title: `Shared mutable field spans async boundaries: ${report.field}`,
+      message:
+        `${report.field} is written before an await or async internal call and ` +
+        `is also consumed by other methods. This can leak retry/cache-buster state ` +
+        `across concurrent call chains.`,
+      file: filePath,
+      line: report.primaryLine,
+      locations: uniqueLocations([
+        {
+          file: filePath,
+          line: report.primaryLine,
+          label: `first async write`,
+        },
+        ...report.writerLines.map((line) => ({
+          file: filePath,
+          line,
+          label: `writer`,
+        })),
+        ...report.readerLines.map((line) => ({
+          file: filePath,
+          line,
+          label: `reader/reset`,
+        })),
+      ]),
+      details: {
+        field: report.field,
+        writerMethods: report.writerMethods,
+        readerMethods: report.readerMethods,
+        reasons: report.reasons,
+      },
+    }))
+
+  return {
+    sourceFile,
+    classInfo,
+    recursiveMethods,
+    sharedFieldReport,
+    findings,
+  }
+}
+
+export function analyzeStateMachine(filePath = STATE_MACHINE_FILE) {
+  const sourceFile = readSourceFile(filePath)
+  const findings = []
+  const ignoredActionReport = []
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isClassDeclaration(statement) || !statement.name) continue
+
+    const className = statement.name.text
+    for (const member of statement.members) {
+      if (!ts.isMethodDeclaration(member) || !member.body || !member.name) {
+        continue
+      }
+
+      const methodName = formatMemberName(member.name)
+      const returnsIgnored = []
+
+      walk(member.body, (node) => {
+        if (!ts.isReturnStatement(node) || !node.expression) return
+        if (!ts.isObjectLiteralExpression(node.expression)) return
+
+        const actionProperty = getObjectLiteralPropertyValue(
+          node.expression,
+          `action`
+        )
+        if (actionProperty !== `ignored`) return
+
+        const statePropertyNode = getObjectLiteralPropertyNode(
+          node.expression,
+          `state`
+        )
+        const stateIsThis =
+          statePropertyNode != null &&
+          ts.isPropertyAssignment(statePropertyNode) &&
+          statePropertyNode.initializer.kind === ts.SyntaxKind.ThisKeyword
+
+        returnsIgnored.push({
+          line: getLine(sourceFile, node),
+          stateIsThis,
+        })
+      })
+
+      if (returnsIgnored.length === 0) continue
+
+      ignoredActionReport.push({
+        className,
+        methodName,
+        lines: returnsIgnored.map((entry) => entry.line),
+      })
+
+      if (ALLOWED_IGNORED_ACTION_CLASSES.has(className)) continue
+
+      for (const entry of returnsIgnored) {
+        findings.push({
+          kind: `ignored-response-transition`,
+          severity: `warning`,
+          title: `Non-delegating state returns ignored action`,
+          message:
+            `${className}.${methodName} returns { action: 'ignored' } outside ` +
+            `the delegate/error states. This is a high-risk pattern for retry loops ` +
+            `when the caller keeps requesting with unchanged URL state.`,
+          file: filePath,
+          line: entry.line,
+          locations: [
+            {
+              file: filePath,
+              line: entry.line,
+              label: `${className}.${methodName}`,
+            },
+          ],
+          details: {
+            className,
+            methodName,
+            stateIsThis: entry.stateIsThis,
+          },
+        })
+      }
+    }
+  }
+
+  return {
+    sourceFile,
+    findings,
+    ignoredActionReport,
+  }
+}
+
+export function analyzeProtocolLiterals(filePaths, options = {}) {
+  const findings = []
+  const report = []
+  const requireConstantsInFiles =
+    options.requireConstantsInFiles ?? (() => false)
+
+  for (const filePath of filePaths) {
+    const sourceFile = readSourceFile(filePath)
+
+    walk(sourceFile, (node) => {
+      const candidate = getProtocolLiteralCandidate(sourceFile, node)
+      if (!candidate) return
+
+      const requireConstants = requireConstantsInFiles(filePath)
+      const kind =
+        candidate.literal === candidate.canonical
+          ? requireConstants
+            ? `raw-protocol-literal`
+            : null
+          : `protocol-literal-drift`
+
+      if (!kind) return
+
+      report.push({
+        ...candidate,
+        kind,
+      })
+
+      findings.push({
+        kind,
+        severity: `warning`,
+        title:
+          kind === `raw-protocol-literal`
+            ? `Raw Electric protocol literal should use shared constant`
+            : `Near-miss Electric protocol literal: ${candidate.literal}`,
+        message:
+          kind === `raw-protocol-literal`
+            ? `${candidate.literal} is a canonical Electric protocol literal ` +
+              `used directly in implementation code. Import the shared constant ` +
+              `instead to avoid drift between call sites.`
+            : `${candidate.literal} is a near-miss for the canonical Electric ` +
+              `protocol literal ${candidate.canonical}. Use the shared constant ` +
+              `or canonical string to avoid URL/header drift.`,
+        file: filePath,
+        line: candidate.line,
+        locations: [
+          {
+            file: filePath,
+            line: candidate.line,
+            label: candidate.context,
+          },
+        ],
+        details: {
+          literal: candidate.literal,
+          canonical: candidate.canonical,
+          context: candidate.context,
+        },
+      })
+    })
+  }
+
+  return {
+    findings: findings.sort(compareFindings),
+    report: report.sort(compareReports),
+  }
+}
+
+export function loadChangedLines(range, files) {
+  const relativeFiles = files.map((file) => path.relative(GIT_ROOT, file))
+  const diffOutput = execFileSync(
+    `git`,
+    [`diff`, `--unified=0`, `--no-color`, range, `--`, ...relativeFiles],
+    {
+      cwd: GIT_ROOT,
+      encoding: `utf8`,
+      stdio: [`ignore`, `pipe`, `pipe`],
+    }
+  )
+
+  return parseChangedLines(diffOutput)
+}
+
+export function filterFindingsToChangedLines(findings, changedLines) {
+  return findings.filter((finding) => {
+    const locations = finding.locations?.length
+      ? finding.locations
+      : [{ file: finding.file, line: finding.line }]
+
+    return locations.some((location) =>
+      lineIsChanged(changedLines, location.file, location.line)
+    )
+  })
+}
+
+export function filterFindingsToChangedFiles(findings, changedLines) {
+  const changedFiles = new Set(changedLines.keys())
+  return findings.filter((finding) => changedFiles.has(finding.file))
+}
+
+export function formatAnalysisResult(result, options = {}) {
+  const changedLines = options.changedLines
+  const findings = changedLines
+    ? filterFindingsToChangedLines(result.findings, changedLines)
+    : result.findings
+
+  const lines = []
+  lines.push(`Findings: ${findings.length}`)
+
+  if (findings.length === 0) {
+    lines.push(`No findings.`)
+  } else {
+    for (const finding of findings) {
+      lines.push(
+        `${finding.severity.toUpperCase()} ${finding.kind} ` +
+          `${path.relative(result.packageDir, finding.file)}:${finding.line}`
+      )
+      lines.push(`  ${finding.title}`)
+      lines.push(`  ${finding.message}`)
+    }
+  }
+
+  if (!changedLines) {
+    lines.push(``)
+    lines.push(`Recursive Methods:`)
+    for (const report of result.reports.recursiveMethods) {
+      const cycles =
+        report.callees.length === 0
+          ? `no internal calls`
+          : report.callees.join(`, `)
+      lines.push(
+        `  ${report.name} (${path.relative(result.packageDir, report.file)}:${report.line}) -> ${cycles}`
+      )
+    }
+
+    lines.push(``)
+    lines.push(`Shared Field Candidates:`)
+    for (const report of result.reports.sharedFieldReport) {
+      const flag = report.risky ? `!` : `-`
+      lines.push(
+        `  ${flag} ${report.field}: writers=${report.writerMethods.join(`, `) || `none`} ` +
+          `readers=${report.readerMethods.join(`, `) || `none`}`
+      )
+    }
+
+    lines.push(``)
+    lines.push(`Ignored Action Sites:`)
+    for (const report of result.reports.ignoredActionReport) {
+      lines.push(
+        `  ${report.className}.${report.methodName} lines ${report.lines.join(`, `)}`
+      )
+    }
+
+    lines.push(``)
+    lines.push(`Protocol Literal Sites:`)
+    if (result.reports.protocolLiteralReport.length === 0) {
+      lines.push(`  none`)
+    } else {
+      for (const report of result.reports.protocolLiteralReport) {
+        lines.push(
+          `  ${report.kind} ${path.relative(result.packageDir, report.file)}:${report.line} ` +
+            `${report.literal} -> ${report.canonical} (${report.context})`
+        )
+      }
+    }
+  }
+
+  return lines.join(`\n`)
+}
+
+function analyzeMethod(sourceFile, methodNames, fieldNames, methodNode) {
+  const name = formatMemberName(methodNode.name)
+  const summary = {
+    name,
+    file: sourceFile.fileName,
+    line: getLine(sourceFile, methodNode.name),
+    async: methodNode.modifiers?.some(
+      (modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword
+    )
+      ? true
+      : false,
+    public: !name.startsWith(`#`) && name !== `constructor`,
+    calls: [],
+    fieldReads: new Map(),
+    fieldWrites: new Map(),
+    awaits: [],
+  }
+
+  walk(methodNode.body, (node) => {
+    if (ts.isAwaitExpression(node)) {
+      summary.awaits.push(getLine(sourceFile, node))
+      return
+    }
+
+    if (ts.isCallExpression(node)) {
+      const callee = getThisMemberName(node.expression)
+      if (callee && methodNames.has(callee)) {
+        summary.calls.push({
+          callee,
+          line: getLine(sourceFile, node),
+        })
+      }
+      return
+    }
+
+    if (!ts.isPropertyAccessExpression(node)) return
+
+    const member = getThisMemberName(node)
+    if (!member || methodNames.has(member) || !fieldNames.has(member)) return
+
+    if (ts.isCallExpression(node.parent) && node.parent.expression === node) {
+      return
+    }
+
+    const line = getLine(sourceFile, node)
+    if (isWritePosition(node)) {
+      pushMapArray(summary.fieldWrites, member, line)
+    } else {
+      pushMapArray(summary.fieldReads, member, line)
+    }
+  })
+
+  return summary
+}
+
+function buildClassInfo(sourceFile, classDecl) {
+  const fieldNames = new Set()
+  const methodNames = new Set()
+  const methods = new Map()
+
+  for (const member of classDecl.members) {
+    if (
+      ts.isPropertyDeclaration(member) &&
+      member.name &&
+      (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name))
+    ) {
+      fieldNames.add(formatMemberName(member.name))
+      continue
+    }
+
+    if (
+      ts.isGetAccessorDeclaration(member) &&
+      member.name &&
+      (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name))
+    ) {
+      fieldNames.add(formatMemberName(member.name))
+      continue
+    }
+
+    if (
+      ts.isMethodDeclaration(member) &&
+      member.name &&
+      (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name))
+    ) {
+      methodNames.add(formatMemberName(member.name))
+      continue
+    }
+  }
+
+  for (const member of classDecl.members) {
+    if (!ts.isMethodDeclaration(member) || !member.body || !member.name)
+      continue
+    methods.set(
+      formatMemberName(member.name),
+      analyzeMethod(sourceFile, methodNames, fieldNames, member)
+    )
+  }
+
+  return {
+    sourceFile,
+    fieldNames,
+    methodNames,
+    methods,
+  }
+}
+
+function buildRecursiveMethodReport(classInfo) {
+  const graph = new Map()
+  for (const [name, method] of classInfo.methods) {
+    graph.set(name, [
+      ...new Set(
+        method.calls
+          .map((call) => call.callee)
+          .filter((callee) => callee !== name)
+      ),
+    ])
+  }
+
+  const recursiveSet = new Set()
+  for (const component of stronglyConnectedComponents(graph)) {
+    if (component.length > 1) {
+      component.forEach((name) => recursiveSet.add(name))
+      continue
+    }
+
+    const [single] = component
+    const method = classInfo.methods.get(single)
+    if (method?.calls.some((call) => call.callee === single)) {
+      recursiveSet.add(single)
+    }
+  }
+
+  return [...classInfo.methods.values()]
+    .filter((method) => recursiveSet.has(method.name))
+    .map((method) => ({
+      name: method.name,
+      file: method.file,
+      line: method.line,
+      callees: [...new Set(method.calls.map((call) => call.callee))].sort(),
+    }))
+    .sort(compareReports)
+}
+
+function buildSharedFieldReport(classInfo) {
+  const reports = []
+
+  for (const field of [...classInfo.fieldNames].sort()) {
+    if (SHARED_FIELD_IGNORE.has(field)) continue
+    if (!isCandidateEphemeralField(field)) continue
+
+    const writers = []
+    const readers = []
+    const reasons = []
+
+    for (const method of classInfo.methods.values()) {
+      const writeLines = method.fieldWrites.get(field) ?? []
+      const readLines = method.fieldReads.get(field) ?? []
+
+      if (writeLines.length > 0) {
+        const hasAsyncBoundary = writeLines.some((line) =>
+          hasAsyncBoundaryAfterLine(method, classInfo.methods, line)
+        )
+
+        writers.push({
+          method: method.name,
+          lines: writeLines,
+          hasAsyncBoundary,
+        })
+
+        if (hasAsyncBoundary) {
+          reasons.push(
+            `${field} is written in ${method.name} before a later await/async internal call`
+          )
+        }
+      }
+
+      if (readLines.length > 0) {
+        readers.push({
+          method: method.name,
+          lines: readLines,
+        })
+      }
+    }
+
+    if (writers.length === 0 && readers.length === 0) continue
+
+    const writerMethods = writers.map((writer) => writer.method)
+    const readerMethods = readers.map((reader) => reader.method)
+    const writerLines = writers.flatMap((writer) => writer.lines)
+    const readerLines = readers.flatMap((reader) => reader.lines)
+    const crossMethodUse = new Set(writerMethods.concat(readerMethods)).size > 1
+    const hasRiskyWriter = writers.some((writer) => writer.hasAsyncBoundary)
+    const constructUrlConsumes = readers.some(
+      (reader) => reader.method === `#constructUrl`
+    )
+    const publicMethodTouches = readers
+      .concat(writers)
+      .some((entry) => !entry.method.startsWith(`#`))
+    const highRiskField = /(?:Buster|Retry)/.test(field)
+
+    if (constructUrlConsumes) {
+      reasons.push(
+        `${field} is consumed by #constructUrl, which multiple paths call`
+      )
+    }
+    if (publicMethodTouches) {
+      reasons.push(`${field} is reachable from a public API surface`)
+    }
+
+    reports.push({
+      field,
+      risky:
+        crossMethodUse &&
+        hasRiskyWriter &&
+        (constructUrlConsumes || highRiskField),
+      primaryLine: writerLines[0] ?? readerLines[0],
+      writerMethods,
+      readerMethods,
+      writerLines,
+      readerLines,
+      reasons: [...new Set(reasons)].sort(),
+    })
+  }
+
+  return reports.sort(compareReports)
+}
+
+function stronglyConnectedComponents(graph) {
+  let index = 0
+  const stack = []
+  const indices = new Map()
+  const lowLinks = new Map()
+  const onStack = new Set()
+  const components = []
+
+  const visit = (node) => {
+    indices.set(node, index)
+    lowLinks.set(node, index)
+    index += 1
+    stack.push(node)
+    onStack.add(node)
+
+    for (const neighbor of graph.get(node) ?? []) {
+      if (!indices.has(neighbor)) {
+        visit(neighbor)
+        lowLinks.set(node, Math.min(lowLinks.get(node), lowLinks.get(neighbor)))
+      } else if (onStack.has(neighbor)) {
+        lowLinks.set(node, Math.min(lowLinks.get(node), indices.get(neighbor)))
+      }
+    }
+
+    if (lowLinks.get(node) !== indices.get(node)) return
+
+    const component = []
+    while (stack.length > 0) {
+      const current = stack.pop()
+      onStack.delete(current)
+      component.push(current)
+      if (current === node) break
+    }
+    components.push(component.sort())
+  }
+
+  for (const node of graph.keys()) {
+    if (!indices.has(node)) visit(node)
+  }
+
+  return components
+}
+
+function parseChangedLines(diffOutput) {
+  const changedLines = new Map()
+  let currentFile
+
+  for (const line of diffOutput.split(`\n`)) {
+    if (line.startsWith(`+++ b/`)) {
+      currentFile = path.join(GIT_ROOT, line.slice(6))
+      continue
+    }
+
+    if (!line.startsWith(`@@`) || !currentFile) continue
+
+    const match = /@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line)
+    if (!match) continue
+
+    const start = Number(match[1])
+    const count = Number(match[2] ?? `1`)
+    const lines = changedLines.get(currentFile) ?? new Set()
+    const end = count === 0 ? start : start + count - 1
+
+    for (let lineNumber = start; lineNumber <= end; lineNumber += 1) {
+      lines.add(lineNumber)
+    }
+    changedLines.set(currentFile, lines)
+  }
+
+  return changedLines
+}
+
+function listAnalysisFiles(packageDir) {
+  const filePaths = []
+
+  for (const relativeDir of ANALYSIS_DIRS) {
+    const absoluteDir = path.join(packageDir, relativeDir)
+    if (!fs.existsSync(absoluteDir)) continue
+    walkDirectory(absoluteDir, filePaths)
+  }
+
+  return filePaths.sort()
+}
+
+function walkDirectory(directory, filePaths) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.name.startsWith(`.`)) continue
+    if (ANALYSIS_EXCLUDED_DIRS.has(entry.name)) continue
+
+    const absolutePath = path.join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      walkDirectory(absolutePath, filePaths)
+      continue
+    }
+
+    if (!ANALYSIS_EXTENSIONS.has(path.extname(entry.name))) continue
+    if (absolutePath === path.join(PACKAGE_DIR, `src`, `constants.ts`)) continue
+    filePaths.push(absolutePath)
+  }
+}
+
+function lineIsChanged(changedLines, file, line) {
+  return changedLines.get(file)?.has(line) ?? false
+}
+
+function readSourceFile(filePath) {
+  const text = fs.readFileSync(filePath, `utf8`)
+  return ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true)
+}
+
+function getProtocolLiteralCandidate(sourceFile, node) {
+  if (ts.isCallExpression(node)) {
+    return getProtocolLiteralCandidateFromCall(sourceFile, node)
+  }
+
+  if (isProtocolHeaderProperty(node)) {
+    return getProtocolLiteralCandidateFromHeaderProperty(sourceFile, node)
+  }
+
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return getProtocolLiteralCandidateFromLiteral(sourceFile, node)
+  }
+
+  return null
+}
+
+function getProtocolLiteralCandidateFromCall(sourceFile, callExpression) {
+  if (!ts.isPropertyAccessExpression(callExpression.expression)) return null
+  if (!PROTOCOL_LITERAL_METHODS.has(callExpression.expression.name.text)) {
+    return null
+  }
+
+  const [firstArg] = callExpression.arguments
+  const literal = getStringLiteralValue(firstArg)
+  if (!literal) return null
+
+  const receiver = callExpression.expression.expression
+  const receiverContext = getProtocolReceiverContext(receiver)
+  if (!receiverContext) return null
+
+  return createProtocolLiteralCandidate(
+    sourceFile,
+    firstArg,
+    literal,
+    `${receiverContext}.${callExpression.expression.name.text}`
+  )
+}
+
+function getProtocolLiteralCandidateFromHeaderProperty(
+  sourceFile,
+  propertyNode
+) {
+  const literal = getPropertyNameValue(propertyNode.name)
+  if (!literal) return null
+
+  return createProtocolLiteralCandidate(
+    sourceFile,
+    propertyNode.name,
+    literal,
+    `headers object property`
+  )
+}
+
+function getProtocolLiteralCandidateFromLiteral(sourceFile, node) {
+  const literal = node.text
+  if (!PROTOCOL_LITERAL_CANONICAL_VALUES.includes(literal)) return null
+
+  const parent = node.parent
+  if (!ts.isArrayLiteralExpression(parent)) return null
+  if (!isProtocolLiteralArray(parent)) return null
+
+  return createProtocolLiteralCandidate(
+    sourceFile,
+    node,
+    literal,
+    `protocol literal array`
+  )
+}
+
+function createProtocolLiteralCandidate(sourceFile, node, literal, context) {
+  const canonical = PROTOCOL_LITERAL_BY_NORMALIZED.get(
+    normalizeLiteral(literal)
+  )
+  if (!canonical) return null
+
+  return {
+    file: sourceFile.fileName,
+    line: getLine(sourceFile, node),
+    literal,
+    canonical,
+    context,
+  }
+}
+
+function getProtocolReceiverContext(receiver) {
+  if (ts.isPropertyAccessExpression(receiver)) {
+    if (receiver.name.text === `searchParams`) return `searchParams`
+    if (receiver.name.text === `headers`) return `headers`
+  }
+
+  if (ts.isIdentifier(receiver) && receiver.text === `headers`) {
+    return `headers`
+  }
+
+  return null
+}
+
+function isHeadersObjectLiteral(node) {
+  const parent = node.parent
+
+  if (
+    ts.isPropertyAssignment(parent) &&
+    getPropertyNameValue(parent.name) === `headers`
+  ) {
+    return true
+  }
+
+  if (
+    ts.isNewExpression(parent) &&
+    ts.isIdentifier(parent.expression) &&
+    parent.expression.text === `Headers`
+  ) {
+    return true
+  }
+
+  return false
+}
+
+function isProtocolHeaderProperty(node) {
+  if (!ts.isPropertyAssignment(node) || !node.name) return false
+  if (!ts.isObjectLiteralExpression(node.parent)) return false
+  return isHeadersObjectLiteral(node.parent)
+}
+
+function isProtocolLiteralArray(node) {
+  const parent = node.parent
+  if (!ts.isVariableDeclaration(parent) || !ts.isIdentifier(parent.name)) {
+    return false
+  }
+
+  return /(?:Header|Param)s$/.test(parent.name.text)
+}
+
+function walk(node, visit) {
+  visit(node)
+  ts.forEachChild(node, (child) => walk(child, visit))
+}
+
+function getThisMemberName(node) {
+  if (!ts.isPropertyAccessExpression(node)) return null
+  if (node.expression.kind !== ts.SyntaxKind.ThisKeyword) return null
+  return formatMemberName(node.name)
+}
+
+function isWritePosition(node) {
+  const parent = node.parent
+  if (!parent) return false
+
+  if (
+    ts.isBinaryExpression(parent) &&
+    parent.left === node &&
+    parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+    parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment
+  ) {
+    return true
+  }
+
+  if (
+    (ts.isPrefixUnaryExpression(parent) ||
+      ts.isPostfixUnaryExpression(parent)) &&
+    (parent.operator === ts.SyntaxKind.PlusPlusToken ||
+      parent.operator === ts.SyntaxKind.MinusMinusToken)
+  ) {
+    return true
+  }
+
+  return false
+}
+
+function getLine(sourceFile, node) {
+  return (
+    sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1
+  )
+}
+
+function formatMemberName(nameNode) {
+  if (ts.isPrivateIdentifier(nameNode)) {
+    return nameNode.text.startsWith(`#`) ? nameNode.text : `#${nameNode.text}`
+  }
+  if (
+    ts.isIdentifier(nameNode) ||
+    ts.isStringLiteral(nameNode) ||
+    ts.isNumericLiteral(nameNode)
+  ) {
+    return `${nameNode.text}`
+  }
+  return nameNode.getText()
+}
+
+function getPropertyNameValue(nameNode) {
+  if (
+    ts.isIdentifier(nameNode) ||
+    ts.isStringLiteral(nameNode) ||
+    ts.isNoSubstitutionTemplateLiteral(nameNode)
+  ) {
+    return nameNode.text
+  }
+
+  return null
+}
+
+function getStringLiteralValue(node) {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text
+  }
+
+  return null
+}
+
+function hasAsyncBoundaryAfterLine(method, methods, line) {
+  if (method.awaits.some((awaitLine) => awaitLine > line)) return true
+
+  return method.calls.some((call) => {
+    if (call.line <= line) return false
+    return methods.get(call.callee)?.async ?? false
+  })
+}
+
+function isCandidateEphemeralField(field) {
+  return /(?:Buster|Retry|Count|Counter|Recent|AbortController|Promise|Refresh|Duplicate)/.test(
+    field
+  )
+}
+
+function pushMapArray(map, key, value) {
+  const values = map.get(key)
+  if (values) {
+    values.push(value)
+    return
+  }
+  map.set(key, [value])
+}
+
+function uniqueLocations(locations) {
+  const seen = new Set()
+  const result = []
+
+  for (const location of locations) {
+    const key = `${location.file}:${location.line}:${location.label ?? ``}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(location)
+  }
+
+  return result
+}
+
+function getObjectLiteralPropertyNode(objectLiteral, propertyName) {
+  return objectLiteral.properties.find((property) => {
+    if (!ts.isPropertyAssignment(property) || !property.name) return false
+    return formatMemberName(property.name) === propertyName
+  })
+}
+
+function getObjectLiteralPropertyValue(objectLiteral, propertyName) {
+  const property = getObjectLiteralPropertyNode(objectLiteral, propertyName)
+  if (!property || !ts.isPropertyAssignment(property)) return undefined
+  if (ts.isStringLiteral(property.initializer)) return property.initializer.text
+  return undefined
+}
+
+function compareFindings(left, right) {
+  const fileCompare = left.file.localeCompare(right.file)
+  if (fileCompare !== 0) return fileCompare
+  return left.line - right.line
+}
+
+function compareReports(left, right) {
+  const leftLine = left.line ?? left.primaryLine ?? 0
+  const rightLine = right.line ?? right.primaryLine ?? 0
+  if (leftLine !== rightLine) return leftLine - rightLine
+  return (left.file ?? ``).localeCompare(right.file ?? ``)
+}
+
+function resolveGitRoot() {
+  try {
+    return execFileSync(`git`, [`rev-parse`, `--show-toplevel`], {
+      cwd: PACKAGE_DIR,
+      encoding: `utf8`,
+      stdio: [`ignore`, `pipe`, `ignore`],
+    }).trim()
+  } catch {
+    return PACKAGE_DIR
+  }
+}
+
+function normalizeLiteral(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, ``)
+}