@patterkit/cli 0.2.7 → 0.3.0

package/dist/cli.js

@@ -194628,6 +194628,201 @@ function exportBundle(input) {
   };
 }
 
+// ../ops/src/reachability.ts
+var normaliseRef = (ref) => ref.includes(".") ? ref : `@patter.${ref.slice(1)}`;
+var SEP = "\0";
+var keyOf = (ref, sceneId) => ref.startsWith("@scene.") ? `${sceneId}${SEP}${ref}` : ref;
+var shown = (key2) => {
+  const bare = key2.includes(SEP) ? key2.slice(key2.indexOf(SEP) + 1) : key2;
+  const at = bare.indexOf(":");
+  return at < 0 ? bare : `${bare.slice(0, at)} +${bare.slice(at + 1)}`;
+};
+var svRef = (ast) => Array.isArray(ast) && ast[0] === "sv" ? `@${String(ast[1])}.${String(ast[2])}` : void 0;
+function latchOf(ast, sceneId) {
+  const direct = svRef(ast);
+  if (direct !== void 0) return keyOf(direct, sceneId);
+  if (!Array.isArray(ast)) return void 0;
+  if (ast[0] === "bin" && ast[1] === "==") {
+    const [, , l2, r] = ast;
+    for (const [a, b] of [[l2, r], [r, l2]]) {
+      const ref = svRef(a);
+      if (ref !== void 0 && Array.isArray(b) && b[0] === "b" && b[1] === true) return keyOf(ref, sceneId);
+    }
+    return void 0;
+  }
+  if (ast[0] === "call" && ast[1] === "check_flags") {
+    const ref = svRef(ast[2]);
+    const args = ast.slice(3);
+    if (ref === void 0 || args.length !== 1) return void 0;
+    const arg = args[0];
+    if (Array.isArray(arg) && arg[0] === "fd" && arg[1] === "+") return `${keyOf(ref, sceneId)}:${String(arg[2])}`;
+  }
+  return void 0;
+}
+function disjuncts(ast) {
+  if (Array.isArray(ast) && ast[0] === "bin" && ast[1] === "or") {
+    const [, , l2, r] = ast;
+    return [...disjuncts(l2), ...disjuncts(r)];
+  }
+  return [ast];
+}
+function terms(ast, sceneId, negated = false, into = []) {
+  const latch = latchOf(ast, sceneId);
+  if (latch !== void 0) {
+    into.push({ key: latch, negated });
+    return into;
+  }
+  if (!Array.isArray(ast)) return into;
+  if (ast[0] === "u" && ast[1] === "not") return terms(ast[2], sceneId, !negated, into);
+  if (ast[0] === "bin" && ast[1] === "and" && !negated) {
+    terms(ast[2], sceneId, false, into);
+    terms(ast[3], sceneId, false, into);
+  }
+  return into;
+}
+var requirementsOf = (expr, sceneId) => expr === void 0 ? [] : terms(expr.ast, sceneId);
+var asFlags = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+function reachabilityIssues(loaded, compiled) {
+  const bundle = compiled ?? exportBundle({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
+  const hostTokens = new Set((loaded.project.scopeRegistry?.scopes ?? []).map((s) => s.token));
+  const preset = /* @__PURE__ */ new Set();
+  const notALatch = (decl, key2) => {
+    if (decl.temporary) {
+      preset.add(key2);
+      for (const v of decl.values ?? []) preset.add(`${key2}:${v}`);
+      return;
+    }
+    if (decl.type === "boolean" && decl.default === true) preset.add(key2);
+    if (decl.type === "flags") for (const v of asFlags(decl.default)) preset.add(`${key2}:${v}`);
+  };
+  for (const decl of loaded.project.properties ?? []) notALatch(decl, `@patter.${decl.name}`);
+  for (const scene of loaded.scenes) {
+    for (const decl of scene.sceneProps ?? []) notALatch(decl, `${scene.id}${SEP}@scene.${decl.name}`);
+  }
+  const latched = /* @__PURE__ */ new Set();
+  const broken = /* @__PURE__ */ new Set();
+  const writers = /* @__PURE__ */ new Map();
+  const noteWrite = (key2, requires) => {
+    latched.add(key2);
+    (writers.get(key2) ?? writers.set(key2, []).get(key2)).push({ requires });
+  };
+  const breakKey = (key2) => {
+    broken.add(key2);
+    for (const k of latched) if (k.startsWith(`${key2}:`)) broken.add(k);
+  };
+  const scanEffects = (effects, sceneId, need) => {
+    for (const e of effects ?? []) {
+      const ref = normaliseRef(e.target);
+      const key2 = keyOf(ref, sceneId);
+      const ast = e.value.ast;
+      if (Array.isArray(ast) && ast[0] === "b" && ast[1] === true) {
+        noteWrite(key2, need);
+        continue;
+      }
+      if (Array.isArray(ast) && ast[0] === "call" && ast[1] === "set_flags" && svRef(ast[2]) === ref) {
+        let clean3 = true;
+        for (const arg of ast.slice(3)) {
+          if (Array.isArray(arg) && arg[0] === "fd" && arg[1] === "+") noteWrite(`${key2}:${String(arg[2])}`, need);
+          else clean3 = false;
+        }
+        if (clean3) continue;
+      }
+      breakKey(key2);
+    }
+  };
+  const walk2 = (nodes, sceneId, gate) => {
+    for (const node of nodes) {
+      const here = [...gate, ...requirementsOf(node.condition, sceneId)];
+      if (node.type === "group") walk2(node.children, sceneId, here);
+      else {
+        scanEffects(node.onEnter, sceneId, here);
+        scanEffects(node.onExit, sceneId, here);
+      }
+    }
+  };
+  for (const scene of Object.values(bundle.scenes)) {
+    scanEffects(scene.onEntry, scene.id, []);
+    for (const block of scene.blocks) walk2(block.children, scene.id, []);
+  }
+  for (const key2 of [...latched]) {
+    const at = key2.indexOf(":");
+    if (at > 0 && broken.has(key2.slice(0, at))) broken.add(key2);
+  }
+  const hostDriven = (key2) => hostTokens.has(key2.slice(1, key2.indexOf(".")));
+  const monotonic = (key2) => latched.has(key2) && !broken.has(key2) && !preset.has(key2) && !hostDriven(key2);
+  const cache2 = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Set();
+  const mustHold = (key2) => {
+    const done = cache2.get(key2);
+    if (done !== void 0) return { need: done, cut: false };
+    if (inFlight.has(key2)) return { need: /* @__PURE__ */ new Set(), cut: true };
+    const routes = writers.get(key2);
+    if (routes === void 0 || routes.length === 0) return { need: /* @__PURE__ */ new Set(), cut: false };
+    inFlight.add(key2);
+    let shared;
+    let cut = false;
+    for (const route of routes) {
+      const need = /* @__PURE__ */ new Set();
+      for (const t of route.requires) {
+        if (t.negated || !monotonic(t.key)) continue;
+        need.add(t.key);
+        const deeper = mustHold(t.key);
+        cut ||= deeper.cut;
+        for (const k of deeper.need) need.add(k);
+      }
+      shared = shared === void 0 ? need : new Set([...shared].filter((k) => need.has(k)));
+    }
+    inFlight.delete(key2);
+    const result = shared ?? /* @__PURE__ */ new Set();
+    if (!cut) cache2.set(key2, result);
+    return { need: result, cut };
+  };
+  const refute = (gate) => {
+    for (const no of gate.filter((t) => t.negated)) {
+      if (!monotonic(no.key)) continue;
+      if (gate.some((t) => !t.negated && t.key === no.key)) {
+        return `it asks for ${shown(no.key)} to be both set and not set`;
+      }
+      for (const yes of gate.filter((t) => !t.negated && t.key !== no.key)) {
+        if (!monotonic(yes.key)) continue;
+        const chain = mustHold(yes.key);
+        if (!chain.cut && chain.need.has(no.key)) {
+          return `${shown(yes.key)} can only become true after ${shown(no.key)}, which nothing sets back, so this condition can never hold`;
+        }
+      }
+    }
+    return void 0;
+  };
+  const issues = [];
+  const report = (nodes, sceneId, gate) => {
+    for (const node of nodes) {
+      const own = node.condition;
+      const branches = own ? disjuncts(own.ast) : [void 0];
+      let reason;
+      const refuted = branches.every((b) => {
+        const r = refute([...gate, ...b ? terms(b, sceneId) : []]);
+        reason ??= r;
+        return r !== void 0;
+      });
+      if (refuted && reason !== void 0 && own) {
+        issues.push({
+          nodeId: node.id,
+          field: "condition",
+          src: own.src,
+          severity: "warning",
+          message: `this can never run: ${reason}`
+        });
+        continue;
+      }
+      if (node.type === "group") report(node.children, sceneId, [...gate, ...requirementsOf(own, sceneId)]);
+    }
+  };
+  for (const scene of Object.values(bundle.scenes)) {
+    for (const block of scene.blocks) report(block.children, scene.id, []);
+  }
+  return issues;
+}
+
 // ../ops/src/validate.ts
 function runValidate(loaded) {
   const { project, scenes, locales } = loaded;
@@ -194639,10 +194834,12 @@ function runValidate(loaded) {
   const staleBundles = checkBundles(loaded);
   const unresolvedMerges = sidecarIssues(walkFiles(loaded.root, CONFLICT_SIDECAR));
   const orphans = orphanShards(loaded);
+  const reachability = structural.length === 0 && conditions.length === 0 ? reachabilityIssues(loaded) : [];
   return {
     structural,
     conditions,
     interpolation,
+    reachability,
     hygiene,
     staleBundles,
     unresolvedMerges,
@@ -196959,40 +197156,113 @@ function targetHostRef(target, hostTokens) {
   const m = /^@([A-Za-z_][\w]*)\.(.+)$/.exec(target);
   return m && hostTokens.has(m[1]) ? `@${m[1]}.${m[2]}` : void 0;
 }
+function flagKeys(node, hostTokens, fn) {
+  if (node.kind !== "call" || node.name !== fn) return [];
+  const subject = node.args[0];
+  if (!subject || subject.kind !== "scopedvar" || !hostTokens.has(subject.scope)) return [];
+  const ref = `@${subject.scope}.${subject.name}`;
+  return node.args.slice(1).filter((a) => a.kind === "flagdelta").map((a) => `${ref}:${a.name}`);
+}
+function fineRefsIn(node, hostTokens, out) {
+  for (const k of flagKeys(node, hostTokens, "check_flags")) out.add(k);
+  switch (node.kind) {
+    case "unary":
+      fineRefsIn(node.operand, hostTokens, out);
+      break;
+    case "binary":
+      fineRefsIn(node.left, hostTokens, out);
+      fineRefsIn(node.right, hostTokens, out);
+      break;
+    case "call":
+      for (const a of node.args) fineRefsIn(a, hostTokens, out);
+      break;
+    default:
+      break;
+  }
+}
 function analyzeHostScopes(bundle, hostTokens) {
   const written = /* @__PURE__ */ new Set();
   const gatesByBeat = /* @__PURE__ */ new Map();
+  const fineGatesByBeat = /* @__PURE__ */ new Map();
   const proposals = /* @__PURE__ */ new Map();
-  if (hostTokens.size === 0) return { written, gatesByBeat, proposals };
+  const writerSites = /* @__PURE__ */ new Map();
+  const opaqueWrites = /* @__PURE__ */ new Set();
+  const empty = { written, gatesByBeat, proposals, fineGatesByBeat, writerSites, opaqueWrites };
+  if (hostTokens.size === 0) return empty;
   const refsIn = (expr) => {
     const refs = /* @__PURE__ */ new Set();
     if (expr) scanExpr(deserialiseAst(expr.ast), hostTokens, refs, proposals);
     return refs;
   };
-  const scanEffects = (effects) => {
+  const fineIn = (expr) => {
+    const refs = /* @__PURE__ */ new Set();
+    if (expr) fineRefsIn(deserialiseAst(expr.ast), hostTokens, refs);
+    return refs;
+  };
+  const addSite = (key2, witnesses) => {
+    (writerSites.get(key2) ?? writerSites.set(key2, []).get(key2)).push(witnesses);
+  };
+  const scanEffects = (effects, witnesses) => {
     for (const e of effects ?? []) {
-      const t = targetHostRef(e.target, hostTokens);
-      if (t) written.add(t);
+      const target = targetHostRef(e.target, hostTokens);
+      if (target) {
+        written.add(target);
+        addSite(target, witnesses);
+        const flags = e.value ? flagKeys(deserialiseAst(e.value.ast), hostTokens, "set_flags") : [];
+        if (flags.length) for (const k of flags) addSite(k, witnesses);
+        else opaqueWrites.add(target);
+      }
       refsIn(e.value);
     }
   };
-  const walk2 = (nodes, gate) => {
+  const walk2 = (nodes, gate, fine) => {
     for (const node of nodes) {
       const here = /* @__PURE__ */ new Set([...gate, ...refsIn(node.condition)]);
+      const hereFine = /* @__PURE__ */ new Set([...fine, ...fineIn(node.condition)]);
       if (node.type === "group") {
-        walk2(node.children, here);
+        walk2(node.children, here, hereFine);
       } else {
-        scanEffects(node.onEnter);
-        scanEffects(node.onExit);
-        for (const beat of node.beats ?? []) gatesByBeat.set(beat.id, here);
+        const witnesses = (node.beats ?? []).map((b) => b.id);
+        scanEffects(node.onEnter, witnesses);
+        scanEffects(node.onExit, witnesses);
+        for (const beat of node.beats ?? []) {
+          gatesByBeat.set(beat.id, here);
+          fineGatesByBeat.set(beat.id, hereFine);
+        }
       }
     }
   };
   for (const scene of Object.values(bundle.scenes)) {
-    scanEffects(scene.onEntry);
-    for (const block of scene.blocks) walk2(block.children, /* @__PURE__ */ new Set());
+    const sceneBeats = [];
+    const collect = (nodes) => {
+      for (const n of nodes) {
+        if (n.type === "group") collect(n.children);
+        else for (const b of n.beats ?? []) sceneBeats.push(b.id);
+      }
+    };
+    for (const block of scene.blocks) collect(block.children);
+    scanEffects(scene.onEntry, sceneBeats);
+    for (const block of scene.blocks) walk2(block.children, /* @__PURE__ */ new Set(), /* @__PURE__ */ new Set());
+  }
+  return empty;
+}
+function blockedGates(beatId, analysis, drivenRefs, reachedRuns) {
+  const out = [];
+  const gates = /* @__PURE__ */ new Set([...analysis.gatesByBeat.get(beatId) ?? [], ...analysis.fineGatesByBeat.get(beatId) ?? []]);
+  for (const ref of [...gates].sort()) {
+    const coarse = ref.includes(":") ? ref.slice(0, ref.indexOf(":")) : ref;
+    if (drivenRefs.has(coarse)) continue;
+    if (!analysis.written.has(coarse)) continue;
+    if (ref !== coarse && analysis.opaqueWrites.has(coarse)) continue;
+    if (ref === coarse && [...gates].some((g) => g !== ref && g.startsWith(`${ref}:`))) continue;
+    const sites = analysis.writerSites.get(ref) ?? [];
+    if (!sites.length) continue;
+    if (sites.some((s) => !s.length || s.some((w) => !reachedRuns.has(w)))) continue;
+    if (!sites.every((s) => s.every((w) => reachedRuns.get(w) === 0))) continue;
+    const writers = [...new Set(sites.flat())].sort();
+    out.push({ ref, writers });
   }
-  return { written, gatesByBeat, proposals };
+  return out;
 }
 function proposeCoverageDrivers(loaded) {
   const hostTokens = new Set((loaded.project.scopeRegistry?.scopes ?? []).map((s) => s.token));
@@ -197125,12 +197395,15 @@ function* sweep(loaded, options = {}, hooks = {}) {
     const m = meta.get(id);
     const reached = reachedRuns.get(id);
     let needsInput;
+    let blockedBy;
     if (reached === 0) {
       const gates = [...analysis.gatesByBeat.get(id) ?? []].filter((r) => !analysis.written.has(r) && !drivenRefs.has(r));
       if (gates.length) {
         needsInput = gates;
         for (const g of gates) unwrittenInputs.add(g);
       }
+      const blocked = blockedGates(id, analysis, drivenRefs, reachedRuns);
+      if (blocked.length) blockedBy = blocked;
     }
     return {
       id,
@@ -197141,7 +197414,8 @@ function* sweep(loaded, options = {}, hooks = {}) {
       hits: hitCount.get(id),
       reachedRuns: reached,
       reachPct: executed ? reached / executed * 100 : 0,
-      ...needsInput ? { needsInput } : {}
+      ...needsInput ? { needsInput } : {},
+      ...blockedBy ? { blockedBy } : {}
     };
   });
   const neverHit = beats.filter((b) => b.reachedRuns === 0).length;
@@ -197194,9 +197468,16 @@ function renderCoverageText(report, sceneName = (id) => id) {
     out.push("");
     out.push(`${sceneName(scene)}${dead ? `  (${dead} never reached)` : ""}`);
     for (const b of beats) {
-      const mark = b.reachedRuns === 0 ? b.needsInput ? "? " : "\u203C " : "  ";
+      const mark = b.reachedRuns === 0 ? b.needsInput || b.blockedBy ? "? " : "\u203C " : "  ";
       const label = b.character ? `${b.character}: ${clip(b.preview)}` : clip(b.preview || `(${b.kind})`);
       out.push(`  ${mark}${b.reachPct.toFixed(0).padStart(3)}%  ${String(b.hits).padStart(6)}  ${label}`);
+      for (const bg of b.blockedBy ?? []) {
+        const names = bg.writers.map((w) => {
+          const target = report.beats.find((x) => x.id === w);
+          return target ? clip(target.preview || target.id, 28) : w;
+        });
+        out.push(`         gated on ${bg.ref}, written only by: ${names.join(", ")} (never played either)`);
+      }
     }
   }
   return out;
@@ -240535,6 +240816,44 @@ function writeTextFiles(files, encoding = "utf8") {
   return { success: results.every((r) => r.success), results };
 }
 
+// package.json
+var package_default = {
+  name: "@patterkit/cli",
+  version: "0.3.0",
+  description: "The `patter` CLI: validate, format, export, and play a Patter project.",
+  type: "module",
+  license: "MIT",
+  author: "Ian Thomas",
+  homepage: "https://patterkit.dev",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/patterkit/patter.git",
+    directory: "packages/cli"
+  },
+  bugs: "https://github.com/patterkit/patter/issues",
+  publishConfig: {
+    access: "public"
+  },
+  bin: {
+    patter: "./dist/cli.js"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  scripts: {
+    build: "tsup",
+    "build:standalone": "node scripts/build-standalone.mjs",
+    "build:standalone:mac": "node scripts/build-standalone.mjs --targets=darwin-arm64,darwin-x64",
+    "build:standalone:others": "node scripts/build-standalone.mjs --targets=linux-x64,linux-arm64,windows-x64"
+  },
+  dependencies: {
+    "@patterkit/core": "0.2.1",
+    "@patterkit/ops": "0.5.0",
+    "@wildwinter/simple-vc-lib": "^0.4.1"
+  }
+};
+
 // src/main.ts
 var isPatterSource = (path) => SHARD_EXTENSIONS.some((ext) => path.endsWith(ext));
 function writeMergeResult(result, out, announce) {
@@ -240554,6 +240873,8 @@ function writeMergeResult(result, out, announce) {
 var USAGE = `patter - Patter CLI
 
 Usage:
+  patter --version                Print the version (also -v / version)
+  patter --help                   Print this usage (also -h / help)
   patter init    [dir]            Scaffold a new project (the <dir>.patter folder, starter scene, VCS config)
                  [--name X] [--vcs git|perforce|plastic|svn] [--bundle commit|ignore]
   patter validate [path]          Validate a project (structural + expressions + encoding + bundle)
@@ -240671,6 +240992,14 @@ async function main(argv) {
     console.log(USAGE);
     return 0;
   }
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    console.log(package_default.version);
+    return 0;
+  }
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+    console.log(USAGE);
+    return 0;
+  }
   const canonical = cmd === "fmt" ? "format" : cmd === "stats" ? "report" : cmd;
   if (!(canonical in FLAGS)) {
     console.log(USAGE);
@@ -240757,7 +241086,7 @@ async function run(cmd, positionals, flags) {
     }
     case "validate": {
       const loaded = loadProject(positionals[0] ?? ".");
-      const { structural, conditions, interpolation, hygiene, staleBundles, unresolvedMerges, orphans, ok } = runValidate(loaded);
+      const { structural, conditions, interpolation, hygiene, staleBundles, unresolvedMerges, orphans, reachability, ok } = runValidate(loaded);
       for (const i of structural) console.error(`  [${i.code}] ${i.message}`);
       for (const i of conditions) console.error(`  [${i.field}] ${i.nodeId}: ${i.message}  (${i.src})`);
       for (const i of interpolation) console.error(`  [${i.field}] ${i.nodeId}: ${i.message}  (${i.src})`);
@@ -240765,8 +241094,10 @@ async function run(cmd, positionals, flags) {
       for (const i of staleBundles) console.error(`  [stale-bundle] ${i.file}: ${i.message}`);
       for (const i of unresolvedMerges) console.error(`  [unresolved-merge] ${i.file}: ${i.message}`);
       for (const i of orphans) console.error(`  [not-in-project] ${i.file}: ${i.message}`);
+      for (const i of reachability) console.error(`  [unreachable] ${i.nodeId}: ${i.message}  (${i.src})`);
       const count = structural.length + conditions.length + interpolation.length + hygiene.length + staleBundles.length + unresolvedMerges.length + orphans.length;
-      if (ok) console.log(`ok - ${loaded.scenes.length} scene(s), no issues`);
+      const advisory = reachability.length ? `, ${reachability.length} warning(s) above` : "";
+      if (ok) console.log(`ok - ${loaded.scenes.length} scene(s), no issues${advisory}`);
       else console.error(`
 ${count} issue(s)`);
       return ok ? 0 : 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/cli",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "The `patter` CLI: validate, format, export, and play a Patter project.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@patterkit/core": "0.2.1",
-    "@patterkit/ops": "0.4.0",
+    "@patterkit/ops": "0.5.0",
     "@wildwinter/simple-vc-lib": "^0.4.1"
   }
 }