@flowget/graph-validation 0.2.0 → 0.3.0

package/README.md

@@ -42,7 +42,9 @@ What it does:
 - **`validateTriggerInputs(graph, catalog, input)`** — a run-input gate: flags
   every `{{ trigger.<path> }}` the graph references that the run input (the
   builder's test input, or the worker's real event payload) does not provide,
-  path-aware and false-positive-free.
+  path-aware and false-positive-free. Config traversal is bounded (a
+  stack-overflow-DoS guard); a reference nested deeper than the bound is left to
+  the runtime resolver's non-retryable throw rather than pre-checked.
 
 ## Install
 

package/dist/field-tree.js

@@ -108,8 +108,11 @@ export function resolvePath(tree, pathSegments) {
     if (pathSegments.length === 0)
         return { kind: "known" };
     // A malformed drill-in with an empty segment (a trailing/interior dot, e.g.
-    // `{{ trigger. }}`) is permissive — the grammar admits it, but it names no
-    // declared key, so flagging it would be a false positive (unchanged behavior).
+    // `{{ trigger. }}` / `{{ a..b }}`) is permissive HERE — resolvePath is pure
+    // declaration resolution. The empty segment is a grammar-level error that the
+    // reference walker flags upstream (`hasEmptyPathSegment` →
+    // TEMPLATE_EMPTY_SEGMENT, single-operand-only), mirroring the engine's
+    // unconditional runtime throw; resolvePath must not also mis-resolve it here.
     if (pathSegments.some((s) => s === ""))
         return { kind: "known" };
     let level = tree.root;

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { collectReferencedTriggerPaths, validateTriggerInputs, } from "./trigger
 export { buildFieldTree, type FieldPathConflict, type FieldTree, type FieldTreeNode, type PathResolution, resolvePath, } from "./field-tree.js";
 export { ISSUE_CODES, type IssueCode, type ValidationIssue, type ValidationSeverity, } from "./issues.js";
 export { type CatalogIndex, type CatalogNode, indexCatalog, resolveNodeOutputFields, resolveNodeTriggerPayload, } from "./catalog.js";
-export { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasForbiddenPathToken, hasTemplateExpression, isReservedNamespace, isWholeStringTemplate, MAX_TEMPLATE_LENGTH, parseTemplate, parseTemplateExpression, RESERVED_NAMESPACES, templateExpressions, } from "./template-ast.js";
+export { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasEmptyPathSegment, hasForbiddenPathToken, hasTemplateExpression, isReservedNamespace, isWholeStringTemplate, MAX_TEMPLATE_LENGTH, parseTemplate, parseTemplateExpression, RESERVED_NAMESPACES, templateExpressions, } from "./template-ast.js";
 export { isAssignable, isConcreteScalar, isWildcardValueType, jsValueType, } from "./value-type.js";
 export { buildReversedAdjacency, collectUpstream, collectUpstreamFrom, } from "./reachability.js";
 export { compareFieldCoherence, type CoherenceMismatch, type CoherenceMismatchKind, type SchemaFieldProjection, type SchemaProjection, } from "./coherence.js";

package/dist/index.js

@@ -23,7 +23,7 @@ export { ISSUE_CODES, } from "./issues.js";
 // ── Input interface (catalog + output resolution) ───────────
 export { indexCatalog, resolveNodeOutputFields, resolveNodeTriggerPayload, } from "./catalog.js";
 // ── Template-grammar classifier → @flowget/types TemplateAst ─
-export { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasForbiddenPathToken, hasTemplateExpression, isReservedNamespace, isWholeStringTemplate, MAX_TEMPLATE_LENGTH, parseTemplate, parseTemplateExpression, RESERVED_NAMESPACES, templateExpressions, } from "./template-ast.js";
+export { classifyPathKind, findMalformedTemplateTokens, FORBIDDEN_PATH_TOKENS, hasEmptyPathSegment, hasForbiddenPathToken, hasTemplateExpression, isReservedNamespace, isWholeStringTemplate, MAX_TEMPLATE_LENGTH, parseTemplate, parseTemplateExpression, RESERVED_NAMESPACES, templateExpressions, } from "./template-ast.js";
 // ── Coarse value-type lattice ───────────────────────────────
 export { isAssignable, isConcreteScalar, isWildcardValueType, jsValueType, } from "./value-type.js";
 // ── Reachability ────────────────────────────────────────────

package/dist/issues.d.ts

@@ -77,6 +77,15 @@ export declare const ISSUE_CODES: {
     readonly RUN_INPUT_MISSING: "validation/run-input-missing";
     /** A template path uses a forbidden prototype-chain token. */
     readonly TEMPLATE_FORBIDDEN_TOKEN: "validation/template-forbidden-token";
+    /**
+     * A template path has an empty/blank segment — a leading, trailing, or
+     * doubled dot (`{{ trigger. }}`, `{{ steps.x.output. }}`, `{{ a..b }}`). The
+     * engine resolver throws `missing_path` / `missing_step` on an empty token
+     * UNCONDITIONALLY (input-independent), so the static verdict flags it too.
+     * Checked per-operand for a single-operand expression only — a `??` chain
+     * rescues the throw, so flagging inside a chain would be a false positive.
+     */
+    readonly TEMPLATE_EMPTY_SEGMENT: "validation/template-empty-segment";
     /** A whole-string template resolves to a value-type incompatible with the consumer field. */
     readonly TYPE_MISMATCH: "validation/type-mismatch";
     /** A required field is empty. */

package/dist/issues.js

@@ -54,6 +54,15 @@ export const ISSUE_CODES = {
     RUN_INPUT_MISSING: "validation/run-input-missing",
     /** A template path uses a forbidden prototype-chain token. */
     TEMPLATE_FORBIDDEN_TOKEN: "validation/template-forbidden-token",
+    /**
+     * A template path has an empty/blank segment — a leading, trailing, or
+     * doubled dot (`{{ trigger. }}`, `{{ steps.x.output. }}`, `{{ a..b }}`). The
+     * engine resolver throws `missing_path` / `missing_step` on an empty token
+     * UNCONDITIONALLY (input-independent), so the static verdict flags it too.
+     * Checked per-operand for a single-operand expression only — a `??` chain
+     * rescues the throw, so flagging inside a chain would be a false positive.
+     */
+    TEMPLATE_EMPTY_SEGMENT: "validation/template-empty-segment",
     /** A whole-string template resolves to a value-type incompatible with the consumer field. */
     TYPE_MISMATCH: "validation/type-mismatch",
     /** A required field is empty. */

package/dist/references.js

@@ -28,7 +28,7 @@ import { resolveNodeOutputFields, resolveNodeTriggerPayload, } from "./catalog.j
 import { buildFieldTree, resolvePath, } from "./field-tree.js";
 import { ISSUE_CODES } from "./issues.js";
 import { buildReversedAdjacency, collectUpstreamFrom } from "./reachability.js";
-import { hasForbiddenPathToken, hasTemplateExpression, isWholeStringTemplate, parseTemplate, templateExpressions, } from "./template-ast.js";
+import { hasEmptyPathSegment, hasForbiddenPathToken, hasTemplateExpression, isWholeStringTemplate, parseTemplate, templateExpressions, } from "./template-ast.js";
 import { isAssignable, isConcreteScalar } from "./value-type.js";
 /** Bound on nested-data recursion (rows / key-value / nested objects). */
 const MAX_DATA_DEPTH = 64;
@@ -144,6 +144,22 @@ function validateTemplateString(raw, isTopLevel, site, ctx, issues) {
 }
 /** Validate one operand's producer existence + reachability + declared-output. */
 function validateOperandExistence(path, tokenRaw, site, ctx, upstream, issues) {
+    // An empty/blank path segment (`trigger.`, `steps.x.output.`, `a..b`) — the
+    // engine resolver throws `missing_path` / `missing_step` on it UNCONDITIONALLY
+    // (input-independent), so mirror that with a hard error. Grammar-level, like
+    // the forbidden-token guard, so it fires independent of catalog declarations
+    // and BEFORE the namespace/existence logic. Reached only for a single-operand
+    // expression (a `??` chain rescues the throw → flagging inside one is an FP).
+    if (hasEmptyPathSegment(path)) {
+        issues.push({
+            code: ISSUE_CODES.TEMPLATE_EMPTY_SEGMENT,
+            severity: "error",
+            nodeId: site.node.id,
+            fieldKey: site.fieldKey,
+            message: `Node "${site.node.id}" template "${tokenRaw}" has an empty path segment (a leading, trailing, or doubled dot) and will be rejected at runtime.`,
+        });
+        return;
+    }
     if (path.kind === "v1-reserved") {
         const ns = path.segments[0];
         // `workflow.*` / `input.*` are opaque execution primitives — permissive.

package/dist/template-ast.d.ts

@@ -43,6 +43,16 @@ export declare function isReservedNamespace(token: string): boolean;
 export declare const FORBIDDEN_PATH_TOKENS: ReadonlySet<string>;
 /** `true` iff any segment of `path` is a forbidden prototype-chain token. */
 export declare function hasForbiddenPathToken(path: TemplatePath): boolean;
+/**
+ * `true` iff `path` has an empty/blank segment — a leading, trailing, or
+ * doubled dot (`trigger.`, `.foo`, `a..b`, `steps.x.output.`). `PATH_RE`
+ * (`^[\w.-]+$`) admits these, but the engine resolver throws
+ * `missing_path` / `missing_step` on an empty token unconditionally
+ * (input-independent), so a static verdict treats them as invalid. This is a
+ * grammar-level property (like {@link hasForbiddenPathToken}), independent of
+ * any catalog declaration.
+ */
+export declare function hasEmptyPathSegment(path: TemplatePath): boolean;
 /**
  * Defensive upper bound on a template-bearing string. Beyond this the
  * string is treated as a single literal (no token scan) — a belt-and-

package/dist/template-ast.js

@@ -54,6 +54,18 @@ export const FORBIDDEN_PATH_TOKENS = new Set([
 export function hasForbiddenPathToken(path) {
     return path.segments.some((s) => FORBIDDEN_PATH_TOKENS.has(s));
 }
+/**
+ * `true` iff `path` has an empty/blank segment — a leading, trailing, or
+ * doubled dot (`trigger.`, `.foo`, `a..b`, `steps.x.output.`). `PATH_RE`
+ * (`^[\w.-]+$`) admits these, but the engine resolver throws
+ * `missing_path` / `missing_step` on an empty token unconditionally
+ * (input-independent), so a static verdict treats them as invalid. This is a
+ * grammar-level property (like {@link hasForbiddenPathToken}), independent of
+ * any catalog declaration.
+ */
+export function hasEmptyPathSegment(path) {
+    return path.segments.some((s) => s === "");
+}
 /**
  * Defensive upper bound on a template-bearing string. Beyond this the
  * string is treated as a single literal (no token scan) — a belt-and-

package/dist/trigger-inputs.d.ts

@@ -32,6 +32,11 @@
  * This is `input`-shape-agnostic: it never inspects declared payload types, so
  * the identical function serves a seeded test object and a live event payload.
  * (Leaf type-compat on nested paths is deferred — this gate is existence only.)
+ *
+ * **Depth boundary.** Config traversal stops at {@link MAX_DATA_DEPTH} (a
+ * deliberate stack-overflow-DoS guard on untrusted input). A `{{ trigger.… }}`
+ * nested deeper than that in `node.data` is not pre-checked here; it stays
+ * backstopped by the runtime resolver's non-retryable `missing_path` throw.
  */
 import type { WorkflowGraph } from "@flowget/types";
 import { type CatalogNode } from "./catalog.js";

package/dist/trigger-inputs.js

@@ -32,11 +32,28 @@
  * This is `input`-shape-agnostic: it never inspects declared payload types, so
  * the identical function serves a seeded test object and a live event payload.
  * (Leaf type-compat on nested paths is deferred — this gate is existence only.)
+ *
+ * **Depth boundary.** Config traversal stops at {@link MAX_DATA_DEPTH} (a
+ * deliberate stack-overflow-DoS guard on untrusted input). A `{{ trigger.… }}`
+ * nested deeper than that in `node.data` is not pre-checked here; it stays
+ * backstopped by the runtime resolver's non-retryable `missing_path` throw.
  */
 import { indexCatalog } from "./catalog.js";
 import { finalizeIssues, ISSUE_CODES, } from "./issues.js";
 import { hasForbiddenPathToken, hasTemplateExpression, parseTemplate, templateExpressions, } from "./template-ast.js";
-/** Bound on nested-config recursion — mirrors the reference walker. */
+/**
+ * Bound on nested-config recursion — mirrors the reference walker's deliberate
+ * stack-overflow-DoS guard (config values arrive from untrusted input).
+ *
+ * **Parity boundary (intentional, stated):** the engine's runtime template walk
+ * is UNcapped, so a `{{ trigger.<path> }}` buried in `node.data` nested deeper
+ * than this is not collected here and its input is not pre-checked. That
+ * reference is backstopped by the runtime resolver's non-retryable
+ * `missing_path` throw — so a genuinely-missing deep input still fails the run
+ * safely, just at execution rather than pre-flight. Matching the engine's
+ * uncapped walk (removing this guard) would re-expose the DoS and is a separate
+ * cross-repo decision, not this gate's.
+ */
 const MAX_DATA_DEPTH = 64;
 /**
  * Flag every `{{ trigger.<path> }}` the graph references that the run `input`
@@ -131,6 +148,12 @@ function collectFromString(raw, paths) {
         const pathSegments = operand.segments.slice(1);
         if (pathSegments.length === 0)
             continue;
+        // An empty segment (a malformed leading/trailing/doubled dot,
+        // `{{ trigger. }}`) is NOT the run-input gate's concern — a malformed path
+        // names no input key, so `validateGraphStatic`'s reference walker owns
+        // flagging it (TEMPLATE_EMPTY_SEGMENT), and the runtime throws on it
+        // unconditionally regardless. Skipping keeps this gate purely about
+        // referenced-vs-provided.
         if (pathSegments.some((s) => s === ""))
             continue;
         paths.add(pathSegments.join("."));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowget/graph-validation",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Isomorphic, zero-runtime-dependency static validator for Flowget workflow graphs — the single source of validation logic so the builder's pre-submit verdict and the worker's pre-flight verdict are equal by construction. Template-grammar classifier, reference/reachability walker, coarse value-type lattice, and declarative field rules.",
   "keywords": [
     "flowget",