hecks 5.0.0 → 7.0.0

data/lib/hecks/cli.rb

@@ -1,133 +0,0 @@
-require_relative "cli/command_table"
-require_relative "cli/launcher_words"
-
-module Hecks
-  # The `hecks` command an installed gem puts on the path: one router over the
-  # domain-operator tools, each also runnable from a checkout as `exe/hecks <name>`.
-  #
-  # Every subcommand's logic lives under `cli/`, and `exe/hecks` routes to it.
-  #
-  # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
-  module CLI
-    HELP_FLAGS = ["--help", "-h"].freeze
-
-    # Printed above the usage line by `overview`, on every path that reaches it
-    # (a bare `hecks`, `hecks --help`, and an unknown subcommand alike).
-    HERO = <<~BANNER.freeze
-      #   #  #####   ####  #  #    ####
-      #   #  #      #      # #    #
-      #####  ####   #      ##      ###
-      #   #  #      #      # #        #
-      #   #  #####   ####  #  #   ####
-
-          It's all about the specs
-    BANNER
-
-    # Exit status for a missing or unknown subcommand.
-    USAGE_STATUS = 2
-
-    include LauncherWords
-    extend LauncherWords
-
-    module_function
-
-    # The checkout this library is loaded from, which a corpus sweep needs; an installed gem has
-    # none.
-    #
-    # @return [String, nil] the repository root, or nil when `hecks.gemspec` is not beside `lib/`
-    def checkout_root
-      root = File.expand_path("../..", __dir__)
-      root if File.exist?(File.join(root, "hecks.gemspec"))
-    end
-
-    # Routes `argv` to its subcommand and runs it.
-    #
-    # A subcommand followed only by `--help`/`-h` prints its usage without
-    # running it; other arguments still reach the verb itself.
-    #
-    # @param argv [Array<String>] the command line, subcommand first
-    # @param out [#puts] where help goes
-    # @param err [#puts] where usage errors go
-    # @return [Integer] the process exit status: 2 for a bad command, 1 for a bad word, the
-    #   subcommand's own Integer when it returns one, else 0; a subcommand that fails exits
-    #   the process itself
-    def start(argv, out: $stdout, err: $stderr)
-      Encoding.default_external = Encoding::UTF_8
-      Encoding.default_internal = Encoding::UTF_8
-      name, *rest = argv
-      return refuse_command(name, out, err) unless COMMANDS.key?(name)
-      return command_help(name, out) if help_asked?(name, rest)
-
-      words, problem = launcher_words(name, rest)
-      return refuse_words(name, problem, err) if problem
-
-      result = dispatch(name, words)
-      result.is_a?(Integer) ? result : 0
-    end
-
-    # Answers an absent or unknown subcommand with the overview.
-    # @api private
-    # @return [Integer] 0 when help was asked for, else the usage status
-    def refuse_command(name, out, err)
-      asked = HELP_FLAGS.include?(name) || name == "help"
-      err.puts "hecks: unknown command #{name.inspect}" unless asked || name.nil?
-      overview(asked ? out : err)
-      asked ? 0 : USAGE_STATUS
-    end
-
-    # Prints one subcommand's usage.
-    # @api private
-    # @return [Integer] 0
-    def command_help(name, out)
-      help(COMMANDS.fetch(name), out)
-      0
-    end
-
-    # Says why a subcommand's words were refused.
-    # @api private
-    # @return [Integer] 1
-    def refuse_words(name, problem, err)
-      err.puts "hecks #{name}: #{problem}"
-      1
-    end
-
-    # Whether the words ask for a subcommand's usage: a lone flag for `run`, whose other words are
-    # the verb's own, and the flag anywhere for the rest.
-    # @api private
-    def help_asked?(name, rest)
-      return rest.length == 1 && HELP_FLAGS.include?(rest.first) if name == "run"
-
-      rest.any? { |word| HELP_FLAGS.include?(word) }
-    end
-
-    # Runs one known subcommand with the working directory as its root.
-    #
-    # @param name [String] a key of `COMMANDS`
-    # @param argv [Array<String>] the arguments after the subcommand
-    # @return [void]
-    # @raise [SystemExit] when the subcommand exits the process itself
-    def dispatch(name, argv)
-      command = COMMANDS.fetch(name)
-      require_relative command.file
-      command.run.call(argv, "hecks #{name}", name)
-    end
-
-    # @api private
-    def overview(io)
-      io.puts HERO
-      io.puts "usage: hecks <command> [arguments]"
-      io.puts ""
-      width = COMMANDS.keys.map(&:length).max
-      COMMANDS.each { |name, command| io.puts "  #{name.ljust(width)}  #{command.summary}" }
-      io.puts ""
-      io.puts "Run `hecks <command> --help` for one command's usage."
-    end
-
-    # @api private
-    def help(command, io)
-      io.puts "usage: #{command.usage}"
-      io.puts ""
-      io.puts command.summary
-    end
-  end
-end

data/lib/hecks/gate/stages.yml

@@ -1,234 +0,0 @@
-# The checks a stage runs before its change is let through. `hecks gate <stage>` reads this file and
-# the git pre-push hook calls it, so the list of checks lives here and nowhere else.
-#
-# A check is one command run from the repository root, all of a stage's checks at once:
-#   id       the name it is reported and selected by (`only=a,b`)
-#   title    the heading its output is printed under
-#   run      the program and its arguments; `{workers}` is half the machine's cores, at least one
-#   blocked  what a red check means and what to do about it
-#
-# `env` is set only where the caller has not set it: a push check has no use for the Hecks
-# domain's database, so it runs on Memory, as a pull-request run does in CI.
-#
-# A check a second stage repeats is written once, under an anchor (`&name`), and aliased
-# (`*name`) where the other stage takes it, so the two stages cannot drift apart.
-#
-# The `ci` stage is the checks the CI workflow `ci-checks.yml` holds. Each of its steps runs one
-# job's checks with `hecks gate_run.gate stage=ci only=<ids> --wait`, so the commands live here and
-# the workflow keeps only which job runs which ids and what each step is called;
-# spec/gate_ci_stage_spec.rb pins that every check is run by exactly one step. Select checks
-# with `only=`: several of them write generated files and compare, so the stage is not meant to
-# run whole in one checkout.
-pre_push:
-  # HECKS_PROCESS_SPECS keeps the examples tagged `process` (they start child processes, so a plain
-  # `rspec` leaves them out) in the suite this stage runs.
-  env:
-    HECKS_ENVIRONMENT: memory
-    HECKS_PROCESS_SPECS: "1"
-  checks:
-    - id: rspec
-      title: rspec (parallel)
-      run:
-        - sh
-        - -ec
-        - |
-          # Workers are grouped by this machine's own last timings, kept under the git directory
-          # (shared by every worktree, never committed). CI's committed baseline leaves out the io
-          # specs this run includes, so it only seeds the first run; each run then rewrites the log.
-          log="$(git rev-parse --git-common-dir)/hecks_rspec_runtime.log"
-          [ -f "$log" ] || cp .github/rspec_runtime_baseline.log "$log"
-          bundle exec parallel_rspec spec -n {workers} --group-by runtime --runtime-log "$log" --allowed-missing 100 \
-            -o "--format ParallelTests::RSpec::RuntimeLogger --out $log"
-      blocked: the suite is red.
-    - &check_fuzzing
-      id: fuzzing
-      title: spec/fuzzing, which the parallel run above excludes
-      run: [bundle, exec, rspec, spec/fuzzing, --tag, fuzzing]
-      blocked: spec/fuzzing is red.
-    - id: query_agreement
-      title: adapter agreement, one declared query and every engine giving the same answer
-      run: [bundle, exec, rspec, spec/adapters/query_agreement_spec.rb, --tag, io]
-      blocked: the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which.
-    - &check_engine_agreement
-      id: engine_agreement
-      title: engine agreement, every declared comparator on both engines
-      run: [bundle, exec, exe/hecks, conformance_run.check_engine_agreement, --wait]
-      blocked: a comparator is missing a shared case or a cross-engine spec.
-    - &check_model_check
-      id: model_check
-      title: model check, unreachable states, dead transitions and orphaned handlers
-      run: [bundle, exec, exe/hecks, model_check, --wait]
-      blocked: the model checker found something.
-    - &check_doc_coverage
-      id: doc_coverage
-      title: docs coverage, words with no running example
-      run: [bundle, exec, exe/hecks, conformance_run.measure_doc_coverage, --wait]
-      blocked: the language ships something undocumented; write the missing sections and examples.
-    - &check_rubocop
-      id: rubocop
-      title: rubocop, the static style and correctness gate
-      run: [bundle, exec, rubocop, -c, .rubocop.yml]
-      blocked: rubocop found an offense.
-    - &check_codegen_drift
-      id: codegen_drift
-      title: codegen drift, rust/src/generated/ must match a fresh regeneration
-      run: [bundle, exec, exe/hecks, regeneration_run.regenerate_corpus, --check, --wait]
-      blocked: regenerating hits a diff. Only pizzas, mod.rs and Cargo.toml are committed, so run `hecks regenerate_corpus --confirm` (it also materializes the rest on a fresh checkout) and commit what it changed.
-    - &check_comment_style
-      id: comment_style
-      title: comment style, every comment under lib/hecks against docs/COMMENT_STYLE_GUIDE.md
-      run: [bundle, exec, exe/hecks, style_run.check_comments, paths=lib/hecks, --wait]
-      blocked: a comment breaks the style guide, such as a line past 100 characters; `hecks fix_comments` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check.
-    - &check_comment_blocks
-      id: comment_blocks
-      title: comment blocks, no run of comment lines past ADR 0075's cap
-      run: [bundle, exec, exe/hecks, style_run.check_comments, "paths=lib,spec,examples", only=long_block, --wait]
-      blocked: a comment block ran past the cap; shorten it.
-    - &check_rust_fmt
-      id: rust_fmt
-      title: rustfmt, every Rust crate laid out as `cargo fmt` would
-      run:
-        - sh
-        - -ec
-        - |
-          # The main crate's generated modules are not committed, so cargo fmt would stop at a
-          # missing file on a fresh checkout; its hand-written entry points are named instead.
-          rustfmt --check --edition 2021 rust/src/main.rs rust/src/kernel/mod.rs rust/tests/*.rs
-          for crate in parser codegen lsp host web build; do
-            cargo fmt --check --manifest-path "rust/$crate/Cargo.toml"
-          done
-      blocked: a Rust file is not laid out as rustfmt has it; run `cargo fmt` in its crate (rust/src/exemplar is exempt, it is text templates). Generated Rust is laid out by its generators, so fix the generator, not the output.
-
-# The checks a push of only unguarded lanes (`main`) runs in place of pre_push. The slow suite is
-# skipped there; the style checks are not, since an offense that lands on `main` is a red CI run,
-# and neither is spec/fuzzing, which no commit hook runs any more.
-unguarded_push:
-  env:
-    HECKS_ENVIRONMENT: memory
-  checks:
-    - *check_rubocop
-    - *check_comment_style
-    - *check_comment_blocks
-    - *check_fuzzing
-
-# The Rust io specs `ci-rust-io.yml` runs in its `rspec_rust_io` job, for a push that wants their
-# answer first: `hecks gate_run.gate stage=rust_io --wait`. No hook or workflow runs it. It sets CI
-# as the job does, so a skipped example fails here as it fails there. rust/src/generated is not
-# committed, so the check materializes it first, as the job's generated-rust action does. The specs
-# mutate rust/, and a stage's checks run at once, so the job's two legs run one after the other in
-# a single check. spec/gate_rust_io_stage_spec.rb pins the spec lists to the workflow's matrix.
-rust_io:
-  env:
-    CI: "true"
-    HECKS_ENVIRONMENT: memory
-  checks:
-    - id: rust_io
-      title: rust io specs, conformance, coercion, has_many, semantics corpus and feature exclusivity
-      run:
-        - sh
-        - -ec
-        - |
-          # Building the banking crate makes banking the default feature and rewrites the module
-          # list, both tracked. They are put back on the way out, and the check will not start over
-          # a person's uncommitted edits to them.
-          rewritten="rust/Cargo.toml rust/src/generated/mod.rs"
-          if [ -n "$(git status --porcelain -- $rewritten)" ]; then
-            echo "uncommitted changes in $rewritten; commit or discard them first" >&2
-            exit 1
-          fi
-          trap 'git checkout -q -- $rewritten' EXIT
-          env -u CARGO_TARGET_DIR bundle exec exe/hecks regeneration_run.regenerate_corpus --confirm --wait
-          bundle exec exe/hecks build.project_rust domain=examples/banking --wait
-          bundle exec rspec --tag io --profile 8 spec/rust_conformance_spec.rb spec/rust_conformance_fuzz_spec.rb spec/rust_numeric_coercion_spec.rb spec/rust_generated/has_many_spec.rb spec/semantics_corpus_spec.rb
-          bundle exec rspec --tag io --profile 8 spec/rust_generated/domain_feature_exclusivity_spec.rb
-      blocked: a Rust io spec failed, or skipped; the crate it built is under rust/target.
-
-# The checks `.github/workflows/ci-checks.yml` runs. It sets no `env`: the job's journal choice
-# (the `hecks-environment` action) reaches every check, as it reached each command before.
-ci:
-  checks:
-    - *check_model_check
-    - *check_engine_agreement
-    - *check_doc_coverage
-    - *check_rubocop
-    - *check_comment_style
-    - *check_comment_blocks
-    - *check_codegen_drift
-    - *check_rust_fmt
-    - id: rust_clippy
-      title: clippy, every Rust crate with its warnings as errors
-      run:
-        - sh
-        - -ec
-        - |
-          for crate in . parser codegen lsp host web build; do
-            cargo clippy --all-targets --manifest-path "rust/$crate/Cargo.toml" -- -D warnings
-          done
-      blocked: clippy found a warning in a Rust crate, under the strict `[lints.clippy]` table of its Cargo.toml. The main crate needs rust/src/generated, so run `hecks regenerate_corpus --confirm` first on a fresh checkout. Fix the code, or allow a lint at the one site with a line saying why; a warning in generated Rust is fixed in its generator.
-    - id: lint_deploy_recipes
-      title: generated deploy recipes, a command with no checked exit status or no echo
-      run: [bundle, exec, exe/hecks, deploy, makefile_check.lint, --wait]
-      blocked: a generated deploy Makefile has an unchecked command, or real AWS or database work with no echo telling the person running it what is about to happen.
-    - id: fuzz
-      title: fuzz, every example domain on the Memory adapter
-      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, --wait]
-      blocked: a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output.
-    - id: fuzz_sqlite
-      title: fuzz on a real on-disk SQLite database
-      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=sqlite, seeds=6, --wait]
-      blocked: the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats.
-    - id: fuzz_postgres
-      title: fuzz on real Postgres, up to four workers (each in its own scratch schema)
-      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=postgres, seeds=3, steps=20, --wait]
-      blocked: the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD.
-    - id: vocabulary_drift
-      title: vocabulary, the reserved-name tables regenerated must match the committed ones
-      run:
-        - sh
-        - -ec
-        - |
-          bundle exec exe/hecks language_run.project_vocabulary --confirm --wait
-          bundle exec exe/hecks language_run.project_reserved_names --confirm --wait
-          git diff --exit-code -- lib/hecks/vocabulary.rb rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs
-      blocked: a generated vocabulary file is stale; the check rewrote it, so commit the result.
-    - id: ci_gates
-      title: ci gates, the CiGate rows must match the marked regions of the workflows
-      run: [bundle, exec, exe/hecks, regeneration_run.project_ci_gates, --wait]
-      blocked: a CiGate row changed with no projection, or a region was edited by hand; run `hecks regeneration_run.project_ci_gates --confirm`.
-    - id: tools_doc
-      title: tools doc, docs/tools.md must match the RetiredScript rows
-      run: [bundle, exec, exe/hecks, regeneration_run.project_tools_doc, --wait]
-      blocked: a command's arguments changed with no regenerated doc; run `hecks regeneration_run.project_tools_doc --confirm`.
-    - id: rust_coverage
-      title: rust coverage, every generated module
-      run: [bundle, exec, exe/hecks, query, corpus_run.corpus_rust_coverage, --wait]
-      blocked: a construct a domain declares has no generated Rust, or an entry on RUST_COVERAGE_PENDING is now fixed and must be deleted.
-    - id: rust_coverage_codegen
-      title: rust coverage against hecks-codegen's own manifest, pizzas governance identity banking meta
-      run:
-        - sh
-        - -ec
-        - |
-          for module in pizzas governance identity banking meta; do
-            bundle exec exe/hecks query build.rust_coverage module_name=$module codegen=rust --wait
-          done
-      blocked: hecks-codegen generated nothing for a construct a domain declares.
-    - id: kernel_coverage
-      title: rust kernel coverage, every capability variant has a kernel file
-      run: [bundle, exec, exe/hecks, kernel_run.measure_kernel_coverage, --wait]
-      blocked: a capability's enum variant has no rust/src/kernel file behind it.
-    - id: rust_vocabulary_drift
-      title: rust vocabulary, the kernel vocab tables regenerated must match the committed ones
-      run:
-        - sh
-        - -ec
-        - |
-          bundle exec exe/hecks language_run.project_rust_vocabulary --confirm --wait
-          git diff --exit-code -- rust/src/kernel/vocab/
-          untracked="$(git status --porcelain --untracked-files=all -- rust/src/kernel/vocab/)"
-          if [ -n "$untracked" ]; then
-            echo "rust/src/kernel/vocab has uncommitted generated files:" >&2
-            echo "$untracked" >&2
-            exit 1
-          fi
-      blocked: the generated kernel vocab tables are stale or untracked; the check rewrote them, so commit the result.