weavatrix 0.2.13 → 0.2.14

package/src/precision/lsp-overlay/build.js

@@ -0,0 +1,238 @@
+import {boundedInteger} from '../../bounds.js'
+import {createTypeScriptLspClient} from '../typescript-lsp-provider.js'
+import {baseOverlay} from './contract.js'
+import {precisionOverlayMatches} from './contract.js'
+import {collectReferenceResults} from './reference-results.js'
+import {
+  PrecisionBudgetError,
+  PrecisionLimitError,
+  PrecisionStaleGraphError,
+  PrecisionStaleSemanticInputsError,
+  graphJavaScriptUniverse,
+  precisionSemanticInputs,
+  publicSemanticSafetyReason,
+} from './semantic-inputs.js'
+import {
+  awaitWithBudget,
+  ensureBudget,
+  initializeSourceSession,
+  remaining,
+} from './source-session.js'
+import {readPrecisionOverlay, writePrecisionOverlay} from './store.js'
+import {eligibleTargets, symbolIndex} from './target-index.js'
+import {queryPrecisionTarget} from './target-query.js'
+
+function persist(session, overlay) {
+  return session.graphPath ? writePrecisionOverlay(session.graphPath, overlay) : overlay
+}
+
+function coverage(session, verifiedEdges = session.links.length) {
+  return {
+    candidates: session.eligible.total,
+    selected: session.targets.length,
+    queried: session.queried,
+    references: session.references,
+    unclassifiedReferences: session.unclassifiedReferences,
+    verifiedEdges,
+    truncated: session.truncated,
+  }
+}
+
+function completedOverlay(session) {
+  const state = session.errors || session.truncated || session.unclassifiedReferences
+    ? 'PARTIAL' : 'COMPLETE'
+  return baseOverlay(session.graph, state, {
+    request: session.request,
+    engines: [{
+      provider: session.client.provider || 'typescript-language-server',
+      version: session.client.version || null,
+      typescriptVersion: session.client.typescriptVersion || null,
+      typescriptSource: session.client.typescriptSource || null,
+      language: 'typescript/javascript',
+      capability: 'textDocument/references',
+      status: state,
+    }],
+    semanticInputFingerprint: session.semanticInputs.fingerprint,
+    coverage: coverage(session),
+    links: session.links,
+    referenceEvidence: session.referenceEvidence,
+    ...(session.collectLocations ? {locations: session.exactLocations} : {}),
+    noReferenceSymbols: session.noReferenceSymbols,
+    ...(session.errors ? {reason: `${session.errors} semantic request(s) failed or were refused`}
+      : session.truncated ? {reason: 'semantic precision stopped at a configured safety limit'}
+        : session.unclassifiedReferences
+          ? {reason: 'some exact references could not be classified as runtime or type-only'} : {}),
+  })
+}
+
+function failedOverlay(session, error) {
+  const stale = error instanceof PrecisionStaleGraphError
+  const semanticInputsChanged = error instanceof PrecisionStaleSemanticInputsError
+  const deadlineReached = error instanceof PrecisionBudgetError || remaining(session) <= 0
+  const state = stale || semanticInputsChanged || deadlineReached ? 'PARTIAL' : 'UNAVAILABLE'
+  return baseOverlay(session.graph, state, {
+    request: session.request,
+    reason: stale
+      ? 'repository content no longer matched the graph snapshot'
+      : semanticInputsChanged ? 'TypeScript project inputs changed while semantic precision was running'
+        : deadlineReached ? 'semantic precision stopped at its global deadline'
+          : error?.name === 'LspTimeoutError' ? 'bundled TypeScript language server timed out'
+            : 'bundled TypeScript language server was unavailable',
+    engines: [{
+      provider: 'typescript-language-server',
+      version: null,
+      language: 'typescript/javascript',
+      capability: 'textDocument/references',
+      status: state,
+    }],
+    coverage: {
+      candidates: session.eligible.total,
+      selected: session.targets.length,
+      queried: stale || semanticInputsChanged ? 0 : session.queried,
+      references: stale || semanticInputsChanged ? 0 : session.references,
+      unclassifiedReferences: stale || semanticInputsChanged ? 0 : session.unclassifiedReferences,
+      verifiedEdges: 0,
+      truncated: session.truncated || stale || semanticInputsChanged || deadlineReached,
+    },
+    links: [],
+    noReferenceSymbols: [],
+  })
+}
+
+function createSession(options) {
+  const boundedMax = boundedInteger(options.maxSymbols, 32, 1, 64)
+  const boundedReferences = boundedInteger(options.maxReferences, 2_048, 1, 16_384)
+  const boundedLinks = boundedInteger(options.maxLinks, 2_048, 1, 16_384)
+  const boundedTimeout = boundedInteger(options.timeoutMs, 45_000, 100, 60_000)
+  return {
+    ...options,
+    boundedMax,
+    boundedReferences,
+    boundedLinks,
+    deadline: Date.now() + boundedTimeout,
+    request: {maxSymbols: boundedMax, maxReferences: boundedReferences, maxLinks: boundedLinks},
+    links: [],
+    seen: new Set(),
+    evidenceSeen: new Set(),
+    queried: 0,
+    references: 0,
+    unclassifiedReferences: 0,
+    errors: 0,
+    truncated: false,
+    noReferenceSymbols: [],
+    referenceEvidence: [],
+    exactLocations: [],
+    collectLocations: Array.isArray(options.targetIds) && options.targetIds.length > 0,
+    stop: false,
+  }
+}
+
+export async function buildLspPrecisionOverlay({
+  repoRoot,
+  graph,
+  graphPath,
+  mode = 'lsp',
+  maxSymbols = Number(process.env.WEAVATRIX_PRECISION_MAX_SYMBOLS) || 32,
+  maxReferences = Number(process.env.WEAVATRIX_PRECISION_MAX_REFERENCES) || 2_048,
+  maxLinks = Number(process.env.WEAVATRIX_PRECISION_MAX_LINKS) || 2_048,
+  timeoutMs = Number(process.env.WEAVATRIX_PRECISION_TIMEOUT_MS) || 45_000,
+  targetIds,
+  clientFactory,
+} = {}) {
+  if (!graph || !repoRoot) throw new Error('precision overlay requires repoRoot and graph')
+  const session = createSession({
+    repoRoot, graph, graphPath, mode, maxSymbols, maxReferences, maxLinks,
+    timeoutMs, targetIds, clientFactory,
+  })
+  if (mode === 'off') {
+    return persist(session, baseOverlay(graph, 'OFF', {
+      request: session.request,
+      reason: 'precision disabled by request',
+    }))
+  }
+  session.universe = graphJavaScriptUniverse(graph)
+  if (!session.universe.files.length) {
+    return persist(session, baseOverlay(graph, 'UNAVAILABLE', {
+      request: session.request,
+      reason: 'semantic precision currently supports JavaScript and TypeScript repositories',
+    }))
+  }
+  session.semanticInputs = precisionSemanticInputs(repoRoot, graph, {deadline: session.deadline})
+  if (!session.semanticInputs.safe) {
+    return persist(session, baseOverlay(graph, 'UNAVAILABLE', {
+      request: session.request,
+      reason: publicSemanticSafetyReason(session.semanticInputs.reason),
+      engines: [{
+        provider: 'typescript-language-server', version: null,
+        language: 'typescript/javascript', capability: 'textDocument/references',
+        status: 'UNAVAILABLE',
+      }],
+    }))
+  }
+  if (graphPath) {
+    const cached = readPrecisionOverlay(graphPath, graph)
+    if (cached?.state === 'COMPLETE'
+      && precisionOverlayMatches(cached, graph, {request: session.request})
+      && cached.semanticInputFingerprint === session.semanticInputs.fingerprint) return cached
+  }
+  session.eligible = eligibleTargets(graph, session.boundedMax, targetIds)
+  session.targets = session.eligible.targets
+  if (!session.targets.length) {
+    return persist(session, baseOverlay(graph, 'COMPLETE', {
+      request: session.request,
+      semanticInputFingerprint: session.semanticInputs.fingerprint,
+      reason: 'no eligible JavaScript/TypeScript semantic targets',
+    }))
+  }
+  session.truncated = session.eligible.total > session.boundedMax
+  session.index = symbolIndex(graph)
+  session.nodesById = new Map((graph.nodes || []).map((node) => [String(node.id), node]))
+  initializeSourceSession(session)
+  try {
+    const makeClient = clientFactory || createTypeScriptLspClient
+    session.client = await awaitWithBudget(
+      session,
+      () => makeClient({repoRoot, timeoutMs: Math.max(100, remaining(session))}),
+    )
+    for (const target of session.targets) {
+      let locations
+      try {
+        locations = await queryPrecisionTarget(session, target)
+      } catch (error) {
+        if (error instanceof PrecisionStaleGraphError) throw error
+        if (error instanceof PrecisionBudgetError || error instanceof PrecisionLimitError
+          || remaining(session) <= 0) {
+          session.truncated = true
+          session.stop = true
+          break
+        }
+        session.errors++
+        continue
+      }
+      collectReferenceResults(session, target, locations)
+      if (remaining(session) <= 0) {
+        session.truncated = true
+        session.stop = true
+      }
+      if (session.stop) break
+    }
+    ensureBudget(session)
+    const semanticInputsAfter = precisionSemanticInputs(repoRoot, graph, {deadline: session.deadline})
+    ensureBudget(session)
+    if (!semanticInputsAfter.safe
+      || semanticInputsAfter.fingerprint !== session.semanticInputs.fingerprint) {
+      throw new PrecisionStaleSemanticInputsError()
+    }
+    return persist(session, completedOverlay(session))
+  } catch (error) {
+    return persist(session, failedOverlay(session, error))
+  } finally {
+    if (session.client) {
+      const closeBudget = Math.min(2_000, Math.max(0, remaining(session)))
+      if (closeBudget > 0 && session.client.close) {
+        try { await awaitWithBudget(session, () => session.client.close(closeBudget)) }
+        catch { session.client.kill?.() }
+      } else session.client.kill?.()
+    }
+  }
+}

package/src/precision/lsp-overlay/contract.js

@@ -0,0 +1,61 @@
+import {typeScriptLspContract} from '../typescript-lsp-provider.js'
+
+export const PRECISION_OVERLAY_V = 3
+export const PRECISION_FILE = 'precision.json'
+export const JS_TS_FILE = /\.(?:[cm]?[jt]sx?)$/i
+export const endpoint = (value) => String(value && typeof value === 'object' ? value.id : value)
+export const norm = (value) => String(value || '').replace(/\\/g, '/').replace(/^\.\//, '')
+export const graphMode = (graph) => ['full', 'no-tests', 'tests-only'].includes(graph?.graphBuildMode)
+  ? graph.graphBuildMode : 'full'
+export const graphScope = (graph) => String(graph?.graphBuildScope || '')
+export const precisionMode = (graph) => graph?.graphPrecisionMode === 'off' ? 'off' : 'lsp'
+export const providerContractFor = (graph) => precisionMode(graph) === 'off' ? 'off' : typeScriptLspContract()
+export const graphContractFor = (graph) => ({
+  extractorSchemaV: Number(graph?.extractorSchemaV) || 0,
+  ...(graph?.repositoryFreshnessBuilderVersion != null
+    ? {repositoryFreshnessBuilderVersion: String(graph.repositoryFreshnessBuilderVersion)} : {}),
+  ...(graph?.graphBuilderVersion != null ? {graphBuilderVersion: String(graph.graphBuilderVersion)} : {}),
+  ...(graph?.internalBuilderVersion != null ? {internalBuilderVersion: String(graph.internalBuilderVersion)} : {}),
+})
+
+function sameRequest(actual, expected) {
+  if (!expected) return true
+  return Number(actual?.maxSymbols) === Number(expected.maxSymbols)
+    && Number(actual?.maxReferences) === Number(expected.maxReferences)
+    && Number(actual?.maxLinks) === Number(expected.maxLinks)
+}
+
+export function precisionOverlayMatches(overlay, graph, {request} = {}) {
+  const actualContract = overlay?.graphContract
+  return Number(overlay?.precisionOverlayV) === PRECISION_OVERLAY_V
+    && String(overlay?.baseGraphRevision || '') === String(graph?.graphRevision || '')
+    && String(overlay?.graphBuildMode || 'full') === graphMode(graph)
+    && String(overlay?.graphBuildScope || '') === graphScope(graph)
+    && String(overlay?.precisionMode || '') === precisionMode(graph)
+    && String(overlay?.providerContract || '') === providerContractFor(graph)
+    && actualContract != null && typeof actualContract === 'object'
+    && JSON.stringify(actualContract) === JSON.stringify(graphContractFor(graph))
+    && sameRequest(overlay?.request, request)
+}
+
+export function baseOverlay(graph, state, extra = {}) {
+  return {
+    precisionOverlayV: PRECISION_OVERLAY_V,
+    baseGraphRevision: String(graph.graphRevision || ''),
+    graphBuildMode: graphMode(graph),
+    graphBuildScope: graphScope(graph),
+    precisionMode: precisionMode(graph),
+    providerContract: providerContractFor(graph),
+    graphContract: graphContractFor(graph),
+    state,
+    engines: [],
+    coverage: {
+      candidates: 0, selected: 0, queried: 0, references: 0,
+      unclassifiedReferences: 0, verifiedEdges: 0, truncated: false,
+    },
+    links: [],
+    referenceEvidence: [],
+    noReferenceSymbols: [],
+    ...extra,
+  }
+}

package/src/precision/lsp-overlay/reference-results.js

@@ -0,0 +1,108 @@
+import {classifyTypeScriptReferenceUsage} from '../typescript-lsp-provider.js'
+import {endpoint, norm} from './contract.js'
+import {locationStart, repoFileFromLocation, sourceAt} from './target-index.js'
+import {remaining, sourceForClassification} from './source-session.js'
+
+function moduleDependencyAt(session, source, file, targetFile, exactLine) {
+  if (source !== file || !targetFile) return null
+  return (session.graph.links || []).find((link) => endpoint(link.source) === file
+    && endpoint(link.target) === targetFile
+    && ['imports', 're_exports'].includes(String(link.relation || ''))
+    && Number.isInteger(link.line) && link.line === exactLine)
+}
+
+function addUnknownEvidence(session, source, targetId, line, character) {
+  const key = `${source}\0${targetId}\0${line}\0${character}`
+  if (session.evidenceSeen.has(key)) return true
+  if (session.referenceEvidence.length >= session.boundedLinks) {
+    session.truncated = true
+    session.stop = true
+    return false
+  }
+  session.evidenceSeen.add(key)
+  session.unclassifiedReferences++
+  session.referenceEvidence.push({
+    source,
+    target: targetId,
+    line,
+    character,
+    classification: 'unknown',
+    provider: 'typescript-language-server',
+  })
+  return true
+}
+
+function addExactLink(session, targetId, source, location, line, character, usage, moduleDependency) {
+  const relation = 'references'
+  const key = `${source}\0${relation}\0${targetId}\0${line}\0${character}`
+  if (session.seen.has(key)) return true
+  if (session.links.length >= session.boundedLinks) {
+    session.truncated = true
+    session.stop = true
+    return false
+  }
+  session.seen.add(key)
+  session.links.push({
+    source,
+    target: targetId,
+    relation,
+    line,
+    character,
+    ...(Number.isInteger(location?.range?.end?.line) ? {endLine: location.range.end.line + 1} : {}),
+    ...(Number.isInteger(location?.range?.end?.character) ? {endCharacter: location.range.end.character} : {}),
+    provenance: 'EXACT_LSP',
+    provider: 'typescript-language-server',
+    ...(usage === 'type' || moduleDependency?.typeOnly === true ? {typeOnly: true} : {}),
+    ...(usage === 'compile' || moduleDependency?.compileOnly === true ? {compileOnly: true} : {}),
+  })
+  return true
+}
+
+export function collectReferenceResults(session, target, locations) {
+  for (const location of locations) {
+    if (remaining(session) <= 0 || session.references >= session.boundedReferences) {
+      session.truncated = true
+      session.stop = true
+      break
+    }
+    session.references++
+    const file = repoFileFromLocation(session.repoRoot, location)
+    const start = locationStart(location)
+    if (!file || !start || !Number.isInteger(start.line) || !Number.isInteger(start.character)) continue
+    const source = sourceAt(session.index, file, start)
+    const targetId = String(target.id)
+    const exactLine = start.line + 1
+    const character = start.character
+    const targetFile = norm(target.source_file)
+    const moduleDependency = moduleDependencyAt(
+      session, source, file, targetFile, exactLine,
+    )
+    const sourceText = sourceForClassification(session, file)
+    let usage = sourceText == null
+      ? 'unknown'
+      : classifyTypeScriptReferenceUsage(file, sourceText, start)
+    if (usage === 'unknown' && moduleDependency?.typeOnly === true) usage = 'type'
+    if (usage === 'unknown' && moduleDependency?.compileOnly === true) usage = 'compile'
+    if (session.collectLocations) session.exactLocations.push({
+      file,
+      source: source || file,
+      target: targetId,
+      line: exactLine,
+      character,
+      ...(Number.isInteger(location?.range?.end?.line) ? {endLine: location.range.end.line + 1} : {}),
+      ...(Number.isInteger(location?.range?.end?.character) ? {endCharacter: location.range.end.character} : {}),
+      classification: usage,
+    })
+    if (!source || source === targetId) {
+      if (usage === 'unknown') session.unclassifiedReferences++
+      continue
+    }
+    if (usage === 'unknown') {
+      if (!addUnknownEvidence(session, source, targetId, exactLine, character)) break
+      continue
+    }
+    if (!addExactLink(
+      session, targetId, source, location, exactLine, character, usage, moduleDependency,
+    )) break
+  }
+}

package/src/precision/lsp-overlay/semantic-inputs.js

@@ -0,0 +1,62 @@
+import {typeScriptProjectSafety} from '../typescript-lsp-provider.js'
+import {JS_TS_FILE, graphMode, graphScope, norm} from './contract.js'
+
+export class PrecisionBudgetError extends Error {
+  constructor(message = 'semantic precision deadline reached') {
+    super(message)
+    this.name = 'PrecisionBudgetError'
+  }
+}
+
+export class PrecisionLimitError extends Error {
+  constructor(message) { super(message); this.name = 'PrecisionLimitError' }
+}
+
+export class PrecisionStaleGraphError extends Error {
+  constructor() {
+    super('repository content did not match the graph snapshot')
+    this.name = 'PrecisionStaleGraphError'
+  }
+}
+
+export class PrecisionStaleSemanticInputsError extends Error {
+  constructor() {
+    super('TypeScript project inputs changed while semantic precision was running')
+    this.name = 'PrecisionStaleSemanticInputsError'
+  }
+}
+
+export function graphJavaScriptUniverse(graph) {
+  const files = [...new Set((graph.nodes || []).filter((node) => {
+    const id = String(node?.id || '')
+    const file = norm(node?.source_file || id)
+    return id === file && JS_TS_FILE.test(file)
+  }).map((node) => norm(node.source_file || node.id)))].sort()
+  const hashed = Object.keys(graph.fileHashes || {}).map(norm).filter((file) => JS_TS_FILE.test(file)).sort()
+  const fileSet = new Set(files)
+  const complete = graphMode(graph) === 'full' && !graphScope(graph)
+    && files.length === hashed.length && hashed.every((file) => fileSet.has(file))
+  return {files, complete}
+}
+
+export function precisionSemanticInputs(repoRoot, graph, options = {}) {
+  const universe = graphJavaScriptUniverse(graph)
+  if (!universe.files.length) {
+    return {safe: false, reason: 'NO_JAVASCRIPT_TYPESCRIPT_INPUTS', fingerprint: null, universe}
+  }
+  return {...typeScriptProjectSafety(repoRoot, universe.files, options), universe}
+}
+
+export function precisionSemanticInputsMatch(overlay, repoRoot, graph) {
+  const current = precisionSemanticInputs(repoRoot, graph)
+  return current.safe === true
+    && typeof current.fingerprint === 'string'
+    && current.fingerprint.length > 0
+    && String(overlay?.semanticInputFingerprint || '') === current.fingerprint
+}
+
+export function publicSemanticSafetyReason(reason) {
+  return reason === 'CONFIGURED_TSSERVER_PLUGINS'
+    ? 'configured TypeScript language-service plugins are not allowed'
+    : 'TypeScript project configuration could not be verified safely'
+}

package/src/precision/lsp-overlay/source-session.js

@@ -0,0 +1,134 @@
+import {createHash} from 'node:crypto'
+import {readFileSync, statSync} from 'node:fs'
+import {createRepoBoundary} from '../../repo-path.js'
+import {norm} from './contract.js'
+import {
+  PrecisionBudgetError,
+  PrecisionLimitError,
+  PrecisionStaleGraphError,
+} from './semantic-inputs.js'
+
+export function initializeSourceSession(session) {
+  session.boundary = createRepoBoundary(session.repoRoot)
+  session.opened = new Set()
+  session.openedTexts = new Map()
+  session.classificationTexts = new Map()
+  session.classificationBytes = 0
+  session.openedBytes = 0
+  session.fullUniverseOpened = false
+}
+
+export const remaining = (session) => session.deadline - Date.now()
+
+export function ensureBudget(session) {
+  if (remaining(session) <= 0) throw new PrecisionBudgetError()
+}
+
+export function awaitWithBudget(session, operation) {
+  ensureBudget(session)
+  const wait = remaining(session)
+  return new Promise((resolvePromise, rejectPromise) => {
+    const timer = setTimeout(() => rejectPromise(new PrecisionBudgetError()), wait)
+    Promise.resolve().then(operation).then(
+      (value) => { clearTimeout(timer); resolvePromise(value) },
+      (error) => { clearTimeout(timer); rejectPromise(error) },
+    )
+  })
+}
+
+function verifiedSource(session, relPath, maxBytes = 4 * 1024 * 1024) {
+  const file = norm(relPath)
+  const expectedHash = session.graph.fileHashes?.[file]
+  if (!file || !/^[a-f0-9]{64}$/i.test(String(expectedHash || ''))) {
+    throw new PrecisionStaleGraphError()
+  }
+  const resolvedFile = session.boundary.resolve(file)
+  if (!resolvedFile.ok) throw new PrecisionStaleGraphError()
+  let size
+  try { size = statSync(resolvedFile.path).size }
+  catch { throw new PrecisionStaleGraphError() }
+  if (size > maxBytes) throw new PrecisionLimitError('precision source-read budget reached')
+  let body
+  try { body = readFileSync(resolvedFile.path) }
+  catch { throw new PrecisionStaleGraphError() }
+  if (body.byteLength > maxBytes) throw new PrecisionLimitError('precision source-read budget reached')
+  if (createHash('sha256').update(body).digest('hex') !== expectedHash) {
+    throw new PrecisionStaleGraphError()
+  }
+  return {file, body, bytes: body.byteLength, text: body.toString('utf8')}
+}
+
+export async function ensureOpen(session, relPath) {
+  const file = norm(relPath)
+  if (!file || session.opened.has(file)) return
+  ensureBudget(session)
+  if (session.opened.size >= 96) throw new PrecisionLimitError('precision open-document limit reached')
+  const maxBytes = Math.min(4 * 1024 * 1024, 32 * 1024 * 1024 - session.openedBytes)
+  const {bytes, text} = verifiedSource(session, file, maxBytes)
+  if (bytes > 4 * 1024 * 1024) throw new PrecisionLimitError('precision document exceeds 4 MiB limit')
+  if (session.openedBytes + bytes > 32 * 1024 * 1024) {
+    throw new PrecisionLimitError('precision source-transfer budget reached')
+  }
+  await awaitWithBudget(session, () => session.client.openDocument(file, text))
+  session.opened.add(file)
+  session.openedTexts.set(file, text)
+  session.openedBytes += bytes
+}
+
+export function sourceForClassification(session, relPath) {
+  const file = norm(relPath)
+  if (session.openedTexts.has(file)) return session.openedTexts.get(file)
+  if (session.classificationTexts.has(file)) return session.classificationTexts.get(file)
+  if (session.classificationTexts.size >= 96) return null
+  let source
+  try {
+    source = verifiedSource(
+      session,
+      file,
+      Math.min(4 * 1024 * 1024, 32 * 1024 * 1024 - session.classificationBytes),
+    )
+  } catch (error) {
+    if (error instanceof PrecisionLimitError) return null
+    throw error
+  }
+  session.classificationTexts.set(file, source.text)
+  session.classificationBytes += source.bytes
+  return source.text
+}
+
+export async function ensureFullUniverse(session) {
+  if (session.fullUniverseOpened) return true
+  if (!session.universe.complete) return false
+  const additional = session.universe.files.filter((file) => !session.opened.has(file))
+  if (session.opened.size + additional.length > 96) {
+    session.truncated = true
+    return false
+  }
+  let projectedBytes = session.openedBytes
+  for (const file of additional) {
+    ensureBudget(session)
+    if (!/^[a-f0-9]{64}$/i.test(String(session.graph.fileHashes?.[file] || ''))) {
+      throw new PrecisionStaleGraphError()
+    }
+    const resolvedFile = session.boundary.resolve(file)
+    if (!resolvedFile.ok) throw new PrecisionStaleGraphError()
+    let bytes
+    try { bytes = statSync(resolvedFile.path).size }
+    catch { throw new PrecisionStaleGraphError() }
+    if (bytes > 4 * 1024 * 1024 || projectedBytes + bytes > 32 * 1024 * 1024) {
+      session.truncated = true
+      return false
+    }
+    projectedBytes += bytes
+  }
+  for (const file of additional) await ensureOpen(session, file)
+  session.fullUniverseOpened = session.universe.files.every((file) => session.opened.has(file))
+  return session.fullUniverseOpened
+}
+
+export function requestReferences(session, relPath, position) {
+  return awaitWithBudget(
+    session,
+    () => session.client.references(relPath, position, false, Math.max(1, remaining(session))),
+  )
+}