plan-verify 0.0.0-stage → 0.1.0

package/src/main.ts

@@ -0,0 +1,273 @@
+/**
+ * plan-verify command line.
+ * User arguments start at process.argv index 2 under both Node and ScriptC.
+ */
+
+import { readFileSync } from "node:fs";
+import { bindScenario, evaluate, formatCheckJson, formatCheckText, formatErrorJson } from "./check.ts";
+import { parseProperty, parseSpec } from "./ears.ts";
+import { parseScenarioJson } from "./jsonvalue.ts";
+import { formatLintJson, formatLintText, lintSpec } from "./lint.ts";
+import { buildProblems } from "./report.ts";
+import { formatScenariosJson, formatScenariosText, listScenarios } from "./scenarios.ts";
+import { analyzePolicy, formatPolicyJson, formatPolicyText } from "./policy.ts";
+import { formatEmitJson, printSmt } from "./smt.ts";
+import { spaceSize } from "./solver.ts";
+import { displayQuote } from "./text.ts";
+import type { Requirement } from "./spec.ts";
+
+const EXIT_OK = 0;
+const EXIT_VIOLATIONS = 1;
+const EXIT_USAGE = 2;
+
+function main(): void {
+  const args: string[] = [];
+  for (let i = 2; i < process.argv.length; i++) args.push(process.argv[i]);
+  if (args.length === 0) {
+    console.error("error: missing command");
+    usage(true);
+    process.exit(EXIT_USAGE);
+  }
+  const command = args[0];
+  if (command === "help" || command === "--help" || command === "-h") {
+    usage(false);
+    process.exit(EXIT_OK);
+  }
+  if (command === "policy") {
+    commandPolicy(args.slice(1));
+    return;
+  }
+  if (command === "check") {
+    commandCheck(args.slice(1));
+    return;
+  }
+  if (command === "emit-smt") {
+    commandEmit(args.slice(1));
+    return;
+  }
+  if (command === "lint") {
+    commandLint(args.slice(1));
+    return;
+  }
+  if (command === "report") {
+    commandReport(args.slice(1));
+    return;
+  }
+  if (command === "scenarios") {
+    commandScenarios(args.slice(1));
+    return;
+  }
+  console.error("error: unknown command " + displayQuote(command));
+  usage(true);
+  process.exit(EXIT_USAGE);
+}
+
+interface Flags {
+  json: boolean;
+  input: string;
+  property: string;
+  positionals: string[];
+  error: string;
+}
+
+function parseFlags(args: string[], allowInput: boolean, allowProperty: boolean): Flags {
+  const flags: Flags = { json: false, input: "", property: "", positionals: [], error: "" };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") flags.json = true;
+    else if (arg === "--input") {
+      if (!allowInput) {
+        flags.error = "unknown option --input";
+        return flags;
+      }
+      if (flags.input.length > 0) {
+        flags.error = "repeated option --input";
+        return flags;
+      }
+      if (i + 1 >= args.length) {
+        flags.error = "missing value for --input";
+        return flags;
+      }
+      i++;
+      flags.input = args[i];
+    } else if (arg === "--property") {
+      if (!allowProperty) {
+        flags.error = "unknown option --property";
+        return flags;
+      }
+      if (flags.property.length > 0) {
+        flags.error = "repeated option --property";
+        return flags;
+      }
+      if (i + 1 >= args.length) {
+        flags.error = "missing value for --property";
+        return flags;
+      }
+      i++;
+      flags.property = args[i];
+    } else if (arg.startsWith("--")) {
+      flags.error = "unknown option " + arg;
+      return flags;
+    } else flags.positionals.push(arg);
+  }
+  return flags;
+}
+
+function commandCheck(args: string[]): void {
+  const flags = parseFlags(args, true, false);
+  if (flags.error.length > 0) fail(flags.json, flags.error);
+  if (flags.positionals.length !== 1 || flags.input.length === 0) {
+    fail(flags.json, "usage: plan-verify check [--json] <spec> --input <scenario>");
+  }
+  const specPath = flags.positionals[0];
+  const scenarioPath = flags.input;
+  const specText = readText(specPath);
+  if (specText === null) fail(flags.json, "cannot read " + specPath);
+  const spec = parseSpec(specText);
+  if (!spec.ok) fail(flags.json, specPath + ":" + String(spec.line) + ": " + spec.message);
+  const scenarioText = readText(scenarioPath);
+  if (scenarioText === null) fail(flags.json, "cannot read " + scenarioPath);
+  const json = parseScenarioJson(scenarioText);
+  if (!json.ok) fail(flags.json, scenarioPath + ":" + String(json.line) + ": " + json.message);
+  const bound = bindScenario(spec.spec, json.object);
+  if (!bound.ok) fail(flags.json, "scenario " + scenarioPath + ": " + bound.message);
+  const violations = evaluate(spec.spec, bound.env);
+  if (flags.json) console.log(formatCheckJson(specPath, scenarioPath, violations));
+  else console.log(formatCheckText(specPath, scenarioPath, violations));
+  if (violations.length === 0) process.exit(EXIT_OK);
+  process.exit(EXIT_VIOLATIONS);
+}
+
+function commandEmit(args: string[]): void {
+  const flags = parseFlags(args, false, false);
+  if (flags.error.length > 0) fail(flags.json, flags.error);
+  if (flags.positionals.length !== 1) fail(flags.json, "usage: plan-verify emit-smt [--json] <spec>");
+  const specPath = flags.positionals[0];
+  const specText = readText(specPath);
+  if (specText === null) fail(flags.json, "cannot read " + specPath);
+  const spec = parseSpec(specText);
+  if (!spec.ok) fail(flags.json, specPath + ":" + String(spec.line) + ": " + spec.message);
+  const smt = printSmt(specPath, spec.spec);
+  if (flags.json) console.log(formatEmitJson(specPath, smt));
+  else console.log(smt);
+  process.exit(EXIT_OK);
+}
+
+function commandLint(args: string[]): void {
+  const flags = parseFlags(args, false, false);
+  if (flags.error.length > 0) fail(flags.json, flags.error);
+  if (flags.input.length > 0 || flags.positionals.length !== 1) fail(flags.json, "usage: plan-verify lint [--json] <spec>");
+  const specPath = flags.positionals[0];
+  const specText = readText(specPath);
+  if (specText === null) fail(flags.json, "cannot read " + specPath);
+  const spec = parseSpec(specText);
+  if (!spec.ok) fail(flags.json, specPath + ":" + String(spec.line) + ": " + spec.message);
+  const outcome = lintSpec(spec.spec);
+  if (outcome.kind === "error") fail(flags.json, outcome.message);
+  const findings =
+    outcome.report.conflicts.length +
+    outcome.report.gaps.length +
+    outcome.report.misuse.length +
+    outcome.report.wording.length +
+    outcome.report.redundant.length +
+    outcome.report.duplicate.length +
+    outcome.report.vacuous.length +
+    outcome.report.unused.length;
+  if (flags.json) console.log(formatLintJson(specPath, outcome.report));
+  else console.log(formatLintText(specPath, outcome.report));
+  if (findings === 0) process.exit(EXIT_OK);
+  process.exit(EXIT_VIOLATIONS);
+}
+
+function commandReport(args: string[]): void {
+  const flags = parseFlags(args, false, false);
+  if (flags.error.length > 0) fail(flags.json, flags.error);
+  if (flags.json) fail(true, "usage: plan-verify report <spec>");
+  if (flags.positionals.length !== 1) fail(false, "usage: plan-verify report <spec>");
+  const specPath = flags.positionals[0];
+  const specText = readText(specPath);
+  if (specText === null) fail(false, "cannot read " + specPath);
+  const spec = parseSpec(specText);
+  if (!spec.ok) fail(false, specPath + ":" + String(spec.line) + ": " + spec.message);
+  const outcome = lintSpec(spec.spec);
+  if (outcome.kind === "error") fail(false, outcome.message);
+  const doc = buildProblems(specPath, spec.spec, outcome.report);
+  console.log(doc.text);
+  if (doc.count === 0) process.exit(EXIT_OK);
+  process.exit(EXIT_VIOLATIONS);
+}
+
+function commandScenarios(args: string[]): void {
+  const flags = parseFlags(args, false, false);
+  if (flags.error.length > 0) fail(flags.json, flags.error);
+  if (flags.positionals.length !== 1) fail(flags.json, "usage: plan-verify scenarios [--json] <spec>");
+  const specPath = flags.positionals[0];
+  const specText = readText(specPath);
+  if (specText === null) fail(flags.json, "cannot read " + specPath);
+  const spec = parseSpec(specText);
+  if (!spec.ok) fail(flags.json, specPath + ":" + String(spec.line) + ": " + spec.message);
+  if (spaceSize(spec.spec) < 0) {
+    fail(flags.json, "a symbol has an empty domain. Declare at least one allowed value.");
+  }
+  const rows = listScenarios(spec.spec);
+  if (flags.json) console.log(formatScenariosJson(specPath, rows));
+  else console.log(formatScenariosText(specPath, rows));
+  process.exit(EXIT_OK);
+}
+
+function commandPolicy(args: string[]): void {
+  const flags = parseFlags(args, false, true);
+  if (flags.error.length > 0) fail(flags.json, flags.error);
+  if (flags.positionals.length !== 1) fail(flags.json, "usage: plan-verify policy [--json] <spec> [--property <file>]");
+  const specPath = flags.positionals[0];
+  const specText = readText(specPath);
+  if (specText === null) fail(flags.json, "cannot read " + specPath);
+  const parsed = parseSpec(specText);
+  if (!parsed.ok) fail(flags.json, specPath + ":" + String(parsed.line) + ": " + parsed.message);
+  if (spaceSize(parsed.spec) < 0) {
+    fail(flags.json, "a symbol has an empty domain. Declare at least one allowed value.");
+  }
+  let propertyReqs: Requirement[] = [];
+  if (flags.property.length > 0) {
+    const propertyText = readText(flags.property);
+    if (propertyText === null) fail(flags.json, "cannot read " + flags.property);
+    const property = parseProperty(propertyText, parsed.spec);
+    if (!property.ok) fail(flags.json, flags.property + ":" + String(property.line) + ": " + property.message);
+    propertyReqs = property.requirements;
+  }
+  const report = analyzePolicy(parsed.spec, flags.property, propertyReqs);
+  if (flags.json) console.log(formatPolicyJson(specPath, parsed.spec, report));
+  else console.log(formatPolicyText(specPath, parsed.spec, report));
+  if (report.holds) process.exit(EXIT_OK);
+  process.exit(EXIT_VIOLATIONS);
+}
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function fail(json: boolean, message: string): never {
+  if (json) console.log(formatErrorJson(message));
+  else console.error("error: " + message);
+  process.exit(EXIT_USAGE);
+}
+
+function usage(toStderr: boolean): void {
+  const text =
+    "usage:\n" +
+    "  plan-verify check [--json] <spec> --input <scenario>\n" +
+    "  plan-verify emit-smt [--json] <spec>\n" +
+    "  plan-verify lint [--json] <spec>\n" +
+    "  plan-verify report <spec>\n" +
+    "  plan-verify scenarios [--json] <spec>\n" +
+    "  plan-verify policy [--json] <spec> [--property <file>]\n" +
+    "  plan-verify help";
+  if (toStderr) console.error(text);
+  else console.log(text);
+}
+
+main();

package/src/policy.ts

@@ -0,0 +1,148 @@
+/**
+ * Policy search.
+ * With no property, report one scenario the requirements allow and one they
+ * forbid. With a property, search for a scenario that satisfies every
+ * requirement and violates the property.
+ * The first hit is the smallest assignment: false before true, enums in
+ * declaration order, integers from low to high.
+ */
+
+import { evaluateRequirements, type Violation } from "./check.ts";
+import { displayCode, type Requirement, type Spec } from "./spec.ts";
+import { firstScenario } from "./solver.ts";
+import { Binding, formatScenario } from "./term.ts";
+import { formatInt } from "./text.ts";
+
+export interface PolicyReport {
+  propertyPath: string;
+  holds: boolean;
+  note: string;
+  accepted: Binding | null;
+  rejected: Binding | null;
+  counterexample: Binding | null;
+  breaks: Violation[];
+}
+
+export function analyzePolicy(spec: Spec, propertyPath: string, propertyReqs: Requirement[]): PolicyReport {
+  if (propertyPath.length === 0) {
+    const accepted = firstScenario(spec, 0, propertyReqs);
+    const rejected = firstScenario(spec, 1, propertyReqs);
+    const breaks = rejected === null ? [] : evaluateRequirements(spec, spec.requirements, rejected);
+    return {
+      propertyPath: "",
+      holds: true,
+      note: "",
+      accepted: accepted,
+      rejected: rejected,
+      counterexample: null,
+      breaks: breaks,
+    };
+  }
+  const counterexample = firstScenario(spec, 2, propertyReqs);
+  if (counterexample !== null) {
+    return {
+      propertyPath: propertyPath,
+      holds: false,
+      note: "",
+      accepted: null,
+      rejected: null,
+      counterexample: counterexample,
+      breaks: evaluateRequirements(spec, propertyReqs, counterexample),
+    };
+  }
+  const accepted = firstScenario(spec, 0, propertyReqs);
+  const note =
+    accepted === null
+      ? "No scenario satisfies every requirement, so none violates the property."
+      : "No scenario satisfies every requirement and violates the property.";
+  return {
+    propertyPath: propertyPath,
+    holds: true,
+    note: note,
+    accepted: null,
+    rejected: null,
+    counterexample: null,
+    breaks: [],
+  };
+}
+
+export function formatPolicyText(specPath: string, spec: Spec, report: PolicyReport): string {
+  const lines: string[] = [];
+  lines.push("spec: " + specPath);
+  if (report.propertyPath.length > 0) lines.push("property: " + report.propertyPath);
+  if (report.propertyPath.length === 0) {
+    lines.push("accepted:");
+    if (report.accepted === null) lines.push("No scenario satisfies every requirement.");
+    else {
+      lines.push(formatScenario(spec, report.accepted));
+      lines.push("This scenario satisfies every requirement.");
+    }
+    lines.push("rejected:");
+    if (report.rejected === null) lines.push("No scenario violates a requirement.");
+    else {
+      lines.push(formatScenario(spec, report.rejected));
+      lines.push("This scenario violates a requirement.");
+      appendBreaks(lines, report.breaks);
+    }
+    return lines.join("\n");
+  }
+  if (report.counterexample !== null) {
+    lines.push("counterexample:");
+    lines.push(formatScenario(spec, report.counterexample));
+    lines.push("This scenario satisfies every requirement and violates the property.");
+    appendBreaks(lines, report.breaks);
+    return lines.join("\n");
+  }
+  lines.push(report.note);
+  return lines.join("\n");
+}
+
+function appendBreaks(lines: string[], breaks: Violation[]): void {
+  for (let i = 0; i < breaks.length; i++) {
+    const item = breaks[i];
+    lines.push("");
+    lines.push(item.id + " line " + formatInt(item.line));
+    lines.push(item.sentence);
+    lines.push(item.because);
+  }
+}
+
+interface NameValue {
+  name: string;
+  value: string;
+}
+
+export function formatPolicyJson(specPath: string, spec: Spec, report: PolicyReport): string {
+  const breaks: { id: string; line: number; sentence: string; because: string }[] = [];
+  for (let i = 0; i < report.breaks.length; i++) {
+    const item = report.breaks[i];
+    breaks.push({ id: item.id, line: item.line, sentence: item.sentence, because: item.because });
+  }
+  return JSON.stringify(
+    {
+      ok: report.holds,
+      spec: specPath,
+      property: report.propertyPath,
+      holds: report.holds,
+      note: report.note,
+      acceptedFound: report.accepted !== null,
+      accepted: pairs(spec, report.accepted),
+      rejectedFound: report.rejected !== null,
+      rejected: pairs(spec, report.rejected),
+      counterexampleFound: report.counterexample !== null,
+      counterexample: pairs(spec, report.counterexample),
+      breaks: breaks,
+    },
+    null,
+    2,
+  );
+}
+
+function pairs(spec: Spec, env: Binding | null): NameValue[] {
+  const out: NameValue[] = [];
+  if (env === null) return out;
+  for (let i = 0; i < spec.symbols.length; i++) {
+    out.push({ name: spec.symbols[i].name, value: displayCode(spec, spec.symbols[i], env.code[i]) });
+  }
+  return out;
+}