@chenglou/freerange 0.0.1

package/src/requirements/infer.ts

@@ -0,0 +1,334 @@
+import type {SiteID, ValueID} from '../ir/ids.ts'
+import type {InstructionIR} from '../ir/instructions.ts'
+import type {FunctionIR} from '../ir/program.ts'
+import type {InferredPrecondition, NumericExpression} from './model.ts'
+
+export type ExpressionContext = {
+  parameterExpressions: Array<NumericExpression | null>
+  // Calls pass the caller's value keys directly, so duplicate arguments and facts created
+  // in a callee refer to the same identity as the caller. Local keys use a nested namespace
+  // to avoid colliding with the caller's ValueIDs.
+  parameterIdentityKeys: string[]
+  identityNamespace: string
+  parameterIndexByValue: Array<number | undefined>
+  instructionByValue: Array<InstructionIR | undefined>
+  instructionCount: number
+}
+
+export function createExpressionContext(
+  fn: FunctionIR,
+  parameterExpressions: Array<NumericExpression | null>,
+  parameterIdentityKeys?: string[],
+  identityNamespace = `${fn.name}/`,
+): ExpressionContext {
+  const identityKeys = parameterIdentityKeys ?? fn.parameters.map((_, index) => `p${index}`)
+  if (identityKeys.length !== fn.parameters.length) {
+    throw new Error(`Expected ${fn.parameters.length} parameter identity keys for ${fn.name}`)
+  }
+  const context: ExpressionContext = {
+    parameterExpressions,
+    parameterIdentityKeys: identityKeys,
+    identityNamespace,
+    parameterIndexByValue: [],
+    instructionByValue: [],
+    instructionCount: 0,
+  }
+  for (let index = 0; index < fn.parameters.length; index++) {
+    context.parameterIndexByValue[fn.parameters[index]!.value] = index
+  }
+  for (const block of fn.blocks) {
+    for (const instruction of block.instructions) {
+      context.instructionByValue[instruction.result] = instruction
+      context.instructionCount += 1
+    }
+  }
+  return context
+}
+
+// Follow assignments and reads through records built in this function. The returned IR
+// value is the value that was actually stored, so ordinary analysis, assertion proofs,
+// and requirement expressions all use the same definition of identity.
+export function resolveStoredValue(value: ValueID, context: ExpressionContext): ValueID {
+  const producer = context.instructionByValue[value]
+  if (producer?.kind === 'moduleWrite') return resolveStoredValue(producer.value, context)
+  if (producer?.kind === 'property') {
+    const object = resolveStoredValue(producer.object, context)
+    const objectProducer = context.instructionByValue[object]
+    if (objectProducer?.kind === 'object') {
+      const property = objectProducer.properties.find(candidate => candidate.name === producer.property)
+      if (property != null) return resolveStoredValue(property.value, context)
+    }
+  }
+  return value
+}
+
+// The producer walk expands a value's defining DAG into an expression tree, and a value
+// used twice appears twice — chained squaring (`const b = a * a; const c = b * b`) doubles
+// per level, so tree size is exponential in the worst case while the DAG stays linear.
+// The budget is by construction, not a magic number: each visit charges against the
+// function's own instruction count, so a requirement can never be more complex than the
+// function that produced it. Exhaustion returns null, which surfaces as the nonzero-divisor
+// assumes line (or the element-in-bounds assumes line for element reads) — analysis keeps
+// going either way.
+export function numericExpression(value: ValueID, context: ExpressionContext): NumericExpression | null {
+  let remainingVisits = context.instructionCount
+  const walk = (current: ValueID): NumericExpression | null => {
+    const stored = resolveStoredValue(current, context)
+    if (stored !== current) return walk(stored)
+    const parameterIndex = context.parameterIndexByValue[current]
+    if (parameterIndex != null) return context.parameterExpressions[parameterIndex] ?? null
+    const instruction = context.instructionByValue[current]
+    if (instruction == null) return null
+    // Only an instruction expansion is charged — re-expanding the same instruction is
+    // exactly what the duplication blowup repeats, while parameter and constant leaves are
+    // bounded by the expansions' own fan-in.
+    if (remainingVisits <= 0) return null
+    remainingVisits -= 1
+    switch (instruction.kind) {
+      case 'constant': return {kind: 'constant', value: instruction.value}
+      case 'binary': {
+        const left = walk(instruction.left)
+        const right = walk(instruction.right)
+        return left == null || right == null
+          ? null
+          : {kind: 'binary', operator: instruction.operator, left, right}
+      }
+      case 'floor': {
+        const operand = walk(instruction.value)
+        return operand == null ? null : {kind: 'floor', operand}
+      }
+      // A module write's result is the assigned value, so the written expression carries over.
+      case 'moduleWrite': return walk(instruction.value)
+      // Requirement expressions name only the function's own parameters; a module binding is
+      // not caller-visible, so a requirement cannot name it.
+      case 'moduleRead':
+      case 'moduleHavoc':
+      case 'platformValue':
+      case 'booleanConstant':
+      case 'not':
+      case 'absolute':
+      case 'call':
+      case 'compare':
+      case 'maximum':
+      case 'minimum':
+      case 'object':
+      case 'nullishConstant':
+      case 'opaqueConstant':
+      case 'unknownBoolean':
+      case 'mathUnary':
+      case 'stringLength':
+      case 'parsedNumber':
+      case 'numberCheck':
+      case 'staticRequire':
+      case 'staticAssert':
+      case 'tagCheck':
+      case 'nullishCheck':
+      case 'arrayLiteral':
+      case 'arrayIndex': return null
+      // An array's length is fixed at construction (no push in the subset), so a length
+      // read over a nameable array could join the expression language later; not yet.
+      case 'arrayLength': return null
+      case 'property': {
+        const base = walk(instruction.object)
+        return base == null ? null : {kind: 'property', base, name: instruction.property}
+      }
+    }
+  }
+  return walk(value)
+}
+
+export function staticRequirement(
+  instruction: InstructionIR | undefined,
+  site: SiteID,
+  context: ExpressionContext,
+  purpose?: 'finiteInput',
+): Extract<InferredPrecondition, {kind: 'declaredComparison' | 'declaredNumberCheck'}> | null {
+  if (instruction?.kind === 'compare') {
+    const left = numericExpression(instruction.left, context)
+    const right = numericExpression(instruction.right, context)
+    return left == null || right == null
+      ? null
+      : {kind: 'declaredComparison', operator: instruction.operator, left, right, site}
+  }
+  if (instruction?.kind === 'numberCheck') {
+    const expression = numericExpression(instruction.value, context)
+    return expression == null
+      ? null
+      : {kind: 'declaredNumberCheck', predicate: instruction.predicate, expression, site, ...(purpose == null ? {} : {purpose})}
+  }
+  return null
+}
+
+// A stable name for the runtime value an IR value holds. Forward value facts and exact
+// same-value operations share this rule instead of maintaining separate notions of
+// identity. Property and array reads are stable under the accepted subset's immutability
+// rules; module and platform reads stay value-keyed because they may change between reads.
+export function canonicalValueKey(value: ValueID, context: ExpressionContext): string {
+  const stored = resolveStoredValue(value, context)
+  if (stored !== value) return canonicalValueKey(stored, context)
+  const parameterIndex = context.parameterIndexByValue[value]
+  if (parameterIndex != null) return context.parameterIdentityKeys[parameterIndex] ?? `p${parameterIndex}`
+  const producer = context.instructionByValue[value]
+  if (producer?.kind === 'property') {
+    return `${canonicalValueKey(producer.object, context)}.${JSON.stringify(producer.property)}`
+  }
+  if (producer?.kind === 'arrayLength') return `${canonicalValueKey(producer.array, context)}.length`
+  if (producer?.kind === 'stringLength') return `${canonicalValueKey(producer.value, context)}.length`
+  if (producer?.kind === 'arrayIndex') {
+    return `${canonicalValueKey(producer.array, context)}[${canonicalValueKey(producer.index, context)}]`
+  }
+  return `v:${context.identityNamespace}${value}`
+}
+
+export function sameRuntimeValue(left: ValueID, right: ValueID, context: ExpressionContext): boolean {
+  return left === right || canonicalValueKey(left, context) === canonicalValueKey(right, context)
+}
+
+export function addPrecondition(preconditions: InferredPrecondition[], candidate: InferredPrecondition): void {
+  if (candidate.kind === 'declaredNumberCheck') {
+    if (candidate.predicate === 'finite' && preconditions.some(precondition =>
+      precondition.kind === 'declaredNumberCheck'
+      && (precondition.predicate === 'integer' || precondition.predicate === 'finite')
+      && sameExpression(precondition.expression, candidate.expression))) return
+    if (candidate.predicate === 'integer') {
+      const redundantFinite = preconditions.findIndex(precondition =>
+        precondition.kind === 'declaredNumberCheck'
+        && precondition.predicate === 'finite'
+        && sameExpression(precondition.expression, candidate.expression))
+      if (redundantFinite >= 0) preconditions.splice(redundantFinite, 1)
+    }
+  }
+  if (!preconditions.some(precondition => samePrecondition(precondition, candidate))) preconditions.push(candidate)
+}
+
+export function numericParameterPath(
+  expression: NumericExpression,
+): {parameter: number; properties: string[]} | null {
+  if (expression.kind === 'parameter') return {parameter: expression.index, properties: []}
+  if (expression.kind !== 'property') return null
+  const base = numericParameterPath(expression.base)
+  return base == null ? null : {...base, properties: [...base.properties, expression.name]}
+}
+
+export function constantRequirementStatus(
+  requirement: Extract<InferredPrecondition, {kind: 'declaredComparison' | 'declaredNumberCheck'}>,
+): boolean | null {
+  if (requirement.kind === 'declaredNumberCheck') {
+    const value = constantNumericExpression(requirement.expression)
+    if (value == null) return null
+    switch (requirement.predicate) {
+      case 'finite': return Number.isFinite(value)
+      case 'integer': return Number.isInteger(value)
+      case 'nan': return Number.isNaN(value)
+    }
+  }
+  const left = constantNumericExpression(requirement.left)
+  const right = constantNumericExpression(requirement.right)
+  if (left == null || right == null) return null
+  switch (requirement.operator) {
+    case 'lessThan': return left < right
+    case 'lessThanOrEqual': return left <= right
+    case 'greaterThan': return left > right
+    case 'greaterThanOrEqual': return left >= right
+    case 'equal': return left === right
+    case 'notEqual': return left !== right
+  }
+}
+
+function constantNumericExpression(expression: NumericExpression): number | null {
+  switch (expression.kind) {
+    case 'constant': return expression.value
+    case 'parameter':
+    case 'property': return null
+    case 'floor': {
+      const operand = constantNumericExpression(expression.operand)
+      return operand == null ? null : Math.floor(operand)
+    }
+    case 'binary': {
+      const left = constantNumericExpression(expression.left)
+      const right = constantNumericExpression(expression.right)
+      if (left == null || right == null) return null
+      switch (expression.operator) {
+        case 'add': return left + right
+        case 'subtract': return left - right
+        case 'multiply': return left * right
+        case 'divide': return left / right
+        case 'remainder': return left % right
+      }
+    }
+  }
+}
+
+// Rewrites a nonzero obligation into the simplest condition the caller can read, peeling
+// only float-EXACT layers so the biconditional survives:
+// - X - c is nonzero  <=>  X is not c   (IEEE subtraction is zero only on exact equality)
+// - X + c is nonzero  <=>  X is not -c  (same argument)
+// - c * X is nonzero  <=>  X is nonzero, when |c| >= 1 and finite (|c * x| >= |x| can
+//   never underflow to zero; small constants CAN — 1e-200 * 1e-200 is 0 — so those stay)
+// - X / c never peels: a tiny dividend over a huge divisor underflows to zero.
+// The multiply case recurses (still a nonzero form); a peel against a constant ends the
+// chain (width is not 4 is an endpoint — further peeling through rounding would lie).
+// Termination is structural: every step shrinks the expression.
+export function peelNonzero(expression: NumericExpression, site: SiteID, operation: 'division' | 'remainder'): InferredPrecondition {
+  if (expression.kind === 'binary') {
+    const {operator, left, right} = expression
+    const constantSide = right.kind === 'constant' ? right : left.kind === 'constant' ? left : null
+    const otherSide = right.kind === 'constant' ? left : right
+    if (constantSide != null && Number.isFinite(constantSide.value)) {
+      if (operator === 'subtract') {
+        // c - X and X - c both peel to X is not c.
+        return {kind: 'notEqualConstant', expression: otherSide, value: constantSide.value, operation, site}
+      }
+      if (operator === 'add') {
+        return {kind: 'notEqualConstant', expression: otherSide, value: -constantSide.value, operation, site}
+      }
+      if (operator === 'multiply' && Math.abs(constantSide.value) >= 1) {
+        return peelNonzero(otherSide, site, operation)
+      }
+    }
+  }
+  return {kind: 'nonzero', expression, operation, site}
+}
+
+// Keep one condition per originating operation. Propagated requirements retain the
+// operation's site, so repeated calls with the same substituted expression collapse while
+// separate operations that need the same condition remain separate findings.
+function samePrecondition(left: InferredPrecondition, right: InferredPrecondition): boolean {
+  if (left.site !== right.site) return false
+  if (left.kind !== right.kind) return false
+  if (left.kind === 'inBounds' && right.kind === 'inBounds') {
+    return sameExpression(left.index, right.index) && sameExpression(left.sequence, right.sequence)
+  }
+  if (left.kind === 'inBounds' || right.kind === 'inBounds') return false
+  if (left.kind === 'declaredComparison' && right.kind === 'declaredComparison') {
+    return left.operator === right.operator
+      && sameExpression(left.left, right.left)
+      && sameExpression(left.right, right.right)
+  }
+  if (left.kind === 'declaredComparison' || right.kind === 'declaredComparison') return false
+  if (left.kind === 'declaredNumberCheck' && right.kind === 'declaredNumberCheck') {
+    return left.predicate === right.predicate && sameExpression(left.expression, right.expression)
+  }
+  if (left.kind === 'declaredNumberCheck' || right.kind === 'declaredNumberCheck') return false
+  if (left.kind === 'notEqualConstant' && right.kind === 'notEqualConstant' && left.value !== right.value) return false
+  return sameExpression(left.expression, right.expression)
+}
+
+function sameExpression(left: NumericExpression, right: NumericExpression): boolean {
+  if (left.kind !== right.kind) return false
+  switch (left.kind) {
+    case 'parameter': return left.index === (right as Extract<NumericExpression, {kind: 'parameter'}>).index
+    case 'constant': return left.value === (right as Extract<NumericExpression, {kind: 'constant'}>).value
+    case 'binary': {
+      const other = right as Extract<NumericExpression, {kind: 'binary'}>
+      return left.operator === other.operator
+        && sameExpression(left.left, other.left)
+        && sameExpression(left.right, other.right)
+    }
+    case 'floor': return sameExpression(left.operand, (right as Extract<NumericExpression, {kind: 'floor'}>).operand)
+    case 'property': {
+      const other = right as Extract<NumericExpression, {kind: 'property'}>
+      return left.name === other.name && sameExpression(left.base, other.base)
+    }
+  }
+}

package/src/requirements/model.ts

@@ -0,0 +1,77 @@
+import type {SiteID} from '../ir/ids.ts'
+import type {ArithmeticOperator, ComparisonOperator} from '../ir/instructions.ts'
+
+export type NumericExpression =
+  | {kind: 'parameter'; index: number}
+  | {kind: 'constant'; value: number}
+  | {kind: 'binary'; operator: ArithmeticOperator; left: NumericExpression; right: NumericExpression}
+  // Math.floor over a nameable expression. Lets a division by a floored value mint a
+  // requirement instead of stopping — and a floored divisor is an integer, so under the
+  // nonzero requirement its magnitude is at least 1 and the quotient stays finite.
+  | {kind: 'floor'; operand: NumericExpression}
+  // A property read off a nameable record, e.g. grid.columnCount. Sound to name because
+  // values are immutable after construction: the property cannot change between function
+  // entry and the operation that needs the requirement.
+  | {kind: 'property'; base: NumericExpression; name: string}
+
+// An element read the engine could not prove in bounds: arr[i]! asserts presence, and
+// when the index interval does not sit inside the length interval, the entry's guarantees
+// rest on the read actually being in bounds. The peer of InferredPrecondition, minus the
+// expression language (an assumption line needs only its site).
+export type BoundsAssumption = {
+  site: SiteID
+  // What is accepted without proof at the site: an asserted element read is in bounds, or a
+  // divisor the requirement language cannot express over the caller's arguments (a join,
+  // a module read, an element read, a call result — or an exhausted expression walk) is
+  // nonzero. The divisor case is the fallback for what used to be the divisorUnknown
+  // stop: one honest assumes line instead of losing everything downstream of the division.
+  kind: 'elementInBounds' | 'nonzeroDivisor'
+}
+
+export type InferredPrecondition =
+  | {
+      kind: 'nonzero'
+      expression: NumericExpression
+      // Which operation needs the divisor nonzero — division or remainder — for the prose.
+      operation: 'division' | 'remainder'
+      // Propagated records keep the callee's site, so a caller's report points at the
+      // actual operation even when the requirement surfaces two calls up.
+      site: SiteID
+    }
+  // An asserted element read (data[i]!) whose bounds the engine could not prove, with
+  // both the index and the sequence nameable over the caller's arguments. The caller-
+  // actionable upgrade of BoundsAssumption below: the condition is
+  // Number.isInteger(index) && 0 <= index < sequence.length.
+  | {
+      kind: 'inBounds'
+      index: NumericExpression
+      sequence: NumericExpression
+      site: SiteID
+    }
+  // The peeled form of a nonzero obligation: dividing by `width - 4` requires width to
+  // not be 4. Produced only by float-exact peeling (see peelNonzero), so the biconditional
+  // holds: the printed condition is neither weaker nor stronger than the divisor being
+  // nonzero.
+  | {
+      kind: 'notEqualConstant'
+      expression: NumericExpression
+      value: number
+      operation: 'division' | 'remainder'
+      site: SiteID
+    }
+  // A leading console.assert requirement after substituting the current caller's
+  // expressions. Structured operands keep propagation independent of source text.
+  | {
+      kind: 'declaredComparison'
+      operator: ComparisonOperator
+      left: NumericExpression
+      right: NumericExpression
+      site: SiteID
+    }
+  | {
+      kind: 'declaredNumberCheck'
+      predicate: 'integer' | 'finite' | 'nan'
+      expression: NumericExpression
+      site: SiteID
+      purpose?: 'finiteInput'
+    }

package/src/typescript/check.ts

@@ -0,0 +1,56 @@
+import {resolve} from 'node:path'
+import * as ts from 'typescript'
+import {TypeScriptDiagnosticsError} from './diagnostics.ts'
+
+export type CheckedSource = {
+  sourceFile: ts.SourceFile
+  checker: ts.TypeChecker
+}
+
+// When no tsconfig is in scope, single-file analysis gets the recommended authoring
+// checks. Project file mode uses the project's existing Program instead of this helper.
+const fallbackOptions: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ESNext,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  moduleDetection: ts.ModuleDetectionKind.Force,
+  strict: true,
+  noUncheckedIndexedAccess: true,
+  exactOptionalPropertyTypes: true,
+  noEmit: true,
+  skipLibCheck: true,
+  types: [],
+}
+
+export function checkFile(file: string): CheckedSource {
+  const absoluteFile = resolve(file)
+  const program = ts.createProgram([absoluteFile], fallbackOptions)
+  return checkedSource(program, absoluteFile, fallbackOptions)
+}
+
+export function checkSource(file: string, source: string): CheckedSource {
+  const absoluteFile = resolve(file)
+  const sourceFile = ts.createSourceFile(absoluteFile, source, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS)
+  const defaultHost = ts.createCompilerHost(fallbackOptions)
+  const host: ts.CompilerHost = {
+    ...defaultHost,
+    getSourceFile: (requestedFile, languageVersion, onError, shouldCreateNewSourceFile) => {
+      if (resolve(requestedFile) === absoluteFile) return sourceFile
+      return defaultHost.getSourceFile(requestedFile, languageVersion, onError, shouldCreateNewSourceFile)
+    },
+    fileExists: requestedFile => resolve(requestedFile) === absoluteFile || defaultHost.fileExists(requestedFile),
+    readFile: requestedFile => resolve(requestedFile) === absoluteFile ? source : defaultHost.readFile(requestedFile),
+  }
+  const program = ts.createProgram([absoluteFile], fallbackOptions, host)
+  return checkedSource(program, absoluteFile, fallbackOptions)
+}
+
+function checkedSource(program: ts.Program, file: string, options: ts.CompilerOptions): CheckedSource {
+  const diagnostics = ts.getPreEmitDiagnostics(program)
+  if (diagnostics.length > 0) {
+    throw new TypeScriptDiagnosticsError(diagnostics, options, process.cwd())
+  }
+  const sourceFile = program.getSourceFile(file)
+  if (sourceFile == null) throw new Error(`TypeScript did not load ${file}`)
+  return {sourceFile, checker: program.getTypeChecker()}
+}

package/src/typescript/diagnostics.ts

@@ -0,0 +1,69 @@
+import * as ts from 'typescript'
+
+export type DiagnosticLevel = 'error' | 'warning' | 'suggestion'
+
+type DiagnosticLocation = {
+  file: string
+  line: number
+  column: number
+}
+
+export class TypeScriptDiagnosticsError extends Error {
+  constructor(
+    readonly diagnostics: readonly ts.Diagnostic[],
+    readonly options: ts.CompilerOptions,
+    readonly currentDirectory: string,
+  ) {
+    super(formatTypeScriptDiagnostics(diagnostics, {...options, pretty: false}, currentDirectory))
+    this.name = 'TypeScriptDiagnosticsError'
+  }
+}
+
+export function formatTypeScriptDiagnostics(
+  diagnostics: readonly ts.Diagnostic[],
+  options: ts.CompilerOptions,
+  currentDirectory: string,
+): string {
+  const host: ts.FormatDiagnosticsHost = {
+    getCurrentDirectory: () => currentDirectory,
+    getCanonicalFileName: ts.sys.useCaseSensitiveFileNames ? file => file : file => file.toLowerCase(),
+    getNewLine: () => ts.sys.newLine,
+  }
+  return usePrettyOutput(options['pretty'])
+    ? ts.formatDiagnosticsWithColorAndContext(diagnostics, host)
+    : ts.formatDiagnostics(diagnostics, host)
+}
+
+export function usePrettyOutput(configured?: unknown): boolean {
+  if (typeof configured === 'boolean') return configured
+  const noColor = process.env['NO_COLOR']
+  if (noColor != null && noColor !== '') return false
+  const forceColor = process.env['FORCE_COLOR']
+  if (forceColor != null && forceColor !== '') return true
+  return ts.sys.writeOutputIsTTY?.() === true
+}
+
+export function color(code: number, text: string | number): string {
+  return `\u001B[${code}m${text}\u001B[0m`
+}
+
+export function formatDiagnosticPrefix(
+  location: DiagnosticLocation,
+  level: DiagnosticLevel,
+  rule: string,
+  pretty: boolean,
+): string {
+  const formattedLocation = formatDiagnosticLocation(location, pretty)
+  const separator = pretty ? ' - ' : ': '
+  const levelColor = level === 'error' ? 91 : level === 'warning' ? 93 : 96
+  const formattedLevel = pretty ? color(levelColor, level) : level
+  const ruleLabel = ` [${rule}]: `
+  return `${formattedLocation}${separator}${formattedLevel}${pretty ? color(90, ruleLabel) : ruleLabel}`
+}
+
+export function formatDiagnosticLocation(location: DiagnosticLocation, pretty: boolean): string {
+  const {file, line, column} = location
+  return pretty
+    ? `${color(96, file)}:${color(93, line)}:${color(93, column)}`
+    : `${file}(${line},${column})`
+}

package/src/typescript/project.ts

@@ -0,0 +1,101 @@
+import {dirname, isAbsolute, relative, resolve, sep} from 'node:path'
+import * as ts from 'typescript'
+import {TypeScriptDiagnosticsError} from './diagnostics.ts'
+
+export type LoadedTypeScriptProject = {
+  rootDirectory: string
+  parsed: ts.ParsedCommandLine
+  program: ts.Program
+}
+
+export type ProjectSource = {
+  project: LoadedTypeScriptProject
+  sourceFile: ts.SourceFile
+}
+
+export function findTypeScriptConfig(searchFrom: string): string | null {
+  return ts.findConfigFile(resolve(searchFrom), file => ts.sys.fileExists(file), 'tsconfig.json') ?? null
+}
+
+export function loadTypeScriptProjectGraph(configPath: string): LoadedTypeScriptProject[] {
+  const loaded: LoadedTypeScriptProject[] = []
+  const byConfigPath = new Map<string, LoadedTypeScriptProject | null>()
+
+  const load = (requestedConfigPath: string): LoadedTypeScriptProject => {
+    const absoluteConfigPath = resolve(requestedConfigPath)
+    const existing = byConfigPath.get(absoluteConfigPath)
+    if (existing === null) {
+      throw new Error(`Circular TypeScript project reference involving ${absoluteConfigPath}`)
+    }
+    if (existing !== undefined) return existing
+    byConfigPath.set(absoluteConfigPath, null)
+    const parsed = parseConfig(absoluteConfigPath)
+    requireStrictNullChecks(parsed.options, absoluteConfigPath)
+    for (const reference of parsed.projectReferences ?? []) load(ts.resolveProjectReferencePath(reference))
+    const program = ts.createProgram({
+      rootNames: parsed.fileNames,
+      options: parsed.options,
+      configFileParsingDiagnostics: parsed.errors,
+      ...(parsed.projectReferences == null ? {} : {projectReferences: parsed.projectReferences}),
+    })
+    const project = {
+      rootDirectory: dirname(absoluteConfigPath),
+      parsed,
+      program,
+    }
+    byConfigPath.set(absoluteConfigPath, project)
+    loaded.push(project)
+    return project
+  }
+
+  load(configPath)
+  return loaded
+}
+
+export function projectSources(projects: LoadedTypeScriptProject[]): ProjectSource[] {
+  const sources = new Map<string, ProjectSource>()
+  for (const project of projects) {
+    for (const sourceFile of project.program.getSourceFiles()) {
+      if (sourceFile.isDeclarationFile || sourceFile.fileName.includes(`${sep}node_modules${sep}`)) continue
+      const absoluteFile = resolve(sourceFile.fileName)
+      const existing = sources.get(absoluteFile)
+      const candidate = {project, sourceFile}
+      if (existing == null
+        || ownershipScore(project, absoluteFile) > ownershipScore(existing.project, absoluteFile)) {
+        sources.set(absoluteFile, candidate)
+      }
+    }
+  }
+  return [...sources.values()]
+    .sort((left, right) => left.sourceFile.fileName.localeCompare(right.sourceFile.fileName))
+}
+
+function parseConfig(configPath: string): ts.ParsedCommandLine {
+  const parsed = ts.getParsedCommandLineOfConfigFile(configPath, undefined, {
+    ...ts.sys,
+    onUnRecoverableConfigFileDiagnostic: diagnostic => {
+      throw new TypeScriptDiagnosticsError([diagnostic], {}, dirname(configPath))
+    },
+  })
+  if (parsed == null) throw new Error(`TypeScript could not parse ${configPath}`)
+  if (parsed.errors.length > 0) {
+    throw new TypeScriptDiagnosticsError(parsed.errors, parsed.options, dirname(configPath))
+  }
+  return parsed
+}
+
+function requireStrictNullChecks(options: ts.CompilerOptions, configPath: string): void {
+  // TypeScript 6 defaults strict mode on. An explicit strictNullChecks setting wins;
+  // otherwise strict:false is the only way the effective option is disabled.
+  const enabled = options.strictNullChecks ?? options.strict !== false
+  if (enabled) return
+  throw new Error(
+    `freerange requires strictNullChecks. Enable "strict": true or "strictNullChecks": true in ${configPath}.`,
+  )
+}
+
+function ownershipScore(project: LoadedTypeScriptProject, file: string): number {
+  const path = relative(project.rootDirectory, file)
+  const inside = path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`))
+  return inside ? project.rootDirectory.length : -1
+}