@chenglou/freerange 0.0.1

package/src/engine/outcome.ts

@@ -0,0 +1,137 @@
+import type {AbstractValue} from '../domain/value.ts'
+import type {FunctionID, ModuleBindingID, SiteID} from '../ir/ids.ts'
+import type {FunctionIR, UnsupportedFunctionIR, UnsupportedReason} from '../ir/program.ts'
+import type {BoundsAssumption, InferredPrecondition} from '../requirements/model.ts'
+import type {SharedState, ValueFact} from './state.ts'
+
+export type RequirementFailure =
+  | {kind: 'declared'; site: SiteID; status: 'refuted' | 'unproven'}
+  | {kind: 'finiteInput'; site: SiteID; status: 'refuted' | 'unproven'}
+  | {kind: 'nonzeroDivisor'; site: SiteID; operation: 'division' | 'remainder'}
+  | {kind: 'elementInBounds'; site: SiteID}
+
+// Why one function's evaluation stopped on some path. Code branches only on `kind`; prose
+// is composed only in src/report.
+export type StopReason =
+  | {kind: 'recursion'; callee: FunctionID}
+  // The called function never lowered, or its own evaluation has stops. The callee's report
+  // entry carries the next hop or the root cause.
+  | {kind: 'calleeStopped'; callee: FunctionID}
+  // A loop header's abstract state kept changing through the fixed-point backstop. No
+  // result computed before convergence is published as a guarantee.
+  | {kind: 'loopLimit'; updates: number}
+  // A loop whose exit edge is never taken on any analyzed path, e.g.
+  // `for (let index = 0; true; index += 1) {}`. The fixed point converged with every path
+  // still inside the loop, so the function has no reachable return.
+  | {kind: 'nonExitingLoop'}
+  // A stop terminator was reached. Only the file-wide rejections (eval, type-check
+  // suppression) produce one today, as the whole-file initializer replacement.
+  | {kind: 'unsupportedCode'; reason: UnsupportedReason}
+  // A moduleRead found nothing usable in the slot. Report prose comes from the binding's
+  // category: imported, an untracked object, an unsupported type, or read before its
+  // initialization.
+  | {kind: 'moduleRead'; binding: ModuleBindingID}
+  // A value reached an operation that needs a concrete runtime kind, but the analysis
+  // carries it without one. This includes opaque values and narrowing shapes the engine
+  // does not model. The path stops; the rest of the function and file report normally.
+  | {kind: 'kindMismatch'}
+  // A bare array read (arr[i]) remained possibly undefined and reached an operation that
+  // needs a present value. This can be diagnostic-clean when noUncheckedIndexedAccess is
+  // disabled, so it has its own actionable reason instead of looking like unsupported
+  // TypeScript narrowing.
+  | {kind: 'possiblyMissingElement'}
+  // A written or inferred requirement failed. A direct failure has no callee; propagation
+  // through a same-file call names the callee visible at that call while retaining the
+  // original requirement site.
+  | {
+      kind: 'requirementFailure'
+      failure: RequirementFailure
+      callee: FunctionID | null
+    }
+
+export type Stop = {
+  site: SiteID
+  reason: StopReason
+}
+
+// The result for one interior console.assert. A blocked result means its function did not
+// finish analysis on every path without a site-specific assumption.
+export type AssertionVerdict = {
+  site: SiteID
+  text: string
+  verdict: 'proven' | 'refuted' | 'unproven' | 'dead' | 'blocked'
+}
+
+// One evaluation can hold BOTH a normal outcome and stops: in
+// `if (flag > 0) return 10; unsupportedThing()` the true branch returns 10 while the other
+// path stops. Empty `stops` means every path completed.
+export type FunctionEvaluation = {
+  normal: {returnValue: AbstractValue; sharedState: SharedState; valueFacts: ValueFact[]} | null
+  preconditions: InferredPrecondition[]
+  boundsAssumptions: BoundsAssumption[]
+  assertions: AssertionVerdict[]
+  stops: Stop[]
+}
+
+// The result of a fully completed evaluation: the only data that may reach contract
+// consumers (a caller adopting callee state, the report's requires/ensures lines).
+// completedEvaluation below is the single way to obtain it, and refuses whenever any stop
+// exists, so partial results structurally cannot flow into those consumers.
+export type CompletedEvaluation = {
+  returnValue: AbstractValue
+  sharedState: SharedState
+  valueFacts: ValueFact[]
+  preconditions: InferredPrecondition[]
+  boundsAssumptions: BoundsAssumption[]
+}
+
+export function completedEvaluation(evaluation: FunctionEvaluation): CompletedEvaluation | null {
+  if (evaluation.stops.length > 0 || evaluation.normal == null) return null
+  return {
+    returnValue: evaluation.normal.returnValue,
+    sharedState: evaluation.normal.sharedState,
+    valueFacts: evaluation.normal.valueFacts,
+    preconditions: evaluation.preconditions,
+    boundsAssumptions: evaluation.boundsAssumptions,
+  }
+}
+
+export type FunctionAnalysis =
+  | {
+      kind: 'analyzed'
+      lowering: FunctionIR
+      preconditions: InferredPrecondition[]
+      boundsAssumptions: BoundsAssumption[]
+      returnValue: AbstractValue
+      assertions: AssertionVerdict[]
+    }
+  // Some path stopped. The evidence fields share no names with the contract fields above,
+  // so report code cannot consume them interchangeably: observedReturn describes only the
+  // paths that completed, and observedNeeds the requirements inferred on the path prefixes
+  // the analysis did evaluate (a sibling path may contribute one after another path stopped).
+  | {
+      kind: 'partial'
+      lowering: FunctionIR
+      stops: [Stop, ...Stop[]]
+      observedReturn: {value: AbstractValue} | null
+      observedNeeds: InferredPrecondition[]
+      observedBoundsAssumptions: BoundsAssumption[]
+      assertions: AssertionVerdict[]
+    }
+  // The function did not lower. The variant carries a reference (not a copy) to its
+  // lowering record, so a mismatched pair is unrepresentable and the report needs no
+  // defensive re-checks.
+  | {kind: 'notLowered'; lowering: UnsupportedFunctionIR}
+
+export type LoweredFunctionAnalysis = Exclude<FunctionAnalysis, {kind: 'notLowered'}>
+
+export type ProgramAnalysis = {
+  // Dense, index-aligned with ProgramIR.functions.
+  functions: FunctionAnalysis[]
+  // The synthetic module initializer's own analysis. Reports print it only when it stopped.
+  initializer: LoweredFunctionAnalysis
+  // Indexed by ModuleBindingID: the exact value functions may trust, or null when only the
+  // binding's declared kind is known. Reports use this to print assumes lines for reads of
+  // assumed-finite module numbers.
+  moduleValues: Array<AbstractValue | null>
+}

package/src/engine/state.ts

@@ -0,0 +1,155 @@
+import type {AbstractValue} from '../domain/value.ts'
+import {joinValues, sameValues, widenValue} from '../domain/value.ts'
+
+// Indexed by ModuleBindingID, fixed length per program. Flows through calls, so a
+// callee's module writes are visible to the caller after a completed call. Null means the
+// binding is not initialized; reading it stops the path.
+export type SharedState = Array<AbstractValue | null>
+
+export type ExecutionState = {
+  values: Array<AbstractValue | undefined>
+  shared: SharedState
+  // Conditions established by a guard or by a requirement/assumption already recorded
+  // on this path. Value keys name immutable runtime values, so assignment naturally uses
+  // a new key. Joins intersect the list. This is deliberately a closed set of three facts,
+  // with no transitivity or arithmetic, stored as a small deduplicated array.
+  valueFacts: ValueFact[]
+}
+
+export type ValueFact =
+  | {kind: 'nonzero'; value: string}
+  // The strict `index < array.length` half of a bounds guard. The index's own abstract
+  // number must still prove integer, non-NaN, and nonnegative.
+  | {kind: 'belowLength'; index: string; array: string}
+  // A requirement or assumption for an asserted read proves the complete condition.
+  | {kind: 'validIndex'; index: string; array: string}
+
+export function hasNonzeroFact(facts: ValueFact[], value: string): boolean {
+  return facts.some(fact => fact.kind === 'nonzero' && fact.value === value)
+}
+
+export function hasIndexFact(
+  facts: ValueFact[],
+  kind: 'belowLength' | 'validIndex',
+  index: string,
+  array: string,
+): boolean {
+  return facts.some(fact => fact.kind === kind && fact.index === index && fact.array === array)
+}
+
+export function addValueFact(facts: ValueFact[], candidate: ValueFact): void {
+  if (!facts.some(fact => sameValueFact(fact, candidate))) facts.push(candidate)
+}
+
+export function intersectValueFacts(left: ValueFact[], right: ValueFact[]): ValueFact[] {
+  const intersection: ValueFact[] = []
+  for (const leftFact of left) {
+    for (const rightFact of right) {
+      const shared = intersectValueFact(leftFact, rightFact)
+      if (shared != null) addValueFact(intersection, shared)
+    }
+  }
+  return intersection
+}
+
+function intersectValueFact(left: ValueFact, right: ValueFact): ValueFact | null {
+  if (sameValueFact(left, right)) return left
+  if (left.kind === 'nonzero' || right.kind === 'nonzero') return null
+  if (left.index !== right.index || left.array !== right.array) return null
+  return {kind: 'belowLength', index: left.index, array: left.array}
+}
+
+function sameValueFact(left: ValueFact, right: ValueFact): boolean {
+  if (left.kind !== right.kind) return false
+  if (left.kind === 'nonzero' && right.kind === 'nonzero') return left.value === right.value
+  if (left.kind === 'nonzero' || right.kind === 'nonzero') return false
+  return left.index === right.index && left.array === right.array
+}
+
+export function emptySharedState(moduleCount: number): SharedState {
+  return Array.from({length: moduleCount}, () => null)
+}
+
+export function cloneSharedState(state: SharedState): SharedState {
+  // Slots are replaced whole on write, never mutated, so a shallow copy suffices.
+  return state.slice()
+}
+
+export function cloneState(state: ExecutionState): ExecutionState {
+  return {
+    values: state.values.slice(),
+    shared: cloneSharedState(state.shared),
+    // Facts are never mutated, only appended or filtered, so a shallow copy suffices.
+    valueFacts: state.valueFacts.slice(),
+  }
+}
+
+// A new state field must participate in both the merged value and `changed`. Listing the
+// fields here makes that review mandatory when ExecutionState grows.
+const mergedStateFields: Record<keyof ExecutionState, true> = {values: true, shared: true, valueFacts: true}
+
+// Joins one incoming state into the block's previous state and reports whether the block
+// must run again. The comparison happens while each joined value is already in hand, so
+// propagation does not walk the complete historical frame a second time.
+export function mergeStates(previous: ExecutionState, candidate: ExecutionState, widen: boolean): {state: ExecutionState; changed: boolean} {
+  void mergedStateFields
+  const values: ExecutionState['values'] = []
+  const length = Math.max(previous.values.length, candidate.values.length)
+  let changed = previous.values.length !== length
+  for (let index = 0; index < length; index++) {
+    const previousValue = previous.values[index]
+    const candidateValue = candidate.values[index]
+    if (previousValue == null) {
+      values[index] = candidateValue
+      if (candidateValue != null) changed = true
+    } else if (candidateValue == null) {
+      values[index] = previousValue
+    } else {
+      const joined = joinValues(previousValue, candidateValue)
+      const merged = widen ? widenValue(previousValue, joined) : joined
+      values[index] = merged
+      if (!sameValues(previousValue, merged)) changed = true
+    }
+  }
+  const shared: SharedState = []
+  for (let index = 0; index < previous.shared.length; index++) {
+    const previousValue = previous.shared[index]
+    const candidateValue = candidate.shared[index]
+    if (previousValue == null || candidateValue == null) {
+      shared.push(null)
+      if (previousValue != null) changed = true
+    } else {
+      const joined = joinValues(previousValue, candidateValue)
+      const merged = widen ? widenValue(previousValue, joined) : joined
+      shared.push(merged)
+      if (!sameValues(previousValue, merged)) changed = true
+    }
+  }
+  const valueFacts = intersectValueFacts(previous.valueFacts, candidate.valueFacts)
+  if (
+    valueFacts.length !== previous.valueFacts.length
+    || valueFacts.some(fact => !previous.valueFacts.some(previousFact => sameValueFact(fact, previousFact)))
+  ) changed = true
+  const state: ExecutionState = {
+    values,
+    shared,
+    valueFacts,
+  }
+  return {state, changed}
+}
+
+// Uninitialized dominates: a binding is only initialized when every joined path
+// initialized it.
+export function joinModuleSlots(left: SharedState, right: SharedState): SharedState {
+  const joined: SharedState = []
+  for (let index = 0; index < left.length; index++) {
+    const leftValue = left[index]
+    const rightValue = right[index]
+    joined.push(
+      leftValue == null || rightValue == null
+        ? null
+        : joinValues(leftValue, rightValue),
+    )
+  }
+  return joined
+}