@flow-as-code/core 0.1.0

package/src/lint/rules/action-count.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MAX_ACTIONS_PER_FLOW } from "../../flowdoc.js";
+import type { Rule } from "../types.js";
+
+/**
+ * "No more than 250 Actions per flow."
+ * https://docs.aws.amazon.com/connect/latest/devguide/flow-language-example.html
+ * (transcribed in conformance/flow-language/actions.md, document envelope).
+ *
+ * The FlowDoc schema says maxItems 250, but nothing on the authoring path runs
+ * the schema: render, codegen, materialization, and both emitters read the
+ * document straight. `Flow.add` refuses the 251st block, so a flow built with
+ * the builder cannot exceed the limit, but a FlowDoc that arrives any other way
+ * (hand-edited, exported from an instance, produced by another tool) reached
+ * emit with no complaint and failed at deploy time with a Connect error that
+ * names no block. This rule is the check on the FlowDoc path.
+ */
+export const actionCount: Rule = {
+  id: "action-count",
+  description: `A flow holds no more than ${String(MAX_ACTIONS_PER_FLOW)} actions.`,
+  check({ doc, report }) {
+    const count = doc.content.Actions.length;
+    if (count > MAX_ACTIONS_PER_FLOW) {
+      report({
+        severity: "error",
+        message: `Flow has ${String(count)} actions; Connect allows at most ${String(
+          MAX_ACTIONS_PER_FLOW,
+        )}.`,
+      });
+    }
+  },
+};

package/src/lint/rules/error-branches.ts

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  ActionType,
+  NO_MATCHING_CONDITION,
+  NO_MATCHING_ERROR,
+  TERMINAL_ACTIONS,
+} from "../../actions.js";
+import { isTerminal } from "../graph.js";
+import type { Rule } from "../types.js";
+
+const MODELED = new Set<string>(Object.values(ActionType));
+
+/**
+ * The backstop for the type-level enforcement in the builder. It catches what
+ * types cannot: hand-edited FlowDocs, exported flows, and studio edits.
+ *
+ * Only modeled actions are checked. We cannot know an unmodeled action's error
+ * set, and some documented actions genuinely have none.
+ */
+export const errorBranches: Rule = {
+  id: "error-branches",
+  description: "Every non-terminal modeled action must wire its catch-all error branch.",
+  check({ doc, report }) {
+    for (const action of doc.content.Actions) {
+      if (isTerminal(action)) continue;
+      if (!MODELED.has(action.Type)) continue;
+      if (TERMINAL_ACTIONS.includes(action.Type)) continue;
+
+      // Compare is the one modeled action that fails with NoMatchingCondition.
+      const expected =
+        action.Type === ActionType.Compare ? NO_MATCHING_CONDITION : NO_MATCHING_ERROR;
+      const wired = (action.Transitions.Errors ?? []).some((e) => e.ErrorType === expected);
+      if (!wired) {
+        report({
+          severity: "error",
+          blockId: action.Identifier,
+          message: `${action.Type} does not wire its "${expected}" branch.`,
+        });
+      }
+    }
+  },
+};

package/src/lint/rules/index.ts

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Rule registry. Ids are stable and never renamed: the conformance fixtures,
+// the CLI, the studio, and the future Go provider all key off them.
+
+import { actionAllowedInFlowType } from "./action-allowed-in-flow-type.js";
+import { actionCount } from "./action-count.js";
+import { errorBranches } from "./error-branches.js";
+import { moduleDepth5 } from "./module-depth-5.js";
+import { noLiteralArn } from "./no-literal-arn.js";
+import { noUnresolvedToken } from "./no-unresolved-token.js";
+import { promptLength3000 } from "./prompt-length-3000.js";
+import { reachableBlocks } from "./reachable-blocks.js";
+import { recordingConsentBeforeRecord } from "./recording-consent-before-record.js";
+import { terminalBlocks } from "./terminal-blocks.js";
+import { uniqueNames } from "./unique-names.js";
+import type { Rule } from "../types.js";
+
+export const allRules: readonly Rule[] = [
+  noLiteralArn,
+  noUnresolvedToken,
+  reachableBlocks,
+  errorBranches,
+  terminalBlocks,
+  moduleDepth5,
+  promptLength3000,
+  recordingConsentBeforeRecord,
+  uniqueNames,
+  actionAllowedInFlowType,
+  actionCount,
+];
+
+export function ruleById(id: string): Rule | undefined {
+  return allRules.find((r) => r.id === id);
+}
+
+export { NO_LITERAL_ARN, literalArnMessage, literalArnPaths } from "./no-literal-arn.js";
+
+export {
+  actionAllowedInFlowType,
+  actionCount,
+  errorBranches,
+  moduleDepth5,
+  noLiteralArn,
+  noUnresolvedToken,
+  promptLength3000,
+  reachableBlocks,
+  recordingConsentBeforeRecord,
+  terminalBlocks,
+  uniqueNames,
+};

package/src/lint/rules/module-depth-5.ts

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ActionType } from "../../actions.js";
+import { parseToken } from "../../refs.js";
+import type { FlowDoc } from "../../flowdoc.js";
+import type { Rule } from "../types.js";
+
+/**
+ * "You can invoke modules within other modules, supporting up to five levels of
+ * nesting with a stack limit to prevent recursive invocations."
+ * https://docs.aws.amazon.com/connect/latest/adminguide/contact-flow-modules.html
+ */
+export const MAX_MODULE_DEPTH = 5;
+
+function invokedModules(doc: FlowDoc): string[] {
+  const names: string[] = [];
+  for (const action of doc.content.Actions) {
+    if (action.Type !== ActionType.InvokeFlowModule) continue;
+    const id = action.Parameters.FlowModuleId;
+    if (typeof id !== "string") continue;
+    const ref = parseToken(id);
+    if (ref?.type === "module") names.push(ref.name);
+  }
+  return names;
+}
+
+/**
+ * Depth is only computable across a set: a document alone cannot know what the
+ * modules it invokes go on to invoke. Linting a single document therefore
+ * reports nothing here, which is correct rather than a false pass.
+ */
+export const moduleDepth5: Rule = {
+  id: "module-depth-5",
+  description:
+    "Flow module invocation must not nest more than five levels deep, and must not recurse.",
+  check({ doc, all, report }) {
+    // Depth is measured from an entry point. Walking from every document would
+    // report the same violation once per document in the chain, so only flows
+    // start a walk. A module unreachable from any flow is dead code, which is
+    // reachable-blocks territory rather than this rule's.
+    if (doc.kind !== "flow") return;
+
+    const modules = new Map(all.filter((d) => d.kind === "module").map((d) => [d.name, d]));
+
+    const walk = (current: FlowDoc, depth: number, stack: string[]): void => {
+      for (const name of invokedModules(current)) {
+        if (stack.includes(name)) {
+          report({
+            severity: "error",
+            message: `Recursive module invocation: ${[...stack, name].join(" -> ")}.`,
+          });
+          continue;
+        }
+        if (depth + 1 > MAX_MODULE_DEPTH) {
+          report({
+            severity: "error",
+            message: `Module nesting reaches depth ${depth + 1} via ${[...stack, name].join(" -> ")}; Connect allows ${MAX_MODULE_DEPTH}.`,
+          });
+          continue;
+        }
+        const next = modules.get(name);
+        if (next !== undefined) walk(next, depth + 1, [...stack, name]);
+      }
+    };
+
+    walk(doc, 0, [doc.name]);
+  },
+};

package/src/lint/rules/no-literal-arn.ts

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { documentStrings, findingsForActions, walkStrings } from "../graph.js";
+import type { Rule } from "../types.js";
+
+const ARN = /arn:aws[a-z-]*:/;
+
+/** This rule's id, for tools that report the violation before lint can run. */
+export const NO_LITERAL_ARN = "no-literal-arn";
+
+/** The sentence every literal-ARN report ends with. */
+export function literalArnMessage(path: string): string {
+  return `"${path}" contains a literal ARN. Use a \${cdref:type:name} token instead.`;
+}
+
+/**
+ * Paths of every string holding a literal ARN in an arbitrary JSON value.
+ *
+ * Takes `unknown` rather than a FlowDoc on purpose: the CLI runs this over a
+ * document the schema has already rejected, because the schema's own pattern
+ * errors describe that one mistake several times over and never name the rule.
+ * See packages/cli/src/docs.ts.
+ */
+export function literalArnPaths(value: unknown): string[] {
+  return walkStrings(value)
+    .filter(([, v]) => ARN.test(v))
+    .map(([path]) => path);
+}
+
+/**
+ * References are tokens, never literal ARNs. A literal ARN pins a flow to one
+ * account, region, and instance, which is the whole thing this tooling exists
+ * to avoid.
+ */
+export const noLiteralArn: Rule = {
+  id: NO_LITERAL_ARN,
+  description: "Authored content must not contain a literal ARN; use a ${cdref:...} token.",
+  hard: true,
+  check({ doc, report }) {
+    // `refs` is authored content too: it is what the studio's reference
+    // pickers and the emitters read, and an ARN placed there satisfied this
+    // rule while the schema was the only thing catching it.
+    const documentLevel = [...documentStrings(doc), ...walkStrings(doc.refs ?? [], "refs")];
+    for (const [path, value] of documentLevel) {
+      if (ARN.test(value)) {
+        report({ severity: "error", message: literalArnMessage(path) });
+      }
+    }
+
+    for (const { action, strings } of findingsForActions(doc)) {
+      for (const [path, value] of strings) {
+        if (ARN.test(value)) {
+          report({
+            severity: "error",
+            blockId: action.Identifier,
+            message: `${path.startsWith("Transitions") ? "Transition" : "Parameter"} ${literalArnMessage(path)}`,
+          });
+        }
+      }
+    }
+  },
+};

package/src/lint/rules/no-unresolved-token.ts

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { documentStrings, findingsForActions } from "../graph.js";
+import { TOKEN_PATTERN, parseToken } from "../../refs.js";
+import type { Rule } from "../types.js";
+
+/** Any ${...} placeholder, so malformed tokens are caught rather than ignored. */
+/**
+ * Only placeholders that ATTEMPT to be a reference are this rule's business.
+ *
+ * Scanning every `${...}` produced false positives on ordinary prompt text:
+ * "Your balance is ${amount}" is a literal string Connect plays verbatim, since
+ * Connect's own dynamic syntax is JSONPath ($.Attributes.x), not ${}. Matching
+ * on the `cdref` prefix still catches the cases that matter, a well-formed
+ * token interpolated into a longer string and a misspelled cdref, without
+ * claiming authority over text we do not own.
+ */
+const CDREF_PLACEHOLDER = /\$\{\s*cdref[^}]*\}/gi;
+
+/**
+ * Every token must be well formed, must occupy its entire field, and must
+ * appear in the refs index. A token Connect never resolves deploys a flow that
+ * fails at runtime with an opaque error.
+ */
+export const noUnresolvedToken: Rule = {
+  id: "no-unresolved-token",
+  description:
+    "Every ${cdref:...} token must be well formed, stand alone, and appear in the refs index.",
+  hard: true,
+  check({ doc, report }) {
+    const indexed = new Set((doc.refs ?? []).map((r) => r.token));
+
+    const entries: { blockId?: string; path: string; value: string }[] = [
+      ...documentStrings(doc).map(([path, value]) => ({ path, value })),
+      ...findingsForActions(doc).flatMap(({ action, strings }) =>
+        strings.map(([path, value]) => ({ blockId: action.Identifier, path, value })),
+      ),
+    ];
+
+    const where = (path: string): string =>
+      path.startsWith("content.Metadata")
+        ? ""
+        : path.startsWith("Transitions")
+          ? "Transition "
+          : "Parameter ";
+
+    for (const { blockId, path, value } of entries) {
+      const placeholders = value.match(CDREF_PLACEHOLDER) ?? [];
+      if (placeholders.length === 0) continue;
+
+      // Connect requires reference fields to be fully static or a single
+      // JSONPath identifier, so a token cannot be part of a longer string.
+      if (!TOKEN_PATTERN.test(value)) {
+        report({
+          severity: "error",
+          ...(blockId === undefined ? {} : { blockId }),
+          message: `${where(path)}"${path}" embeds a token in a larger string ("${value}"). A token must be the entire value.`,
+        });
+        continue;
+      }
+
+      const token = placeholders[0]!;
+      if (parseToken(token) === undefined) {
+        report({
+          severity: "error",
+          ...(blockId === undefined ? {} : { blockId }),
+          message: `${where(path)}"${path}" contains a malformed token "${token}".`,
+        });
+      } else if (!indexed.has(token)) {
+        report({
+          severity: "error",
+          ...(blockId === undefined ? {} : { blockId }),
+          message: `Token "${token}" is missing from the refs index. Re-run synth to regenerate it.`,
+        });
+      }
+    }
+  },
+};

package/src/lint/rules/prompt-length-3000.ts

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ActionType } from "../../actions.js";
+import type { Rule } from "../types.js";
+
+/**
+ * "When you use text, either for text-to-speech or chat, you can use a maximum
+ * of 3,000 billed characters, which is 6,000 characters total."
+ * https://docs.aws.amazon.com/connect/latest/adminguide/play.html
+ *
+ * The Get customer input block states the same limit for its own text:
+ * https://docs.aws.amazon.com/connect/latest/adminguide/get-customer-input.html
+ *
+ * Billed characters are the spoken text. SSML markup counts toward the 6,000
+ * total but not the 3,000 billed, so the two are checked separately.
+ */
+export const MAX_BILLED_CHARACTERS = 3000;
+export const MAX_TOTAL_CHARACTERS = 6000;
+
+/** The modeled actions that carry a Text or SSML prompt. */
+const PROMPT_ACTIONS: readonly string[] = [
+  ActionType.MessageParticipant,
+  ActionType.GetParticipantInput,
+];
+
+const stripSsmlTags = (s: string): string => s.replace(/<[^>]*>/g, "");
+
+export const promptLength3000: Rule = {
+  id: "prompt-length-3000",
+  description: "Prompt text must stay within 3,000 billed characters and 6,000 total.",
+  check({ doc, report }) {
+    for (const action of doc.content.Actions) {
+      if (!PROMPT_ACTIONS.includes(action.Type)) continue;
+
+      const text = action.Parameters.Text;
+      if (typeof text === "string" && text.length > MAX_BILLED_CHARACTERS) {
+        report({
+          severity: "error",
+          blockId: action.Identifier,
+          message: `Text is ${text.length} characters; Connect allows ${MAX_BILLED_CHARACTERS} billed characters.`,
+        });
+      }
+
+      const ssml = action.Parameters.SSML;
+      if (typeof ssml === "string") {
+        if (ssml.length > MAX_TOTAL_CHARACTERS) {
+          report({
+            severity: "error",
+            blockId: action.Identifier,
+            message: `SSML is ${ssml.length} characters; Connect allows ${MAX_TOTAL_CHARACTERS} total.`,
+          });
+        }
+        const spoken = stripSsmlTags(ssml).length;
+        if (spoken > MAX_BILLED_CHARACTERS) {
+          report({
+            severity: "error",
+            blockId: action.Identifier,
+            message: `SSML contains ${spoken} spoken characters; Connect allows ${MAX_BILLED_CHARACTERS} billed characters.`,
+          });
+        }
+      }
+    }
+  },
+};

package/src/lint/rules/reachable-blocks.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { reachable, transitionTargets } from "../graph.js";
+import { actionsById } from "../graph.js";
+import type { Rule } from "../types.js";
+
+/**
+ * Unreachable actions are kept, never dropped, but they are almost always an
+ * editing mistake. Dangling targets are a hard error: Connect rejects the flow.
+ */
+export const reachableBlocks: Rule = {
+  id: "reachable-blocks",
+  description:
+    "Every action should be reachable from StartAction, and every transition target must exist.",
+  check({ doc, report }) {
+    const byId = actionsById(doc);
+
+    if (!byId.has(doc.content.StartAction)) {
+      report({
+        severity: "error",
+        message: `StartAction "${doc.content.StartAction}" does not match any action.`,
+      });
+    }
+
+    for (const action of doc.content.Actions) {
+      for (const target of transitionTargets(action)) {
+        if (!byId.has(target)) {
+          report({
+            severity: "error",
+            blockId: action.Identifier,
+            message: `Transition points at "${target}", which does not exist.`,
+          });
+        }
+      }
+    }
+
+    const live = reachable(doc);
+    for (const action of doc.content.Actions) {
+      if (!live.has(action.Identifier)) {
+        report({
+          severity: "warning",
+          blockId: action.Identifier,
+          message: "Action is not reachable from StartAction.",
+        });
+      }
+    }
+  },
+};

package/src/lint/rules/recording-consent-before-record.ts

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ActionType } from "../../actions.js";
+import { actionsById, transitionTargets } from "../graph.js";
+import type { FlowAction, FlowDoc } from "../../flowdoc.js";
+import type { Rule } from "../types.js";
+
+/**
+ * Recording a caller without first telling them is a legal problem in many
+ * jurisdictions. This rule is deliberately generic: it requires that every path
+ * reaching an action which enables recording passes through an action that
+ * plays the participant something first. What that message says is the
+ * operator's business; that one exists is checkable here.
+ */
+function enablesRecording(action: FlowAction): boolean {
+  if (action.Type !== ActionType.UpdateContactRecordingBehavior) return false;
+  const behavior = action.Parameters.RecordingBehavior;
+  if (behavior === null || typeof behavior !== "object") return false;
+  const participants = (behavior as { RecordedParticipants?: unknown }).RecordedParticipants;
+  // An empty list disables recording, per the action's documentation.
+  return Array.isArray(participants) && participants.length > 0;
+}
+
+/** The parameters that play something on the two announcing actions. */
+const BODY_FIELDS = ["Text", "SSML", "PromptId"] as const;
+
+/**
+ * MessageParticipant carries exactly one of Text, SSML, or PromptId.
+ * GetParticipantInput plays its prompt before waiting for a key ("This call
+ * may be recorded. Press 1 to continue." is the usual consent menu), but every
+ * prompt field is optional on its action page, so a menu with none is silent.
+ * https://docs.aws.amazon.com/connect/latest/devguide/participant-actions-messageparticipant.html
+ * https://docs.aws.amazon.com/connect/latest/devguide/participant-actions-getparticipantinput.html
+ *
+ * Content is what counts, not the key: the studio's body switch writes
+ * `Text: ""` until the author types, and an empty or blank Text or SSML plays
+ * nothing on either action.
+ */
+function announces(action: FlowAction): boolean {
+  if (
+    action.Type !== ActionType.MessageParticipant &&
+    action.Type !== ActionType.GetParticipantInput
+  ) {
+    return false;
+  }
+  return BODY_FIELDS.some((k) => {
+    const body = action.Parameters[k];
+    return typeof body === "string" && body.trim() !== "";
+  });
+}
+
+/** Ids from which `targetId` is reachable without passing an announcement. */
+function pathsWithoutAnnouncement(doc: FlowDoc, targetId: string): boolean {
+  const byId = actionsById(doc);
+  const seen = new Set<string>();
+  const queue: string[] = [doc.content.StartAction];
+
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    if (id === targetId) return true;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const action = byId.get(id);
+    if (action === undefined) continue;
+    // An announcement on this path satisfies the rule, so stop exploring it.
+    if (announces(action)) continue;
+    queue.push(...transitionTargets(action));
+  }
+  return false;
+}
+
+export const recordingConsentBeforeRecord: Rule = {
+  id: "recording-consent-before-record",
+  description: "Recording must not start before the participant has been played a message.",
+  check({ doc, report }) {
+    for (const action of doc.content.Actions) {
+      if (!enablesRecording(action)) continue;
+      if (pathsWithoutAnnouncement(doc, action.Identifier)) {
+        report({
+          severity: "error",
+          blockId: action.Identifier,
+          message:
+            "Recording is enabled on a path that plays no message first. Announce recording before starting it.",
+        });
+      }
+    }
+  },
+};

package/src/lint/rules/terminal-blocks.ts

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TERMINAL_ACTIONS } from "../../actions.js";
+import { isTerminal, reachable } from "../graph.js";
+import { actionsById } from "../graph.js";
+import type { Rule } from "../types.js";
+
+/**
+ * A flow that cannot terminate strands the contact. Also catches the inverse
+ * mistake: an action with empty Transitions that is not a terminal type, which
+ * Connect treats as an unintended dead end.
+ */
+export const terminalBlocks: Rule = {
+  id: "terminal-blocks",
+  description:
+    "A flow must reach a terminal action, and only terminal action types may have empty transitions.",
+  check({ doc, report }) {
+    const byId = actionsById(doc);
+    const live = reachable(doc);
+
+    const reachesTerminal = [...live].some((id) => {
+      const a = byId.get(id);
+      return a !== undefined && isTerminal(a) && TERMINAL_ACTIONS.includes(a.Type);
+    });
+
+    if (!reachesTerminal) {
+      report({
+        severity: "error",
+        message: "No terminal action is reachable from StartAction; the flow cannot end.",
+      });
+    }
+
+    for (const action of doc.content.Actions) {
+      if (isTerminal(action) && !TERMINAL_ACTIONS.includes(action.Type)) {
+        report({
+          severity: "warning",
+          blockId: action.Identifier,
+          message: `${action.Type} has no transitions but is not a terminal action type, so the flow dead-ends here.`,
+        });
+      }
+    }
+  },
+};

package/src/lint/rules/unique-names.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isValidIdentifier } from "../../flowdoc.js";
+import type { Rule } from "../types.js";
+
+/**
+ * Identifiers are unique within a flow and document names unique within a set,
+ * because both are used as keys by the emitters.
+ */
+export const uniqueNames: Rule = {
+  id: "unique-names",
+  description:
+    "Action Identifiers are unique within a flow, document names unique within a set, and both are valid.",
+  check({ doc, all, report }) {
+    const seen = new Set<string>();
+    for (const action of doc.content.Actions) {
+      if (seen.has(action.Identifier)) {
+        report({
+          severity: "error",
+          blockId: action.Identifier,
+          message: `Duplicate Identifier "${action.Identifier}".`,
+        });
+      }
+      seen.add(action.Identifier);
+
+      if (!isValidIdentifier(action.Identifier)) {
+        report({
+          severity: "error",
+          blockId: action.Identifier,
+          message: `Identifier "${action.Identifier}" is not valid: at most 50 characters, and none of % : ( \\ / ) = $ , ; [ ] { }.`,
+        });
+      }
+    }
+
+    if (all.filter((d) => d.name === doc.name).length > 1) {
+      report({
+        severity: "error",
+        message: `Duplicate document name "${doc.name}" in this flow set.`,
+      });
+    }
+  },
+};