proschi 0.4.0 → 0.5.0

package/README.md

@@ -13,6 +13,8 @@ proschi fmt docs/                   # format files in place (--check: only repor
 proschi render checkout.proschi --out diagrams   # SVG diagrams (also --format md|html|hld-md|hld-html)
 proschi test docs/                  # run requirements and tests (exit 1 on a failure)
 proschi analyze shortener.proschi   # load, latency, availability and cost per node
+proschi problem check               # validate practice problem folders (see docs/PRACTICE.md)
+proschi problem new seat-map        # scaffold a practice problem
 proschi-language-server --stdio     # for any editor with an LSP client
 ```
 
@@ -33,6 +35,13 @@ server reports failing requirements and tests as warnings and adds load to
 node hovers. The model and its default numbers:
 [Simulation and tests](https://github.com/gvart/proschi/blob/main/docs/EDITORS.md#simulation-and-tests).
 
+`problem check [--format text|github|json] [dir]` validates the practice
+problems, one folder each (front matter, given, starter, reference solution
+and the `wrong/` designs that must fail), with the same rules as the practice
+page's test suite; `problem new <id> [--dir <dir>]` scaffolds one. Inside the
+repository both default to `frontend/src/practice/problems`. The format and
+the rules: [docs/PRACTICE.md](https://github.com/gvart/proschi/blob/main/docs/PRACTICE.md).
+
 ## Rendering
 
 ```

package/dist/cli.cjs

@@ -2986,7 +2986,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve3.call(this, root, ref);
+      let _sch = resolve4.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3013,7 +3013,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve3(root, ref) {
+    function resolve4(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3843,7 +3843,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve3(baseURI, relativeURI, options) {
+    function resolve4(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const {
         parsed: baseParsed,
@@ -4212,7 +4212,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve3,
+      resolve: resolve4,
       resolveComponent,
       equal,
       serialize,
@@ -11869,13 +11869,13 @@ var require_resolve_block_scalar = __commonJS({
   "node_modules/yaml/dist/compose/resolve-block-scalar.js"(exports2) {
     "use strict";
     var Scalar = require_Scalar();
-    function resolveBlockScalar(ctx, scalar, onError) {
-      const start = scalar.offset;
-      const header = parseBlockScalarHeader(scalar, ctx.options.strict, onError);
+    function resolveBlockScalar(ctx, scalar2, onError) {
+      const start = scalar2.offset;
+      const header = parseBlockScalarHeader(scalar2, ctx.options.strict, onError);
       if (!header)
         return { value: "", type: null, comment: "", range: [start, start, start] };
       const type = header.mode === ">" ? Scalar.Scalar.BLOCK_FOLDED : Scalar.Scalar.BLOCK_LITERAL;
-      const lines = scalar.source ? splitLines(scalar.source) : [];
+      const lines = scalar2.source ? splitLines(scalar2.source) : [];
       let chompStart = lines.length;
       for (let i = lines.length - 1; i >= 0; --i) {
         const content = lines[i][1];
@@ -11887,12 +11887,12 @@ var require_resolve_block_scalar = __commonJS({
       if (chompStart === 0) {
         const value2 = header.chomp === "+" && lines.length > 0 ? "\n".repeat(Math.max(1, lines.length - 1)) : "";
         let end2 = start + header.length;
-        if (scalar.source)
-          end2 += scalar.source.length;
+        if (scalar2.source)
+          end2 += scalar2.source.length;
         return { value: value2, type, comment: header.comment, range: [start, end2, end2] };
       }
-      let trimIndent = scalar.indent + header.indent;
-      let offset = scalar.offset + header.length;
+      let trimIndent = scalar2.indent + header.indent;
+      let offset = scalar2.offset + header.length;
       let contentStart = 0;
       for (let i = 0; i < chompStart; ++i) {
         const [indent2, content] = lines[i];
@@ -11970,7 +11970,7 @@ var require_resolve_block_scalar = __commonJS({
         default:
           value += "\n";
       }
-      const end = start + header.length + scalar.source.length;
+      const end = start + header.length + scalar2.source.length;
       return { value, type, comment: header.comment, range: [start, end, end] };
     }
     function parseBlockScalarHeader({ offset, props }, strict, onError) {
@@ -12053,8 +12053,8 @@ var require_resolve_flow_scalar = __commonJS({
     "use strict";
     var Scalar = require_Scalar();
     var resolveEnd = require_resolve_end();
-    function resolveFlowScalar(scalar, strict, onError) {
-      const { offset, type, source: source2, end } = scalar;
+    function resolveFlowScalar(scalar2, strict, onError) {
+      const { offset, type, source: source2, end } = scalar2;
       let _type;
       let value;
       const _onError = (rel, code, msg) => onError(offset + rel, code, msg);
@@ -12073,7 +12073,7 @@ var require_resolve_flow_scalar = __commonJS({
           break;
         /* istanbul ignore next should not happen */
         default:
-          onError(scalar, "UNEXPECTED_TOKEN", `Expected a flow scalar value, but found: ${type}`);
+          onError(scalar2, "UNEXPECTED_TOKEN", `Expected a flow scalar value, but found: ${type}`);
           return {
             value: "",
             type: null,
@@ -12288,26 +12288,26 @@ var require_compose_scalar = __commonJS({
         tag = findScalarTagByTest(ctx, value, token, onError);
       else
         tag = ctx.schema[identity.SCALAR];
-      let scalar;
+      let scalar2;
       try {
         const res = tag.resolve(value, (msg) => onError(tagToken ?? token, "TAG_RESOLVE_FAILED", msg), ctx.options);
-        scalar = identity.isScalar(res) ? res : new Scalar.Scalar(res);
+        scalar2 = identity.isScalar(res) ? res : new Scalar.Scalar(res);
       } catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         onError(tagToken ?? token, "TAG_RESOLVE_FAILED", msg);
-        scalar = new Scalar.Scalar(value);
+        scalar2 = new Scalar.Scalar(value);
       }
-      scalar.range = range;
-      scalar.source = value;
+      scalar2.range = range;
+      scalar2.source = value;
       if (type)
-        scalar.type = type;
+        scalar2.type = type;
       if (tagName)
-        scalar.tag = tagName;
+        scalar2.tag = tagName;
       if (tag.format)
-        scalar.format = tag.format;
+        scalar2.format = tag.format;
       if (comment)
-        scalar.comment = comment;
-      return scalar;
+        scalar2.comment = comment;
+      return scalar2;
     }
     function findScalarTagByName(schema, value, tagName, tagToken, onError) {
       if (tagName === "!")
@@ -13464,9 +13464,9 @@ var require_lexer = __commonJS({
         }
       }
       *parseQuotedScalar() {
-        const quote2 = this.charAt(0);
-        let end = this.buffer.indexOf(quote2, this.pos + 1);
-        if (quote2 === "'") {
+        const quote3 = this.charAt(0);
+        let end = this.buffer.indexOf(quote3, this.pos + 1);
+        if (quote3 === "'") {
           while (end !== -1 && this.buffer[end + 1] === "'")
             end = this.buffer.indexOf("'", end + 2);
         } else {
@@ -14135,37 +14135,37 @@ var require_parser = __commonJS({
           };
         }
       }
-      *scalar(scalar) {
+      *scalar(scalar2) {
         if (this.type === "map-value-ind") {
           const prev = getPrevProps(this.peek(2));
           const start = getFirstKeyStartProps(prev);
           let sep;
-          if (scalar.end) {
-            sep = scalar.end;
+          if (scalar2.end) {
+            sep = scalar2.end;
             sep.push(this.sourceToken);
-            delete scalar.end;
+            delete scalar2.end;
           } else
             sep = [this.sourceToken];
           const map = {
             type: "block-map",
-            offset: scalar.offset,
-            indent: scalar.indent,
-            items: [{ start, key: scalar, sep }]
+            offset: scalar2.offset,
+            indent: scalar2.indent,
+            items: [{ start, key: scalar2, sep }]
           };
           this.onKeyLine = true;
           this.stack[this.stack.length - 1] = map;
         } else
-          yield* this.lineEnd(scalar);
+          yield* this.lineEnd(scalar2);
       }
-      *blockScalar(scalar) {
+      *blockScalar(scalar2) {
         switch (this.type) {
           case "space":
           case "comment":
           case "newline":
-            scalar.props.push(this.sourceToken);
+            scalar2.props.push(this.sourceToken);
             return;
           case "scalar":
-            scalar.source = this.source;
+            scalar2.source = this.source;
             this.atNewLine = true;
             this.indent = 0;
             if (this.onNewLine) {
@@ -14797,8 +14797,8 @@ __export(cli_exports, {
   run: () => run
 });
 module.exports = __toCommonJS(cli_exports);
-var import_node_fs5 = require("node:fs");
-var import_node_path6 = require("node:path");
+var import_node_fs6 = require("node:fs");
+var import_node_path7 = require("node:path");
 
 // src/openapi/config.ts
 var import_node_fs2 = require("node:fs");
@@ -15464,15 +15464,15 @@ function readString(text, start) {
 }
 function stripTrailingComment(text) {
   let depth = 0;
-  let quote2 = null;
+  let quote3 = null;
   for (let i = 0; i < text.length; i++) {
     const ch = text[i];
-    if (quote2) {
+    if (quote3) {
       if (ch === "\\") i++;
-      else if (ch === quote2) quote2 = null;
+      else if (ch === quote3) quote3 = null;
       continue;
     }
-    if (ch === '"') quote2 = ch;
+    if (ch === '"') quote3 = ch;
     else if (ch === "{" || ch === "[") depth++;
     else if (ch === "}" || ch === "]") depth = Math.max(0, depth - 1);
     else if (ch === "#" && depth === 0 && (i === 0 || /\s/.test(text[i - 1]))) return text.slice(0, i);
@@ -15878,14 +15878,14 @@ var Parser = class {
     const loc = this.locOf(pathToken, line);
     const entry = { path, loc };
     this.imports.push(entry);
-    const { resolve: resolve3 } = this.options;
-    if (!resolve3) {
+    const { resolve: resolve4 } = this.options;
+    if (!resolve4) {
       this.warning(`Imports are not resolved in this context; '${path}' was not loaded`, loc);
       return;
     }
     let target;
     try {
-      target = resolve3(path, this.file ?? this.options.path);
+      target = resolve4(path, this.file ?? this.options.path);
     } catch {
       target = void 0;
     }
@@ -18510,6 +18510,9 @@ function noPath(run2, from, to) {
   return pass(`No connection or step goes directly from ${x} to ${y}`);
 }
 
+// ../frontend/src/hld/engine.ts
+var defaultEngine = { available: true, analyze: (d) => analyze(d), runTests: (d, a) => runTests(d, a) };
+
 // src/fmt.ts
 var FMT_USAGE = `  proschi fmt [--check] <file|dir>...`;
 var FMT_HELP = `fmt     Rewrites files in the canonical layout and lists the ones it changed.
@@ -18755,14 +18758,700 @@ function checkFiles(files, extra) {
   return [...byFile].map(([file, diagnostics]) => ({ file, diagnostics: diagnostics.sort((x, y) => x.line - y.line || x.col - y.col) }));
 }
 
+// src/problem.ts
+var import_node_fs5 = require("node:fs");
+var import_node_path6 = require("node:path");
+
+// ../frontend/src/practice/frontMatter.ts
+var FrontMatterError = class extends Error {
+  /** 1-based line in the file. */
+  line;
+  constructor(message, line) {
+    super(`line ${line}: ${message}`);
+    this.name = "FrontMatterError";
+    this.line = line;
+  }
+};
+var KEY = /^([A-Za-z][A-Za-z0-9_-]*):(?:[ \t]+(.*))?$/;
+var NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+var AMBIGUOUS = /^(?:true|false|yes|no|on|off|null|~)$/i;
+var INDICATORS = "-?:,[]{}#&*!|>'\"%@`";
+function isPlainSafe(s, inFlow = false) {
+  if (s === "" || s !== s.trim() || /[\n\r\t]/.test(s)) return false;
+  if (INDICATORS.includes(s[0]) || s.includes(": ") || s.includes(" #") || s.endsWith(":")) return false;
+  if (NUMBER.test(s) || AMBIGUOUS.test(s)) return false;
+  return !(inFlow && /[,[\]{}]/.test(s));
+}
+function scalar(text, line, inFlow) {
+  if (text.startsWith('"')) {
+    if (!/^"(?:[^"\\]|\\.)*"$/.test(text)) throw new FrontMatterError(`Unterminated or malformed double-quoted string: ${text}`, line);
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new FrontMatterError(`Invalid escape in double-quoted string: ${text}`, line);
+    }
+  }
+  if (text.startsWith("'")) {
+    if (!/^'(?:[^']|'')*'$/.test(text)) throw new FrontMatterError(`Unterminated or malformed single-quoted string: ${text}`, line);
+    return text.slice(1, -1).replace(/''/g, "'");
+  }
+  if (NUMBER.test(text)) return Number(text);
+  if (!isPlainSafe(text, inFlow)) throw new FrontMatterError(`Ambiguous value ${JSON.stringify(text)}; put it in double quotes`, line);
+  return text;
+}
+function stringItem(text, line, inFlow) {
+  const value = scalar(text, line, inFlow);
+  if (typeof value !== "string") throw new FrontMatterError(`List items must be strings; quote ${text}`, line);
+  return value;
+}
+function flowItems(inner, line) {
+  const items = [];
+  let current = "";
+  let quote3;
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i];
+    if (quote3) {
+      current += c;
+      if (quote3 === '"' && c === "\\") current += inner[++i] ?? "";
+      else if (c === quote3) {
+        if (quote3 === "'" && inner[i + 1] === "'") current += inner[++i];
+        else quote3 = void 0;
+      }
+    } else if (c === '"' || c === "'") {
+      quote3 = c;
+      current += c;
+    } else if (c === ",") {
+      items.push(current.trim());
+      current = "";
+    } else current += c;
+  }
+  if (quote3) throw new FrontMatterError("Unterminated string in list", line);
+  if (current.trim() !== "" || items.length > 0) items.push(current.trim());
+  if (items.some((item) => item === "")) throw new FrontMatterError("Empty item in list", line);
+  return items.map((item) => stringItem(item, line, true));
+}
+function parseFrontMatter(text) {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  if (lines[0] !== "---") throw new FrontMatterError('The file must start with a line "---"', 1);
+  const end = lines.indexOf("---", 1);
+  if (end < 0) throw new FrontMatterError('No closing "---" line after the front matter', 1);
+  const data = {};
+  let list;
+  for (let i = 1; i < end; i++) {
+    const raw = lines[i];
+    const line = i + 1;
+    if (raw.trim() === "" || /^\s*#/.test(raw)) continue;
+    if (/\t/.test(raw.match(/^\s*/)[0])) throw new FrontMatterError("Indent with spaces, not tabs", line);
+    const item = raw.match(/^ +- (.*)$/) ?? raw.match(/^ +-()$/);
+    if (item) {
+      if (!list) throw new FrontMatterError('A list item must follow a key with no value, e.g. "hints:"', line);
+      const value2 = item[1].trim();
+      if (value2 === "") throw new FrontMatterError("Empty list item", line);
+      list.items.push(stringItem(value2, line, false));
+      continue;
+    }
+    if (/^\s/.test(raw)) throw new FrontMatterError(`Unexpected indented line: ${raw.trim()}`, line);
+    list = void 0;
+    const m = raw.match(KEY);
+    if (!m) throw new FrontMatterError(`Expected "key: value", got: ${raw}`, line);
+    const [, key, rest] = m;
+    if (Object.prototype.hasOwnProperty.call(data, key)) throw new FrontMatterError(`Duplicate key '${key}'`, line);
+    const value = (rest ?? "").trim();
+    if (value === "") {
+      list = { key, items: [] };
+      data[key] = list.items;
+    } else if (value.startsWith("[")) {
+      if (!value.endsWith("]")) throw new FrontMatterError(`A list must close on the same line: ${value}`, line);
+      data[key] = flowItems(value.slice(1, -1), line);
+    } else {
+      data[key] = scalar(value, line, false);
+    }
+  }
+  for (const [key, value] of Object.entries(data)) {
+    if (Array.isArray(value) && value.length === 0) {
+      const line = lines.findIndex((l, i) => i > 0 && i < end && l.startsWith(`${key}:`)) + 1;
+      throw new FrontMatterError(`'${key}' has no value`, line);
+    }
+  }
+  return { data, body: lines.slice(end + 1).join("\n").trim() };
+}
+
+// ../frontend/src/practice/types.ts
+var DIFFICULTIES = ["easy", "medium", "hard"];
+
+// ../frontend/src/practice/problemFiles.ts
+var PROBLEM_MD = "problem.md";
+var GIVEN = "given.proschi";
+var STARTER = "starter.proschi";
+var SOLUTION = "solution.proschi";
+var WRONG_DIR = "wrong";
+var REQUIRED = [PROBLEM_MD, GIVEN, STARTER, SOLUTION];
+var ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var EXPECT_FAIL = /^#\s*expect-fail:\s*(.*?)\s*$/;
+var ProblemFolderError = class extends Error {
+  folder;
+  file;
+  line;
+  /** The message without the folder and file. */
+  detail;
+  constructor(folder, message, file, line) {
+    super(`problems/${folder}: ${file ? `${file}${line ? `:${line}` : ""}: ` : ""}${message}`);
+    this.name = "ProblemFolderError";
+    this.detail = message;
+    this.folder = folder;
+    this.file = file;
+    this.line = line;
+  }
+};
+function expectFailLines(source2) {
+  const names = [];
+  for (const line of source2.split("\n")) {
+    if (!line.startsWith("#")) break;
+    const m = line.match(EXPECT_FAIL);
+    if (m) names.push(m[1]);
+  }
+  return names;
+}
+var FIELDS = ["title", "summary", "difficulty", "tags", "order", "hints"];
+function readProblemMd(id, text) {
+  const fail2 = (message, line) => {
+    throw new ProblemFolderError(id, message, PROBLEM_MD, line);
+  };
+  let data;
+  let body;
+  try {
+    ({ data, body } = parseFrontMatter(text));
+  } catch (e) {
+    if (e instanceof FrontMatterError) return fail2(e.message.replace(/^line \d+: /, ""), e.line);
+    throw e;
+  }
+  for (const key of Object.keys(data)) if (!FIELDS.includes(key)) fail2(`Unknown front matter field '${key}' (use ${FIELDS.join(", ")})`);
+  const str = (key) => {
+    const v = data[key];
+    if (typeof v !== "string" || v.trim() === "") return fail2(`'${key}' must be a non-empty string`);
+    return v;
+  };
+  const list = (key) => {
+    const v = data[key];
+    if (!Array.isArray(v) || v.length === 0) return fail2(`'${key}' must be a list with at least one item`);
+    return v;
+  };
+  const difficulty = str("difficulty");
+  if (!DIFFICULTIES.includes(difficulty)) fail2(`'difficulty' must be one of ${DIFFICULTIES.join(", ")}`);
+  const order = data.order;
+  if (order !== void 0 && typeof order !== "number") fail2("'order' must be a number");
+  if (body === "") fail2("The statement (the Markdown after the front matter) is empty");
+  return {
+    title: str("title"),
+    summary: str("summary"),
+    difficulty,
+    tags: list("tags"),
+    ...typeof order === "number" ? { order } : {},
+    statement: body,
+    hints: list("hints")
+  };
+}
+function problemFromFiles(id, files) {
+  const fail2 = (message) => {
+    throw new ProblemFolderError(id, message);
+  };
+  if (!ID.test(id)) fail2('The folder name is the problem id and must be lowercase words joined by "-", e.g. url-shortener');
+  for (const name of REQUIRED) if (files[name] === void 0) fail2(`Missing ${name}`);
+  for (const name of Object.keys(files)) {
+    const wrong2 = name.startsWith(`${WRONG_DIR}/`) ? name.slice(WRONG_DIR.length + 1) : void 0;
+    if (!REQUIRED.includes(name) && !(wrong2 && /^[a-z0-9][a-z0-9-]*\.proschi$/.test(wrong2))) {
+      fail2(`Unexpected file ${name}: a problem folder holds ${REQUIRED.join(", ")} and ${WRONG_DIR}/<name>.proschi (lowercase, digits and "-")`);
+    }
+  }
+  const meta = readProblemMd(id, files[PROBLEM_MD]);
+  const wrong = Object.keys(files).filter((name) => name.startsWith(`${WRONG_DIR}/`)).sort().map((name) => ({ name: name.slice(WRONG_DIR.length + 1, -".proschi".length), source: files[name], expectFail: expectFailLines(files[name]) }));
+  return {
+    id,
+    ...meta,
+    given: files[GIVEN],
+    starter: files[STARTER],
+    solution: files[SOLUTION],
+    ...wrong.length ? { wrong } : {}
+  };
+}
+
+// ../frontend/src/dsl/imports.ts
+function joinImportPath(fromPath, importPath) {
+  const parts = importPath.startsWith("/") || !fromPath ? [] : fromPath.split("/").slice(0, -1);
+  for (const part of importPath.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === ".." && parts.length > 0 && parts[parts.length - 1] !== "..") parts.pop();
+    else parts.push(part);
+  }
+  return parts.join("/");
+}
+function mapResolver(files) {
+  const paths = Object.keys(files);
+  return (importPath, fromPath) => {
+    const path = joinImportPath(fromPath, importPath);
+    if (Object.prototype.hasOwnProperty.call(files, path)) return { path, source: files[path] };
+    const name = path.split("/").pop();
+    const sameName = paths.filter((p) => p.split("/").pop() === name);
+    return sameName.length === 1 ? { path: sameName[0], source: files[sameName[0]] } : void 0;
+  };
+}
+
+// ../frontend/src/playground/imports.ts
+function filesResolver(files, rootPath) {
+  const resolve4 = mapResolver(files);
+  return (importPath, fromPath) => {
+    if (joinImportPath(fromPath, importPath) === rootPath) return { path: rootPath, source: "" };
+    return resolve4(importPath, fromPath);
+  };
+}
+
+// ../frontend/src/practice/workspace.ts
+var PROBLEM_FILE = "problem.proschi";
+var SOLUTION_FILE = "solution.proschi";
+var CAPACITY_MESSAGE = "capacity is set by the problem; change the design (replicas, shards, caching) instead";
+function problemResolver(problem) {
+  return filesResolver({ [PROBLEM_FILE]: problem.given }, SOLUTION_FILE);
+}
+function enforceProblemCapacity(result) {
+  const capacity = result.diagram.capacity;
+  if (!capacity?.some((c) => c.loc.file !== PROBLEM_FILE)) return result;
+  const kept = [];
+  const errors = [];
+  for (const c of capacity) {
+    if (c.loc.file === PROBLEM_FILE) {
+      kept.push(c);
+      continue;
+    }
+    const { node, loc, shards, ...rest } = c;
+    if (Object.keys(rest).length > 0) {
+      errors.push({ severity: "error", message: `${CAPACITY_MESSAGE} (only \`shards <n>\` may be set in your file)`, ...loc });
+    }
+    if (shards !== void 0) kept.push({ node, shards, loc });
+  }
+  const diagram = { ...result.diagram };
+  if (kept.length) diagram.capacity = kept;
+  else delete diagram.capacity;
+  return { ...result, diagram, diagnostics: [...result.diagnostics, ...errors] };
+}
+function parseSolution(problem, source2) {
+  return enforceProblemCapacity(parse(source2, { path: SOLUTION_FILE, resolve: problemResolver(problem) }));
+}
+function runTests2(parsed, engine) {
+  if (!engine.available) return { blocked: "no-engine", results: [], passed: 0, solved: false };
+  if (parsed.diagnostics.some((d) => d.severity === "error")) return { blocked: "errors", results: [], passed: 0, solved: false };
+  const analysis = engine.analyze(parsed.diagram);
+  const results = engine.runTests(parsed.diagram, analysis);
+  const passed = results.filter((r) => r.passed).length;
+  return { results, passed, solved: results.length > 0 && passed === results.length };
+}
+
+// ../frontend/src/practice/validate.ts
+var IMPORT_LINE = `import "${PROBLEM_FILE}"`;
+function trafficUseCases(given) {
+  return [...(given.match(/traffic\s*\{([\s\S]*?)\}/)?.[1] ?? "").matchAll(/^\s*"([^"]+)"/gm)].map((m) => m[1]);
+}
+function firstCodeLine(source2) {
+  const lines = source2.split("\n");
+  const i = lines.findIndex((l) => !l.startsWith("#"));
+  return i < 0 ? { text: "", line: lines.length } : { text: lines[i], line: i + 1 };
+}
+function validateProblem(problem, engine = defaultEngine) {
+  const violations = [];
+  const add = (file, message, line) => violations.push({ file, message, ...line ? { line } : {} });
+  const fileOf = (d, own) => d.file === PROBLEM_FILE ? GIVEN : own;
+  const report = (own, ds) => {
+    for (const d of ds) add(fileOf(d, own), `${d.severity}: ${d.message}`, d.line);
+  };
+  if (!/^## Functional requirements$/m.test(problem.statement)) add(PROBLEM_MD, 'The statement needs a "## Functional requirements" section');
+  const useCases = trafficUseCases(problem.given);
+  if (useCases.length === 0) add(GIVEN, "The given needs a traffic block naming at least one use case");
+  for (const name of useCases) {
+    if (!problem.statement.includes(`**${name}**`)) add(PROBLEM_MD, `The statement must name the use case **${name}** in bold`);
+    if (!problem.solution.includes(`usecase "${name}"`)) add(SOLUTION, `The solution must define usecase "${name}" from the traffic`);
+  }
+  const importLine = problem.given.split("\n").findIndex((l) => /^\s*import /.test(l));
+  if (importLine >= 0) add(GIVEN, "The given must not import anything", importLine + 1);
+  report(GIVEN, parse(problem.given).diagnostics.filter((d) => d.severity === "error"));
+  if (format(problem.given) !== problem.given) add(GIVEN, "Not in canonical format; run proschi fmt");
+  if (!problem.solution.startsWith(`${IMPORT_LINE}
+`)) add(SOLUTION, `Must start with ${IMPORT_LINE}`, 1);
+  const solution = parseSolution(problem, problem.solution);
+  report(SOLUTION, solution.diagnostics);
+  if (format(problem.solution) !== problem.solution) add(SOLUTION, "Not in canonical format; run proschi fmt");
+  const solutionRun = runTests2(solution, engine);
+  const testNames = new Set(solutionRun.results.map((r) => r.name));
+  if (solutionRun.blocked === "no-engine") add(SOLUTION, "No simulation to run the tests with");
+  else if (solutionRun.blocked !== "errors") {
+    if (solutionRun.results.length === 0) add(GIVEN, "The problem has no requirements or tests");
+    for (const r of solutionRun.results.filter((r2) => !r2.passed)) add(SOLUTION, `Fails "${r.name}": ${r.message}`, r.loc?.file === void 0 ? r.loc?.line : void 0);
+  }
+  if (!problem.starter.startsWith(`${IMPORT_LINE}
+`)) add(STARTER, `Must start with ${IMPORT_LINE}`, 1);
+  const starter = parseSolution(problem, problem.starter);
+  report(STARTER, starter.diagnostics.filter((d) => d.severity === "error"));
+  const starterRun = runTests2(starter, engine);
+  const starterFails = starterRun.results.filter((r) => !r.passed).map((r) => r.name);
+  if (!starterRun.blocked && starterFails.length === 0) add(STARTER, "The starter passes every test; it must leave something to solve");
+  const wrong = (problem.wrong ?? []).map((w) => {
+    const file = `${WRONG_DIR}/${w.name}.proschi`;
+    const expectFail = w.expectFail.length ? w.expectFail : expectFailLines(w.source);
+    if (expectFail.length === 0) add(file, 'Start the file with one or more "# expect-fail: <test name>" lines', 1);
+    const code = firstCodeLine(w.source);
+    if (code.text !== IMPORT_LINE) add(file, `After the comment lines the file must start with ${IMPORT_LINE}`, code.line);
+    const parsed = parseSolution(problem, w.source);
+    report(file, parsed.diagnostics.filter((d) => d.severity === "error"));
+    const run2 = runTests2(parsed, engine);
+    const failed = run2.results.filter((r) => !r.passed).map((r) => r.name);
+    const missing = [];
+    if (!run2.blocked) {
+      const lines = w.source.split("\n");
+      for (const name of expectFail) {
+        const line = lines.findIndex((l) => l.startsWith("#") && l.includes(name)) + 1 || void 0;
+        if (!testNames.has(name) && !failed.includes(name)) {
+          add(file, `No test or requirement is named "${name}" (names: ${[...testNames].map((n) => JSON.stringify(n)).join(", ")})`, line);
+          missing.push(name);
+        } else if (!failed.includes(name)) {
+          add(file, `Expected to fail "${name}", but it passes`, line);
+          missing.push(name);
+        }
+      }
+    }
+    return { name: w.name, file, expectFail, failed, missing, alsoFails: failed.filter((n) => !expectFail.includes(n)) };
+  });
+  return { id: problem.id, tests: solutionRun.results.length, starterFails, wrong, violations };
+}
+
+// src/problemTemplate.ts
+function problemTemplate(id) {
+  const title = id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+  return {
+    "problem.md": `---
+title: ${title}
+summary: TODO One line for the problem list and the landing page.
+difficulty: easy
+tags: [caching, todo]
+hints:
+  - TODO A nudge, e.g. what answers most reads without the database?
+  - TODO Closer, e.g. a miss reads the database, then fills the cache.
+  - TODO Nearly the answer, e.g. two of everything survives any node failure.
+---
+
+TODO A short context: what the system does and for whom.
+
+## Functional requirements
+
+- **Fetch item**: a user asks for an item by id and gets it back. Name its
+  two scenarios \`"Cache hit"\` and \`"Cache miss"\`.
+
+Use these use case and scenario names exactly: the traffic, requirements and
+tests in \`problem.proschi\` refer to them.
+
+## Scale
+
+- Fetch item: **1k rps**, 90% of them for items read recently.
+
+## Constraints
+
+- p99 of fetching an item under **100 ms**.
+- Available **99.9%** of the time.
+- Losing any single machine must not take the service down.
+- At most **$2,000 / month**.
+
+## What is given
+
+\`problem.proschi\` declares the \`user\` and holds the traffic,
+requirements and tests. Your file imports it; add the components,
+connections and the use case.
+`,
+    "given.proschi": `# TODO The problem as Proschi: the fixed nodes the solver connects to, the
+# traffic, the requirements and the tests that encode the key insight.
+title "${title}" "TODO One line"
+
+user "User" [Actor]
+
+traffic {
+  "Fetch item" 1k rps mix "Cache hit" 90%, "Cache miss" 10%
+}
+
+requirements {
+  p99 "Fetch item" < 100ms
+  availability "Fetch item" >= 99.9%
+  survive any node failure
+  cost <= 2000 usd/month
+}
+
+test "Items are read from the cache first" {
+  "Fetch item" calls any cache before any database
+  "Fetch item" scenario "Cache hit" never calls any database
+}
+`,
+    "starter.proschi": `import "problem.proschi"
+
+# TODO A small, valid start: usually one use case with its first step.
+api "Item API" [REST API]
+
+user -> api
+
+usecase "Fetch item" {
+  user -> api  : GET /items/42
+  api --> user : 200 item
+}
+`,
+    "solution.proschi": `import "problem.proschi"
+
+lb    "Load Balancer" [AWS Load Balancer] x2
+api   "Item API"      [REST API]          x2
+cache "Item Cache"    [Redis]             x2
+db    "Items DB"      [PostgreSQL]        x2
+
+user -> lb
+lb   -> api   : HTTPS
+api  -> cache : GET / SET
+api  -> db    : SELECT
+
+decision "Cache items in Redis" because "Most reads are for recent items; the cache answers them in a millisecond"
+
+usecase "Fetch item" "Return one item" {
+  user -> lb    : GET /items/42
+  lb   -> api   : GET /items/42
+  api  -> cache : GET item:42
+
+  alt "Cache hit" when "the item was read recently" {
+    cache --> api : item
+  } alt "Cache miss" when "the item is not cached" {
+    cache --> api   : nil
+    api    -> db    : SELECT item 42
+    db    --> api   : item
+    api   ->> cache : SET item:42
+  }
+  api --> lb   : 200 item
+  lb  --> user : 200 item
+}
+`,
+    "wrong/database-only.proschi": `# expect-fail: Items are read from the cache first
+# TODO A plausible wrong design (here: no cache) and the tests it must fail.
+import "problem.proschi"
+
+lb  "Load Balancer" [AWS Load Balancer] x2
+api "Item API"      [REST API]          x2
+db  "Items DB"      [PostgreSQL]        x2
+
+user -> lb
+lb   -> api : HTTPS
+api  -> db  : SELECT
+
+usecase "Fetch item" {
+  user -> lb  : GET /items/42
+  lb   -> api : GET /items/42
+  api  -> db  : SELECT item 42
+  db  --> api  : item
+  api --> lb   : 200 item
+  lb  --> user : 200 item
+}
+`
+  };
+}
+
+// src/problem.ts
+var PROBLEM_USAGE = `  proschi problem check [--format text|github|json] [dir]
+  proschi problem new <id> [--dir <problems dir>]`;
+var PROBLEM_HELP = `problem Practice problems, one folder each (docs/PRACTICE.md).
+        check validates every problem folder in dir (default: the repository's
+        frontend/src/practice/problems when run inside it): front matter, the
+        given (no errors, canonical format), the solution (no diagnostics,
+        canonical, passes every test), the starter (fails a test) and each
+        wrong/ design (fails every test its "# expect-fail:" lines name).
+        Exits with 1 on any violation.
+        new scaffolds a folder that already passes check, with TODOs.`;
+var REPO_PROBLEMS = (0, import_node_path6.join)("frontend", "src", "practice", "problems");
+function findProblemsDir(cwd = process.cwd()) {
+  for (let dir = (0, import_node_path6.resolve)(cwd); ; dir = (0, import_node_path6.dirname)(dir)) {
+    const candidate = (0, import_node_path6.join)(dir, REPO_PROBLEMS);
+    if ((0, import_node_fs5.existsSync)(candidate) && (0, import_node_fs5.statSync)(candidate).isDirectory()) return candidate;
+    if ((0, import_node_path6.dirname)(dir) === dir) return void 0;
+  }
+}
+function readProblemFolder(folder) {
+  const files = {};
+  for (const entry of (0, import_node_fs5.readdirSync)(folder, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    if (entry.isFile()) files[entry.name] = (0, import_node_fs5.readFileSync)((0, import_node_path6.join)(folder, entry.name), "utf8");
+    else if (entry.isDirectory()) {
+      for (const sub of (0, import_node_fs5.readdirSync)((0, import_node_path6.join)(folder, entry.name), { withFileTypes: true })) {
+        if (!sub.name.startsWith(".")) files[`${entry.name}/${sub.name}`] = sub.isFile() ? (0, import_node_fs5.readFileSync)((0, import_node_path6.join)(folder, entry.name, sub.name), "utf8") : "";
+      }
+    }
+  }
+  return files;
+}
+function checkProblems(dir) {
+  return (0, import_node_fs5.readdirSync)(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules").map((e) => e.name).sort().map((id) => {
+    const folder = displayPath3((0, import_node_path6.join)(dir, id));
+    try {
+      const problem = problemFromFiles(id, readProblemFolder((0, import_node_path6.join)(dir, id)));
+      return { folder, loaded: true, ...validateProblem(problem) };
+    } catch (e) {
+      if (!(e instanceof ProblemFolderError)) throw e;
+      const violation = { file: e.file ?? ".", message: e.detail, ...e.line ? { line: e.line } : {} };
+      return { folder, loaded: false, id, tests: 0, starterFails: [], wrong: [], violations: [violation] };
+    }
+  });
+}
+var quote2 = (names) => names.map((n) => `"${n}"`).join(", ");
+var escape3 = (s) => s.replace(/%/g, "%25").replace(/\r?\n/g, "%0A");
+function formatProblemReports(dir, reports, style) {
+  if (style === "json") return JSON.stringify({ dir: displayPath3(dir), problems: reports }, null, 2);
+  const lines = [];
+  const where = (r, v) => v.file === "." ? r.folder : (0, import_node_path6.join)(r.folder, v.file);
+  for (const r of reports) {
+    if (style === "github") {
+      for (const v of r.violations) lines.push(`::error file=${where(r, v)},line=${v.line ?? 1},title=proschi problem ${r.id}::${escape3(v.message)}`);
+      continue;
+    }
+    const ok = r.violations.length === 0;
+    const wrong = r.wrong.length === 1 ? "1 wrong design" : `${r.wrong.length} wrong designs`;
+    lines.push(`${ok ? "\u2713" : "\u2717"} ${r.id}${r.loaded ? `: ${r.tests} tests, the starter fails ${r.starterFails.length}, ${wrong}` : ""}`);
+    for (const v of r.violations) lines.push(`    ${where(r, v)}${v.line ? `:${v.line}` : ""}: ${v.message}`);
+    for (const w of r.wrong) {
+      if (w.missing.length) continue;
+      lines.push(`    ${WRONG_DIR}/${w.name}: fails ${quote2(w.expectFail)}${w.alsoFails.length ? `; also fails ${quote2(w.alsoFails)}` : ""}`);
+    }
+  }
+  if (style === "text") {
+    const violations = reports.reduce((n, r) => n + r.violations.length, 0);
+    const wrong = reports.reduce((n, r) => n + r.wrong.length, 0);
+    const bad = reports.filter((r) => r.violations.length).length;
+    lines.push(
+      `${reports.length} problem${reports.length === 1 ? "" : "s"}, ${wrong} wrong design${wrong === 1 ? "" : "s"}: ${violations ? `${violations} violation(s) in ${bad} problem${bad === 1 ? "" : "s"}` : "no violations"}`
+    );
+  }
+  return lines.join("\n");
+}
+function problemCheck(args, out, err, cwd) {
+  let style = "text";
+  const paths = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--format") {
+      const value = args[++i];
+      if (value !== "text" && value !== "github" && value !== "json") {
+        err(`Unknown format '${value ?? ""}'; use text, github or json`);
+        return 2;
+      }
+      style = value;
+    } else if (arg.startsWith("-")) {
+      err(`Unknown option ${arg}
+
+Usage:
+${PROBLEM_USAGE}`);
+      return 2;
+    } else paths.push(arg);
+  }
+  if (paths.length > 1) {
+    err(`Give one problems directory
+
+Usage:
+${PROBLEM_USAGE}`);
+    return 2;
+  }
+  const dir = paths[0] ? (0, import_node_path6.resolve)(cwd, paths[0]) : findProblemsDir(cwd);
+  if (!dir) {
+    err(`Not inside the Proschi repository; give the problems directory
+
+Usage:
+${PROBLEM_USAGE}`);
+    return 2;
+  }
+  if (!(0, import_node_fs5.existsSync)(dir) || !(0, import_node_fs5.statSync)(dir).isDirectory()) {
+    err(`No such directory: ${paths[0] ?? dir}`);
+    return 2;
+  }
+  const reports = checkProblems(dir);
+  if (reports.length === 0) {
+    err(`No problem folders in ${displayPath3(dir)}`);
+    return 1;
+  }
+  const text = formatProblemReports(dir, reports, style);
+  if (text) out(text);
+  return reports.some((r) => r.violations.length > 0) ? 1 : 0;
+}
+function problemNew(args, out, err, cwd) {
+  let dirArg;
+  const ids = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--dir") {
+      dirArg = args[++i];
+      if (!dirArg) {
+        err("Expected a directory after --dir");
+        return 2;
+      }
+    } else if (arg.startsWith("-")) {
+      err(`Unknown option ${arg}
+
+Usage:
+${PROBLEM_USAGE}`);
+      return 2;
+    } else ids.push(arg);
+  }
+  if (ids.length !== 1) {
+    err(`Usage:
+${PROBLEM_USAGE}`);
+    return 2;
+  }
+  const id = ids[0];
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(id)) {
+    err(`The id '${id}' must be lowercase words joined by "-", e.g. url-shortener (it is the folder name and the URL)`);
+    return 2;
+  }
+  const dir = dirArg ? (0, import_node_path6.resolve)(cwd, dirArg) : findProblemsDir(cwd) ?? (0, import_node_path6.resolve)(cwd, "problems");
+  const folder = (0, import_node_path6.join)(dir, id);
+  if ((0, import_node_fs5.existsSync)(folder)) {
+    err(`${displayPath3(folder)} already exists`);
+    return 1;
+  }
+  const files = problemTemplate(id);
+  for (const [name, text] of Object.entries(files)) {
+    (0, import_node_fs5.mkdirSync)((0, import_node_path6.dirname)((0, import_node_path6.join)(folder, name)), { recursive: true });
+    (0, import_node_fs5.writeFileSync)((0, import_node_path6.join)(folder, name), text);
+  }
+  const shown = displayPath3(folder);
+  out(`Created ${shown}/
+  ${Object.keys(files).join("\n  ")}
+
+It already passes \`proschi problem check\`; now make it your problem:
+  1. problem.md: title, summary, difficulty, tags, hints, and the statement
+     (name every use case in bold and spell out the scenario names).
+  2. given.proschi: the fixed nodes, the traffic, the requirements and the
+     tests that encode the key insight. Capacity overrides go here only.
+  3. solution.proschi: a good answer that passes every test; starter.proschi:
+     a small valid start that fails at least one.
+  4. Calibrate: set the latency, cost and availability limits between the
+     reference design and brute-force designs, and prove it with wrong/
+     designs that start with "# expect-fail: <test name>".
+  5. Run: proschi problem check ${displayPath3(dir)}`);
+  return 0;
+}
+function runProblem(args, out, err, cwd = process.cwd()) {
+  const [sub, ...rest] = args;
+  if (sub === "check") return problemCheck(rest, out, err, cwd);
+  if (sub === "new") return problemNew(rest, out, err, cwd);
+  err(`${sub ? `Unknown problem command '${sub}'
+
+` : ""}Usage:
+${PROBLEM_USAGE}`);
+  return 2;
+}
+
 // src/cli.ts
-var VERSION = true ? "0.4.0" : "dev";
+var VERSION = true ? "0.5.0" : "dev";
 var USAGE = `Usage:
   proschi check [--strict] [--format text|github|json] [--openapi <node>=<spec>]... <file|dir>...
   proschi parse <file>
 ${RENDER_USAGE}
 ${FMT_USAGE}
 ${SIM_USAGE}
+${PROBLEM_USAGE}
   proschi --version
 
 check   Reports errors and warnings. Directories are searched for *.proschi files.
@@ -18775,19 +19464,20 @@ parse   Prints {"diagram", "diagnostics"} as JSON; the shape is described by
         schema/proschi-diagram.schema.json.
 ${RENDER_HELP}
 ${FMT_HELP}
-${SIM_HELP}`;
+${SIM_HELP}
+${PROBLEM_HELP}`;
 function collectFiles(paths) {
   const out = [];
   const walk = (dir) => {
-    for (const entry of (0, import_node_fs5.readdirSync)(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    for (const entry of (0, import_node_fs6.readdirSync)(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
       if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-      const full = (0, import_node_path6.join)(dir, entry.name);
+      const full = (0, import_node_path7.join)(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.name.endsWith(".proschi")) out.push(full);
     }
   };
   for (const p of paths) {
-    if ((0, import_node_fs5.statSync)(p).isDirectory()) walk(p);
+    if ((0, import_node_fs6.statSync)(p).isDirectory()) walk(p);
     else out.push(p);
   }
   return out;
@@ -18835,6 +19525,7 @@ function run(argv, out = console.log, err = console.error) {
   if (command === "fmt") return runFmt(rest, collectFiles, out, err);
   if (command === "test") return runTest(rest, collectFiles, out, err);
   if (command === "analyze") return runAnalyze(rest, out, err);
+  if (command === "problem") return runProblem(rest, out, err);
   if (command === "check") {
     let strict = false;
     let style = "text";

package/dist/server.cjs

@@ -28971,7 +28971,7 @@ function positionAt(text, offset) {
 
 // src/server.ts
 if (process.argv.includes("--version")) {
-  console.log(true ? "0.4.0" : "dev");
+  console.log(true ? "0.5.0" : "dev");
   process.exit(0);
 }
 var connection = (0, import_node.createConnection)(import_node.ProposedFeatures.all);
@@ -29012,7 +29012,7 @@ connection.onInitialize(() => ({
     documentFormattingProvider: true,
     codeActionProvider: { codeActionKinds: [import_node.CodeActionKind.QuickFix] }
   },
-  serverInfo: { name: "proschi-language-server", version: true ? "0.4.0" : "dev" }
+  serverInfo: { name: "proschi-language-server", version: true ? "0.5.0" : "dev" }
 }));
 function validate(document) {
   const analysis = analysisOf(document);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proschi",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Command-line checker and language server for Proschi architecture diagrams",
   "license": "MIT",
   "repository": {