@avi2dg/checks 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.21.0
+
+Released 2026-09-26.
+
+### Features
+
+- **scripts:** let quality.json set the runs-on of generated workflows (#66)
+
 ## 0.20.0
 
 Released 2026-09-26.

package/dist/feature-rules.js

@@ -153,6 +153,10 @@ var Gates = Schema3.Struct({
   scheduled: Schema3.optionalKey(Schema3.Array(Command).annotate({ description: "The commands a cron-scheduled workflow runs" })),
   lint: Schema3.optionalKey(LintGates)
 });
+var RunsOn = Schema3.NonEmptyArray(Schema3.NonEmptyString).annotate({
+  identifier: "RunsOn",
+  description: "The runner labels every job the kit generates runs on; ubuntu-latest when absent"
+});
 var EffectSources = Schema3.Struct({
   paths: Schema3.NonEmptyArray(PathGlob).annotate({
     description: "Where source is written in Effect, held to the Effect rules of oxlint and the language service"
@@ -233,6 +237,7 @@ var Quality = Schema3.Struct({
   $schema: Schema3.optionalKey(Schema3.String),
   defaultBranch: Schema3.optionalKey(Schema3.NonEmptyString.annotate({ description: "The branch pull requests merge into; main when absent" })),
   gates: Schema3.optionalKey(Gates),
+  runsOn: Schema3.optionalKey(RunsOn),
   commitIdentity: Schema3.optionalKey(CommitIdentity),
   sources: Schema3.optionalKey(Sources),
   size: Schema3.optionalKey(Size),

package/docs/configs/quality-file.md

@@ -14,6 +14,7 @@ The kit's bins find the file at the git root and read it there:
     "ci": ["bun run lint", "bun run typecheck", "bun run test"],
     "scheduled": ["bunx checks-flake --runs 10 --report flake-report.json"]
   },
+  "runsOn": ["self-hosted", "Linux", "X64", "winbox"],
   "commitIdentity": { "authors": [{ "name": "avi2d", "email": "avi2dg@gmail.com" }] },
   "sources": {
     "production": ["src/**/*.ts"],
@@ -43,6 +44,7 @@ The kit's bins find the file at the git root and read it there:
 | `gates.ci` | `checks-ci-wiring`, `checks-quality` | the commands CI runs on every pull request, as [checks-ci-wiring](../gates/checks-ci-wiring.md) says |
 | `gates.scheduled` | `checks-ci-wiring` | the commands a schedule runs |
 | `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply, as [Gate selection](../gates/checks-lint.md#gate-selection) says |
+| `runsOn` | `checks-quality` | the runner labels every job the ci and commitlint workflows run on, `ubuntu-latest` when absent |
 | `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit, as [checks-commit-identity](../gates/checks-commit-identity.md) says |
 | `sources.production` | `checks-size-budget`, `checks-repetition`, `checks-quality` | the source the repository ships, as [checks-size-budget](../gates/checks-size-budget.md) and [checks-repetition](../gates/checks-repetition.md) say |
 | `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not, as [The Effect rules](effect-rules.md) says |

package/docs/gates/checks-quality.md

@@ -32,6 +32,8 @@ A rule only this repository needs stays in its own `.oxlintrc.json`, whose overr
 GitHub Actions reads its own YAML and nothing else, so `checks-quality generate` also writes the kit recipe workflows whole.
 `.github/workflows/ci.yml` runs every `gates.ci` command but the title lint as its own step after a frozen install.
 `.github/workflows/commitlint.yml` lints the pull request title with the installed kit config.
+Both jobs run on the runner labels `quality.json` `runsOn` lists, or on `ubuntu-latest` when the key is absent.
+A self-hosted runner in a public repository runs the code of any pull request from a fork.
 A step one repository alone needs lives in another workflow file, never in the recipe.
 All generated workflows are committed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {

package/quality.schema.json

@@ -88,6 +88,9 @@
       },
       "additionalProperties": false
     },
+    "runsOn": {
+      "$ref": "#/$defs/RunsOn"
+    },
     "commitIdentity": {
       "type": "object",
       "properties": {
@@ -406,6 +409,21 @@
       "type": "string",
       "minLength": 1
     },
+    "RunsOn": {
+      "type": "array",
+      "prefixItems": [
+        {
+          "type": "string",
+          "minLength": 1
+        }
+      ],
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "The runner labels every job the kit generates runs on; ubuntu-latest when absent"
+    },
     "Identity": {
       "type": "object",
       "properties": {

package/scripts/quality-file.ts

@@ -82,6 +82,11 @@ const Gates = Schema.Struct({
   lint: Schema.optionalKey(LintGates),
 });
 
+const RunsOn = Schema.NonEmptyArray(Schema.NonEmptyString).annotate({
+  identifier: "RunsOn",
+  description: "The runner labels every job the kit generates runs on; ubuntu-latest when absent",
+});
+
 const EffectSources = Schema.Struct({
   paths: Schema.NonEmptyArray(PathGlob).annotate({
     description: "Where source is written in Effect, held to the Effect rules of oxlint and the language service",
@@ -205,6 +210,7 @@ export const Quality = Schema.Struct({
     Schema.NonEmptyString.annotate({ description: "The branch pull requests merge into; main when absent" }),
   ),
   gates: Schema.optionalKey(Gates),
+  runsOn: Schema.optionalKey(RunsOn),
   commitIdentity: Schema.optionalKey(CommitIdentity),
   sources: Schema.optionalKey(Sources),
   size: Schema.optionalKey(Size),

package/scripts/quality.ts

@@ -105,11 +105,26 @@ function runsInTitleLint(gate: string, commitlintConfig: string): boolean {
   return words !== undefined && invokes(plainCommand(titleLint(commitlintConfig)), words);
 }
 
+// YAML 1.2's core schema resolves these plain scalars to a null, a boolean or a number, and YAML 1.1 parsers also read yes, no, on and off as booleans.
+const NON_STRING_SCALAR =
+  /^(?:~|null|Null|NULL|true|True|TRUE|false|False|FALSE|y|Y|yes|Yes|YES|n|N|no|No|NO|on|On|ON|off|Off|OFF|[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?|0o[0-7]+|0x[0-9a-fA-F]+|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN))$/;
+
 function runScalar(command: string): string {
-  return /(^[\s#&*!|>@`'"%{[-])|:\s|\s#|:$|[\n\\]/.test(command) ? JSON.stringify(command) : command;
+  return /(^[\s#&*!|>@`'"%{[-])|:\s|\s#|:$|[\n\\]/.test(command) || NON_STRING_SCALAR.test(command)
+    ? JSON.stringify(command)
+    : command;
+}
+
+function flowScalar(label: string): string {
+  return /[,[\]{}]/.test(label) ? JSON.stringify(label) : runScalar(label);
+}
+
+function runsOnLine(runsOn: Quality["runsOn"]): string {
+  if (runsOn === undefined) return "ubuntu-latest";
+  return `[${runsOn.map(flowScalar).join(", ")}]`;
 }
 
-export function commitlintWorkflow(commitlintConfig: string): string {
+export function commitlintWorkflow(commitlintConfig: string, runsOn: Quality["runsOn"]): string {
   return `permissions:
   contents: read
 on:
@@ -117,7 +132,7 @@ on:
     types: [opened, edited, synchronize, reopened]
 jobs:
   commitlint:
-    runs-on: ubuntu-latest
+    runs-on: ${runsOnLine(runsOn)}
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
@@ -135,7 +150,13 @@ jobs:
 `;
 }
 
-export function suiteWorkflow(defaultBranch: string, gates: readonly string[], bunVersionFile: boolean, nodeVersionFile: boolean): string {
+export function suiteWorkflow(
+  defaultBranch: string,
+  gates: readonly string[],
+  bunVersionFile: boolean,
+  nodeVersionFile: boolean,
+  runsOn: Quality["runsOn"],
+): string {
   const node = nodeVersionFile
     ? "      - uses: actions/setup-node@v5\n        with:\n          node-version-file: .node-version\n"
     : "";
@@ -143,20 +164,20 @@ export function suiteWorkflow(defaultBranch: string, gates: readonly string[], b
     ? "      - uses: oven-sh/setup-bun@v2\n        with:\n          bun-version-file: .bun-version\n"
     : "      - uses: oven-sh/setup-bun@v2\n";
   const steps = gates.map((gate) => `      - run: ${runScalar(gate)}\n`).join("");
-  return `name: ci\non:\n  push:\n    branches: [${defaultBranch}]\n  pull_request:\n    types: [opened, edited, synchronize, reopened]\njobs:\n  checks:\n    runs-on: ubuntu-latest\n    steps:\n      # The head, not GitHub's merge ref, so the tree the gates read is the commit the range ends at.\n      # The whole history, since the range starts where the head branched from the base branch.\n      - uses: actions/checkout@v5\n        with:\n          ref: \${{ github.event.pull_request.head.sha || github.sha }}\n          fetch-depth: 0\n${node}${setup}      - run: bun install --frozen-lockfile\n${steps}`;
+  return `name: ci\non:\n  push:\n    branches: [${defaultBranch}]\n  pull_request:\n    types: [opened, edited, synchronize, reopened]\njobs:\n  checks:\n    runs-on: ${runsOnLine(runsOn)}\n    steps:\n      # The head, not GitHub's merge ref, so the tree the gates read is the commit the range ends at.\n      # The whole history, since the range starts where the head branched from the base branch.\n      - uses: actions/checkout@v5\n        with:\n          ref: \${{ github.event.pull_request.head.sha || github.sha }}\n          fetch-depth: 0\n${node}${setup}      - run: bun install --frozen-lockfile\n${steps}`;
 }
 
 export function workflowsFor(quality: Quality, recipe: WorkflowRecipe): readonly GeneratedWorkflow[] {
   const commitlint: GeneratedWorkflow = {
     file: COMMITLINT_WORKFLOW,
-    content: commitlintWorkflow(recipe.commitlintConfig),
+    content: commitlintWorkflow(recipe.commitlintConfig, quality.runsOn),
   };
   if (quality.gates?.ci === undefined) return [commitlint];
   const suite = quality.gates.ci.filter((gate) => !runsInTitleLint(gate, recipe.commitlintConfig));
   return [
     {
       file: SUITE_WORKFLOW,
-      content: suiteWorkflow(quality.defaultBranch ?? DEFAULT_BRANCH, suite, recipe.bunVersionFile, recipe.nodeVersionFile),
+      content: suiteWorkflow(quality.defaultBranch ?? DEFAULT_BRANCH, suite, recipe.bunVersionFile, recipe.nodeVersionFile, quality.runsOn),
     },
     commitlint,
   ];