@avi2dg/checks 0.63.1 → 0.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.63.1",
+  "version": "0.65.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -44,6 +44,7 @@
     "src/delivery/release-pr.ts",
     "src/delivery/release-preflight.ts",
     "src/delivery/release-schedule.ts",
+    "src/delivery/schedule-policy.ts",
     "src/delivery/release-publish.ts",
     "src/delivery/release-push.ts",
     "src/delivery/release-tag.ts",
@@ -53,6 +54,7 @@
     "src/testing/block-screens.ts",
     "src/testing/test.ts",
     "src/testing/test-skips.ts",
+    "src/testing/affected-tests.ts",
     "src/core/swc.ts",
     "src/testing/test-report.ts",
     "src/testing/flake.ts",
@@ -76,11 +78,13 @@
     "src/delivery/workflow-references.ts",
     "src/delivery/bun-pin.ts",
     "src/delivery/mutation-job.ts",
+    "src/delivery/job-timeout.ts",
     "src/delivery/runner-policy.ts",
     "src/delivery/secrets.ts",
     "src/delivery/secrets-pack.ts",
     "src/delivery/pr-text.ts",
     "src/delivery/setup.ts",
+    "src/delivery/setup-workflow.ts",
     "src/delivery/gitleaks.ts",
     "src/delivery/gitleaks.toml",
     "src/quality/comment-matchers.ts",

package/src/delivery/ci-wiring.ts

@@ -4,9 +4,11 @@ import { defaultBranch, git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
 import { findBunPinFaults, formatBunPinReport, readBunPinPolicy } from "./bun-pin.ts";
+import { findLongJobs, formatLongJobReport } from "./job-timeout.ts";
 import { readScheduleFiles, readShellFiles } from "./mutation-job.ts";
 import { findScheduledReleases, formatScheduleReport } from "./release-schedule.ts";
 import { findRunnerFaults, formatRunnerReport, jobRuns, readRunnerConfig } from "./runner-policy.ts";
+import { findScheduledRuns, formatScheduledRunReport } from "./schedule-policy.ts";
 import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
 import { findMissingWorkflows, formatMissingReport, isRecord, names, workflowJobs, type Workflow } from "./workflow-references.ts";
 
@@ -65,6 +67,7 @@ const TITLE_LINT = "bunx checks-commit-title";
 const TITLE_CALLS = ["bun src/delivery/commit-title.ts", "./node_modules/.bin/commitlint"];
 const ScriptsManifest = Schema.Struct({
   scripts: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+  private: Schema.optionalKey(Schema.Boolean),
 });
 // Without these a pull_request workflow never sees the commits a pull request pushes.
 const GATING_TYPES = ["opened", "synchronize"];
@@ -271,16 +274,19 @@ export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflo
     catch: (error) => new WiringError({ message: `cannot parse ${path}: ${String(error)}` }),
   });
 
-const readScripts = Effect.fn("readScripts")(function* (root: string) {
+const readManifest = Effect.fn("readManifest")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const file = (yield* Path.Path).join(root, "package.json");
-  const { scripts = {} } = (yield* fs.exists(file))
+  return (yield* fs.exists(file))
     ? yield* fs.readFileString(file).pipe(
         Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(ScriptsManifest))),
         Effect.mapError((cause) => new WiringError({ message: `cannot read ${file}: ${cause.message}` })),
       )
     : ScriptsManifest.make({});
-  return new Map(Object.entries(scripts));
+});
+
+const readScripts = Effect.fn("readScripts")(function* (root: string) {
+  return new Map(Object.entries((yield* readManifest(root)).scripts ?? {}));
 });
 
 export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
@@ -322,17 +328,24 @@ const wiring = Effect.gen(function* () {
   yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
   const missing = findMissingWorkflows(workflows);
   if (missing.length > 0) yield* Console.error(formatMissingReport(missing));
-  const scripts = yield* readScripts(root);
+  const manifest = yield* readManifest(root);
+  const scripts = new Map(Object.entries(manifest.scripts ?? {}));
+  const visibility = yield* readVisibility;
   const runs = workflows.flatMap((workflow) => workflowJobs(workflow).flatMap(([, job]) => jobRuns(workflow, job)));
   const runners = yield* readRunnerConfig(root);
-  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts, files: yield* readShellFiles(root, scripts, runs), runners }, workflows);
+  const faults = findRunnerFaults({ visibility, scripts, files: yield* readShellFiles(root, scripts, runs), runners }, workflows);
   if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
   const bunFaults = findBunPinFaults(yield* readBunPinPolicy(root, workflows), workflows);
   if (bunFaults.length > 0) yield* Console.error(formatBunPinReport(bunFaults));
   const scheduleFiles = yield* readScheduleFiles(root, scripts, runs);
-  const scheduled = findScheduledReleases(workflows, { scripts, files: scheduleFiles });
+  const owner = { visibility, publishes: manifest.private !== true };
+  const scheduled = findScheduledReleases(workflows, { scripts, files: scheduleFiles }, owner);
   if (scheduled.length > 0) yield* Console.error(formatScheduleReport(scheduled));
-  return gaps.length === 0 && faults.length === 0 && missing.length === 0 && bunFaults.length === 0 && scheduled.length === 0;
+  const scheduledRuns = findScheduledRuns(workflows, { scripts, files: scheduleFiles }, owner);
+  if (scheduledRuns.length > 0) yield* Console.error(formatScheduledRunReport(scheduledRuns));
+  const longJobs = findLongJobs(workflows);
+  if (longJobs.length > 0) yield* Console.error(formatLongJobReport(longJobs));
+  return [gaps, faults, missing, bunFaults, scheduled, scheduledRuns, longJobs].every((found) => found.length === 0);
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/src/delivery/job-timeout.ts

@@ -0,0 +1,30 @@
+import { workflowJobs, type Workflow } from "./workflow-references.ts";
+
+export type LongJob = {
+  readonly location: string;
+  readonly fault: string;
+};
+
+const LIMIT = 60;
+const SET = `set timeout-minutes to a number of at most ${LIMIT}`;
+
+function timeoutFault(timeout: unknown): string | undefined {
+  if (timeout === undefined) return "the job sets no timeout-minutes, so a hung run holds its runner for GitHub's 360 minute default; " + SET;
+  if (typeof timeout !== "number") return "its timeout-minutes cannot be shown to stay within an hour before the run; " + SET;
+  return timeout > LIMIT ? `its timeout-minutes of ${timeout} lets the job run for hours; ${SET}` : undefined;
+}
+
+// A job that calls a reusable workflow cannot set timeout-minutes, and the called workflow's own jobs are judged where it lives.
+export function findLongJobs(workflows: readonly Workflow[]): readonly LongJob[] {
+  return workflows.flatMap((workflow) =>
+    workflowJobs(workflow).flatMap(([id, job]) => {
+      if (job["uses"] !== undefined) return [];
+      const fault = timeoutFault(job["timeout-minutes"]);
+      return fault === undefined ? [] : [{ location: `${workflow.path} job ${id}`, fault }];
+    }),
+  );
+}
+
+export function formatLongJobReport(jobs: readonly LongJob[]): string {
+  return [`ci-wiring: ${jobs.length} job(s) can run for hours:`, ...jobs.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}

package/src/delivery/release-push.ts

@@ -12,7 +12,7 @@ const LABEL = "release-push";
 const USAGE = "usage: release-push.ts <release-workflow> <workflow>...";
 const UNTAGGED = "tag the release commit with checks-release-tag, whose refusal says what to fix";
 const POLL = Duration.seconds(15);
-const POLLS = 180;
+const POLLS = 88;
 
 const Run = Schema.Struct({ path: Schema.String, status: Schema.String, conclusion: Schema.NullOr(Schema.String), html_url: Schema.String });
 type Run = typeof Run.Type;

package/src/delivery/release-schedule.ts

@@ -5,6 +5,7 @@ import { isRecord, locate, names, workflowJobs, type Workflow } from "./workflow
 
 export type ScheduledRelease = {
   readonly location: string;
+  readonly fault: string;
 };
 
 export type ScheduleContext = {
@@ -12,18 +13,26 @@ export type ScheduleContext = {
   readonly files: ReadonlyMap<string, string>;
 };
 
-const EMPTY: ScheduleContext = { scripts: new Map(), files: new Map() };
+export type ScheduleOwner = {
+  readonly visibility: "private" | "public" | "unknown";
+  readonly publishes: boolean;
+};
 
 const RELEASE_BINS = ["pr", "push", "tag", "publish"].flatMap((bin) => [`checks-release-${bin}`, `release-${bin}.ts`]);
+const PUBLISH_BINS = ["checks-release-publish", "release-publish.ts"];
+const NUMBER = /^\d+$/;
+const BY_HAND = "drop the schedule, so a release runs only when someone starts it";
+
+function isBinIn(bins: readonly string[], word: string): boolean {
+  return bins.some((name) => word === name || word.endsWith(`/${name}`));
+}
 
-function isReleaseBin(word: string): boolean {
-  return RELEASE_BINS.some((name) => word === name || word.endsWith(`/${name}`));
+function isPublishCommand([head = "", ...rest]: Command): boolean {
+  return (head === "npm" && rest[0] === "publish") || isBinIn(PUBLISH_BINS, head);
 }
 
 function isReleaseCommand(program: Command): boolean {
-  const [head = "", ...rest] = program;
-  if (head === "npm" && rest[0] === "publish") return true;
-  return isReleaseBin(head);
+  return isPublishCommand(program) || isBinIn(RELEASE_BINS, program[0] ?? "");
 }
 
 function localUses(job: Readonly<Record<string, unknown>>): string | undefined {
@@ -31,9 +40,10 @@ function localUses(job: Readonly<Record<string, unknown>>): string | undefined {
   return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
 }
 
-function workflowReleases(
+function workflowRuns(
   workflow: Workflow,
   context: ScheduleContext,
+  isBin: (program: Command) => boolean,
   byPath: ReadonlyMap<string, Workflow>,
   walkedWorkflows: readonly string[],
 ): boolean {
@@ -41,32 +51,57 @@ function workflowReleases(
   if (
     workflowJobs(workflow)
       .flatMap(([, job]) => jobRuns(workflow, job))
-      .some((run) => runsBin(run, context.scripts, files, isReleaseCommand, true))
+      .some((run) => runsBin(run, context.scripts, files, isBin, true))
   )
     return true;
   return workflowJobs(workflow).some(([, job]) => {
     const called = localUses(job);
     if (called === undefined || walkedWorkflows.includes(called)) return false;
     const next = byPath.get(called);
-    return next !== undefined && workflowReleases(next, context, byPath, [...walkedWorkflows, called]);
+    return next !== undefined && workflowRuns(next, context, isBin, byPath, [...walkedWorkflows, called]);
   });
 }
 
-function schedules(document: unknown): boolean {
+function crons(document: unknown): readonly unknown[] {
+  const on = isRecord(document) ? document["on"] : undefined;
+  const schedule = isRecord(on) ? on["schedule"] : undefined;
+  return Array.isArray(schedule) ? schedule.map((entry) => (isRecord(entry) ? entry["cron"] : undefined)) : [];
+}
+
+// At most once a day is one minute and one hour, whatever the day, month and weekday fields allow.
+export function atMostDaily(cron: unknown): boolean {
+  if (typeof cron !== "string") return false;
+  const fields = cron.trim().split(/\s+/);
+  return fields.length === 5 && NUMBER.test(fields[0] ?? "") && NUMBER.test(fields[1] ?? "");
+}
+
+// A run outside CI cannot read whether the repository is private, so only a package.json that sets private refuses there.
+function releaseFault(workflow: Workflow, owner: ScheduleOwner, publishesToNpm: boolean): string | undefined {
+  if (owner.visibility === "private" || !owner.publishes || !publishesToNpm) return "only a public package that publishes to npm releases on a schedule; " + BY_HAND;
+  const entries = crons(workflow.document);
+  if (entries.length === 1 && entries.every(atMostDaily)) return undefined;
+  return 'the release runs more than once a day; keep one cron at a minute and an hour, such as "7 3 * * *"';
+}
+
+export function schedules(document: unknown): boolean {
   const on = isRecord(document) ? document["on"] : undefined;
   return isRecord(on) ? "schedule" in on : (names(on) ?? []).includes("schedule");
 }
 
-export function findScheduledReleases(workflows: readonly Workflow[], context: ScheduleContext = EMPTY): readonly ScheduledRelease[] {
+export function releasesOnSchedule(workflows: readonly Workflow[], context: ScheduleContext): readonly Workflow[] {
   const byPath = new Map(workflows.map((workflow) => [workflow.path, workflow] as const));
-  return workflows
-    .filter((workflow) => schedules(workflow.document) && workflowReleases(workflow, context, byPath, [workflow.path]))
-    .map((workflow) => ({ location: locate(workflow.path, workflow.text.split("\n"))(["on"], "schedule", "on schedule") }));
+  return workflows.filter((workflow) => schedules(workflow.document) && workflowRuns(workflow, context, isReleaseCommand, byPath, [workflow.path]));
+}
+
+export function findScheduledReleases(workflows: readonly Workflow[], context: ScheduleContext, owner: ScheduleOwner): readonly ScheduledRelease[] {
+  const byPath = new Map(workflows.map((workflow) => [workflow.path, workflow] as const));
+  const publishesToNpm = workflows.some((workflow) => workflowRuns(workflow, context, isPublishCommand, byPath, [workflow.path]));
+  return releasesOnSchedule(workflows, context).flatMap((workflow) => {
+    const fault = releaseFault(workflow, owner, publishesToNpm);
+    return fault === undefined ? [] : [{ location: locate(workflow.path, workflow.text.split("\n"))(["on"], "schedule", "on schedule"), fault }];
+  });
 }
 
 export function formatScheduleReport(scheduled: readonly ScheduledRelease[]): string {
-  return [
-    `ci-wiring: ${scheduled.length} workflow(s) release on a schedule:`,
-    ...scheduled.map(({ location }) => `  ${location}: drop the schedule, so a release runs only when someone starts it`),
-  ].join("\n");
+  return [`ci-wiring: ${scheduled.length} workflow(s) release on a schedule:`, ...scheduled.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
 }

package/src/delivery/schedule-policy.ts

@@ -0,0 +1,64 @@
+import { runsBin } from "./mutation-job.ts";
+import { releasesOnSchedule, schedules } from "./release-schedule.ts";
+import { jobRuns } from "./runner-policy.ts";
+import { invokes, plainCommand, type Command } from "./shell-command.ts";
+import { isRecord, locate, workflowJobs, type Workflow } from "./workflow-references.ts";
+import type { ScheduleContext, ScheduleOwner } from "./release-schedule.ts";
+
+export type ScheduledRun = {
+  readonly location: string;
+  readonly fault: string;
+};
+
+const ADVISORY_BINS = ["checks-advisories", "advisories.ts"];
+const INSTALL = ["bun", "install"];
+const NUMBER = /^\d+$/;
+const WEEKDAY = /^(?:[0-7]|sun|mon|tue|wed|thu|fri|sat)$/i;
+const BY_HAND = "drop the schedule, so it runs only when someone starts it with gh workflow run";
+
+function isAdvisoryBin([head = ""]: Command): boolean {
+  return ADVISORY_BINS.some((name) => head === name || head.endsWith(`/${name}`));
+}
+
+function crons(document: unknown): readonly unknown[] {
+  const on = isRecord(document) ? document["on"] : undefined;
+  const schedule = isRecord(on) ? on["schedule"] : undefined;
+  return Array.isArray(schedule) ? schedule.map((entry) => (isRecord(entry) ? entry["cron"] : undefined)) : [];
+}
+
+// Once a week is one minute, one hour and one weekday, on any day of any month.
+export function weekly(cron: unknown): boolean {
+  if (typeof cron !== "string") return false;
+  const [minute = "", hour = "", day = "", month = "", weekday = "", ...rest] = cron.trim().split(/\s+/);
+  return rest.length === 0 && NUMBER.test(minute) && NUMBER.test(hour) && day === "*" && month === "*" && WEEKDAY.test(weekday);
+}
+
+function scansAdvisoriesOnly(workflow: Workflow, context: ScheduleContext): boolean {
+  const files = (file: string) => context.files.get(file);
+  const runs = workflowJobs(workflow).flatMap(([, job]) => jobRuns(workflow, job));
+  const scans = runs.filter((run) => runsBin(run, context.scripts, files, isAdvisoryBin, true));
+  return scans.length > 0 && runs.every((run) => scans.includes(run) || invokes(plainCommand(run.script), INSTALL));
+}
+
+function advisoryFault(workflow: Workflow, owner: ScheduleOwner): string | undefined {
+  if (owner.visibility === "private") return "a private repository scans advisories by hand; " + BY_HAND;
+  if (!owner.publishes) return "a package.json that sets private publishes nothing to npm, so it scans advisories by hand; " + BY_HAND;
+  const entries = crons(workflow.document);
+  if (entries.length === 1 && entries.every(weekly)) return undefined;
+  return 'the advisory scan runs more than once a week; keep one cron at a minute, an hour and a weekday, such as "15 5 * * 1"';
+}
+
+// A workflow that releases on a schedule is the release rule's to judge, so this rule passes over it.
+export function findScheduledRuns(workflows: readonly Workflow[], context: ScheduleContext, owner: ScheduleOwner): readonly ScheduledRun[] {
+  const releasing = new Set(releasesOnSchedule(workflows, context));
+  return workflows.flatMap((workflow) => {
+    if (!schedules(workflow.document) || releasing.has(workflow)) return [];
+    const fault = scansAdvisoriesOnly(workflow, context) ? advisoryFault(workflow, owner) : BY_HAND;
+    if (fault === undefined) return [];
+    return [{ location: locate(workflow.path, workflow.text.split("\n"))(["on"], "schedule", "on schedule"), fault }];
+  });
+}
+
+export function formatScheduledRunReport(scheduled: readonly ScheduledRun[]): string {
+  return [`ci-wiring: ${scheduled.length} workflow(s) run on a schedule:`, ...scheduled.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}

package/src/delivery/setup-workflow.ts

@@ -0,0 +1,43 @@
+const HOSTED_FALLBACK = "ubuntu-latest";
+const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
+
+export function ciWorkflow(isPrivate: boolean, hasBuild: boolean): string {
+  const lines = [
+    "name: ci",
+    "",
+    "on:",
+    "  pull_request:",
+    "    types: [opened, synchronize]",
+    "",
+    "concurrency:",
+    "  group: ci-${{ github.event.pull_request.number }}",
+    "  cancel-in-progress: true",
+    "",
+    "jobs:",
+    "  checks:",
+    "    runs-on: " + (isPrivate ? HOSTED_DEFAULT : HOSTED_FALLBACK),
+    "    timeout-minutes: 30",
+    "    steps:",
+    "      - uses: actions/checkout@v5",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: oven-sh/setup-bun@v2",
+    "        with:",
+    "          bun-version-file: .bun-version",
+    "      - run: bun install --frozen-lockfile",
+  ];
+  if (hasBuild) {
+    lines.push("      - run: bun run build", "      - run: git diff --exit-code");
+  }
+  lines.push("      - run: bun run lint", "      - run: bun run typecheck", "      - run: bun run test");
+  lines.push(
+    "      - id: title",
+    "        name: lint the title",
+    "        env:",
+    "          PR_TITLE: ${{ github.event.pull_request.title }}",
+    "          GH_TOKEN: ${{ github.token }}",
+    "        run: bunx checks-commit-title",
+    "",
+  );
+  return lines.join("\n");
+}

package/src/delivery/setup.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { runMain, Usage } from "../core/main.ts";
+import { ciWorkflow } from "./setup-workflow.ts";
 import { TEMPLATES } from "../docs/doc-templates.ts";
 import { scriptOptions } from "../testing/test.ts";
 import { withServiceOverrides, type ServiceOverride } from "../quality/effect-scope.ts";
@@ -10,8 +11,6 @@ import severities from "../quality/presets/effect.language-service.json" with {
 const NAME = "checks-setup";
 const USAGE = "usage: " + NAME + " [--private]";
 const PRIVATE = "--private";
-const HOSTED_FALLBACK = "ubuntu-latest";
-const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
 const IGNORE_ENTRY = "node_modules/";
 const KIT_ID = "@avi2dg/checks";
 
@@ -116,42 +115,6 @@ const KNIP_CONFIG = [
   "",
 ].join("\n");
 
-function workflow(isPrivate: boolean, hasBuild: boolean): string {
-  const lines = [
-    "name: ci",
-    "",
-    "on:",
-    "  pull_request:",
-    "    types: [opened, synchronize]",
-    "",
-    "jobs:",
-    "  checks:",
-    "    runs-on: " + (isPrivate ? HOSTED_DEFAULT : HOSTED_FALLBACK),
-    "    steps:",
-    "      - uses: actions/checkout@v5",
-    "        with:",
-    "          fetch-depth: 0",
-    "      - uses: oven-sh/setup-bun@v2",
-    "        with:",
-    "          bun-version-file: .bun-version",
-    "      - run: bun install --frozen-lockfile",
-  ];
-  if (hasBuild) {
-    lines.push("      - run: bun run build", "      - run: git diff --exit-code");
-  }
-  lines.push("      - run: bun run lint", "      - run: bun run typecheck", "      - run: bun run test");
-  lines.push(
-    "      - id: title",
-    "        name: lint the title",
-    "        env:",
-    "          PR_TITLE: ${{ github.event.pull_request.title }}",
-    "          GH_TOKEN: ${{ github.token }}",
-    "        run: bunx checks-commit-title",
-    "",
-  );
-  return lines.join("\n");
-}
-
 const kitText = Effect.fn("kitText")(function* (file: string) {
   const system = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -385,7 +348,7 @@ const check = Effect.gen(function* () {
     : OXLINT_CONFIG;
   yield* setupTsconfig(root, oxlintText);
   yield* setupFile(root, "knip.config.ts", KNIP_CONFIG);
-  yield* setupFile(root, ".github/workflows/ci.yml", workflow(isPrivate, outcome.hasBuild));
+  yield* setupFile(root, ".github/workflows/ci.yml", ciWorkflow(isPrivate, outcome.hasBuild));
   for (const kind of Object.keys(TEMPLATES)) {
     yield* setupFile(root, "templates/" + kind + ".md", yield* kitText("dist/templates/" + kind + ".md"));
   }