Reference

Command line

ulang-lite check FILE...
ulang-lite eval FILE... --action ACTION --facts FACTS.json
ulang-lite format FILE

Run it as node vendor/ulang-lite/bin/ulang-lite.ts, or through the ./ulang-lite wrapper from Install as below. Every example on this page was run when the site was built.

Exit status	Meaning
`0`	success
`1`	a file or the facts were rejected
`2`	usage error

check

Parses and validates every contract in each file. For a valid contract it prints one line with the clause count, the actions and the digest; for a rejected file, one diagnostic.

example projectreal output

$ ./ulang-lite check policy/deploy.ul
policy/deploy.ul: ok ProductionDeploy (6 clauses; actions deploy, rollback; sha256 686358ddc154b77b5b7b3a24870b8dd6f79b23d376ed039d6824a923284e4059)

example projectreal output

$ ./ulang-lite check scratch/typo.ul
scratch/typo.ul:29:24: unsupported[unknown-field]: unknown field DeployRequest.error_rate
[exit status 1]

eval

Loads the files, finds the one contract that lists the action, checks the facts and decides. Prints one line of JSON.

example projectreal output

$ ./ulang-lite eval policy/deploy.ul --action deploy --facts facts/green.json
{"verdict":"PERMIT","clause_id":"ProductionDeploy.deploy.permit","contract_sha256":"686358ddc154b77b5b7b3a24870b8dd6f79b23d376ed039d6824a923284e4059"}

example projectreal output

$ ./ulang-lite eval policy/deploy.ul --action deploy --facts facts/freeze.json
{"verdict":"DENY","clause_id":"ProductionDeploy.change_freeze","contract_sha256":"686358ddc154b77b5b7b3a24870b8dd6f79b23d376ed039d6824a923284e4059"}

example projectreal output

$ ./ulang-lite eval policy/deploy.ul --action deploy --facts facts/bad-type.json
facts/bad-type.json: invalid type or domain for DeployRequest.approvals
[exit status 1]

example projectreal output

$ ./ulang-lite eval policy/deploy.ul --action hotfix --facts facts/green.json
no contract triggers action hotfix
[exit status 1]

An action listed by more than one loaded contract is refused as well.

format

Prints the canonical text of a valid file: comments dropped, one fixed layout, numbers normalised. The SHA-256 of a contract's canonical text is the digest check prints.

example projectreal output

$ ./ulang-lite format policy/deploy.ul
CONTRACT ProductionDeploy {
  ENFORCEMENT_MODE: enforced
  CONTEXT {
    ENTITIES DeployRequest {
      environment: string
      tests_passed: bool
      approvals: int
      author_approved_own_change: bool
      error_rate_pct: float
      change_freeze: bool
    }
    CONSTANTS {
      min_approvals: int == 2 [SOURCE:ENG-HANDBOOK-7.1]
      max_error_rate_pct: float == 1.5 [SOURCE:SRE-SLO-3]
    }
  }
  TRIGGER {
    deploy()
    rollback()
  }
  GUARANTEE {
    ENSURE deploy() WHEN DeployRequest.tests_passed == true [SOURCE:tests_green]
    ENSURE deploy() WHEN DeployRequest.approvals >= min_approvals [SOURCE:two_approvals]
  }
  PROHIBITION {
    FORBID deploy WHEN DeployRequest.change_freeze == true AND DeployRequest.environment == "production" [SOURCE:change_freeze]
    FORBID deploy WHEN DeployRequest.author_approved_own_change == true [SOURCE:no_self_approval]
    FORBID deploy WHEN DeployRequest.error_rate_pct > max_error_rate_pct [SOURCE:error_budget]
    FORBID rollback WHEN DeployRequest.environment != "production" AND DeployRequest.environment != "staging" [SOURCE:known_environments]
  }
  OBSERVABILITY {
    LOG "deploy decision" ON decision
  }
}

Diagnostics and usage errors

Diagnostics read file:line:column: kind[code]: message, with columns counted in Unicode code points. Every code is explained under Diagnostics. A usage error goes to standard error:

example projectreal output

$ ./ulang-lite
usage: ulang-lite check FILE...
       ulang-lite eval FILE... --action ACTION --facts FACTS.json
       ulang-lite format FILE
[exit status 2]