@galaxy-tool-util/schema 1.2.0 → 1.5.0

package/dist/workflow/draft-checks.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Pure logic for Galaxy draft workflows (`class: GalaxyWorkflowDraft`).
+ *
+ * Substrate for the `gxwf draft-validate`, `gxwf draft-next-step`, and
+ * `gxwf _draft-extract` CLI commands. No I/O.
+ *
+ * The sentinel constants mirror `gxformat2/draft.py`. Drift is enforced by
+ * `make check-sync-draft-sentinel` against the JSON snapshot in
+ * `schema-sources/v19_09/draft_constants.json`.
+ */
+export declare const TODO_SENTINEL_PATTERN: RegExp;
+export declare const PLAN_FIELDS: readonly ["_plan_state", "_plan_context", "_plan_in", "_plan_out"];
+export type PlanField = (typeof PLAN_FIELDS)[number];
+export declare const DRAFT_CLASS = "GalaxyWorkflowDraft";
+export declare function isTodoSentinel(value: unknown): value is string;
+export declare function isDraftWorkflow(doc: unknown): boolean;
+export type StepPath = string[];
+export type TodoLocation = {
+    kind: "tool_id";
+} | {
+    kind: "tool_version";
+} | {
+    kind: "in_key";
+    key: string;
+} | {
+    kind: "out_id";
+    id: string;
+} | {
+    kind: "output_source";
+    output_label: string;
+    port: string;
+};
+export interface TodoHit {
+    path: StepPath;
+    location: TodoLocation;
+    sentinel: string;
+}
+export interface PlanHit {
+    path: StepPath;
+    field: PlanField;
+    value: string;
+}
+export interface DraftSurvey {
+    /** True iff `doc.class === "GalaxyWorkflowDraft"`. */
+    isDraft: boolean;
+    /** TODO sentinel hits in declaration order across the (sub)workflow tree. */
+    todos: TodoHit[];
+    /** `_plan_*` field hits on draft steps across the (sub)workflow tree. */
+    planFields: PlanHit[];
+}
+/**
+ * Walk a draft workflow once, returning every TODO sentinel and `_plan_*`
+ * field with its step path. Non-draft documents return `{ isDraft: false }`
+ * with empty arrays.
+ *
+ * Step paths are `[outerLabel, ..., innerStepLabel]`. Subworkflows recurse
+ * only when the inner `run:` block also carries `class: GalaxyWorkflowDraft`.
+ *
+ * Note: this survey is step-focused — it intentionally does NOT report
+ * top-level `_plan_*` fields on a draft workflow root. Those are flagged
+ * by `validateDraft` (a rules-focused walker); `detectDraft` exists to
+ * drive `nextDraftStep` / `extractConcreteSubset`, which only act on
+ * per-step state.
+ */
+export declare function detectDraft(workflow: unknown): DraftSurvey;
+export interface DraftValidationDiagnostic {
+    /** Step path; empty array for workflow-level diagnostics. */
+    path: StepPath;
+    message: string;
+}
+export interface DraftValidationResult {
+    ok: boolean;
+    structureErrors: DraftValidationDiagnostic[];
+    topologyErrors: DraftValidationDiagnostic[];
+    semanticErrors: DraftValidationDiagnostic[];
+    warnings: DraftValidationDiagnostic[];
+    survey: DraftSurvey;
+}
+/**
+ * Validate a draft Galaxy workflow. Collects all diagnostics — does not throw.
+ *
+ *   structureErrors  Effect Schema decode failures.
+ *   topologyErrors   Concrete-topology must hold even in drafts: workflow
+ *                    input labels, output labels, step labels, and step types
+ *                    cannot be TODO sentinels. Step/port edge refs must
+ *                    resolve to a declared step + declared port (TODO_*
+ *                    ports count if declared in the step's `out:`).
+ *   semanticErrors   TODO-shaped strings (start with `TODO`) that don't
+ *                    match the canonical sentinel form (e.g. `TODO-foo`,
+ *                    `TODOfoo`, `TODO_` trailing).
+ *   warnings         Bare `TODO` in port position; top-level `_plan_*`.
+ *
+ * The returned `survey` is the same shape detectDraft() returns and is
+ * usable by downstream nextDraftStep / extractConcreteSubset callers.
+ */
+export declare function validateDraft(workflow: unknown): DraftValidationResult;
+export type NextStepResult = {
+    draft: false;
+} | {
+    draft: true;
+    step: StepPath;
+    work: string[];
+};
+/**
+ * Pick the next step a downstream agent should work on. Pure function;
+ * idempotent — same input → same output, byte-for-byte.
+ *
+ * Walks steps in topological order (steps with no draft-step source deps
+ * first), tie-breaking by alphabetical step label. The first step that
+ * carries any TODO sentinel or `_plan_*` field is returned with a
+ * prompt-shaped `work[]` array. Subworkflows (draft inner `run:`) are
+ * descended only after their outer step is itself fully concrete.
+ *
+ * Returns `{ draft: false }` when the workflow has no remaining work
+ * (this includes non-draft documents — there is nothing to do).
+ */
+export declare function nextDraftStep(workflow: unknown): NextStepResult;
+export type DropReason = {
+    kind: "step_has_todo";
+    locations: TodoLocation[];
+} | {
+    kind: "step_has_plan_field";
+    fields: PlanField[];
+} | {
+    kind: "cascade";
+    depends_on: StepPath[];
+};
+export interface DroppedStep {
+    path: StepPath;
+    reason: DropReason;
+}
+export interface DroppedOutput {
+    /**
+     * Step path of the workflow the output lives in. `[]` for the top-level
+     * document; `[outerStep, ...]` for inner subworkflow outputs.
+     */
+    path: StepPath;
+    label: string;
+    reason: DropReason;
+}
+export interface RewrittenStepInput {
+    path: StepPath;
+    in_key: string;
+    /** Dropped step/port refs removed from this input's `source:`. */
+    removed_refs: string[];
+    /** Surviving step/port refs after the rewrite. Empty when only a `default:` keeps the entry alive. */
+    surviving_refs: string[];
+}
+export interface ExtractResult {
+    /**
+     * Trimmed workflow dict. Still carries `class: GalaxyWorkflowDraft` —
+     * promoting to `GalaxyWorkflow` is the CLI command's call, not B's.
+     * `_plan_*` fields are preserved verbatim (including top-level fields and
+     * any survivor steps — though by construction survivor steps never have
+     * `_plan_*`, since carrying one is itself a drop trigger). Stripping lives
+     * in the `clean` module (E).
+     */
+    workflow: unknown;
+    /**
+     * Dropped steps across the (sub)workflow tree. Ordering within a single
+     * workflow level: by cascade round (round 0 = direct TODO/_plan_* drops;
+     * rounds 1+ = cascade drops), then by alphabetical step-path within a
+     * round. Across levels: a level's drops come first, then for each
+     * surviving subworkflow step (in source iteration order) its drops
+     * follow, recursively. Cascade rounds are local to a workflow level — not
+     * compared across nesting.
+     *
+     * `cascade.depends_on` paths point at the steps cited in the dead `in:`.
+     * In the common case these appear in `dropped_steps` themselves; in the
+     * subworkflow-port-loss case the cited path may be a *surviving* outer
+     * subworkflow step whose inner workflow lost the referenced port — look
+     * under that step's recursed inner drops for the underlying cause.
+     */
+    dropped_steps: DroppedStep[];
+    /**
+     * Workflow outputs dropped because their source step / port went away.
+     * Carries `path` to distinguish top-level outputs (`path: []`) from inner
+     * subworkflow outputs (`path: [outerStep, ...]`). Ordered alphabetically
+     * by label within a level; across levels, top-level first, then per
+     * surviving subworkflow step in iteration order.
+     */
+    dropped_outputs: DroppedOutput[];
+    /**
+     * Per-input rewrites where the source survived in part. Two cases:
+     *   - Multi-source input lost some refs but kept others (rewritten to the
+     *     surviving subset; string form if 1 left, list form if >1).
+     *   - Single-source input lost its only ref but the input has a `default:`
+     *     so the entry stays alive — `surviving_refs` is empty, the rewritten
+     *     value retains the default and drops the `source:` key.
+     */
+    rewritten_step_inputs: RewrittenStepInput[];
+}
+/**
+ * Trim a draft workflow down to its concrete subset: drop any step that
+ * carries a TODO sentinel or `_plan_*` field, then cascade-drop steps whose
+ * `in:` becomes dead, then drop workflow outputs whose source went away.
+ * Multi-source inputs are rewritten in place to the surviving ref subset.
+ *
+ * Pure + idempotent. The result always carries `class: GalaxyWorkflowDraft`
+ * — promotion to concrete is a CLI-layer decision (E).
+ *
+ * Non-draft inputs pass through unchanged with empty drop / rewrite arrays.
+ */
+export declare function extractConcreteSubset(workflow: unknown): ExtractResult;
+//# sourceMappingURL=draft-checks.d.ts.map

package/dist/workflow/draft-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-checks.d.ts","sourceRoot":"","sources":["../../src/workflow/draft-checks.ts"],"names":[],"mappings":"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"}