tla-ts 0.0.1 → 0.0.3-dev.a50fc89

package/src/spec-description.ts

@@ -0,0 +1,509 @@
+import type { Definition, Expression, SourceLocation, SourceRange } from "./ast";
+import type { ModelConfig } from "./config";
+import type { InstanceAction } from "./environment";
+import { TlaError } from "./errors";
+import {
+  bindDefinitions,
+  bindOperatorArguments,
+  evaluate,
+  forEachBinding,
+  formatRange,
+  getDefinition,
+  isConstantLevel,
+  isLocallyResolved,
+  lookupScope,
+  resolveGlobalOperator,
+  type Closure,
+  type Environment,
+  type Scope,
+} from "./evaluate";
+import { TEMPORAL_LEVEL } from "./levels";
+import { getLevel } from "./liveness";
+import { createRecord, createSet, createTuple, formatValue, type Value } from "./values";
+
+export interface SpecAction {
+  name: string;
+  location: SourceLocation;
+  parameters: [string, Value][];
+  expression: Expression;
+  scope: Scope | undefined;
+}
+
+interface SpecDescription {
+  inits: SpecAction[];
+  actions: SpecAction[];
+  temporals: SpecAction[];
+  invariants: SpecAction[];
+  impliedInits: SpecAction[];
+  impliedActions: SpecAction[];
+  impliedTemporals: SpecAction[];
+}
+
+const UNNAMED_ACTION = "UnnamedAction";
+
+const BUILTIN_RANGE: SourceRange = {
+  module: "--TLA+ BUILTINS--",
+  start: { line: 0, column: 0 },
+  end: { line: 0, column: 0 },
+};
+
+const toLocationValue = (location: SourceLocation) => {
+  const range = location.range ?? BUILTIN_RANGE;
+  return createRecord([
+    ["beginLine", range.start.line],
+    ["beginColumn", range.start.column],
+    ["endLine", range.end.line],
+    ["endColumn", range.end.column],
+    ["module", range.module],
+  ]);
+};
+
+const toActionValue = (action: SpecAction) => {
+  const fields: [string, Value][] = [
+    ["name", action.name],
+    ["location", toLocationValue(action.location)],
+  ];
+  if (action.parameters.length === 0) return createRecord(fields);
+  return createRecord([
+    ...fields,
+    ["context", createRecord(action.parameters)],
+    ["parameters", createTuple(action.parameters.map((parameter) => parameter[0]))],
+  ]);
+};
+
+const createAction = (name: string, expression: Expression): SpecAction => ({
+  name,
+  location: expression.location,
+  parameters: [],
+  expression,
+  scope: undefined,
+});
+
+const getConstantContext = (environment: Environment, scope: Scope | undefined) => ({
+  environment,
+  scope,
+  state: undefined,
+  next: undefined,
+});
+
+const getOperatorName = (expression: Expression) =>
+  expression.kind === "Identifier"
+    ? expression.name
+    : expression.kind === "Apply"
+      ? expression.operator
+      : undefined;
+
+const getArguments = (expression: Expression) =>
+  expression.kind === "Apply" ? expression.args : [];
+
+const resolveClosure = (
+  expression: Expression,
+  scope: Scope | undefined,
+  environment: Environment,
+) => {
+  const name = getOperatorName(expression);
+  if (name === undefined) return undefined;
+  if (isLocallyResolved(expression)) {
+    const binding = lookupScope(scope, name);
+    return binding?.kind === "Operator" && binding.operator.kind === "Closure"
+      ? binding.operator
+      : undefined;
+  }
+  if (environment.constants.has(name) || environment.variableIndex.has(name)) return undefined;
+  const operator = resolveGlobalOperator(name, environment);
+  return operator?.kind === "Closure" ? operator : undefined;
+};
+
+const isEvaluable = (expression: Expression, environment: Environment) => {
+  try {
+    evaluate(expression, getConstantContext(environment, undefined));
+    return true;
+  } catch (error) {
+    if (error instanceof TlaError) return false;
+    throw error;
+  }
+};
+
+const isConstantValue = (definition: Definition | undefined, environment: Environment) =>
+  definition?.kind === "Operator" &&
+  definition.params.length === 0 &&
+  definition.body.kind !== "Number" &&
+  definition.body.kind !== "String" &&
+  isConstantLevel(definition, environment) &&
+  isEvaluable(definition.body, environment);
+
+const isConstantDefinition = (closure: Closure, environment: Environment) => {
+  const definition = getDefinition(closure.name, environment);
+  return definition?.body === closure.body && isConstantValue(definition, environment);
+};
+
+const getThunk = (expression: Expression, scope: Scope | undefined) => {
+  if (expression.kind !== "Identifier" || !isLocallyResolved(expression)) return undefined;
+  const binding = lookupScope(scope, expression.name);
+  return binding?.kind === "Thunk" ? binding : undefined;
+};
+
+const getParameters = (closure: Closure | undefined, scope: Scope | undefined) =>
+  (closure?.params ?? []).flatMap((param): [string, Value][] => {
+    const binding = lookupScope(scope, param.name);
+    return binding?.kind === "Value" ? [[param.name, binding.value]] : [];
+  });
+
+const tryCollect = <Result>(collect: () => Result, fallback: () => Result) => {
+  try {
+    return collect();
+  } catch (error) {
+    if (error instanceof TlaError) return fallback();
+    throw error;
+  }
+};
+
+const getInstanceActions = (
+  instanceAction: InstanceAction,
+  expression: Expression,
+  scope: Scope | undefined,
+  called: Closure | undefined,
+  environment: Environment,
+): SpecAction[] => {
+  const args = getArguments(expression);
+  const callAction = (): SpecAction[] => [
+    { name: instanceAction.name, location: expression.location, parameters: [], expression, scope },
+  ];
+  if (!called || args.length === 0) {
+    return [{ ...instanceAction, parameters: [], expression, scope }];
+  }
+  if (args.some((arg) => getLevel(arg, scope, environment) !== 0)) return callAction();
+  return tryCollect(
+    () => [
+      {
+        ...instanceAction,
+        parameters: args.map((arg, index): [string, Value] => [
+          called.params[index].name.replace(/#\d+$/, ""),
+          evaluate(arg, getConstantContext(environment, scope)),
+        ]),
+        expression,
+        scope,
+      },
+    ],
+    callAction,
+  );
+};
+
+const getActions = (
+  expression: Expression,
+  scope: Scope | undefined,
+  closure: Closure | undefined,
+  environment: Environment,
+  instanceActions: Map<string, InstanceAction>,
+): SpecAction[] => {
+  const createSplitAction = (): SpecAction => ({
+    name: closure?.name ?? UNNAMED_ACTION,
+    location: expression.location,
+    parameters: getParameters(closure, scope),
+    expression,
+    scope,
+  });
+  switch (expression.kind) {
+    case "Let":
+      return getActions(
+        expression.body,
+        bindDefinitions(expression.definitions, getConstantContext(environment, scope)),
+        closure,
+        environment,
+        instanceActions,
+      );
+    case "Label":
+      return getActions(expression.body, scope, closure, environment, instanceActions);
+    case "Or":
+      return expression.operands.flatMap((operand) =>
+        getActions(operand, scope, closure, environment, instanceActions),
+      );
+    case "Exists":
+      return tryCollect(
+        () => {
+          const actions: SpecAction[] = [];
+          forEachBinding(
+            expression.bounds,
+            getConstantContext(environment, scope),
+            (boundScope) => {
+              actions.push(
+                ...getActions(expression.body, boundScope, closure, environment, instanceActions),
+              );
+              return false;
+            },
+          );
+          return actions.length === 0 ? [createSplitAction()] : actions;
+        },
+        () => [createSplitAction()],
+      );
+  }
+  const instanceAction = isLocallyResolved(expression)
+    ? undefined
+    : instanceActions.get(getOperatorName(expression) ?? "");
+  const called = resolveClosure(expression, scope, environment);
+  if (instanceAction)
+    return getInstanceActions(instanceAction, expression, scope, called, environment);
+  if (!called) return [createSplitAction()];
+  const args = getArguments(expression);
+  const callAction = (): SpecAction[] => [
+    { name: called.name, location: expression.location, parameters: [], expression, scope },
+  ];
+  if (isConstantDefinition(called, environment)) return callAction();
+  if (args.some((arg) => getLevel(arg, scope, environment) !== 0)) return callAction();
+  return tryCollect(() => {
+    const boundScope = args.reduce<Scope | undefined>(
+      (current, arg, index) => ({
+        name: called.params[index].name,
+        binding: {
+          kind: "Value",
+          value: evaluate(arg, getConstantContext(environment, scope)),
+        },
+        parent: current,
+      }),
+      called.scope,
+    );
+    return getActions(called.body, boundScope, called, environment, instanceActions);
+  }, callAction);
+};
+
+const describeSpecification = (
+  expression: Expression,
+  scope: Scope | undefined,
+  environment: Environment,
+  description: SpecDescription,
+  next: { expression: Expression; scope: Scope | undefined }[],
+): void => {
+  const recurse = (inner: Expression, innerScope: Scope | undefined) =>
+    describeSpecification(inner, innerScope, environment, description, next);
+  if (expression.kind === "Let") {
+    recurse(
+      expression.body,
+      bindDefinitions(expression.definitions, getConstantContext(environment, scope)),
+    );
+    return;
+  }
+  const thunk = getThunk(expression, scope);
+  if (thunk) {
+    recurse(thunk.expression, thunk.scope);
+    return;
+  }
+  const called = resolveClosure(expression, scope, environment);
+  if (called && isConstantDefinition(called, environment)) return;
+  if (called && called.params.length === 0) {
+    if (getLevel(called.body, called.scope, environment) === 1) {
+      description.inits.push(createAction(called.name, called.body));
+      return;
+    }
+    recurse(called.body, called.scope);
+    return;
+  }
+  if (called && expression.kind === "Apply" && called.params.length === expression.args.length) {
+    recurse(
+      called.body,
+      bindOperatorArguments(called, expression.args, getConstantContext(environment, scope)),
+    );
+    return;
+  }
+  if (expression.kind === "And") {
+    expression.operands.forEach((operand) => recurse(operand, scope));
+    return;
+  }
+  if (expression.kind === "Always") {
+    if (expression.expression.kind === "BoxAction") {
+      next.push({ expression: expression.expression.action, scope });
+      return;
+    }
+    description.temporals.push(createAction(UNNAMED_ACTION, expression));
+    return;
+  }
+  const level = getLevel(expression, scope, environment);
+  if (level <= 1) description.inits.push(createAction(UNNAMED_ACTION, expression));
+  else if (level === TEMPORAL_LEVEL) {
+    description.temporals.push(createAction(UNNAMED_ACTION, expression));
+  }
+};
+
+const describeProperty = (
+  configName: string,
+  expression: Expression,
+  scope: Scope | undefined,
+  environment: Environment,
+  description: SpecDescription,
+): void => {
+  const recurse = (inner: Expression, innerScope: Scope | undefined) =>
+    describeProperty(configName, inner, innerScope, environment, description);
+  if (expression.kind === "Let") {
+    recurse(
+      expression.body,
+      bindDefinitions(expression.definitions, getConstantContext(environment, scope)),
+    );
+    return;
+  }
+  const thunk = getThunk(expression, scope);
+  if (thunk) {
+    recurse(thunk.expression, thunk.scope);
+    return;
+  }
+  const called = resolveClosure(expression, scope, environment);
+  if (called && isConstantDefinition(called, environment)) return;
+  if (called && called.params.length === getArguments(expression).length) {
+    recurse(
+      called.body,
+      expression.kind === "Apply"
+        ? bindOperatorArguments(called, expression.args, getConstantContext(environment, scope))
+        : called.scope,
+    );
+    return;
+  }
+  if (expression.kind === "Forall") {
+    const isEnumerated = tryCollect(
+      () => {
+        forEachBinding(expression.bounds, getConstantContext(environment, scope), (boundScope) => {
+          recurse(expression.body, boundScope);
+          return false;
+        });
+        return true;
+      },
+      () => false,
+    );
+    if (isEnumerated) return;
+  }
+  if (expression.kind === "And") {
+    expression.operands.forEach((operand) => recurse(operand, scope));
+    return;
+  }
+  if (expression.kind === "Always") {
+    const inner = expression.expression;
+    if (inner.kind === "BoxAction") {
+      description.impliedActions.push(createAction(configName, inner));
+    } else if (getLevel(inner, scope, environment) < 2) {
+      description.invariants.push(createAction(configName, inner));
+    } else {
+      description.impliedTemporals.push(createAction(configName, expression));
+    }
+    return;
+  }
+  const level = getLevel(expression, scope, environment);
+  if (level <= 1) description.impliedInits.push(createAction(configName, expression));
+  else if (level === TEMPORAL_LEVEL) {
+    description.impliedTemporals.push(createAction(configName, expression));
+  }
+};
+
+const getOperatorDefinition = (name: string, environment: Environment) => {
+  const definition = getDefinition(name, environment);
+  return definition?.kind === "Operator" && !isConstantValue(definition, environment)
+    ? definition
+    : undefined;
+};
+
+const describeDefinition = (definition: Definition) =>
+  createRecord([
+    ["name", definition.name],
+    ["location", toLocationValue(definition.location)],
+  ]);
+
+const describe = (
+  config: ModelConfig,
+  environment: Environment,
+  instanceActions: Map<string, InstanceAction>,
+) => {
+  const description: SpecDescription = {
+    inits: [],
+    actions: [],
+    temporals: [],
+    invariants: [],
+    impliedInits: [],
+    impliedActions: [],
+    impliedTemporals: [],
+  };
+  const next: { expression: Expression; scope: Scope | undefined }[] = [];
+  const specification =
+    config.specification === undefined
+      ? undefined
+      : getOperatorDefinition(config.specification, environment);
+  if (specification) {
+    describeSpecification(specification.body, undefined, environment, description, next);
+    next.forEach((item) =>
+      description.actions.push(
+        ...getActions(item.expression, item.scope, undefined, environment, instanceActions),
+      ),
+    );
+  }
+  const init =
+    config.init === undefined ? undefined : resolveGlobalOperator(config.init, environment);
+  if (init?.kind === "Closure") description.inits.push(createAction(config.init ?? "", init.body));
+  const nextOperator =
+    config.next === undefined ? undefined : resolveGlobalOperator(config.next, environment);
+  if (nextOperator?.kind === "Closure") {
+    description.actions.push(
+      ...getActions(
+        nextOperator.body,
+        nextOperator.scope,
+        nextOperator,
+        environment,
+        instanceActions,
+      ),
+    );
+  }
+  config.invariants.forEach((name) => {
+    const definition = getOperatorDefinition(name, environment);
+    if (definition) description.invariants.push(createAction(name, definition.body));
+  });
+  config.properties.forEach((name) => {
+    const definition = getOperatorDefinition(name, environment);
+    if (definition) describeProperty(name, definition.body, undefined, environment, description);
+  });
+  return description;
+};
+
+// TLC's split of the next-state relation into the actions it names in a behavior.
+export const getNextActions = (
+  config: ModelConfig,
+  environment: Environment,
+  instanceActions: Map<string, InstanceAction>,
+) => describe(config, environment, instanceActions).actions;
+
+export const getActionLabel = (action: SpecAction) => {
+  const parameters = action.parameters.map((parameter) => formatValue(parameter[1]));
+  return `${action.name === UNNAMED_ACTION ? "Action" : action.name}${parameters.length === 0 ? "" : `(${parameters.join(",")})`} ${formatRange(action.location.range ?? BUILTIN_RANGE)}`;
+};
+
+export const getSpecificationValue = (
+  config: ModelConfig,
+  environment: Environment,
+  variableLocations: SourceLocation[],
+  instanceActions: Map<string, InstanceAction>,
+): Value => {
+  const description = describe(config, environment, instanceActions);
+  const toSet = (actions: SpecAction[]) => createSet(actions.map(toActionValue));
+  const toDefinitionSet = (names: string[]) =>
+    createSet(
+      names.flatMap((name) => {
+        const definition = getOperatorDefinition(name, environment);
+        return definition ? [describeDefinition(definition)] : [];
+      }),
+    );
+  return createRecord([
+    ["inits", toSet(description.inits)],
+    ["actions", toSet(description.actions)],
+    ["temporals", toSet(description.temporals)],
+    ["invariants", toSet(description.invariants)],
+    ["impliedinits", toSet(description.impliedInits)],
+    ["impliedactions", toSet(description.impliedActions)],
+    ["impliedtemporals", toSet(description.impliedTemporals)],
+    [
+      "variables",
+      createSet(
+        environment.variables.map((name, index) =>
+          createRecord([
+            ["name", name],
+            ["location", toLocationValue(variableLocations[index])],
+          ]),
+        ),
+      ),
+    ],
+    ["actionconstraints", toDefinitionSet(config.actionConstraints)],
+    ["constraints", toDefinitionSet(config.constraints)],
+  ]);
+};

package/src/standard-levels.ts

@@ -0,0 +1,105 @@
+import type { OperatorLevels } from "./levels";
+
+type Signature =
+  | [string, number, number[], number[], number[]]
+  | [string, number, number[], number[], number[], number[][], string[]];
+
+// The levels SANY computes for the dummy definitions in tla2sany/StandardModules of the operators
+// that tla-ts implements natively.
+const SIGNATURES: Signature[] = [
+  ["Nat", 0, [], [], []],
+  ["+", 0, [0, 0], [2, 2], [1, 1]],
+  ["-", 0, [0, 0], [2, 2], [1, 1]],
+  ["*", 0, [0, 0], [3, 3], [0, 0]],
+  ["^", 0, [0, 0], [2, 2], [1, 1]],
+  ["<", 0, [0, 0], [2, 2], [1, 1]],
+  [">", 0, [0, 0], [2, 2], [1, 1]],
+  ["<=", 0, [0, 0], [2, 2], [1, 1]],
+  [">=", 0, [0, 0], [2, 2], [1, 1]],
+  ["%", 0, [0, 0], [2, 2], [1, 1]],
+  ["\\div", 0, [0, 0], [2, 2], [1, 1]],
+  ["..", 0, [0, 0], [2, 2], [1, 1]],
+  ["Int", 0, [], [], []],
+  ["-.", 0, [0], [2], [1]],
+  ["Seq", 0, [0], [2], [1]],
+  ["Len", 0, [0], [2], [1]],
+  ["\\o", 0, [0, 0], [2, 2], [1, 1]],
+  ["Append", 0, [0, 0], [2, 2], [1, 1]],
+  ["Head", 0, [0], [2], [1]],
+  ["Tail", 0, [0], [2], [1]],
+  ["SubSeq", 0, [0, 0, 0], [2, 2, 2], [1, 1, 1]],
+  ["SelectSeq", 0, [0, 1], [2, 2], [1, 1], [], ["1,0,0"]],
+  ["IsFiniteSet", 0, [0], [2], [1]],
+  ["Cardinality", 0, [0], [2], [1]],
+  ["IsABag", 0, [0], [2], [1]],
+  ["BagToSet", 0, [0], [2], [1]],
+  ["SetToBag", 0, [0], [3], [1]],
+  ["BagIn", 0, [0, 0], [2, 2], [1, 1]],
+  ["EmptyBag", 0, [], [], []],
+  ["\\oplus", 0, [0, 0], [2, 2], [1, 1]],
+  ["\\ominus", 0, [0, 0], [2, 2], [1, 1]],
+  ["BagUnion", 0, [0], [2], [1]],
+  ["\\sqsubseteq", 0, [0, 0], [2, 2], [1, 1]],
+  ["SubBag", 0, [0], [2], [1]],
+  ["BagOfAll", 0, [1, 0], [2, 2], [1, 1]],
+  ["BagCardinality", 0, [0], [2], [1]],
+  ["CopiesIn", 0, [0, 0], [2, 2], [1, 1]],
+  ["Print", 0, [0, 0], [3, 3], [0, 1]],
+  ["PrintT", 0, [0], [3], [0]],
+  ["Assert", 0, [0, 0], [2, 3], [1, 0]],
+  ["JavaTime", 0, [], [], []],
+  ["TLCGet", 0, [0], [3], [0]],
+  ["TLCSet", 0, [0, 0], [3, 3], [0, 0]],
+  [":>", 0, [0, 0], [2, 3], [1, 1]],
+  ["@@", 0, [0, 0], [2, 2], [1, 1]],
+  ["Permutations", 0, [0], [2], [1]],
+  ["SortSeq", 0, [0, 2], [2, 2], [1, 1], [], ["1,0,0", "1,0,1"]],
+  ["RandomElement", 0, [0], [3], [1]],
+  ["Any", 0, [], [], []],
+  ["ToString", 0, [0], [2], [1]],
+  ["TLCEval", 0, [0], [3], [1]],
+  ["AssertEq", 0, [0, 0], [2, 2], [1, 1]],
+  ["AssertError", 0, [0, 0], [2, 3], [1, 0]],
+  ["TLCGetOrDefault", 0, [0, 0], [3, 3], [0, 0]],
+  ["TLCGetAndSet", 0, [0, 2, 0, 0], [3, 3, 3, 3], [0, 0, 0, 0], [], ["1,2,1"]],
+  ["Trace", 0, [], [], []],
+  ["CounterExample", 0, [], [], []],
+  ["ToTrace", 0, [0], [3], [0]],
+  ["TLCModelValue", 0, [0], [2], [1]],
+  ["TLCDefer", 0, [0], [3], [0]],
+  ["TLCNoOp", 0, [0], [3], [1]],
+  ["PickSuccessor", 0, [0], [3], [1]],
+  ["TLCCache", 0, [0, 0], [3, 3], [1, 0]],
+  ["TLCFP", 0, [0], [3], [0]],
+  ["TLCEvalDefinition", 0, [0], [3], [0]],
+  ["ToJson", 0, [0], [2], [1]],
+  ["ToJsonArray", 0, [0], [2], [1]],
+  ["ToJsonObject", 0, [0], [2], [1]],
+  ["JsonSerialize", 0, [0, 0], [3, 3], [0, 0]],
+  ["JsonDeserialize", 0, [0], [3], [0]],
+  ["ndJsonSerialize", 0, [0, 0], [3, 3], [0, 0]],
+  ["ndJsonDeserialize", 0, [0], [3], [0]],
+  ["RandomSubset", 0, [0, 0], [2, 2], [1, 1]],
+  ["RandomSetOfSubsets", 0, [0, 0, 0], [2, 3, 2], [1, 0, 1]],
+  ["TestRandomSetOfSubsets", 0, [0, 0, 0], [2, 3, 2], [1, 0, 1]],
+];
+
+export const STANDARD_LEVELS = new Map(
+  SIGNATURES.map((signature): [string, OperatorLevels] => [
+    signature[0],
+    {
+      name: signature[0],
+      level: signature[1],
+      params: new Set(),
+      constraints: new Map(),
+      argConstraints: new Map(),
+      argParams: new Set(),
+      formals: signature[2].map((arity, index) => ({ name: `$${index}`, arity })),
+      maxLevels: signature[3],
+      weights: signature[4],
+      minMaxLevels: signature[5] ?? [],
+      conditions: new Set(signature[6]),
+      nonLeibniz: new Set(),
+    },
+  ]),
+);