@hatua/model 0.0.0 → 0.1.0

package/dist/tree.d.ts

@@ -0,0 +1,311 @@
+import { Block, Branch, Step, Variable, WorkflowDefinition } from '@hatua/schema';
+/**
+ * Pure domain rules over the step tree. No state, no I/O, no YAML — those live
+ * in @hatua/document. Everything here is a function of the typed projection.
+ */
+/**
+ * Which Board a Step sits on: a Block's id, or `null` for the root Board.
+ *
+ * `null` rather than a sentinel string because the root Board is not a Block and
+ * has no id to borrow — a string would have to be one no Block could ever be
+ * called, which is a reserved word this design spent ADR-0014 getting rid of.
+ */
+export type BoardId = string | null;
+/**
+ * One drawable Step tree and the root that gives it its parameters.
+ *
+ * A document holds the root Board, whose root is `triggers:`, plus one per
+ * Block, whose root is its declared contract. Scope is computed against a Board
+ * and never across two, which is what keeps a call a cross-link with a contract
+ * rather than a jump (ADR-0013).
+ */
+export interface Board {
+    readonly id: BoardId;
+    /** The Block this Board belongs to. Absent on the root Board. */
+    readonly block?: Block;
+    readonly steps: readonly Step[];
+}
+/**
+ * Read one key of a document-supplied map.
+ *
+ * `Object.hasOwn` is the whole guarantee, and it is the same one `resolve.ts`
+ * gives for `{{ steps.s2.constructor }}`. A Workflow Definition is user-editable
+ * YAML and the schema's identifier rule permits underscores, so `__proto__` is a
+ * legal field key, a legal declaration key and a legal var key — and a bare
+ * `values[k]` there reads `Object.prototype` rather than nothing, which makes a
+ * missing value look present. Go has no prototype to find, so this is also what
+ * keeps the two languages saying the same thing about the same document.
+ */
+export declare const own: (values: Record<string, unknown> | undefined, key: string) => unknown;
+/** A Step, and the Board it is on. Neither half identifies one alone. */
+export interface StepRef {
+    readonly board: BoardId;
+    readonly id: string;
+}
+/** A position among a list of sibling Steps, named in domain terms rather than YAML paths. */
+export interface InsertPoint {
+    /**
+     * Which Board the position is on: a Block's id, or absent for the root.
+     *
+     * Every path below is rooted here rather than at `['steps']`. That single
+     * parameter is what makes an edit on a Block's Board the same command as an
+     * edit on the root's — which is the property the extract-into-a-block gesture
+     * needs, and what keeps a Block built on the canvas and one hand-written in
+     * Text Mode the same document.
+     */
+    board?: BoardId;
+    /**
+     * The container Step whose children receive it. Absent for the Board's
+     * root sequence.
+     */
+    parentId?: string;
+    /**
+     * Which of a `core.fork`'s branches, by index. Absent for a `core.for_each`'s
+     * own nested `steps`, and absent at the root.
+     */
+    branchIndex?: number;
+    /**
+     * Which of a `core.try`'s two regions. Absent means the body under `steps:`,
+     * which is the same key a loop's children sit under.
+     *
+     * A named region rather than a second index, because the two are not a list:
+     * a try has exactly one body and exactly one handler, and an index would let
+     * a caller ask for the third one.
+     */
+    region?: 'handler';
+    /** Position among the siblings. The list's length appends. */
+    index: number;
+}
+/**
+ * Every Board in the document, root first.
+ *
+ * This is the traversal that cannot forget a Block. A validator walking
+ * `doc.steps` sees a document with three Blocks in it and reports nothing about
+ * any of them, silently — so nothing here walks `doc.steps` directly.
+ */
+export declare function boards(doc: WorkflowDefinition): Generator<Board>;
+/** One Board by id, or undefined when nothing declares it. */
+export declare function boardOf(doc: WorkflowDefinition, id: BoardId): Board | undefined;
+/**
+ * The verb that protects a region and falls back to a handler.
+ *
+ * The one container with two child regions: a body under `steps:` and a handler
+ * under `handler:`. Wrapping one Step is retry, wrapping a region is fallback,
+ * so one verb serves both (ADR-0013).
+ *
+ * Its retry policy — how many attempts, how long to wait — sits in `with:` as
+ * ordinary manifest fields, and deliberately NOT in a structural key. `until`
+ * had to leave `with:` because `FIELD_KIND_TYPES` has no mappable boolean, so a
+ * condition there would have type-checked as text. An attempt count is a number
+ * and `number` IS a mappable field kind, so the argument that moved `until` does
+ * not reach here at all — following it anyway would be copying a conclusion
+ * without its reason, and would cost a structural key, a diagnostic and a form
+ * control that the manifest already gives for nothing.
+ *
+ * It sits beside the region vocabulary rather than beside the other verbs
+ * because the only question anything asks it is which word goes over a region:
+ * `steps:` is one key holding a loop's children and a try's protected body
+ * alike, and this is what tells them apart.
+ */
+export declare const TRY_VERB = "core.try";
+/**
+ * The verb that repeats its children until a condition holds.
+ *
+ * It sits beside `TRY_VERB` and the region vocabulary because the only question
+ * anything asks it here is whether a region always runs: a `core.repeat` tests
+ * its `until` AFTER the body, so the body runs at least once, while a
+ * `core.for_each`'s list may be empty and its body may never run. `steps:` is
+ * one key holding both, so the verb is what tells them apart.
+ */
+export declare const REPEAT_VERB = "core.repeat";
+/** Which of a container's child regions a step list is. */
+export type RegionKind = 'branch' | 'body' | 'handler';
+/**
+ * One child region a container Step owns, and which region it is.
+ *
+ * A Fork contributes one per Branch, a `core.for_each` and a `core.repeat` one
+ * body each, and a `core.try` two — a body under `steps:` and a handler under
+ * `handler:` (ADR-0013).
+ */
+export interface Region {
+    readonly kind: RegionKind;
+    readonly steps: readonly Step[];
+    /**
+     * The word that goes over this region — `if` / `else if` / `else` / `and`
+     * over a Branch, `attempt` or `loop` over a body, `on failure` over a
+     * handler.
+     *
+     * Here rather than at each surface, because two surfaces draw every region:
+     * `<StepList>` puts it in a chip over the region and the canvas puts it in
+     * the band above it, and a word each works out for itself is a word they can
+     * disagree about. `kind` says which region this is and this says what it is
+     * called, so a reader gains both by construction.
+     *
+     * The verb decides the word and never whether the region exists. A `handler:`
+     * on a `core.fork` is meaningless and no runner reads it, but `walkSteps`
+     * still yields the Steps inside it, so a surface refusing to draw it makes
+     * those Steps unreachable rather than absent.
+     */
+    readonly keyword: string;
+    /**
+     * Whether this region runs every time its Step does.
+     *
+     * A Branch does not — its `when` is answered at run time. A `core.try`'s body
+     * does, because it always starts; its handler does not, because it needs a
+     * failure. A `core.repeat`'s body does, because `until` is tested after it; a
+     * `core.for_each`'s does not, because the list may be empty.
+     *
+     * That is the same line `alwaysReturns` in validity.ts draws to decide whether
+     * a region discharges a Block's obligation to return — one question, "is this
+     * region guaranteed to run at all", asked here of geometry and there of
+     * validity. Two readings of it are two answers waiting to disagree.
+     */
+    readonly always: boolean;
+    /** The Branch this region is. Absent on a body and on a handler. */
+    readonly branch?: Branch;
+}
+/**
+ * The regions one Step owns, in document order.
+ *
+ * The single answer to "what does this Step nest". Every traversal of the tree
+ * asks that question, and one that answers it for itself is one that can forget
+ * a region — a region no rule then sees, reported by nothing, in silence. That
+ * has to be spelled out once so a reader gains coverage of a new region by
+ * construction rather than by remembering to ask for it.
+ *
+ * The region is named rather than yielded as a bare list because a reader that
+ * says something different about each — the word over it, whether it always
+ * runs — still has to get its regions from here.
+ */
+export declare function regionsOf(step: Step): Generator<Region>;
+/**
+ * Whether a Step owns child regions at all.
+ *
+ * Asked of `regionsOf` rather than of the three keys, so "container" and "what a
+ * container nests" cannot come apart — a fourth region would otherwise be
+ * walked by every reader while still reading as a leaf to whichever surface
+ * decides how tall a card is or whether it collapses.
+ */
+export declare const isContainer: (step: Step) => boolean;
+/**
+ * What a Step is called on screen: its name, falling back to its id.
+ *
+ * An id is the one thing a Step always has, and it is what a user typed if they
+ * hand-wrote the file. Here rather than at each surface because the list, the
+ * canvas and every sentence a screen reader hears have to name one Step one
+ * way — two spellings is a card and a row that look like two Steps.
+ */
+export declare const nameOf: (step: Step) => string;
+/**
+ * What makes a Step structural, in words: `core.fork · 2 branches`,
+ * `core.try · 1 step · handler`.
+ *
+ * Enumerated off `regionsOf` rather than off the three step keys, so a region
+ * added to the walk shows up in the summary by construction. A summary read off
+ * `steps:` alone says `core.try` on a try carrying only a handler — a card with
+ * a chevron and an `on failure` region under it, describing itself as a leaf.
+ *
+ * A leaf's summary is its verb and nothing else, which is why the canvas shows
+ * this only on the cards `isContainer` makes taller: `LAYOUT.nodeHeight` is "a
+ * card with a name and nothing else", so a leaf card has nowhere to put a row.
+ * One predicate decides the height and the content, and they cannot come apart.
+ */
+export declare function summaryOf(step: Step): string;
+/**
+ * Depth-first walk of every step in one tree, parents before children.
+ *
+ * Every region a container owns is walked here and nowhere else. A region
+ * `regionsOf` forgets is a region no rule ever sees — the validator reports
+ * nothing about it, silently, which is the same failure as a validator that
+ * only ever looked at the root Board.
+ */
+export declare function walkSteps(steps: readonly Step[]): Generator<Step>;
+/**
+ * Every Step in the document, tagged with the Board it is on.
+ *
+ * `walkSteps` is the primitive — "walk this list" — and this is what supplies it
+ * every list there is. A rule written against this one gains Block coverage by
+ * construction rather than by remembering to ask for it.
+ */
+export declare function walkDocument(doc: WorkflowDefinition): Generator<StepRef & {
+    step: Step;
+}>;
+/**
+ * One string naming one Step, for the places that need a flat key — a `Map`, a
+ * React key, a `data-` attribute.
+ *
+ * Minted here rather than concatenated at each call site: five hand-rolled
+ * spellings are five chances to pick a different separator, and two of them
+ * disagreeing is a diagnostic filed under a key nothing looks up. `/` is safe
+ * because the schema holds every id to an identifier, which cannot contain one.
+ */
+export declare const stepKey: ({ board, id }: StepRef) => string;
+/**
+ * One Board as a string, for a reader that holds something per Board.
+ *
+ * Prefixed rather than the bare id, because the root Board is `null` and a
+ * Block whose id is the empty string would key the same — so the two would
+ * share whatever is held, and opening that Block would find the root's.
+ *
+ * Minted here for the reason `stepKey` is: a viewport keyed one way and a
+ * selection keyed another are two maps that disagree about which Board is which.
+ */
+export declare const boardKey: (id: BoardId) => string;
+/**
+ * One child region, and the Step it hangs under.
+ *
+ * A `StepRef` widened by which of that Step's regions this is, because a
+ * `core.try` owns two and a Fork owns *n* — so a Step alone does not name one.
+ * The shape composes with what a `Band` already carries, so the canvas can name
+ * the region it is drawing without a second enumeration.
+ *
+ * Named by `kind` rather than by an ordinal into `regionsOf`, because anything
+ * held against a region — which one is folded shut — outlives the edits made
+ * while it is held. A body and a handler have a `kind` that names them
+ * outright, so neither takes a number and neither can move: adding a Branch to
+ * a Fork that also carries a `handler:` would have shifted an ordinal.
+ *
+ * **A Branch is not stable, and cannot be.** `branchIndex` is an ordinal into
+ * `branches:`, so inserting a Branch before it moves the fold onto its
+ * neighbour. There is nothing better to use: a Branch carries no id, and the
+ * schema refuses its `label` for identity because that is free text a user
+ * renames. Naming a Branch by *where it is* is the whole of what is available,
+ * and the narrower spelling buys the other two regions and not this one.
+ */
+export interface RegionRef {
+    readonly board: BoardId;
+    /** The container Step that owns the region. */
+    readonly id: string;
+    readonly kind: RegionKind;
+    /** Which of the owner's Branches this is. Absent on a body and on a handler. */
+    readonly branchIndex?: number;
+}
+/**
+ * One string naming one region, for the places that need a flat key — a `Set`, a
+ * React key, a `data-` attribute.
+ *
+ * Minted beside `stepKey` and for the same reason: hand-rolled spellings are
+ * chances to pick a different separator, and two readers disagreeing about the
+ * spelling is a region folded under a key nothing looks up. `#` and `:` are safe
+ * because the schema holds every id to an identifier, which contains neither.
+ */
+export declare const regionKey: ({ board, id, kind, branchIndex }: RegionRef) => string;
+/** A Step by Board and id. Both halves are needed: ids are Board-local. */
+export declare function findStep(doc: WorkflowDefinition, ref: StepRef): Step | undefined;
+/**
+ * The variables one Board declares: the workflow's at the root, a Block's inside
+ * one.
+ *
+ * This is the whole of "a `core.set_var` can never reach out of the Board it is
+ * on" — there is no second list to fall back to, so a Block naming a workflow
+ * variable is an unknown name rather than a scope a runner resolves differently.
+ *
+ * Exported because a runner has to answer the same question the builder does,
+ * and the Go SDK's `VarsOn` is this function: a rule restated at two call sites
+ * is two rules the day one of them gains a fallback.
+ */
+export declare const varsOn: (doc: WorkflowDefinition, board: BoardId) => readonly Variable[];
+/** One Board's variable by key, or undefined when that Board declares none. */
+export declare const variableOn: (doc: WorkflowDefinition, board: BoardId, key: string) => Variable | undefined;
+/** Every step id on one Board, for detecting references to steps that vanished. */
+export declare function stepIds(doc: WorkflowDefinition, board: BoardId): Set<string>;

package/dist/tree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/validity.d.ts

@@ -0,0 +1,167 @@
+import { FunctionDeclarations } from '@hatua/expressions';
+import { ContextKey, Manifest, WorkflowDefinition } from '@hatua/schema';
+import { ConnectionTypes } from './connections';
+import { Diagnostic } from './diagnostic';
+/**
+ * Whether a Workflow Definition is filled in enough to run — the rules that read
+ * a Step against its Component Manifest, the verbs Hatua interprets
+ * structurally, the contract a Block declares, and the Connections a `conn`
+ * field may hold.
+ *
+ * Here rather than in @hatua/services for the same reason `tree.ts` is: these
+ * are pure domain rules over the typed projection, so a Host's runner can hold
+ * a definition to exactly what the builder held it to. The store that watches
+ * them and the region that draws a dot are separate concerns and live
+ * elsewhere.
+ *
+ * Every code and what it blocks is declared in
+ * `schemas/definition-diagnostics.yaml` and generated into both languages,
+ * because `blocks` is part of the contract: a code that stopped Publish here and
+ * merely informed in Go would let a workflow publish from one builder and not
+ * another.
+ *
+ * Nothing below walks `doc.steps`. `walkDocument` yields every Step on every
+ * Board, so a rule written here covers a Block's steps by construction — the
+ * alternative is a validator that reports nothing about three Blocks, silently,
+ * because it only ever looked at the root.
+ */
+type ManifestIndex = ReadonlyMap<string, Manifest>;
+/**
+ * Whether a field is shown, and therefore whether it can be missing.
+ *
+ * `when: [otherKey, value]` shows a field only while another field equals a
+ * value — it is how one trigger component reshapes its form across schedule,
+ * API and upstream modes. Counting a hidden field as unfilled would mark a Step
+ * invalid for a field the user cannot see, let alone fill.
+ *
+ * Exported because the form that draws the fields has to ask the same question,
+ * and two copies of it are two answers waiting to disagree: a hidden field that
+ * starts blocking Publish, or a visible required one that stops being reported.
+ * `reference.ts` and `slots.ts` refuse the same duplication for the same
+ * reason — the rule lives once, in the package that owns the domain.
+ */
+export declare const fieldVisible: (field: Manifest["fields"][number], values: Record<string, unknown>) => boolean;
+/**
+ * Required fields with nothing in them, per Step.
+ *
+ * A call and a `core.return` are checked against a declaration rather than a
+ * manifest — `block.<id>`'s fields are the Block's `params`, and a return's are
+ * the Block's `outputs`. Every parameter is required: a declaration IS the
+ * contract, and an optional one would be a second concept for a Block to carry.
+ */
+export declare function missingRequiredFields(doc: WorkflowDefinition, manifests: ManifestIndex): Diagnostic[];
+/**
+ * A Step or a Trigger whose verb nothing declares.
+ *
+ * The two roots fail differently, so they are two codes. A `component.*` verb
+ * nothing declares blocks editing, because building cannot produce it: the
+ * catalogue only offers what it declares, so it means a hand-edit or a Host that
+ * dropped a component — and in the second case the fields are gone too, so there
+ * is nothing to fill in. A `block.*` verb naming nothing blocks Publish only:
+ * renaming or deleting a block is ordinary building, and locking the document
+ * for editing over a name the user can fix three lines away would be absurd.
+ *
+ * Triggers are checked alongside Steps because the same mistake is possible in
+ * `triggers:` and has the same consequence: `missingRequiredFields` returns
+ * early for a manifest it cannot find, so without this a Trigger naming a verb
+ * nothing declares produces no diagnostic at all, while the Board panel draws
+ * it as a card that says its type is unknown.
+ */
+export declare function unknownComponents(doc: WorkflowDefinition, manifests: ManifestIndex): Diagnostic[];
+/**
+ * The verbs Hatua interprets structurally, held to what they mean.
+ *
+ * These are read from the tree rather than from a manifest, because a manifest
+ * cannot express them: `core.fork`'s Branches and `core.for_each`'s body are
+ * positions in the document, not fields under `with:`.
+ */
+export declare function malformedContainers(doc: WorkflowDefinition, manifests?: ManifestIndex): Diagnostic[];
+/**
+ * The rules a Block carries: recursion, where a return may sit, and whether one
+ * is reached.
+ *
+ * Recursion is answered here rather than by a runner's depth limit because
+ * ADR-0013 refuses it at design time — "unbounded recursion is the jump problem
+ * wearing a contract's clothes" — so both builders refuse the same document
+ * rather than one of them discovering it in production.
+ */
+export declare function blockRules(doc: WorkflowDefinition): Diagnostic[];
+/** Every step-level rule, in one pass, indexed by the Step it belongs to. */
+export interface Validity {
+    /**
+     * Diagnostics for each Step that has any, keyed by `stepKey` — Board and id
+     * together, because a Block's `ret` and another Block's `ret` are two Steps.
+     */
+    byStep: ReadonlyMap<string, Diagnostic[]>;
+    /** The same, for Triggers, which are not Steps and are drawn by another region. */
+    byTrigger: ReadonlyMap<string, Diagnostic[]>;
+    /** The same, for what belongs to a Block rather than to any Step in it. */
+    byBlock: ReadonlyMap<string, Diagnostic[]>;
+    /**
+     * The same, for what belongs to a Connection rather than to any Step using it.
+     *
+     * Only CONNECTION_NOT_ESTABLISHED files here: the other connection codes are
+     * raised at a field, so they name a Step or a Trigger as well and belong on
+     * the row the user can act on. A Connection declared and never wired is at
+     * fault on its own — it is unfinished whether or not anything points at it
+     * yet — and there is no Step to hang it on.
+     *
+     * A fourth map for the reason the second and third exist, and the fault is
+     * filed once here rather than raised again at every field that points at the
+     * Connection — the duplication `troubledBlocks` refuses for a call, one seam
+     * over: a Publish gate counting faults must not count one Connection five
+     * times because five Steps use it. The `conn` field that draws it looks the
+     * Connection up by the id it holds.
+     */
+    byConnection: ReadonlyMap<string, Diagnostic[]>;
+    /**
+     * Everything, in the order the rules ran.
+     *
+     * Returned rather than left to a caller to flatten out of `byStep`: a
+     * diagnostic about a Trigger has no `stepId`, so flattening the Step map
+     * silently drops it — and a Publish gate counting what it found there would
+     * pass a workflow whose Trigger is missing a required field.
+     */
+    all: readonly Diagnostic[];
+}
+/**
+ * Every Template on every Board, checked against the type its field declares
+ * and the scope its Step can see.
+ *
+ * The fifth rule family, and the one that reaches into a different package:
+ * `@hatua/expressions` owns the grammar and the checking, and has done since
+ * before anything called it. What was missing was the walk — "which Templates
+ * are there, and what may each of them address" is a question about a Workflow
+ * Definition, which is this package's subject and not that one's.
+ *
+ * **Errors only.** An expression diagnostic carries a severity, and a warning
+ * informs without blocking anything (ADR-0009's gradual typing: an unprovable
+ * type defers to run time). A `Diagnostic` here carries `blocks` instead, whose
+ * two values both block something, so a warning has nothing to become. The
+ * Inspector calls `validate` itself and renders every severity; this pass exists
+ * to mark cards and gate Publish, and neither is a warning's business.
+ *
+ * **Steps only.** A Trigger's fields and a Variable's initial value are
+ * Templates too, and neither has a scope anyone has defined — `scopeFor` takes a
+ * `StepRef` because a scope is a position in a tree, and a Trigger is upstream
+ * of every position. Checking them against a scope invented here would be a
+ * second answer to a question the model has not been asked yet.
+ */
+export declare function expressionRules(doc: WorkflowDefinition, manifests: ManifestIndex, context?: readonly ContextKey[], functions?: FunctionDeclarations): Diagnostic[];
+/**
+ * Every rule family over every Board, filed by the subject each one names.
+ *
+ * `connectionTypes` is the one input that is not the document or a manifest. A
+ * Connection stores an opaque `ref` and nothing more (ADR-0007), so its type
+ * comes from the Host, asynchronously, and may never come at all — a Host that
+ * wires no `ConnectionSource` is correctly configured, not broken.
+ *
+ * **Absence narrows this pass; it never stops it.** Handed no types, the two
+ * connection codes that need one go unreported and every other family runs
+ * exactly as it would have. The alternative — returning nothing until the
+ * Connections arrive — would leave a Host that wires no `ConnectionSource` with
+ * no validation whatsoever, silently, including the rules that have nothing to
+ * do with Connections. See ADR-0022.
+ */
+export declare function validateDefinition(doc: WorkflowDefinition, manifests: ManifestIndex, context?: readonly ContextKey[], connectionTypes?: ConnectionTypes): Validity;
+export {};

package/dist/validity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,17 +1,39 @@
 {
   "name": "@hatua/model",
-  "version": "0.0.0",
-  "description": "Placeholder reserving the name. Nothing is published here; see 0.1.0 and later.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Internal to @hatua/react — published because it is an external of its build, not a supported API. Pure domain rules over the step tree: references, scope, validation.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pedromvgomes/hatua.git",
     "directory": "source/packages/model"
   },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "@hatua/schema": "0.1.0",
+    "@hatua/expressions": "0.1.0",
+    "@hatua/document": "0.1.0"
+  },
+  "devDependencies": {
+    "yaml": "^2.8.1"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reporter=lcovonly --passWithNoTests"
+  }
 }

package/README.md

@@ -1,5 +0,0 @@
-# @hatua/model
-
-This version reserves the package name and contains no code.
-
-Install `0.1.0` or later.