@codyswann/lisa 4.84.10 → 4.85.0

package/rails/copy-overwrite/scripts/lisa_rspec_shard_recorder.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+# -----------------------------------------------------------------------------
+# RSpec shard recorder for `quality-rails.yml` `test_shards`.
+#
+# Loaded into one shard leg with `rspec --require`. It does two things, both at
+# `before(:suite)`, when the project's own spec_helper / rails_helper has
+# already required SimpleCov and loaded `.simplecov`:
+#
+#   1. Hands coverage off to the aggregate. `SimpleCov.finalize_merge false`
+#      makes this process store its `.resultset.json` and stop there: no
+#      report, and no minimum-coverage check against a slice of the suite,
+#      which would fail any project whose floor is above what one shard
+#      reaches. The aggregate job collates every shard and enforces the
+#      project's thresholds once, on the merged result.
+#   2. Writes a run record at the reporter's `close`: the files RSpec itself
+#      loaded (`files_to_run`), each example's run time, and where SimpleCov
+#      writes. The aggregate proves from these records that every spec file
+#      ran exactly once, and folds the timings into the next run's plan.
+#
+# ENVIRONMENT
+#   LISA_RSPEC_SHARD         "K/N" — this leg's shard. Required.
+#   LISA_RSPEC_SHARD_RECORD  Path of the run record to write. Required.
+# -----------------------------------------------------------------------------
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+
+# Hands a shard's coverage to the aggregate and records what RSpec ran.
+module LisaRspecShardRecorder
+  SCHEMA_VERSION = 1
+
+  # Collects example timings and writes the record when the reporter closes.
+  class Listener
+    def initialize(path:, shard:, configuration:)
+      @path = path
+      @shard = shard
+      @configuration = configuration
+      @examples = []
+    end
+
+    def example_finished(notification)
+      example = notification.example
+      @examples << {
+        'file' => LisaRspecShardRecorder.relative(example.metadata[:rerun_file_path] || example.file_path),
+        'run_time' => example.execution_result.run_time.to_f,
+        'status' => example.execution_result.status.to_s
+      }
+    end
+
+    def close(_notification)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, "#{JSON.pretty_generate(record)}\n")
+    end
+
+    def record
+      {
+        'version' => SCHEMA_VERSION,
+        'shard' => @shard,
+        'files_to_run' => @configuration.files_to_run.map { |file| LisaRspecShardRecorder.relative(file) }.sort,
+        'examples' => @examples,
+        'simplecov' => LisaRspecShardRecorder.simplecov_state
+      }
+    end
+  end
+
+  module_function
+
+  def fetch_env(name)
+    value = ENV.fetch(name, '')
+    raise ArgumentError, "lisa-rspec-shard-recorder: #{name} is not set" if value.empty?
+
+    value
+  end
+
+  # Repo-relative, forward-slashed, with no leading "./" and no ":line" suffix.
+  def relative(path)
+    text = path.to_s.sub(/:\d+(?::\d+)*\z/, '')
+    absolute = Pathname.new(File.expand_path(text))
+    absolute.relative_path_from(Pathname.new(Dir.pwd)).to_s
+  end
+
+  def measuring?
+    defined?(::SimpleCov) && defined?(::Coverage) && ::Coverage.running?
+  end
+
+  def simplecov_state
+    return { 'active' => false } unless measuring?
+
+    { 'active' => true, 'coverage_path' => ::SimpleCov.coverage_path }
+  end
+
+  # A shard that enforced the project's floor against its own slice would fail
+  # every project whose floor is above one shard's reach, and a shard that does
+  # not store its resultset leaves the aggregate nothing to merge. Both are
+  # refused loudly rather than worked around.
+  def hand_off_coverage(shard)
+    return unless measuring?
+
+    refuse_unsupported_simplecov
+    refuse_measured_recorder
+    ::SimpleCov.finalize_merge(false)
+    ::SimpleCov.command_name("RSpec shard #{shard}")
+  end
+
+  def refuse_unsupported_simplecov
+    unless ::SimpleCov.respond_to?(:finalize_merge)
+      raise 'lisa-rspec-shard-recorder: this SimpleCov has no `finalize_merge`, so a shard cannot store its ' \
+            'coverage without also checking the minimum against its own slice. test_shards above 1 needs ' \
+            "simplecov >= 1.0 (Lisa's Gemfile.lisa pins it); upgrade it, or leave test_shards at 1."
+    end
+    return if ::SimpleCov.merging
+
+    raise 'lisa-rspec-shard-recorder: SimpleCov merging is off (`merging false`), so this shard would write no ' \
+          '.resultset.json for the aggregate to collate. Remove that setting, or leave test_shards at 1.'
+  end
+
+  # Loaded from inside the project, this file is itself measured and lands in
+  # the shard's resultset as application code the unsharded run never had,
+  # moving the merged percentage. The workflow copies it out first.
+  def refuse_measured_recorder
+    return unless File.expand_path(__FILE__).start_with?("#{File.expand_path(::SimpleCov.root)}/")
+
+    raise 'lisa-rspec-shard-recorder: loaded from inside the project root, so SimpleCov would measure it as ' \
+          'application code. Copy it outside the project (the workflow uses $RUNNER_TEMP) and --require that copy.'
+  end
+
+  def arm!(configuration)
+    shard = fetch_env('LISA_RSPEC_SHARD')
+    path = File.expand_path(fetch_env('LISA_RSPEC_SHARD_RECORD'))
+    hand_off_coverage(shard)
+    listener = Listener.new(path: path, shard: shard, configuration: configuration)
+    configuration.reporter.register_listener(listener, :example_finished, :close)
+    listener
+  end
+end
+
+RSpec.configure do |config|
+  config.before(:suite) { LisaRspecShardRecorder.arm!(config) }
+end

package/rails/copy-overwrite/scripts/lisa_simplecov_collate.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+# -----------------------------------------------------------------------------
+# Merge the RSpec shards' SimpleCov resultsets and enforce the project's
+# coverage thresholds once, on the whole suite.
+#
+#   bundle exec ruby scripts/lisa_simplecov_collate.rb <resultset.json>...
+#
+# `require 'simplecov'` loads the project's own `.simplecov`, so the merged
+# result is filtered, grouped and checked exactly as an unsharded run would
+# be: the same `minimum_coverage` / `coverage ..., minimum:` and every other
+# limit it sets. This file sets no threshold of its own. `SimpleCov.collate`
+# exits non-zero when a threshold fails.
+# -----------------------------------------------------------------------------
+
+require 'simplecov'
+
+# Collates shard resultsets and lets SimpleCov's threshold verdict decide.
+module LisaSimplecovCollate
+  module_function
+
+  def resultsets(argv)
+    abort 'lisa-simplecov-collate: no resultsets given; nothing to collate.' if argv.empty?
+
+    missing = argv.reject { |path| File.file?(path) }
+    abort "lisa-simplecov-collate: resultset(s) not found: #{missing.join(', ')}" unless missing.empty?
+
+    argv.map { |path| File.expand_path(path) }
+  end
+
+  # A `.simplecov` that calls `SimpleCov.start` itself has also started
+  # measuring THIS process. Left running, SimpleCov's own at_exit would format
+  # and check a second time. Stopping it and dropping the result leaves
+  # `collate` the only verdict.
+  def stand_down_own_measurement
+    ::Coverage.result(stop: true, clear: true) if defined?(::Coverage) && ::Coverage.running?
+    ::SimpleCov.clear_result if ::SimpleCov.respond_to?(:clear_result)
+  end
+
+  def run(argv)
+    files = resultsets(argv)
+    puts "Collating #{files.length} SimpleCov resultset(s)."
+    ::SimpleCov.collate(files)
+  ensure
+    stand_down_own_measurement
+  end
+end
+
+LisaSimplecovCollate.run(ARGV) if $PROGRAM_NAME == __FILE__

package/rails/create-only/.github/workflows/ci.yml

@@ -36,6 +36,10 @@ jobs:
     # Rails projects default to PostgreSQL. For a MySQL app, uncomment:
     # with:
     #   database_type: 'mysql'
+    # To split a slow RSpec suite across parallel runners, add
+    # `test_shards: 4` (1-20) to the `with:` block. The legs' SimpleCov
+    # coverage is merged and checked once, and the required `Test (...)`
+    # check keeps its name.
     secrets:
       GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}
       FOSSA_API_KEY: ${{ secrets.FOSSA_API_KEY }}

package/scripts/two-channel-couplings.json

@@ -63,6 +63,18 @@
       "decision": "not-needed",
       "reason": "A runner, not a judge. The gate's verdict is mutant's exit code, and what it runs is read from the project's own `mutation.gate.yml` and `.mutant.yml`; this script's own logic decides whether the gate is enabled and what ref to diff against, both of which come from configuration it does not own. A superseded copy runs the wrong subjects loudly rather than returning a wrong verdict quietly."
     },
+    "quality-rails.yml::scripts/lisa_rspec_shard_recorder.rb": {
+      "decision": "not-needed",
+      "reason": "A reporter, not a judge. It hands SimpleCov's merge finalization to the aggregate and writes a run record; the verdict on that record is `lisa-rspec-shards.mjs verify`, which refuses any record not at the schema version it speaks. A superseded recorder either leaves a record verify rejects or leaves the shard's own minimum check armed, and both are loud reds, never a believed green."
+    },
+    "quality-rails.yml::scripts/lisa-rspec-shards.mjs": {
+      "decision": "warranted",
+      "reason": "Verdict-bearing when test_shards is above 1: its `verify` subcommand is what turns a dropped or duplicated spec file into a red `Test (MySQL)` / `Test (PostgreSQL)`, and its `plan` decides which files each leg runs. Plan and record documents carry a schema version that `verify` refuses on mismatch, and an unknown subcommand or flag fails loudly, so a copy too old to speak this workflow's interface is red rather than green. What that does not cover is a copy at the same schema whose partition check is weaker than the current one; the script exports no contract version the workflow could compare, so the obligation is recorded rather than claimed closed."
+    },
+    "quality-rails.yml::scripts/lisa_simplecov_collate.rb": {
+      "decision": "not-needed",
+      "reason": "A runner, not a judge. It forwards the shards' resultsets to `SimpleCov.collate`, and the threshold verdict is SimpleCov's own, read from the project's `.simplecov` and `simplecov.thresholds.json`; the script sets no threshold. A superseded copy can fail to collate, which is red, but cannot change what the thresholds are."
+    },
     "quality-rails.yml::scripts/lisa-scratch-run.sh": {
       "decision": "not-needed",
       "reason": "A supervisor that hosts a verdict rather than computing one: it owns run-scoped scratch and cleanup around whatever it wraps. Nothing it does can turn a passing suite red or a failing one green — a superseded copy misplaces or fails to reap a scratch directory, which surfaces as its own visible failure rather than as a believed verdict."
@@ -108,13 +120,13 @@
   },
   "inspected": {
     "workflows": 26,
-    "steps": 788,
-    "couplings": 37,
-    "inventory": 204
+    "steps": 823,
+    "couplings": 40,
+    "inventory": 207
   },
   "counts": {
     "package-backed": 11,
-    "apply-lagged": 23,
+    "apply-lagged": 26,
     "never-delivered": 0,
     "undelivered": 3
   },
@@ -122,13 +134,13 @@
     "version-handshake": 4,
     "capability-probe": 0,
     "existence-only": 5,
-    "no-probe": 14,
+    "no-probe": 17,
     "unchecked": 3
   },
   "decisionCounts": {
     "handshake": 4,
-    "not-needed": 12,
-    "warranted": 10
+    "not-needed": 14,
+    "warranted": 11
   },
   "couplings": [
     {
@@ -411,6 +423,53 @@
       ],
       "detail": "`quality-rails.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/check-threshold-ratchet.mjs` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (all/copy-overwrite, rails/copy-overwrite, typescript/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. No existence test guards the read, which is ALL this scan examined of the step's control flow: it did not read anything that could absorb the failure. An absent path most likely fails the job loudly — the better of the two failures, because it is visible — but that is inferred from the missing guard, NOT MEASURED. The step's text does carry `else-branch`, `exit-zero`, `exit-nonzero`, `error-annotation` — located in the step, deliberately NOT related to this read, and enough to make \"it skips silently\" a claim to check rather than assume. STALENESS (a separate dimension from the delivery verdict above): `no-probe`. Neither an existence test nor a version probe bears on this read, so nothing here distinguishes a current artifact from an absent or a superseded one. Tokens found: `workflow-requests-version`. `workflow-requests-version` is workflow-scoped — it does not say THIS step asks."
     },
+    {
+      "key": "quality-rails.yml::scripts/lisa_rspec_shard_recorder.rb",
+      "workflow": "quality-rails.yml",
+      "path": "scripts/lisa_rspec_shard_recorder.rb",
+      "channel": "apply",
+      "verdict": "apply-lagged",
+      "remedy": "run-lisa-apply",
+      "guarded": false,
+      "handling": [
+        "exit-nonzero",
+        "error-annotation"
+      ],
+      "detection": "no-probe",
+      "stalenessSignals": [
+        "workflow-requests-version"
+      ],
+      "decision": "not-needed",
+      "reason": "A reporter, not a judge. It hands SimpleCov's merge finalization to the aggregate and writes a run record; the verdict on that record is `lisa-rspec-shards.mjs verify`, which refuses any record not at the schema version it speaks. A superseded recorder either leaves a record verify rejects or leaves the shard's own minimum check armed, and both are loud reds, never a believed green.",
+      "lanes": [
+        "rails/copy-overwrite"
+      ],
+      "detail": "`quality-rails.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/lisa_rspec_shard_recorder.rb` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (rails/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. No existence test guards the read, which is ALL this scan examined of the step's control flow: it did not read anything that could absorb the failure. An absent path most likely fails the job loudly — the better of the two failures, because it is visible — but that is inferred from the missing guard, NOT MEASURED. The step's text does carry `exit-nonzero`, `error-annotation` — located in the step, deliberately NOT related to this read, and enough to make \"it skips silently\" a claim to check rather than assume. STALENESS (a separate dimension from the delivery verdict above): `no-probe`. Neither an existence test nor a version probe bears on this read, so nothing here distinguishes a current artifact from an absent or a superseded one. Tokens found: `workflow-requests-version`. `workflow-requests-version` is workflow-scoped — it does not say THIS step asks."
+    },
+    {
+      "key": "quality-rails.yml::scripts/lisa_simplecov_collate.rb",
+      "workflow": "quality-rails.yml",
+      "path": "scripts/lisa_simplecov_collate.rb",
+      "channel": "apply",
+      "verdict": "apply-lagged",
+      "remedy": "run-lisa-apply",
+      "guarded": false,
+      "handling": [
+        "exit-zero",
+        "exit-nonzero",
+        "error-annotation"
+      ],
+      "detection": "no-probe",
+      "stalenessSignals": [
+        "workflow-requests-version"
+      ],
+      "decision": "not-needed",
+      "reason": "A runner, not a judge. It forwards the shards' resultsets to `SimpleCov.collate`, and the threshold verdict is SimpleCov's own, read from the project's `.simplecov` and `simplecov.thresholds.json`; the script sets no threshold. A superseded copy can fail to collate, which is red, but cannot change what the thresholds are.",
+      "lanes": [
+        "rails/copy-overwrite"
+      ],
+      "detail": "`quality-rails.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/lisa_simplecov_collate.rb` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (rails/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. No existence test guards the read, which is ALL this scan examined of the step's control flow: it did not read anything that could absorb the failure. An absent path most likely fails the job loudly — the better of the two failures, because it is visible — but that is inferred from the missing guard, NOT MEASURED. The step's text does carry `exit-zero`, `exit-nonzero`, `error-annotation` — located in the step, deliberately NOT related to this read, and enough to make \"it skips silently\" a claim to check rather than assume. STALENESS (a separate dimension from the delivery verdict above): `no-probe`. Neither an existence test nor a version probe bears on this read, so nothing here distinguishes a current artifact from an absent or a superseded one. Tokens found: `workflow-requests-version`. `workflow-requests-version` is workflow-scoped — it does not say THIS step asks."
+    },
     {
       "key": "quality-rails.yml::scripts/lisa-mutation.sh",
       "workflow": "quality-rails.yml",
@@ -435,6 +494,29 @@
       ],
       "detail": "`quality-rails.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/lisa-mutation.sh` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (all/copy-contents). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. The read sits behind an existence test, which is ALL this scan examined of the step's control flow: it did not read the test's other branch, any fallback, any explicit `exit`, or any verification of the step's output. Whether an absent path skips quietly, falls back, or fails loudly is therefore NOT MEASURED — read the step before concluding it proves nothing. The shape worth ruling out is the silent one, where a skip posts no context and an absent required context is not a red one. The step's text does carry `exit-zero`, `exit-nonzero`, `error-annotation` — located in the step, deliberately NOT related to this read, and enough to make \"it skips silently\" a claim to check rather than assume. STALENESS (a separate dimension from the delivery verdict above): `existence-only`. An existence test and no version probe: this coupling can see that the artifact is MISSING and cannot see that it is OLD. A present copy of any vintage runs, and its verdict is believed. Tokens found: `workflow-requests-version`. `workflow-requests-version` is workflow-scoped — it does not say THIS step asks."
     },
+    {
+      "key": "quality-rails.yml::scripts/lisa-rspec-shards.mjs",
+      "workflow": "quality-rails.yml",
+      "path": "scripts/lisa-rspec-shards.mjs",
+      "channel": "apply",
+      "verdict": "apply-lagged",
+      "remedy": "run-lisa-apply",
+      "guarded": false,
+      "handling": [
+        "exit-nonzero",
+        "error-annotation"
+      ],
+      "detection": "no-probe",
+      "stalenessSignals": [
+        "workflow-requests-version"
+      ],
+      "decision": "warranted",
+      "reason": "Verdict-bearing when test_shards is above 1: its `verify` subcommand is what turns a dropped or duplicated spec file into a red `Test (MySQL)` / `Test (PostgreSQL)`, and its `plan` decides which files each leg runs. Plan and record documents carry a schema version that `verify` refuses on mismatch, and an unknown subcommand or flag fails loudly, so a copy too old to speak this workflow's interface is red rather than green. What that does not cover is a copy at the same schema whose partition check is weaker than the current one; the script exports no contract version the workflow could compare, so the obligation is recorded rather than claimed closed.",
+      "lanes": [
+        "rails/copy-overwrite"
+      ],
+      "detail": "`quality-rails.yml` is delivered at `@main`, so this step is live in every consumer on their next run. It reads `scripts/lisa-rspec-shards.mjs` from the CALLER's tree with no package-relative candidate, and Lisa delivers that path on the `lisa apply` channel (rails/copy-overwrite). The two halves land in the wrong order: this step is live everywhere immediately, the file it needs is live only where somebody applied. No existence test guards the read, which is ALL this scan examined of the step's control flow: it did not read anything that could absorb the failure. An absent path most likely fails the job loudly — the better of the two failures, because it is visible — but that is inferred from the missing guard, NOT MEASURED. The step's text does carry `exit-nonzero`, `error-annotation` — located in the step, deliberately NOT related to this read, and enough to make \"it skips silently\" a claim to check rather than assume. STALENESS (a separate dimension from the delivery verdict above): `no-probe`. Neither an existence test nor a version probe bears on this read, so nothing here distinguishes a current artifact from an absent or a superseded one. Tokens found: `workflow-requests-version`. `workflow-requests-version` is workflow-scoped — it does not say THIS step asks."
+    },
     {
       "key": "quality-rails.yml::scripts/lisa-scratch-run.sh",
       "workflow": "quality-rails.yml",

package/typescript/copy-overwrite/.prettierignore

@@ -95,6 +95,7 @@ scripts/lisa-npm-updater.mjs
 scripts/lisa-postinstall.mjs
 scripts/lisa-rails-prepush.mjs
 scripts/lisa-reconcile-policy.mjs
+scripts/lisa-rspec-shards.mjs
 scripts/lisa-run-gates.mjs
 scripts/lisa-schema-validate.mjs
 scripts/lisa-test-node.mjs