@ansible-flow/node 0.0.0-stage → 0.85.0

package/dist/runner/devBundle.js

@@ -0,0 +1,78 @@
+// src/node/runner/devBundle.ts
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+var REF = "refs/afd-dev/run";
+function git(cwd, args, env = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      "git",
+      args,
+      {
+        cwd,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...env },
+        maxBuffer: 16 * 1024 * 1024,
+        timeout: 12e4,
+        windowsHide: true
+      },
+      (error, stdout, stderr) => error ? reject(new Error(stderr.trim().split("\n").at(-1) || error.message)) : resolve(stdout.trim())
+    );
+  });
+}
+async function devBundle(root, serverCommit) {
+  const dir = await mkdtemp(join(tmpdir(), "afd-dev-"));
+  try {
+    const head = await git(root, ["rev-parse", "HEAD"]);
+    const dirty = await git(root, ["status", "--porcelain", "--untracked-files=all"]) !== "";
+    let commit = head;
+    if (dirty) {
+      const env = { GIT_INDEX_FILE: join(dir, "index") };
+      await git(root, ["read-tree", "HEAD"], env);
+      await git(root, ["add", "-A"], env);
+      const tree = await git(root, ["write-tree"], env);
+      commit = await git(
+        root,
+        ["commit-tree", tree, "-p", head, "-m", "Work in progress: a dev run from VS Code"],
+        // The commit is the extension's, whoever has no git identity set up.
+        {
+          GIT_AUTHOR_NAME: "Ansible Flow Designer",
+          GIT_AUTHOR_EMAIL: "dev-run@ansible-flow.invalid",
+          GIT_COMMITTER_NAME: "Ansible Flow Designer",
+          GIT_COMMITTER_EMAIL: "dev-run@ansible-flow.invalid"
+        }
+      );
+    }
+    if (commit === serverCommit) return void 0;
+    const fromServer = await git(root, ["cat-file", "-e", `${serverCommit}^{commit}`]).then(
+      () => true,
+      () => false
+    );
+    const file = join(dir, "work.bundle");
+    await git(root, ["update-ref", REF, commit]);
+    try {
+      try {
+        await git(root, [
+          "bundle",
+          "create",
+          "--quiet",
+          file,
+          REF,
+          ...fromServer ? [`^${serverCommit}`] : []
+        ]);
+      } catch (e) {
+        if (!fromServer || !/empty bundle/i.test(e.message)) throw e;
+        await git(root, ["bundle", "create", "--quiet", file, REF]);
+      }
+    } finally {
+      await git(root, ["update-ref", "-d", REF]).catch(() => void 0);
+    }
+    return { commit, uncommitted: dirty, fromServer, bundle: await readFile(file) };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+export {
+  devBundle
+};
+//# sourceMappingURL=devBundle.js.map

package/dist/runner/devBundle.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/node/runner/devBundle.ts"],
+  "sourcesContent": ["// AFD-282: someone's unpushed work as a git bundle, for a dev run on Ansible Flow Server\n// (AFS-26). The work is HEAD, or, with uncommitted changes, a commit of the working tree made with\n// a temporary index: the user's index, working tree and branches are not touched. It is bundled\n// from the server's commit when this repository has it (the server has everything before it),\n// else with its whole history.\nimport { execFile } from 'node:child_process';\nimport { mkdtemp, readFile, rm } from 'node:fs/promises';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\n\nconst REF = 'refs/afd-dev/run';\n\nfunction git(cwd: string, args: string[], env: Record<string, string> = {}): Promise<string> {\n  return new Promise((resolve, reject) => {\n    execFile(\n      'git',\n      args,\n      {\n        cwd,\n        env: { ...process.env, GIT_TERMINAL_PROMPT: '0', ...env },\n        maxBuffer: 16 * 1024 * 1024,\n        timeout: 120_000,\n        windowsHide: true,\n      },\n      (error, stdout, stderr) =>\n        error\n          ? reject(new Error(stderr.trim().split('\\n').at(-1) || error.message))\n          : resolve(stdout.trim()),\n    );\n  });\n}\n\nexport interface DevWork {\n  /** The commit the bundle holds: HEAD, or the commit of the working tree. */\n  commit: string;\n  /** It has uncommitted changes in it. */\n  uncommitted: boolean;\n  /** Bundled from the server's commit (else the whole history). */\n  fromServer: boolean;\n  bundle: Buffer;\n}\n\n/**\n * The work in the repository at `root` as a bundle, or undefined when it is the server's commit\n * (nothing to send).\n */\nexport async function devBundle(root: string, serverCommit: string): Promise<DevWork | undefined> {\n  const dir = await mkdtemp(join(tmpdir(), 'afd-dev-'));\n  try {\n    const head = await git(root, ['rev-parse', 'HEAD']);\n    const dirty = (await git(root, ['status', '--porcelain', '--untracked-files=all'])) !== '';\n    let commit = head;\n    if (dirty) {\n      // A commit of everything as it is now (what `git add -A` would stage, ignored files left\n      // out), made with an index of its own.\n      const env = { GIT_INDEX_FILE: join(dir, 'index') };\n      await git(root, ['read-tree', 'HEAD'], env);\n      await git(root, ['add', '-A'], env);\n      const tree = await git(root, ['write-tree'], env);\n      commit = await git(\n        root,\n        ['commit-tree', tree, '-p', head, '-m', 'Work in progress: a dev run from VS Code'],\n        // The commit is the extension's, whoever has no git identity set up.\n        {\n          GIT_AUTHOR_NAME: 'Ansible Flow Designer',\n          GIT_AUTHOR_EMAIL: 'dev-run@ansible-flow.invalid',\n          GIT_COMMITTER_NAME: 'Ansible Flow Designer',\n          GIT_COMMITTER_EMAIL: 'dev-run@ansible-flow.invalid',\n        },\n      );\n    }\n    if (commit === serverCommit) return undefined;\n    const fromServer = await git(root, ['cat-file', '-e', `${serverCommit}^{commit}`]).then(\n      () => true,\n      () => false,\n    );\n    const file = join(dir, 'work.bundle');\n    await git(root, ['update-ref', REF, commit]);\n    try {\n      try {\n        await git(root, [\n          'bundle',\n          'create',\n          '--quiet',\n          file,\n          REF,\n          ...(fromServer ? [`^${serverCommit}`] : []),\n        ]);\n      } catch (e) {\n        // Nothing new since the server's commit (HEAD is behind it): the whole history, then.\n        if (!fromServer || !/empty bundle/i.test((e as Error).message)) throw e;\n        await git(root, ['bundle', 'create', '--quiet', file, REF]);\n      }\n    } finally {\n      await git(root, ['update-ref', '-d', REF]).catch(() => undefined);\n    }\n    return { commit, uncommitted: dirty, fromServer, bundle: await readFile(file) };\n  } finally {\n    await rm(dir, { recursive: true, force: true });\n  }\n}\n"],
+  "mappings": ";AAKA,SAAS,gBAAgB;AACzB,SAAS,SAAS,UAAU,UAAU;AACtC,SAAS,cAAc;AACvB,SAAS,YAAY;AAErB,IAAM,MAAM;AAEZ,SAAS,IAAI,KAAa,MAAgB,MAA8B,CAAC,GAAoB;AAC3F,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,QACE;AAAA,QACA,KAAK,EAAE,GAAG,QAAQ,KAAK,qBAAqB,KAAK,GAAG,IAAI;AAAA,QACxD,WAAW,KAAK,OAAO;AAAA,QACvB,SAAS;AAAA,QACT,aAAa;AAAA,MACf;AAAA,MACA,CAAC,OAAO,QAAQ,WACd,QACI,OAAO,IAAI,MAAM,OAAO,KAAK,EAAE,MAAM,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,OAAO,CAAC,IACnE,QAAQ,OAAO,KAAK,CAAC;AAAA,IAC7B;AAAA,EACF,CAAC;AACH;AAgBA,eAAsB,UAAU,MAAc,cAAoD;AAChG,QAAM,MAAM,MAAM,QAAQ,KAAK,OAAO,GAAG,UAAU,CAAC;AACpD,MAAI;AACF,UAAM,OAAO,MAAM,IAAI,MAAM,CAAC,aAAa,MAAM,CAAC;AAClD,UAAM,QAAS,MAAM,IAAI,MAAM,CAAC,UAAU,eAAe,uBAAuB,CAAC,MAAO;AACxF,QAAI,SAAS;AACb,QAAI,OAAO;AAGT,YAAM,MAAM,EAAE,gBAAgB,KAAK,KAAK,OAAO,EAAE;AACjD,YAAM,IAAI,MAAM,CAAC,aAAa,MAAM,GAAG,GAAG;AAC1C,YAAM,IAAI,MAAM,CAAC,OAAO,IAAI,GAAG,GAAG;AAClC,YAAM,OAAO,MAAM,IAAI,MAAM,CAAC,YAAY,GAAG,GAAG;AAChD,eAAS,MAAM;AAAA,QACb;AAAA,QACA,CAAC,eAAe,MAAM,MAAM,MAAM,MAAM,0CAA0C;AAAA;AAAA,QAElF;AAAA,UACE,iBAAiB;AAAA,UACjB,kBAAkB;AAAA,UAClB,oBAAoB;AAAA,UACpB,qBAAqB;AAAA,QACvB;AAAA,MACF;AAAA,IACF;AACA,QAAI,WAAW,aAAc,QAAO;AACpC,UAAM,aAAa,MAAM,IAAI,MAAM,CAAC,YAAY,MAAM,GAAG,YAAY,WAAW,CAAC,EAAE;AAAA,MACjF,MAAM;AAAA,MACN,MAAM;AAAA,IACR;AACA,UAAM,OAAO,KAAK,KAAK,aAAa;AACpC,UAAM,IAAI,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC;AAC3C,QAAI;AACF,UAAI;AACF,cAAM,IAAI,MAAM;AAAA,UACd;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA,GAAI,aAAa,CAAC,IAAI,YAAY,EAAE,IAAI,CAAC;AAAA,QAC3C,CAAC;AAAA,MACH,SAAS,GAAG;AAEV,YAAI,CAAC,cAAc,CAAC,gBAAgB,KAAM,EAAY,OAAO,EAAG,OAAM;AACtE,cAAM,IAAI,MAAM,CAAC,UAAU,UAAU,WAAW,MAAM,GAAG,CAAC;AAAA,MAC5D;AAAA,IACF,UAAE;AACA,YAAM,IAAI,MAAM,CAAC,cAAc,MAAM,GAAG,CAAC,EAAE,MAAM,MAAM,MAAS;AAAA,IAClE;AACA,WAAO,EAAE,QAAQ,aAAa,OAAO,YAAY,QAAQ,MAAM,SAAS,IAAI,EAAE;AAAA,EAChF,UAAE;AACA,UAAM,GAAG,KAAK,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAAA,EAChD;AACF;",
+  "names": []
+}

package/dist/scenario/cli.d.ts

@@ -0,0 +1,39 @@
+import type { FlowDocument } from '@ansible-flow/core/flow/types';
+import { type ScenarioFile, type ScenarioProblem } from '@ansible-flow/core/scenario/scenarios';
+export declare const USAGE: string;
+export interface CliOptions {
+    targets: string[];
+    image?: string;
+    engine?: 'docker' | 'podman';
+    python?: string;
+    junit?: string;
+    /** AFD-118: run in WSL from Windows; the distribution, or '' for the default one. */
+    wsl?: string;
+    only?: string[];
+    keep: boolean;
+    verbose: boolean;
+    simulate: boolean;
+    check: boolean;
+    help: boolean;
+    /** An option this command does not know, or one without its value. */
+    error?: string;
+}
+export declare function parseCliArgs(args: readonly string[]): CliOptions;
+/** Flow files: the ones named, and every *.flow.yaml under the folders named. */
+export declare function flowsOf(target: string): string[];
+export interface FlowScenarios {
+    flowFile: string;
+    scenariosFile: string;
+    doc: FlowDocument;
+    file?: ScenarioFile;
+    /** The file does not read as scenarios. */
+    error?: string;
+    problems: ScenarioProblem[];
+}
+/** The flows under the targets that have a scenarios file, read and checked. */
+export declare function loadScenarioFlows(targets: readonly string[]): FlowScenarios[];
+/** One line per problem: FAIL for errors, WARN for warnings (they do not stop a run). */
+export declare function problemLines(f: FlowScenarios): string[];
+/** The scenarios of one flow, computed by the simulator. */
+export declare function simulateFlow(f: FlowScenarios, only?: readonly string[]): import("@ansible-flow/core/scenario/scenarios").ScenarioResult[];
+export declare const NO_SCENARIOS = "No scenarios found: a flow has them in <flow key>.scenarios.yaml next to its .flow.yaml";

package/dist/scenario/cli.js

@@ -0,0 +1,125 @@
+// src/node/scenario/cli.ts
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseFlow } from "@ansible-flow/core/flow/document";
+import { isFileKey } from "@ansible-flow/core/flow/ids";
+import {
+  checkScenarios,
+  parseScenarios,
+  scenariosFileName
+} from "@ansible-flow/core/scenario/scenarios";
+import { simulateScenario } from "@ansible-flow/core/scenario/simulate";
+var USAGE = [
+  "Usage: node afd-scenarios.js [options] <flow.yaml|folder>...",
+  "",
+  "Runs the scenarios in <flow key>.scenarios.yaml next to each flow; exits 1 when one fails.",
+  "",
+  "  --simulate           compute where each host goes, without Ansible (instant); a scenario",
+  "                       the simulator cannot model is skipped: verify it with a run",
+  "  --check              only check the scenario files against their flows",
+  "  --image IMAGE        run in this execution environment image (Docker or Podman)",
+  "  --engine docker|podman",
+  "  --python PATH        run with ansible-playbook on this machine (default: python3)",
+  "  --wsl                run in WSL from Windows (the default distribution)",
+  "  --wsl-distro NAME    run in this WSL distribution",
+  "  --scenario NAME      run only this scenario (repeatable)",
+  "  --junit FILE         write JUnit XML for CI dashboards",
+  "  --keep               keep each run folder",
+  "  --verbose            print Ansible output"
+].join("\n");
+var WITH_VALUE = /* @__PURE__ */ new Set([
+  "--image",
+  "--engine",
+  "--python",
+  "--junit",
+  "--scenario",
+  "--wsl-distro"
+]);
+var SWITCHES = /* @__PURE__ */ new Set(["--keep", "--verbose", "--simulate", "--check", "--help", "--wsl"]);
+function parseCliArgs(args) {
+  const o = {
+    targets: [],
+    keep: false,
+    verbose: false,
+    simulate: false,
+    check: false,
+    help: false
+  };
+  const only = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (WITH_VALUE.has(a)) {
+      const v = args[++i];
+      if (v === void 0 || v.startsWith("--")) o.error ??= `${a} needs a value`;
+      else if (a === "--image") o.image = v;
+      else if (a === "--engine") {
+        if (v === "docker" || v === "podman") o.engine = v;
+        else o.error ??= `--engine takes docker or podman, not ${v}`;
+      } else if (a === "--python") o.python = v;
+      else if (a === "--junit") o.junit = v;
+      else if (a === "--wsl-distro") o.wsl = v;
+      else only.push(v);
+    } else if (SWITCHES.has(a)) {
+      if (a === "--keep") o.keep = true;
+      if (a === "--verbose") o.verbose = true;
+      if (a === "--simulate") o.simulate = true;
+      if (a === "--check") o.check = true;
+      if (a === "--help") o.help = true;
+      if (a === "--wsl") o.wsl ??= "";
+    } else if (a.startsWith("--")) o.error ??= `Unknown option ${a}`;
+    else o.targets.push(a);
+  }
+  if (only.length) o.only = only;
+  if (o.simulate && o.check) o.error ??= "Give --simulate or --check, not both";
+  if (o.wsl !== void 0 && o.image) o.error ??= "Give --wsl or --image, not both";
+  return o;
+}
+function flowsOf(target) {
+  if (!statSync(target).isDirectory()) return [target];
+  return readdirSync(target, { recursive: true, encoding: "utf8" }).filter((f) => f.endsWith(".flow.yaml") && !f.includes("node_modules")).map((f) => join(target, f));
+}
+function loadScenarioFlows(targets) {
+  const out = [];
+  for (const flowFile of targets.flatMap(flowsOf)) {
+    const doc = parseFlow(readFileSync(flowFile, "utf8")).doc;
+    if (!doc) continue;
+    if (!isFileKey(doc?.flow?.key)) continue;
+    const scenariosFile = join(dirname(flowFile), scenariosFileName(doc.flow.key));
+    if (!existsSync(scenariosFile)) continue;
+    try {
+      const parsed = parseScenarios(readFileSync(scenariosFile, "utf8"));
+      out.push({
+        flowFile,
+        scenariosFile,
+        doc,
+        file: parsed.file,
+        error: parsed.error,
+        problems: parsed.file ? checkScenarios(doc, parsed.file) : []
+      });
+    } catch (e) {
+      out.push({ flowFile, scenariosFile, doc, error: e.message, problems: [] });
+    }
+  }
+  return out;
+}
+function problemLines(f) {
+  if (f.error) return [`FAIL ${f.scenariosFile}: ${f.error}`];
+  return f.problems.map((p) => {
+    const where = p.scenario >= 0 ? ` [${f.file?.scenarios[p.scenario]?.name ?? p.scenario}]` : "";
+    return `${p.severity === "warning" ? "WARN" : "FAIL"} ${f.scenariosFile}${where}: ${p.message}`;
+  });
+}
+function simulateFlow(f, only) {
+  return (f.file?.scenarios ?? []).filter((s) => !only || only.includes(s.name)).map((s) => simulateScenario(f.doc, s));
+}
+var NO_SCENARIOS = "No scenarios found: a flow has them in <flow key>.scenarios.yaml next to its .flow.yaml";
+export {
+  NO_SCENARIOS,
+  USAGE,
+  flowsOf,
+  loadScenarioFlows,
+  parseCliArgs,
+  problemLines,
+  simulateFlow
+};
+//# sourceMappingURL=cli.js.map

package/dist/scenario/cli.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/node/scenario/cli.ts"],
+  "sourcesContent": ["// The scenario command line (AFD-58, AFD-114), apart from its entry file so it can be tested:\n// arguments, the flows with scenarios under the paths named, and the two modes that need no Ansible,\n// --check (the files against their flows) and --simulate (where each host goes, computed).\nimport { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { parseFlow } from '../../core/flow/document';\nimport { isFileKey } from '../../core/flow/ids';\nimport type { FlowDocument } from '../../core/flow/types';\nimport {\n  checkScenarios,\n  parseScenarios,\n  type ScenarioFile,\n  type ScenarioProblem,\n  scenariosFileName,\n} from '../../core/scenario/scenarios';\nimport { simulateScenario } from '../../core/scenario/simulate';\n\nexport const USAGE = [\n  'Usage: node afd-scenarios.js [options] <flow.yaml|folder>...',\n  '',\n  'Runs the scenarios in <flow key>.scenarios.yaml next to each flow; exits 1 when one fails.',\n  '',\n  '  --simulate           compute where each host goes, without Ansible (instant); a scenario',\n  '                       the simulator cannot model is skipped: verify it with a run',\n  '  --check              only check the scenario files against their flows',\n  '  --image IMAGE        run in this execution environment image (Docker or Podman)',\n  '  --engine docker|podman',\n  '  --python PATH        run with ansible-playbook on this machine (default: python3)',\n  '  --wsl                run in WSL from Windows (the default distribution)',\n  '  --wsl-distro NAME    run in this WSL distribution',\n  '  --scenario NAME      run only this scenario (repeatable)',\n  '  --junit FILE         write JUnit XML for CI dashboards',\n  '  --keep               keep each run folder',\n  '  --verbose            print Ansible output',\n].join('\\n');\n\nexport interface CliOptions {\n  targets: string[];\n  image?: string;\n  engine?: 'docker' | 'podman';\n  python?: string;\n  junit?: string;\n  /** AFD-118: run in WSL from Windows; the distribution, or '' for the default one. */\n  wsl?: string;\n  only?: string[];\n  keep: boolean;\n  verbose: boolean;\n  simulate: boolean;\n  check: boolean;\n  help: boolean;\n  /** An option this command does not know, or one without its value. */\n  error?: string;\n}\n\nconst WITH_VALUE = new Set([\n  '--image',\n  '--engine',\n  '--python',\n  '--junit',\n  '--scenario',\n  '--wsl-distro',\n]);\nconst SWITCHES = new Set(['--keep', '--verbose', '--simulate', '--check', '--help', '--wsl']);\n\nexport function parseCliArgs(args: readonly string[]): CliOptions {\n  const o: CliOptions = {\n    targets: [],\n    keep: false,\n    verbose: false,\n    simulate: false,\n    check: false,\n    help: false,\n  };\n  const only: string[] = [];\n  for (let i = 0; i < args.length; i++) {\n    const a = args[i] as string;\n    if (WITH_VALUE.has(a)) {\n      const v = args[++i];\n      if (v === undefined || v.startsWith('--')) o.error ??= `${a} needs a value`;\n      else if (a === '--image') o.image = v;\n      else if (a === '--engine') {\n        if (v === 'docker' || v === 'podman') o.engine = v;\n        else o.error ??= `--engine takes docker or podman, not ${v}`;\n      } else if (a === '--python') o.python = v;\n      else if (a === '--junit') o.junit = v;\n      else if (a === '--wsl-distro') o.wsl = v;\n      else only.push(v);\n    } else if (SWITCHES.has(a)) {\n      if (a === '--keep') o.keep = true;\n      if (a === '--verbose') o.verbose = true;\n      if (a === '--simulate') o.simulate = true;\n      if (a === '--check') o.check = true;\n      if (a === '--help') o.help = true;\n      if (a === '--wsl') o.wsl ??= '';\n    } else if (a.startsWith('--')) o.error ??= `Unknown option ${a}`;\n    else o.targets.push(a);\n  }\n  if (only.length) o.only = only;\n  if (o.simulate && o.check) o.error ??= 'Give --simulate or --check, not both';\n  if (o.wsl !== undefined && o.image) o.error ??= 'Give --wsl or --image, not both';\n  return o;\n}\n\n/** Flow files: the ones named, and every *.flow.yaml under the folders named. */\nexport function flowsOf(target: string): string[] {\n  if (!statSync(target).isDirectory()) return [target];\n  return readdirSync(target, { recursive: true, encoding: 'utf8' })\n    .filter((f) => f.endsWith('.flow.yaml') && !f.includes('node_modules'))\n    .map((f) => join(target, f));\n}\n\nexport interface FlowScenarios {\n  flowFile: string;\n  scenariosFile: string;\n  doc: FlowDocument;\n  file?: ScenarioFile;\n  /** The file does not read as scenarios. */\n  error?: string;\n  problems: ScenarioProblem[];\n}\n\n/** The flows under the targets that have a scenarios file, read and checked. */\nexport function loadScenarioFlows(targets: readonly string[]): FlowScenarios[] {\n  const out: FlowScenarios[] = [];\n  for (const flowFile of targets.flatMap(flowsOf)) {\n    // AFD-147: a flow that does not read (an alias inside what it names, too) has no scenarios.\n    const doc = parseFlow(readFileSync(flowFile, 'utf8')).doc;\n    if (!doc) continue;\n    // AFD-133: a key that cannot name a file names no scenarios file either.\n    if (!isFileKey(doc?.flow?.key)) continue;\n    const scenariosFile = join(dirname(flowFile), scenariosFileName(doc.flow.key));\n    if (!existsSync(scenariosFile)) continue;\n    // AFD-159: a scenarios file that does not read or check fails alone, as a FAIL line.\n    try {\n      const parsed = parseScenarios(readFileSync(scenariosFile, 'utf8'));\n      out.push({\n        flowFile,\n        scenariosFile,\n        doc,\n        file: parsed.file,\n        error: parsed.error,\n        problems: parsed.file ? checkScenarios(doc, parsed.file) : [],\n      });\n    } catch (e) {\n      out.push({ flowFile, scenariosFile, doc, error: (e as Error).message, problems: [] });\n    }\n  }\n  return out;\n}\n\n/** One line per problem: FAIL for errors, WARN for warnings (they do not stop a run). */\nexport function problemLines(f: FlowScenarios): string[] {\n  if (f.error) return [`FAIL ${f.scenariosFile}: ${f.error}`];\n  return f.problems.map((p) => {\n    const where = p.scenario >= 0 ? ` [${f.file?.scenarios[p.scenario]?.name ?? p.scenario}]` : '';\n    return `${p.severity === 'warning' ? 'WARN' : 'FAIL'} ${f.scenariosFile}${where}: ${p.message}`;\n  });\n}\n\n/** The scenarios of one flow, computed by the simulator. */\nexport function simulateFlow(f: FlowScenarios, only?: readonly string[]) {\n  return (f.file?.scenarios ?? [])\n    .filter((s) => !only || only.includes(s.name))\n    .map((s) => simulateScenario(f.doc, s));\n}\n\nexport const NO_SCENARIOS =\n  'No scenarios found: a flow has them in <flow key>.scenarios.yaml next to its .flow.yaml';\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/scenario/runner.d.ts

@@ -0,0 +1,50 @@
+import type { GenerateResult } from '@ansible-flow/core/engine/types';
+import type { FlowDocument } from '@ansible-flow/core/flow/types';
+import type { Environment } from '@ansible-flow/core/run/environment';
+import { type Scenario, type ScenarioFile, type ScenarioResult } from '@ansible-flow/core/scenario/scenarios';
+export interface ScenarioRunOptions {
+    env: Environment;
+    /** Repository root on this machine (mounted read-only in a container). */
+    root: string;
+    /** Folder with callback_plugins/afd_events.py. */
+    probeDir: string;
+    flowFile: string;
+    doc: FlowDocument;
+    file: ScenarioFile;
+    /** Where each scenario's folder is made; removed afterwards unless `keep`. */
+    workDir: string;
+    only?: readonly string[];
+    keep?: boolean;
+    timeoutMs?: number;
+    log?: (line: string) => void;
+    signal?: AbortSignal;
+}
+/**
+ * A scenario's folder: the scenario build of the flow, its extra vars and inventory (AFD-114: the
+ * simulator's parity suite stages many into one container). Undefined when the flow does not
+ * generate.
+ */
+export declare function stageScenario(doc: FlowDocument, s: Scenario, dir: string, source: string): GenerateResult | undefined;
+export declare function runScenarios(o: ScenarioRunOptions): Promise<ScenarioResult[]>;
+/**
+ * A one-line verdict per scenario, and the hosts that ended elsewhere. With the flow at hand, the
+ * ends by their titles with the keys a scenario file uses in brackets (AFD-94). AFD-105: in the
+ * panel's wording, with why when the scenario planted the host's outcome.
+ */
+export declare function describeResults(results: readonly ScenarioResult[], doc?: FlowDocument): string[];
+/**
+ * AFD-114: a simulated scenario that has what the simulator does not model is not judged on the
+ * command line: its verdict is a best effort, so CI skips it rather than pass or fail on a guess.
+ */
+export declare const skipped: (r: ScenarioResult) => boolean;
+/** Scenarios that failed, leaving out the skipped. */
+export declare const failedCount: (results: readonly ScenarioResult[]) => number;
+/** One flow's scenarios as a JUnit `<testsuite>`. */
+export declare function junitSuite(flow: string, results: readonly ScenarioResult[], doc?: FlowDocument): string;
+/**
+ * A JUnit file of several flows' suites under one root (AFD-158: one document per flow, joined,
+ * was not XML once there were two flows).
+ */
+export declare function junitDocument(suites: readonly string[]): string;
+/** One flow's scenarios as a whole JUnit file. */
+export declare function junitXml(flow: string, results: readonly ScenarioResult[], doc?: FlowDocument): string;

package/dist/scenario/runner.js

@@ -0,0 +1,185 @@
+import {
+  fetchRunFile,
+  putRunFolder,
+  removeRunDir,
+  syncWorkspace
+} from "../chunks/chunk-RETJPSKL.js";
+import "../chunks/chunk-THNSGAKN.js";
+import "../chunks/chunk-FG53MLUX.js";
+import {
+  stopStarted
+} from "../chunks/chunk-JDPN3LTT.js";
+import {
+  startProcess
+} from "../chunks/chunk-I6FIOP7G.js";
+
+// src/node/scenario/runner.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { engineFor } from "@ansible-flow/core/engine/engines";
+import { insidePaths, runProcess } from "@ansible-flow/core/run/command";
+import { summarizeRun } from "@ansible-flow/core/run/events";
+import {
+  judge,
+  scenarioInventory,
+  scenarioVars
+} from "@ansible-flow/core/scenario/scenarios";
+import { missWhy } from "@ansible-flow/core/scenario/view";
+var EVENTS = "events";
+var slug = (name) => String(name ?? "").toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/^-|-$/g, "").slice(0, 40) || "scenario";
+async function exec(spec, log, timeoutMs, signal) {
+  const started = startProcess(spec, spec.env, log);
+  const stop = () => {
+    started.terminate();
+    void stopStarted(spec);
+  };
+  const timer = setTimeout(stop, timeoutMs);
+  signal?.addEventListener("abort", stop, { once: true });
+  const code = await started.exit;
+  clearTimeout(timer);
+  signal?.removeEventListener("abort", stop);
+  return code ?? null;
+}
+function stageScenario(doc, s, dir, source) {
+  const generated = engineFor(doc).generate(doc, { source, simulate: true, stubAll: true });
+  if (!generated.ok || generated.files.length === 0) return void 0;
+  for (const f of generated.files) writeFileSync(join(dir, f.name), f.text);
+  writeFileSync(join(dir, "vars.json"), JSON.stringify(scenarioVars(s), null, 2));
+  writeFileSync(join(dir, "inventory.ini"), scenarioInventory(doc, s));
+  writeFileSync(join(dir, "ansible.cfg"), "");
+  return generated;
+}
+async function runOne(o, s, index, log) {
+  const dir = join(o.workDir, `${index + 1}-${slug(s.name)}`);
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const shared = o.env.kind === "container";
+  const ssh = o.env.kind === "ssh" ? o.env : void 0;
+  const eventsDir = shared || ssh?.container ? EVENTS : void 0;
+  chmodSync(dir, shared ? 493 : 448);
+  if (shared) {
+    mkdirSync(join(dir, EVENTS));
+    chmodSync(join(dir, EVENTS), 1023);
+  }
+  try {
+    const generated = stageScenario(o.doc, s, dir, basename(o.flowFile));
+    if (!generated)
+      return judge(o.doc, s, void 0, "The flow does not generate: fix its errors first");
+    if (ssh) {
+      const failed = await syncWorkspace(ssh, { root: o.root, probe: o.probeDir }) ?? await putRunFolder(ssh, dir, eventsDir);
+      if (failed) return judge(o.doc, s, void 0, failed);
+    }
+    const inside = o.env.kind === "local" ? dir.replaceAll("\\", "/") : insidePaths(o.env, { root: o.root, probe: o.probeDir, run: dir }).run ?? dir;
+    const at = (name) => `${inside}/${name}`;
+    const spec = runProcess(
+      o.env,
+      { root: o.root, probe: o.probeDir },
+      {
+        playbook: at(generated.files[0]?.name),
+        inventory: at("inventory.ini"),
+        check: false,
+        runDir: dir,
+        vault: false,
+        // The scenario build runs no binding: the repository's ansible.cfg has nothing to say,
+        // and the empty one written above keeps it from loading from the working directory.
+        hasConfig: false,
+        emptyConfig: true,
+        eventsDir
+      },
+      `afd-scenario-${Date.now().toString(36)}-${index}`
+    );
+    const rc = await exec(spec, log, o.timeoutMs ?? 3e5, o.signal);
+    const events = join(dir, eventsDir ?? "", "events.jsonl");
+    if (ssh) {
+      await fetchRunFile(ssh, dir, `${eventsDir ? `${eventsDir}/` : ""}events.jsonl`, events);
+      await removeRunDir(ssh, dir);
+    }
+    const text = existsSync(events) ? readFileSync(events, "utf8") : "";
+    if (o.signal?.aborted) return judge(o.doc, s, void 0, "Cancelled");
+    if (!text.trim() || rc === null || ![0, 2, 4].includes(rc))
+      return {
+        ...judge(
+          o.doc,
+          s,
+          text.trim() ? summarizeRun(text, generated.routes) : void 0,
+          `ansible-playbook ended with ${rc ?? "an error"}${text.trim() ? "" : " before any routing event"}`
+        ),
+        engine: "ansible"
+      };
+    return { ...judge(o.doc, s, summarizeRun(text, generated.routes)), engine: "ansible" };
+  } catch (e) {
+    return judge(o.doc, s, void 0, e.message);
+  } finally {
+    if (!o.keep) rmSync(dir, { recursive: true, force: true });
+  }
+}
+async function runScenarios(o) {
+  const log = o.log ?? (() => void 0);
+  const results = [];
+  for (const [i, s] of o.file.scenarios.entries()) {
+    if (!s || typeof s !== "object") continue;
+    if (o.only && !o.only.includes(s.name)) continue;
+    if (o.signal?.aborted) break;
+    log(`# Scenario: ${s.name}`);
+    results.push(await runOne(o, s, i, log));
+  }
+  return results;
+}
+function describeResults(results, doc) {
+  const out = [];
+  for (const r of results) {
+    if (skipped(r)) {
+      out.push(`SKIP ${r.name}: the simulator does not model this; verify it with a run`);
+      for (const u of r.needsAnsible ?? []) out.push(`  ${u.message}`);
+      continue;
+    }
+    const how = r.engine === "simulated" ? " (simulated)" : "";
+    out.push(`${r.passed ? "PASS" : "FAIL"} ${r.name}${how}${r.error ? `: ${r.error}` : ""}`);
+    for (const h of r.hosts)
+      if (h.expected !== h.actual) out.push(`  ${missWhy(doc, h, r.forced, true)}`);
+  }
+  return out;
+}
+var skipped = (r) => r.engine === "simulated" && (r.needsAnsible?.length ?? 0) > 0;
+var failedCount = (results) => results.filter((r) => !r.passed && !skipped(r)).length;
+var XML_FORBIDDEN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/g;
+var esc = (t) => t.replaceAll(XML_FORBIDDEN, "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+function junitSuite(flow, results, doc) {
+  const failures = failedCount(results);
+  const skips = results.filter(skipped).length;
+  const cases = results.map((r) => {
+    if (skipped(r))
+      return `    <testcase classname="${esc(flow)}" name="${esc(r.name)}"><skipped message="${esc(`Verify with a run: ${(r.needsAnsible ?? []).map((u) => u.message).join("; ")}`)}"/></testcase>`;
+    if (r.passed) return `    <testcase classname="${esc(flow)}" name="${esc(r.name)}"/>`;
+    const text = describeResults([r], doc).join("\n");
+    return `    <testcase classname="${esc(flow)}" name="${esc(r.name)}"><failure message="${esc(r.error ?? "hosts ended elsewhere")}">${esc(text)}</failure></testcase>`;
+  });
+  return [
+    `  <testsuite name="${esc(flow)}" tests="${results.length}" failures="${failures}"${skips ? ` skipped="${skips}"` : ""}>`,
+    ...cases,
+    "  </testsuite>"
+  ].join("\n");
+}
+function junitDocument(suites) {
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    "<testsuites>",
+    ...suites,
+    "</testsuites>",
+    ""
+  ].join("\n");
+}
+function junitXml(flow, results, doc) {
+  return junitDocument([junitSuite(flow, results, doc)]);
+}
+export {
+  describeResults,
+  failedCount,
+  junitDocument,
+  junitSuite,
+  junitXml,
+  runScenarios,
+  skipped,
+  stageScenario
+};
+//# sourceMappingURL=runner.js.map

package/dist/scenario/runner.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/node/scenario/runner.ts"],
+  "sourcesContent": ["// Runs a flow's scenarios (AFD-58) for the designer and the CI command line alike: per scenario, the\n// SCENARIO build of the flow (every step as its stub), a local-connection inventory and the extra\n// vars go into a folder of their own; ansible-playbook runs in the environment as any run does\n// (runProcess), and its routing events say where each host ended.\nimport { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';\nimport { basename, join } from 'node:path';\nimport { engineFor } from '../../core/engine/engines';\nimport type { GenerateResult } from '../../core/engine/types';\nimport type { FlowDocument } from '../../core/flow/types';\nimport { insidePaths, type ProcessSpec, runProcess } from '../../core/run/command';\nimport type { Environment } from '../../core/run/environment';\nimport { summarizeRun } from '../../core/run/events';\nimport {\n  judge,\n  type Scenario,\n  type ScenarioFile,\n  type ScenarioResult,\n  scenarioInventory,\n  scenarioVars,\n} from '../../core/scenario/scenarios';\nimport { missWhy } from '../../core/scenario/view';\nimport { startProcess } from '../run/exec';\nimport { stopStarted } from '../run/stop';\nimport { fetchRunFile, putRunFolder, removeRunDir, syncWorkspace } from '../ssh/remote';\n\nexport interface ScenarioRunOptions {\n  env: Environment;\n  /** Repository root on this machine (mounted read-only in a container). */\n  root: string;\n  /** Folder with callback_plugins/afd_events.py. */\n  probeDir: string;\n  flowFile: string;\n  doc: FlowDocument;\n  file: ScenarioFile;\n  /** Where each scenario's folder is made; removed afterwards unless `keep`. */\n  workDir: string;\n  only?: readonly string[];\n  keep?: boolean;\n  timeoutMs?: number;\n  log?: (line: string) => void;\n  signal?: AbortSignal;\n}\n\n/** The folder an EE image writes the events into, inside a scenario's folder (AFD-159). */\nconst EVENTS = 'events';\n\n/** AFD-159: a name that is not text (a number, nothing) still names a folder. */\nconst slug = (name: unknown) =>\n  String(name ?? '')\n    .toLowerCase()\n    .replaceAll(/[^a-z0-9]+/g, '-')\n    .replaceAll(/^-|-$/g, '')\n    .slice(0, 40) || 'scenario';\n\n/** Runs one process to its end, feeding its output to `log`; resolves with the exit code. */\nasync function exec(\n  spec: ProcessSpec,\n  log: (line: string) => void,\n  timeoutMs: number,\n  signal?: AbortSignal,\n): Promise<number | null> {\n  const started = startProcess(spec, spec.env, log);\n  // Killing the client leaves a container or a WSL process running; spec.stop ends those.\n  const stop = () => {\n    started.terminate();\n    void stopStarted(spec);\n  };\n  const timer = setTimeout(stop, timeoutMs);\n  signal?.addEventListener('abort', stop, { once: true });\n  const code = await started.exit;\n  clearTimeout(timer);\n  signal?.removeEventListener('abort', stop);\n  return code ?? null;\n}\n\n/**\n * A scenario's folder: the scenario build of the flow, its extra vars and inventory (AFD-114: the\n * simulator's parity suite stages many into one container). Undefined when the flow does not\n * generate.\n */\nexport function stageScenario(\n  doc: FlowDocument,\n  s: Scenario,\n  dir: string,\n  source: string,\n): GenerateResult | undefined {\n  const generated = engineFor(doc).generate(doc, { source, simulate: true, stubAll: true });\n  if (!generated.ok || generated.files.length === 0) return undefined;\n  for (const f of generated.files) writeFileSync(join(dir, f.name), f.text);\n  writeFileSync(join(dir, 'vars.json'), JSON.stringify(scenarioVars(s), null, 2));\n  writeFileSync(join(dir, 'inventory.ini'), scenarioInventory(doc, s));\n  // AFD-126: ANSIBLE_CONFIG points here, so no ansible.cfg of the repository or the user applies.\n  writeFileSync(join(dir, 'ansible.cfg'), '');\n  return generated;\n}\n\nasync function runOne(\n  o: ScenarioRunOptions,\n  s: Scenario,\n  index: number,\n  log: (line: string) => void,\n): Promise<ScenarioResult> {\n  const dir = join(o.workDir, `${index + 1}-${slug(s.name)}`);\n  rmSync(dir, { recursive: true, force: true });\n  mkdirSync(dir, { recursive: true });\n  // AFD-159: Ansible loads plugins, group_vars and host_vars from beside the playbook and the\n  // inventory, so no other user may write here (0777 let one swap them in on a shared CI host).\n  // An EE image runs as a user of its own, which only reads here and writes the events into\n  // EVENTS, open to all and sticky: nothing in it is loaded.\n  const shared = o.env.kind === 'container';\n  // AFD-247: an SSH host runs a copy of this folder; in an image there, the events folder too.\n  const ssh = o.env.kind === 'ssh' ? o.env : undefined;\n  const eventsDir = shared || ssh?.container ? EVENTS : undefined;\n  chmodSync(dir, shared ? 0o755 : 0o700);\n  if (shared) {\n    mkdirSync(join(dir, EVENTS));\n    chmodSync(join(dir, EVENTS), 0o1777);\n  }\n  try {\n    const generated = stageScenario(o.doc, s, dir, basename(o.flowFile));\n    if (!generated)\n      return judge(o.doc, s, undefined, 'The flow does not generate: fix its errors first');\n    if (ssh) {\n      const failed =\n        (await syncWorkspace(ssh, { root: o.root, probe: o.probeDir })) ??\n        (await putRunFolder(ssh, dir, eventsDir));\n      if (failed) return judge(o.doc, s, undefined, failed);\n    }\n    const inside =\n      o.env.kind === 'local'\n        ? dir.replaceAll('\\\\', '/')\n        : (insidePaths(o.env, { root: o.root, probe: o.probeDir, run: dir }).run ?? dir);\n    const at = (name: string) => `${inside}/${name}`;\n    const spec = runProcess(\n      o.env,\n      { root: o.root, probe: o.probeDir },\n      {\n        playbook: at(generated.files[0]?.name as string),\n        inventory: at('inventory.ini'),\n        check: false,\n        runDir: dir,\n        vault: false,\n        // The scenario build runs no binding: the repository's ansible.cfg has nothing to say,\n        // and the empty one written above keeps it from loading from the working directory.\n        hasConfig: false,\n        emptyConfig: true,\n        eventsDir,\n      },\n      `afd-scenario-${Date.now().toString(36)}-${index}`,\n    );\n    const rc = await exec(spec, log, o.timeoutMs ?? 300_000, o.signal);\n    const events = join(dir, eventsDir ?? '', 'events.jsonl');\n    if (ssh) {\n      await fetchRunFile(ssh, dir, `${eventsDir ? `${eventsDir}/` : ''}events.jsonl`, events);\n      await removeRunDir(ssh, dir);\n    }\n    const text = existsSync(events) ? readFileSync(events, 'utf8') : '';\n    if (o.signal?.aborted) return judge(o.doc, s, undefined, 'Cancelled');\n    // 2: hosts failed in the outcome play, as a scenario with failures expects.\n    if (!text.trim() || rc === null || ![0, 2, 4].includes(rc))\n      return {\n        ...judge(\n          o.doc,\n          s,\n          text.trim() ? summarizeRun(text, generated.routes) : undefined,\n          `ansible-playbook ended with ${rc ?? 'an error'}${text.trim() ? '' : ' before any routing event'}`,\n        ),\n        engine: 'ansible',\n      };\n    return { ...judge(o.doc, s, summarizeRun(text, generated.routes)), engine: 'ansible' };\n  } catch (e) {\n    // AFD-159: a scenario that cannot be staged fails alone; the others still run.\n    return judge(o.doc, s, undefined, (e as Error).message);\n  } finally {\n    if (!o.keep) rmSync(dir, { recursive: true, force: true });\n  }\n}\n\nexport async function runScenarios(o: ScenarioRunOptions): Promise<ScenarioResult[]> {\n  const log = o.log ?? (() => undefined);\n  const results: ScenarioResult[] = [];\n  for (const [i, s] of o.file.scenarios.entries()) {\n    // AFD-159: checkScenarios reports an entry that is no map; a run without the check skips it.\n    if (!s || typeof s !== 'object') continue;\n    if (o.only && !o.only.includes(s.name)) continue;\n    if (o.signal?.aborted) break;\n    log(`# Scenario: ${s.name}`);\n    results.push(await runOne(o, s, i, log));\n  }\n  return results;\n}\n\n/**\n * A one-line verdict per scenario, and the hosts that ended elsewhere. With the flow at hand, the\n * ends by their titles with the keys a scenario file uses in brackets (AFD-94). AFD-105: in the\n * panel's wording, with why when the scenario planted the host's outcome.\n */\nexport function describeResults(results: readonly ScenarioResult[], doc?: FlowDocument): string[] {\n  const out: string[] = [];\n  for (const r of results) {\n    if (skipped(r)) {\n      out.push(`SKIP ${r.name}: the simulator does not model this; verify it with a run`);\n      for (const u of r.needsAnsible ?? []) out.push(`  ${u.message}`);\n      continue;\n    }\n    const how = r.engine === 'simulated' ? ' (simulated)' : '';\n    out.push(`${r.passed ? 'PASS' : 'FAIL'} ${r.name}${how}${r.error ? `: ${r.error}` : ''}`);\n    for (const h of r.hosts)\n      if (h.expected !== h.actual) out.push(`  ${missWhy(doc, h, r.forced, true)}`);\n  }\n  return out;\n}\n\n/**\n * AFD-114: a simulated scenario that has what the simulator does not model is not judged on the\n * command line: its verdict is a best effort, so CI skips it rather than pass or fail on a guess.\n */\nexport const skipped = (r: ScenarioResult) =>\n  r.engine === 'simulated' && (r.needsAnsible?.length ?? 0) > 0;\n\n/** Scenarios that failed, leaving out the skipped. */\nexport const failedCount = (results: readonly ScenarioResult[]) =>\n  results.filter((r) => !r.passed && !skipped(r)).length;\n\n/** JUnit XML for CI dashboards: one test case per scenario. */\n/**\n * Text for XML: escaped, and without the control characters XML 1.0 forbids even as references\n * (AFD-158: Ansible output can carry terminal colour codes).\n */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: removing control characters is the point.\nconst XML_FORBIDDEN = /[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\ufffe\\uffff]/g;\nconst esc = (t: string) =>\n  t\n    .replaceAll(XML_FORBIDDEN, '')\n    .replaceAll('&', '&amp;')\n    .replaceAll('<', '&lt;')\n    .replaceAll('>', '&gt;')\n    .replaceAll('\"', '&quot;');\n\n/** One flow's scenarios as a JUnit `<testsuite>`. */\nexport function junitSuite(\n  flow: string,\n  results: readonly ScenarioResult[],\n  doc?: FlowDocument,\n): string {\n  const failures = failedCount(results);\n  const skips = results.filter(skipped).length;\n  const cases = results.map((r) => {\n    if (skipped(r))\n      return `    <testcase classname=\"${esc(flow)}\" name=\"${esc(r.name)}\"><skipped message=\"${esc(`Verify with a run: ${(r.needsAnsible ?? []).map((u) => u.message).join('; ')}`)}\"/></testcase>`;\n    if (r.passed) return `    <testcase classname=\"${esc(flow)}\" name=\"${esc(r.name)}\"/>`;\n    const text = describeResults([r], doc).join('\\n');\n    return `    <testcase classname=\"${esc(flow)}\" name=\"${esc(r.name)}\"><failure message=\"${esc(r.error ?? 'hosts ended elsewhere')}\">${esc(text)}</failure></testcase>`;\n  });\n  return [\n    `  <testsuite name=\"${esc(flow)}\" tests=\"${results.length}\" failures=\"${failures}\"${skips ? ` skipped=\"${skips}\"` : ''}>`,\n    ...cases,\n    '  </testsuite>',\n  ].join('\\n');\n}\n\n/**\n * A JUnit file of several flows' suites under one root (AFD-158: one document per flow, joined,\n * was not XML once there were two flows).\n */\nexport function junitDocument(suites: readonly string[]): string {\n  return [\n    '<?xml version=\"1.0\" encoding=\"UTF-8\"?>',\n    '<testsuites>',\n    ...suites,\n    '</testsuites>',\n    '',\n  ].join('\\n');\n}\n\n/** One flow's scenarios as a whole JUnit file. */\nexport function junitXml(\n  flow: string,\n  results: readonly ScenarioResult[],\n  doc?: FlowDocument,\n): string {\n  return junitDocument([junitSuite(flow, results, doc)]);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/sharedRefs.d.ts

@@ -0,0 +1,22 @@
+import type { FlowDocument, FlowNode } from '@ansible-flow/core/flow/types';
+import type { Finding } from '@ansible-flow/core/flow/validate';
+export interface SharedSource {
+    /** The source flow's version and the subflow at the key path. */
+    version?: number;
+    node?: FlowNode;
+    error?: string;
+}
+/**
+ * The file a shared subflow's `ref.from` names, checked before anything on disk is touched
+ * (AFD-128): a UNC path would make Windows connect to that host and offer the user's credentials,
+ * and a device or a huge file would be read whole. It must be a relative path to a .flow.yaml that
+ * stays, links resolved, inside `root`: the workspace folder, else the folder above the flow's own.
+ */
+export declare function sharedFile(flowFile: string, path: string, root?: string): {
+    file?: string;
+    error?: string;
+};
+/** The source of `from`, for the flow at `flowFile` in the workspace folder `root`. */
+export declare function sharedSource(flowFile: string, from: string, root?: string): SharedSource;
+/** Problems for the flow's shared subflows: a source that is gone, or a newer version of it. */
+export declare function sharedFindings(flowFile: string, doc: FlowDocument, root?: string): Finding[];