Datastar 1.0.4: typed signals, expressions and statements, Rocket helpers, and a reader for the Rocket manifest

.github/workflows/build.yml

@@ -5,25 +5,89 @@ on:
     branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        dotnet-version: ['10.0.x']
+    timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
-      - name: Setup .NET Core SDK ${{ matrix.dotnet-version }}
-        uses: actions/setup-dotnet@v3
+      # The library and its tests target net8.0, net9.0 and net10.0, so all three runtimes are needed.
+      # The SDK in global.json is 10.0.x.
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: ${{ matrix.dotnet-version }}
+          dotnet-version: |
+            8.0.x
+            9.0.x
+            10.0.x
 
-      - name: Install dependencies
-        run: dotnet restore src/Falco.Datastar
+      # The solution covers the library, the tests and every example, so building it is what catches an example that no
+      # longer compiles. It also catches a project path in the solution that does not match the folder on disk, which is
+      # a build that fails on Linux and passes on Windows.
+      - name: Restore
+        run: dotnet restore Falco.Datastar.sln
 
       - name: Build
-        run: dotnet build src/Falco.Datastar -c Release
+        run: dotnet build Falco.Datastar.sln -c Release --no-restore
 
       - name: Test
-        run: dotnet test test/Falco.Datastar.Tests -c Release
+        run: dotnet test test/Falco.Datastar.Tests -c Release --no-build
+
+      # A library with warnings is not finished. The library itself treats them as errors, and this catches them
+      # anywhere else, such as in the tests and the examples.
+      #
+      # The project's own policy is that a NuGet advisory about a dependency is a warning and not a failure: see
+      # WarningsNotAsErrors in src/Falco.Datastar/Falco.Datastar.fsproj. NuGet replays those advisories on every build,
+      # not only on restore, so a gate on every warning would turn red on the day an advisory is published, with no
+      # change to this repository. They are listed here so they are reported and not swallowed, and not failed on.
+      - name: Check for warnings
+        run: |
+          set -o pipefail
+          dotnet build Falco.Datastar.sln -c Release --no-incremental 2>&1 | tee build.log
+          # The advisory warnings the project deliberately allows. Everything else is a failure.
+          if grep -E "warning [A-Z]+[0-9]+" build.log | grep -vE "warning NU19(01|02|03|04)"; then
+            echo "::error::the build produced warnings"
+            exit 1
+          fi
+          echo "no warnings other than the advisories the project allows"
+
+      # The mutation program is deliberately not in the solution, so nothing above builds it. That is what keeps it
+      # from being a dependency of the library, and it is also why it is built here: a syntax error in it would
+      # otherwise land green on every push and only surface in the weekly mutation run.
+      - name: Check the mutation program compiles
+        run: dotnet build test/mutation -c Release
+
+      # Every F# example in the README and the changelog is compiled against the built library. A maintainer reads
+      # the README to decide whether this binding can be trusted, and an example that no longer compiles is the fastest
+      # way to lose them. It is a script rather than a test because it runs the F# compiler once per block, as a child
+      # process, so that each block is compiled on its own rather than seeing the blocks above it.
+      - name: Check the documented examples
+        run: dotnet fsi test/readme-examples.fsx
+
+      # A package that cannot be packed cannot be published, and a missing README or icon only shows up when someone
+      # tries. Packing is the check that runs on every change, so a release is never the thing that finds out.
+      # It publishes nothing: how this library reaches NuGet is the maintainer's business, not this workflow's.
+      - name: Pack
+        run: dotnet pack src/Falco.Datastar -c Release --no-build -o packages
+
+      # The contents are inside the .nupkg, which is a zip, so the entries have to be read out of it rather than
+      # looked for on disk. A package that is missing its README or its icon still packs, and that is only visible here.
+      - name: Check the package contents
+        run: |
+          set -euo pipefail
+          package=$(ls packages/Falco.Datastar.*.nupkg | grep -v symbols | head -1)
+          echo "checking $package"
+          unzip -l "$package" > package.txt
+          for expected in Falco.Datastar.nuspec README.md icon.png \
+                          lib/net8.0/Falco.Datastar.dll lib/net8.0/Falco.Datastar.xml \
+                          lib/net9.0/Falco.Datastar.dll lib/net10.0/Falco.Datastar.dll; do
+            if ! grep -qF "$expected" package.txt; then
+              echo "::error::$expected is missing from the package"
+              exit 1
+            fi
+            echo "found $expected"
+          done

.github/workflows/dst.yml

@@ -0,0 +1,62 @@
+name: dst
+
+# Runs the simulation tests with many seeds. A failure names the seed, and
+# DST_SEED=<seed> dotnet test test/Falco.Datastar.Tests -c Release replays it.
+#
+# It runs on a schedule as well as on demand, because the default push runs only 25 seeds. That is enough to keep the
+# suite honest on every change and quick enough to run each time, and the rare case that 25 seeds misses is exactly the
+# one a scheduled run exists to find. Without it, "we ran 2000 seeds" is a claim about one afternoon.
+on:
+  workflow_dispatch:
+    inputs:
+      seeds:
+        description: "How many seeds to run for each simulation test (1 to this number)"
+        required: true
+        default: "1000"
+  schedule:
+    # Weekly, early in the morning UTC. Offset from the hour so it does not queue behind every other scheduled run.
+    - cron: "23 4 * * 2"
+
+permissions:
+  contents: read
+
+jobs:
+  dst:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            8.0.x
+            9.0.x
+            10.0.x
+
+      # The default for a scheduled run, which has no inputs to read
+      - name: Work out how many seeds to run
+        id: seeds
+        run: |
+          requested="${{ inputs.seeds }}"
+          if [ -z "$requested" ]; then requested=2000; fi
+          if ! [ "$requested" -ge 1 ] 2>/dev/null; then
+            echo "::error::the seed count has to be a number of at least 1, but it was '$requested'"
+            exit 1
+          fi
+          echo "count=$requested" >> "$GITHUB_OUTPUT"
+          echo "running $requested seeds"
+
+      - name: Test with many seeds
+        run: dotnet test test/Falco.Datastar.Tests -c Release --framework net10.0
+        env:
+          DST_SEEDS: ${{ steps.seeds.outputs.count }}
+
+      # The same seeds on the oldest target the library supports, because a simulation that passes on one runtime and
+      # fails on another is still a failure. It is built here rather than with --no-build, because the step above only
+      # produced net10.0 and there is nothing to reuse for net8.0.
+      - name: Test the same seeds on the oldest target
+        run: dotnet test test/Falco.Datastar.Tests -c Release --framework net8.0
+        env:
+          DST_SEEDS: ${{ steps.seeds.outputs.count }}

.github/workflows/e2e.yml

@@ -0,0 +1,34 @@
+name: e2e
+
+# The browser tests only run when someone starts them: Actions tab, e2e, Run workflow.
+# They load Datastar from a CDN and start a real Chromium, so they are not part of the build that runs on every push and pull request.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      # The tests run on .NET 10. The RocketComponents example targets net9.0, and the library targets net8.0 as well.
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            8.0.x
+            9.0.x
+            10.0.x
+
+      - name: Build
+        run: dotnet build test/Falco.Datastar.E2E -c Release
+
+      - name: Install Chromium
+        run: pwsh test/Falco.Datastar.E2E/bin/Release/net10.0/playwright.ps1 install --with-deps chromium
+
+      - name: Test
+        run: dotnet test test/Falco.Datastar.E2E -c Release --no-build

.github/workflows/mutation.yml

@@ -0,0 +1,78 @@
+name: mutation
+
+# Proves that the test suite catches the mistakes this library could plausibly make. See test/mutation.
+#
+# It rewrites a line of src for each mutant and runs the whole suite, so it is slow and it must not run alongside
+# anything else that builds the repository.
+#
+# It runs on a schedule as well as on demand. The reason is that "every mutant is killed" is a claim about the tests as
+# well as the source, and it rots quietly: delete a test that was the only thing catching a mutant, or add one that is
+# too weak to catch it, and nothing fails until someone remembers to click Run workflow. A scheduled run turns that into
+# a red build instead of a sentence nobody has checked in a year.
+on:
+  workflow_dispatch:
+    inputs:
+      filter:
+        description: "Only run the mutants whose name contains this text"
+        required: false
+        default: ""
+  schedule:
+    # Weekly, early in the morning UTC. Not on the hour, because every scheduled workflow on the planet fires at :00 and
+    # the runners queue for them.
+    - cron: "37 4 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  mutation:
+    runs-on: ubuntu-latest
+    # A full run mutates the source about ninety times and builds and tests after each one, which takes a while.
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      # The program runs dotnet test against net10.0 only, because the code under test is the same for every target.
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      # It rewrites files in src, so it needs the tree exactly as committed, otherwise it cannot put it back.
+      - name: Check the tree is clean
+        run: git diff --exit-code
+
+      - name: Check the mutant list against the source
+        # Fails if a mutant no longer finds its text, so the run below does not spend twenty minutes on a list that is stale
+        run: |
+          dotnet build test/mutation -c Release
+          dotnet run --project test/mutation -c Release --no-build -- check
+
+      - name: Build the library
+        run: dotnet build src/Falco.Datastar -c Release
+
+      # The filter goes through the environment rather than into the command, so a value with a quote or a semicolon in
+      # it is one argument and not shell syntax. dst.yml does the same.
+      - name: Mutate
+        env:
+          DST_MUTATION_FILTER: ${{ inputs.filter }}
+        run: |
+          if [ -n "$DST_MUTATION_FILTER" ]; then
+            dotnet run --project test/mutation -c Release --no-build -- "$DST_MUTATION_FILTER"
+          else
+            dotnet run --project test/mutation -c Release --no-build
+          fi
+
+      # A run that is killed cannot restore the source, so a backup left behind means the tree may still be mutated and
+      # the next job would start from it. Cleaning up here means a cancelled run does not poison the following one.
+      - name: Put the source back
+        if: always()
+        run: dotnet run --project test/mutation -c Release --no-build -- clean
+
+      - name: Check the source was put back
+        run: |
+          if [ -n "$(ls src/Falco.Datastar/*.mutation-backup 2>/dev/null)" ]; then
+            echo "::error::a backup file was left behind, so a mutant was not restored"
+            exit 1
+          fi
+          git diff --exit-code

.gitignore

@@ -354,3 +354,6 @@ MigrationBackup/
 
 # Rider (JetBrain's cross-platform .NET IDE) working folder
 .idea/
+
+# Local tooling preferences, not project source
+.commandcode/