@xemahq/dsl 0.1.1

package/src/workflow/lib/expression/walk-artifact-refs.ts

@@ -0,0 +1,232 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Runtime walker — find every AST sub-expression that resolves to an
+//    ArtifactRef the runtime must pre-fetch (plan §C.1 / §C.2). ──
+//
+// Two flavours of pre-fetch target:
+//
+//   1. Payload reach-in — `needs.<X>.outputs.<name>.<payload-field>` where
+//      `<payload-field>` is NOT an ArtifactRef envelope field. The
+//      evaluator reads the field via `ctx.payloadCache.get(versionId)`,
+//      so the runtime must resolve the BASE expression
+//      (`needs.<X>.outputs.<name>` or its indexed / keyed variants) to a
+//      concrete `ArtifactRef` and pre-fetch the payload.
+//
+//   2. `fromJSON(<expr>)` — the argument expression should evaluate to
+//      an ArtifactRef whose payload the evaluator returns via
+//      `payloadCache.get(versionId)`. The runtime pre-fetches the same
+//      way; the difference from #1 is that `fromJSON` is the documented
+//      escape hatch (compile-time skipped) so the walker just yields
+//      the argument node verbatim.
+//
+// The walker yields BASE NODES. The caller (worker prefetch helper)
+// evaluates each yielded node against `ExpressionContext`, normalizes
+// the result to `ArtifactRef[]`, dedupes by `versionId`, and fetches.
+//
+// Workflow-sandbox-safe: zero imports beyond pure AST types. Lives in
+// the `expression/` subpath so workflow code (which can't import the
+// compiler graph) can call it directly.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { isArtifactRefEnvelopeField } from '@xemahq/kernel-contracts/workflow';
+
+import {
+  ExpressionFunction,
+  ExpressionNodeKind,
+  type ExpressionNode,
+} from './ast';
+
+/**
+ * Yield every sub-expression in `node` that should resolve to an
+ * ArtifactRef (or array of refs) for runtime pre-fetch. The caller is
+ * responsible for evaluating each yielded node against an
+ * `ExpressionContext` and shaping the result.
+ *
+ * Important: the walker also recurses INTO yielded matches so a nested
+ * reach-in inside e.g. `byKey[fromJSON(needs.X.outputs.foo).key]` still
+ * surfaces both the outer reach-in's base AND the inner `fromJSON` arg.
+ */
+export function walkRuntimeArtifactRefTargets(
+  node: ExpressionNode,
+  visit: (baseNode: ExpressionNode) => void,
+): void {
+  walk(node, visit);
+}
+
+function walk(
+  node: ExpressionNode,
+  visit: (baseNode: ExpressionNode) => void,
+): void {
+  // Reach-in: `<base>.<field>` where `<base>` resolves to a `needs.X.outputs.<name>`
+  // chain (with optional `[N]` / `byKey['k']` indexing) and `<field>` is NOT an
+  // envelope field. The base node IS the artifact-ref expression.
+  if (node.kind === ExpressionNodeKind.MEMBER) {
+    if (!isArtifactRefEnvelopeField(node.property)) {
+      const base = node.target;
+      if (resolvesToOutputsRef(base)) {
+        visit(base);
+      }
+    }
+  }
+
+  // `fromJSON(<expr>)` — escape hatch. The argument expression must
+  // evaluate to an ArtifactRef at runtime; pre-fetch its payload.
+  // (String-arg `fromJSON(...)` is also valid GitHub-Actions semantics
+  // for parsing literal JSON; the prefetch helper detects non-ref
+  // results and skips them — no pre-fetch needed.)
+  if (
+    node.kind === ExpressionNodeKind.CALL &&
+    node.callee === ExpressionFunction.FROM_JSON
+  ) {
+    for (const arg of node.args) {
+      visit(arg);
+    }
+  }
+
+  // Recurse — same shape the compile-time walker uses, but WITHOUT
+  // skipping fromJSON args (the compiler skips them as the documented
+  // escape hatch; the runtime needs them to fetch).
+  switch (node.kind) {
+    case ExpressionNodeKind.MEMBER:
+      walk(node.target, visit);
+      return;
+    case ExpressionNodeKind.INDEX:
+      walk(node.target, visit);
+      walk(node.index, visit);
+      return;
+    case ExpressionNodeKind.CALL:
+      for (const arg of node.args) walk(arg, visit);
+      return;
+    case ExpressionNodeKind.UNARY_NOT:
+      walk(node.operand, visit);
+      return;
+    case ExpressionNodeKind.BINARY_EQ:
+    case ExpressionNodeKind.BINARY_NEQ:
+    case ExpressionNodeKind.BINARY_AND:
+    case ExpressionNodeKind.BINARY_OR:
+      walk(node.left, visit);
+      walk(node.right, visit);
+      return;
+    case ExpressionNodeKind.LITERAL:
+    case ExpressionNodeKind.IDENTIFIER:
+      return;
+  }
+}
+
+/**
+ * Does the AST node resolve (structurally) to one of:
+ *
+ *   - `needs.<X>.outputs.<name>`               (single output)
+ *   - `needs.<X>.outputs[<N>]`                 (indexed positional)
+ *   - `needs.<X>.outputs.byKey['<k>']`         (keyed matrix access)
+ *
+ * Returning true means evaluating this node against `ctx` is EXPECTED
+ * to yield an ArtifactRef (or ArtifactRef[]); the prefetch helper
+ * checks the actual shape at runtime and silently skips non-refs (a
+ * mid-chain result that's a plain object means the author wrote
+ * something the evaluator will reject when it actually runs — let the
+ * evaluator surface the error there, not at prefetch time).
+ */
+function resolvesToOutputsRef(node: ExpressionNode): boolean {
+  // Form A: needs.<X>.outputs.<name>
+  if (node.kind === ExpressionNodeKind.MEMBER) {
+    if (node.property === 'byKey') {
+      // `outputs.byKey` by itself isn't a ref — only `outputs.byKey['k']`
+      // (the INDEX node) is. Return false; the INDEX form is matched below.
+      return false;
+    }
+    return isNeedsOutputsRoot(node.target);
+  }
+
+  // Form B: needs.<X>.outputs[<N>]  OR  needs.<X>.outputs.byKey['<k>']
+  if (node.kind === ExpressionNodeKind.INDEX) {
+    const indexed = node.target;
+    if (isNeedsOutputsRoot(indexed)) {
+      return true;
+    }
+    if (
+      indexed.kind === ExpressionNodeKind.MEMBER &&
+      indexed.property === 'byKey' &&
+      isNeedsOutputsRoot(indexed.target)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** Match `needs.<X>.outputs`. */
+function isNeedsOutputsRoot(node: ExpressionNode): boolean {
+  if (node.kind !== ExpressionNodeKind.MEMBER) return false;
+  if (node.property !== 'outputs') return false;
+  const needsRoot = node.target;
+  if (needsRoot.kind !== ExpressionNodeKind.MEMBER) return false;
+  const ident = needsRoot.target;
+  if (ident.kind !== ExpressionNodeKind.IDENTIFIER) return false;
+  if (ident.name !== 'needs') return false;
+  return true;
+}
+
+/**
+ * Extract `<X>` from a base node whose shape is
+ * `needs.<X>.outputs.<name>` (or its indexed / keyed variants). Returns
+ * `null` when the base doesn't structurally resolve to a needs-outputs
+ * chain — `fromJSON(...)` arguments and dynamically-shaped refs land
+ * here.
+ */
+export function extractUpstreamJobKey(node: ExpressionNode): string | null {
+  // Form A: needs.<X>.outputs.<name>
+  if (node.kind === ExpressionNodeKind.MEMBER) {
+    const outputsNode = node.target;
+    return extractFromOutputsRoot(outputsNode);
+  }
+  // Form B: needs.<X>.outputs[N] OR needs.<X>.outputs.byKey['k']
+  if (node.kind === ExpressionNodeKind.INDEX) {
+    const indexed = node.target;
+    const fromOutputs = extractFromOutputsRoot(indexed);
+    if (fromOutputs !== null) return fromOutputs;
+    if (
+      indexed.kind === ExpressionNodeKind.MEMBER &&
+      indexed.property === 'byKey'
+    ) {
+      return extractFromOutputsRoot(indexed.target);
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract the upstream output name from a base node, when the shape is
+ * `needs.<X>.outputs.<name>` (Form A). Returns `null` for indexed /
+ * keyed access (Forms B) because the output name isn't statically
+ * known there.
+ *
+ * Pair with `extractUpstreamJobKey` to resolve per-output spec pins at
+ * runtime (plan §B). Falling back to `null` is the cue the prefetch
+ * helper uses to consult the job-level pin instead.
+ */
+export function extractUpstreamOutputName(
+  node: ExpressionNode,
+): string | null {
+  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
+  const outputsNode = node.target;
+  if (outputsNode.kind !== ExpressionNodeKind.MEMBER) return null;
+  if (outputsNode.property !== 'outputs') return null;
+  const needsRoot = outputsNode.target;
+  if (needsRoot.kind !== ExpressionNodeKind.MEMBER) return null;
+  const ident = needsRoot.target;
+  if (ident.kind !== ExpressionNodeKind.IDENTIFIER) return null;
+  if (ident.name !== 'needs') return null;
+  return node.property;
+}
+
+function extractFromOutputsRoot(node: ExpressionNode): string | null {
+  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
+  if (node.property !== 'outputs') return null;
+  const needsRoot = node.target;
+  if (needsRoot.kind !== ExpressionNodeKind.MEMBER) return null;
+  const ident = needsRoot.target;
+  if (ident.kind !== ExpressionNodeKind.IDENTIFIER) return null;
+  if (ident.name !== 'needs') return null;
+  return needsRoot.property;
+}

package/src/workflow/lib/installation-resource-kind.ts

@@ -0,0 +1,107 @@
+/**
+ * Closed enum of installation-resource kinds the compile-time validator
+ * understands. Mirrored on the JSON Schema custom keyword `x-installation-resource`
+ * (see action-input-validator.ts) and on the workflow-engine compiler's
+ * installation-resource resolver.
+ *
+ * Adding a kind here is a 3-step change:
+ *   1. Add the enum value below.
+ *   2. Extend `addKeyword.metaSchema.properties.kind.enum` in
+ *      action-input-validator.ts.
+ *   3. Teach the compiler-side `InstallationResourceResolverService`
+ *      how to query bound resources of that kind from biome-host-api.
+ */
+export enum InstallationResourceKind {
+  /** SMTP / IMAP wallet — `OrgIntegrationCredential` row attached to the installation. */
+  Wallet = 'wallet',
+  /** SCM repository binding on the installation. */
+  Repo = 'repo',
+  /** Tracker (Jira / Linear) project binding. */
+  Project = 'project',
+  /** Messaging (Slack / Discord) channel binding. */
+  Channel = 'channel',
+  /** Documentation (Confluence / KB) space binding. */
+  Space = 'space',
+}
+
+/**
+ * Per-field hint extracted from an action manifest's `spec.inputs` JSON
+ * Schema. The compiler-side validator walks the schema, finds fields
+ * carrying `x-installation-resource`, and produces one of these for
+ * each hit. Path is dotted (`walletId`, `defaults.repoId`, …) and
+ * matches the layout of the caller's `with:` block.
+ */
+export interface InstallationResourceFieldHint {
+  readonly path: string;
+  readonly kind: InstallationResourceKind;
+  /** When true, an empty / missing value at this path is allowed. */
+  readonly optional: boolean;
+}
+
+/**
+ * Walks a JSON Schema object and collects every field annotated with
+ * `x-installation-resource: { kind: ... }`. Object + array properties
+ * are descended into; oneOf / anyOf / allOf branches are NOT — actions
+ * that need a wallet input should declare it on the top-level shape,
+ * not behind a union. Refs aren't followed either (action manifests
+ * are pinned at compile time and use inline schemas).
+ *
+ * The traversal is pure and deterministic — call it once per
+ * `ActionRef.inputsSchema` and cache the result alongside the schema.
+ */
+export function collectInstallationResourceHints(
+  schema: unknown,
+): InstallationResourceFieldHint[] {
+  const out: InstallationResourceFieldHint[] = [];
+  walk(schema, '', new Set<string>(), out);
+  return out;
+}
+
+function walk(
+  node: unknown,
+  path: string,
+  required: ReadonlySet<string>,
+  out: InstallationResourceFieldHint[],
+): void {
+  if (!node || typeof node !== 'object') {return;}
+  const obj = node as Record<string, unknown>;
+  const hint = obj['x-installation-resource'];
+  if (hint && typeof hint === 'object') {
+    const kind = (hint as Record<string, unknown>)['kind'];
+    if (typeof kind === 'string' && isInstallationResourceKind(kind)) {
+      out.push({
+        path,
+        kind,
+        optional: !required.has(lastSegment(path)),
+      });
+    }
+  }
+  const properties = obj['properties'];
+  if (properties && typeof properties === 'object') {
+    const reqList = Array.isArray(obj['required'])
+      ? new Set(obj['required'].filter((x): x is string => typeof x === 'string'))
+      : new Set<string>();
+    for (const [key, child] of Object.entries(properties as Record<string, unknown>)) {
+      walk(child, path === '' ? key : `${path}.${key}`, reqList, out);
+    }
+  }
+  const items = obj['items'];
+  if (items) {
+    walk(items, path === '' ? '[*]' : `${path}[*]`, new Set(), out);
+  }
+}
+
+function lastSegment(path: string): string {
+  const dot = path.lastIndexOf('.');
+  return dot >= 0 ? path.slice(dot + 1) : path;
+}
+
+function isInstallationResourceKind(value: string): value is InstallationResourceKind {
+  return (
+    value === InstallationResourceKind.Wallet ||
+    value === InstallationResourceKind.Repo ||
+    value === InstallationResourceKind.Project ||
+    value === InstallationResourceKind.Channel ||
+    value === InstallationResourceKind.Space
+  );
+}

package/src/workflow/lib/schemas-loader.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from './errors';
+
+/**
+ * Resolves the schema/ directory relative to this compiled file. Module
+ * load MUST succeed if the package is installed correctly; missing
+ * schemas are a packaging bug (see scripts/copy-schemas.mjs).
+ *
+ * We intentionally resolve at module-load time and read the JSON files
+ * synchronously — Ajv compiles once at module load and every subsequent
+ * validate() call is lock-free. Package is published as CommonJS (see
+ * tsconfig.base.json module:commonjs), so `__dirname` is always defined.
+ */
+function schemasRoot(): string {
+  // This module lives at `<sub>/lib/schemas-loader` inside the @xemahq/dsl
+  // bundle (compiled `dist/workflow/lib/...`, source `src/workflow/lib/...`).
+  // Resolution order (first reachable wins):
+  //   1. `dist/schema/`   — install-time, copied by scripts/copy-schemas.mjs
+  //      into the package-root `dist/schema` (two levels up from dist/workflow/lib).
+  //   2. package-root `schema/` — the authored source schemas (three levels up
+  //      from either dist/workflow/lib or src/workflow/lib, i.e. xema-source dev mode).
+  // If neither is reachable, fail fast — the package is malformed.
+  const distSchema = join(__dirname, '..', '..', 'schema');
+  const packageRootSchema = join(__dirname, '..', '..', '..', 'schema');
+  const candidates = [distSchema, packageRootSchema];
+  for (const candidate of candidates) {
+    try {
+      readFileSync(join(candidate, 'workflow.schema.json'), 'utf8');
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+  throw new WorkflowDslError(
+    WorkflowErrorCode.COMPILE_INTERNAL,
+    '@xemahq/dsl/workflow: schema/ directory not found. Package is malformed.',
+    { tried: candidates },
+  );
+}
+
+function readJsonSchema(fileName: string): Readonly<Record<string, unknown>> {
+  const filePath = join(schemasRoot(), fileName);
+  const raw = readFileSync(filePath, 'utf8');
+  try {
+    return JSON.parse(raw) as Readonly<Record<string, unknown>>;
+  } catch (err) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.COMPILE_INTERNAL,
+      `Failed to parse ${fileName}: ${(err as Error).message}`,
+      { fileName },
+    );
+  }
+}
+
+/** Schema object for the canonical Workflow document. */
+export const WORKFLOW_SCHEMA = readJsonSchema('workflow.schema.json');
+
+/** Schema object for a reusable workflow (must declare `on.workflow_call`). */
+export const REUSABLE_WORKFLOW_SCHEMA = readJsonSchema('reusable-workflow.schema.json');
+
+/** Schema object for a single action manifest. */
+export const ACTION_SCHEMA = readJsonSchema('action.schema.json');

package/src/workflow/lib/serializer.ts

@@ -0,0 +1,30 @@
+import { dump as dumpYaml } from 'js-yaml';
+
+import type { WorkflowDocument } from './types';
+
+/**
+ * Render a validated `WorkflowDocument` back to YAML.
+ *
+ * Note on comment preservation: this serializer does NOT carry over
+ * source comments from the original YAML — it dumps the AST verbatim.
+ * Use it when the canonical representation lives in the AST (e.g. the
+ * canvas editor in PR 5.x) and the YAML view is a derived presentation.
+ * If you need to apply a single mutation to existing hand-authored YAML
+ * while keeping comments + key ordering intact, use the `yaml`
+ * package's CST/Document API directly (follow-up; not in this PR).
+ *
+ * Output style is tuned for human-readable diffs:
+ *   - block scalars (flow disabled),
+ *   - 2-space indent,
+ *   - long lines unwrapped so URLs / expressions don't fold mid-token.
+ */
+export function serializeWorkflowDocument(doc: WorkflowDocument): string {
+  return dumpYaml(doc as unknown as Record<string, unknown>, {
+    indent: 2,
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+    quotingType: '"',
+    forceQuotes: false,
+  });
+}