Validate a script before you ship it

Goal

A script proven to parse and compile, without executing it and without supplying any input.

Why bother

A syntax error found by the thing that uses the script is a syntax error found late.

Without this	With this
A typo surfaces when the pipeline runs it	It surfaces in CI, in milliseconds
Checking a script means constructing input for it	No input needed at all
A generated script is trusted until it fails	It is checked before it is stored
Broken scripts reach a deployment	The gate rejects them

The last row is the reason this matters most for generated scripts. A model producing a script needs a fast, deterministic verdict to repair against — and running it is neither fast nor safe.

kis flow -f build.yaml -d

-d plans without executing: it reads the whole definition, resolves every task name against the registry, and validates the parameters. A misspelled task or a missing required field fails here rather than forty minutes into a build.

>> Flow: build.yaml executed in 3.03ms

That is a clean plan — no error lines, and it took milliseconds because nothing ran. A definition with a problem names it instead:

ERR no work instance found of type structrued

kis script validate transform.js

✓ Syntax valid
✓ Compiles successfully

Validation: PASSED

Two checks, and the distinction is useful: syntax is whether it parses, compiles is whether the runtime can build it. A file can parse and still fail to compile.

Neither needs input data, credentials or a running service. That is what makes both usable as a gate rather than as a test.

Step 2 — make it a gate

Flow
Script

Plan every flow in the repository and fail the job if any of them reports an error:

#!/usr/bin/env bash
set -euo pipefail
rc=0
for f in flows/*.yaml; do
  echo "planning $f"
  if kis flow -f "$f" -d 2>&1 | tee /tmp/plan.log | grep -q ' ERR '; then
    echo "  FAILED: $f"; rc=1
  fi
done
exit $rc

Gate on the plan log rather than on the run: a flow that plans clean is a flow whose task names and parameters all resolve, which is the class of mistake worth catching before merge.

validate exits non-zero on failure, so it drops straight into a pipeline:

tasks:
  - name: check-scripts
    shell: |
      set -e
      for f in scripts/*.js; do
        echo "checking $f"
        kis script validate "$f"
      done

set -e is what makes it a gate rather than a report.

Step 3 — check against what you will actually run

Validation auto-detects the language from the file. When a script will run as something other than its extension suggests, say so:

kis script validate rules.txt --runtime starlark

The flow equivalent is checking against the grant you will give it — a script task that will run with namespaces: json,string should be validated the same way, so a call it will not be allowed to make is caught now:

kis script validate transform.js --namespaces json,string

validate versus compile

Command	Answers
`kis script validate`	Does it parse, and does it compile? Reports both, passes or fails
`kis script compile`	Does it compile under this specific language, and how big is it?

Use validate in CI. Use compile when you are choosing a language or debugging why one rejects your file — see Choose a language.

Verify

Break something deliberately and confirm the gate fails.

Flow
Script

cat > /tmp/bad.yaml <<'EOF'
name: broken
tasks:
  - name: oops
    notatask:
      foo: bar
EOF
kis flow -f /tmp/bad.yaml -d 2>&1 | grep ' ERR '

ERR no work instance found of type notatask

echo 'function main() { return }}' > /tmp/bad.js
kis script validate /tmp/bad.js ; echo "exit=$?"

syntax error: JavaScript syntax error: … Unexpected end of input
exit=1

A gate you have never seen fail is a gate you should not trust.

Choose a language
Gate a pipeline on code quality — the same idea for source