Skip to main content

Assertion catalog and CLI

Catalog format: canon-catalog/1. Language: canon-expr/1.

codegate.dependencies​

codegate.dependencies(path: String) -> {configuration_id: String, coverage: String, fan_out_max: Integer, findings_count: Integer, source_id: String, verdict: String}

Collects codegate.dependencies through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

codegate.dependencies.clean​

codegate.dependencies.clean(path: String, source_id: String, configuration_id: String) -> Bool

Recipe:

codegate.dependencies($path).verdict == "pass" and codegate.dependencies($path).findings_count == 0 and codegate.dependencies($path).source_id == $source_id and codegate.dependencies($path).configuration_id == $configuration_id

doc.boolean​

doc.boolean(path: String, pointer: String, format: String = String("json")) -> Bool

Collects document.get through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

doc.integer​

doc.integer(path: String, pointer: String, format: String = String("json")) -> Integer

Collects document.get through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

doc.string​

doc.string(path: String, pointer: String, format: String = String("json")) -> String

Collects document.get through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

ess.conformance.passed​

ess.conformance.passed(path: String, spec_digest: String, implementation: String) -> Bool

Recipe:

ess.report($path).passed > 0 and ess.report($path).failed == 0 and ess.report($path).unsupported == 0 and ess.report($path).errors == 0 and ess.report($path).skipped == 0 and ess.report($path).conformance_status == "passed" and ess.report($path).spec_digest == $spec_digest and ess.report($path).implementation == $implementation

ess.report​

ess.report(path: String) -> {conformance_status: String, errors: Integer, failed: Integer, implementation: String, inventory: List<String>, passed: Integer, skipped: Integer, spec_digest: String, total: Integer, unsupported: Integer}

Collects ess.report through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

ess.run​

ess.run(binding: String) -> {exit_code: Option<Integer>, stderr: String, stdout: String}

Collects ess.run through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

file_exists​

file_exists(path: String) -> Bool

Recipe:

fs.file.exists($path)

fs.dir.exists​

fs.dir.exists(path: String) -> Bool

Collects fs.dir.exists through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

fs.file.exists​

fs.file.exists(path: String) -> Bool

Collects fs.file.exists through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

generated.matches​

generated.matches(expected: String, actual: String) -> Bool

Collects generated.matches through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

git.changed​

git.changed(glob: String) -> Bool

Collects git.changed through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

net.dns.lookup​

net.dns.lookup(host: String, resolver: String) -> {addresses: List<String>, resolver: String, resolves: Bool, ttl_seconds: Integer}

Collects net.host.resolves through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

net.host.resolves​

net.host.resolves(host: String, resolver: String) -> Bool

Recipe:

net.dns.lookup($host, $resolver).resolves

net.tcp.reachable​

net.tcp.reachable(host: String, port: Integer, network: String) -> Bool

Collects net.tcp.reachable through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

nodejs.package.named​

nodejs.package.named(path: String, name: String) -> Bool

Recipe:

doc.string($path, "/name") == $name

process.run​

process.run(binding: String) -> {exit_code: Option<Integer>, stderr: String, stdout: String}

Collects process.run through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

process.succeeded​

process.succeeded(binding: String) -> Bool

Collects process.succeeded through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

proj.tests.run​

proj.tests.run(binding: String) -> {executed: Integer, failed: Integer, inventory: List<String>, passed: Integer, skipped: Integer, total: Integer}

Collects tests.run through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

schema.valid​

schema.valid(path: String, schema: String) -> Bool

Collects document.validates through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

story.has_tag​

story.has_tag(tag: String) -> Bool

Collects story.has_tag through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

story.id​

story.id() -> String

Collects story.id through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

tests.passed​

tests.passed(path: String) -> Bool

Recipe:

tests.report($path).failed == 0 and tests.report($path).executed > 0 and tests.report($path).skipped == 0

tests.report​

tests.report(path: String) -> {executed: Integer, failed: Integer, inventory: List<String>, passed: Integer, skipped: Integer, total: Integer}

Collects tests.report through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

text.contains​

text.contains(path: String, needle: String) -> Bool

Collects text.contains through engineering.builtin/1. The implementation and bindings are locked into the plan at collection.

Command line​

Exit codes: 0 all true; 1 false; 2 invalid input/provider contract or IO error; 3 unknown.

canon-engineering assertions
Usage: assertions [COMMAND]

Commands:
  list      List the released catalog's typed functions and recipes
  describe  Describe a released function's signature and implementation
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

list​

List the released catalog's typed functions and recipes

Usage: list

Options:
  -h, --help
          Print help

describe​

Describe a released function's signature and implementation

Usage: describe <NAME>

Arguments:
  <NAME>


Options:
  -h, --help
          Print help

help​

Print this message or the help of the given subcommand(s)

Usage: help [COMMAND]...

Arguments:
  [COMMAND]...
          Print help for the subcommand(s)

canon-engineering gates
Usage: gates [COMMAND]

Commands:
  validate  Parse, type-check and plan every assertion without collecting observations
  explain   Explain the checked plan, resolved requests and bound implementation identities
  run       Collect all planned observations, retain evidence and evaluate the gate
  evaluate  Replay retained evidence without executing commands, providers or network operations
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

validate​

Parse, type-check and plan every assertion without collecting observations

Usage: validate [OPTIONS]

Options:
      --file <FILE>
          Gates document, relative to root

          [default: .engineering/gates.yaml]

      --root <ROOT>
          Source root whose dirty and untracked files enter the evidence identity

          [default: .]

      --project <PROJECT>
          Explicit command/provider/variable registration; omitted means no process admission

      --base <BASE>
          Revision the change is measured from; `git.changed` is unknown without it

      --subject <SUBJECT>
          Revision under test; `git.changed` is unknown without it

      --story-id <STORY_ID>
          The story the change belongs to; `story.id` is unknown without it

      --story-tag <STORY_TAGS>
          A tag of that story, repeatable; giving none leaves `story.has_tag` unknown

      --default-search-path <DEFAULT_SEARCH_PATH>
          Directory, repeatable, where a command's `program` is looked up when the project has no `search_path`; it must be absolute and outside the tree

  -h, --help
          Print help

explain​

Explain the checked plan, resolved requests and bound implementation identities

Usage: explain [OPTIONS]

Options:
      --file <FILE>
          Gates document, relative to root

          [default: .engineering/gates.yaml]

      --root <ROOT>
          Source root whose dirty and untracked files enter the evidence identity

          [default: .]

      --project <PROJECT>
          Explicit command/provider/variable registration; omitted means no process admission

      --base <BASE>
          Revision the change is measured from; `git.changed` is unknown without it

      --subject <SUBJECT>
          Revision under test; `git.changed` is unknown without it

      --story-id <STORY_ID>
          The story the change belongs to; `story.id` is unknown without it

      --story-tag <STORY_TAGS>
          A tag of that story, repeatable; giving none leaves `story.has_tag` unknown

      --default-search-path <DEFAULT_SEARCH_PATH>
          Directory, repeatable, where a command's `program` is looked up when the project has no `search_path`; it must be absolute and outside the tree

  -h, --help
          Print help

run​

Collect all planned observations, retain evidence and evaluate the gate

Usage: run [OPTIONS]

Options:
      --file <FILE>
          Gates document, relative to root

          [default: .engineering/gates.yaml]

      --root <ROOT>
          Source root whose dirty and untracked files enter the evidence identity

          [default: .]

      --project <PROJECT>
          Explicit command/provider/variable registration; omitted means no process admission

      --base <BASE>
          Revision the change is measured from; `git.changed` is unknown without it

      --subject <SUBJECT>
          Revision under test; `git.changed` is unknown without it

      --story-id <STORY_ID>
          The story the change belongs to; `story.id` is unknown without it

      --story-tag <STORY_TAGS>
          A tag of that story, repeatable; giving none leaves `story.has_tag` unknown

      --default-search-path <DEFAULT_SEARCH_PATH>
          Directory, repeatable, where a command's `program` is looked up when the project has no `search_path`; it must be absolute and outside the tree

      --out <OUT>
          Evidence output under .engineering/assertions/, relative to root

          [default: .engineering/assertions/evidence.json]

      --now <NOW>
          Evaluation instant in Unix seconds; the edge reads the clock when omitted

  -h, --help
          Print help

evaluate​

Replay retained evidence without executing commands, providers or network operations

Usage: evaluate [OPTIONS] --evidence <EVIDENCE>

Options:
      --evidence <EVIDENCE>


      --now <NOW>
          Defaults to the retained evaluation instant for reproducible replay

      --source-identity <SOURCE_IDENTITY>
          Expected source identity. A mismatch makes the retained evidence unavailable

      --context-identity <CONTEXT_IDENTITY>


  -h, --help
          Print help

help​

Print this message or the help of the given subcommand(s)

Usage: help [COMMAND]...

Arguments:
  [COMMAND]...
          Print help for the subcommand(s)