@starci/hfs 4.6.0 → 4.7.1

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -1,8 +1,10 @@
 {{header}}
 name: ci
 
+# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
 on:
   push:
+    branches: ["release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 
@@ -14,24 +16,58 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: false
 
+# The job shape of the StarCi CI standard (knowledge/hfs/ci-standard.yaml): fast, lint per side, the unit run in shards, one coverage merge, build,
+# sonar, and the database types of the lite edition. Timeouts and the shard count come from ci.jobs of .starcistacks/application-stacks.yaml (defaults in the standard).
 jobs:
   fast:
-    timeout-minutes: 20
+    timeout-minutes: {{timeoutFast}}
     runs-on: ubuntu-latest
-{{sonarEnv}}
     steps:
 {{> app/ci-workflows/install-steps.yml}}
-{{> app/ci-workflows/lint-base.yml}}
       - name: production dependency audit
         run: {{auditCommand}}
-{{ciLintSteps}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
 
+  lint:
+    timeout-minutes: {{timeoutLint}}
+    runs-on: ubuntu-latest
+{{sonarEnv}}
+    strategy:
+      fail-fast: false
+      matrix:
+        side: [be, fe]
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/lint-base.yml}}
+{{ciLintSteps}}
+
   test:
-    timeout-minutes: 45
+    timeout-minutes: {{timeoutTest}}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: {{testShards}}
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/jest-cache.yml}}
+      # Each shard measures without the per-file threshold (a shard loads only its share of the specs, and a small suite may leave a shard empty);
+      # the coverage job proves 100 per file on the merged report.
+      - name: unit
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+{{> app/ci-workflows/jest-cache-save.yml}}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && hashFiles('{{lcovReport}}') != ''
+        with:
+          name: coverage-shard-${{ matrix.shard }}
+          path: {{lcovReport}}
+
+  coverage:
+    needs: test
+    timeout-minutes: {{timeoutCoverage}}
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
     permissions:
@@ -39,9 +75,12 @@ jobs:
       id-token: write
     steps:
 {{> app/ci-workflows/install-steps.yml}}
-{{> app/ci-workflows/jest-cache.yml}}
-      - name: unit
-        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          pattern: coverage-shard-*
+          path: {{lcovShardsDir}}
+      - name: merge coverage
+        run: npx starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
       - name: coverage proof
         run: {{ciCoverageProof}}
         env:
@@ -54,19 +93,20 @@ jobs:
 {{codecovSteps}}
 
   build:
-    timeout-minutes: 30
+    timeout-minutes: {{timeoutBuild}}
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}
       - name: build be
         run: npm run build:be
 {{ciBuildSteps}}
+{{> app/ci-workflows/build-cache-save.yml}}
       - name: database migration checks
         run: {{ciDatabaseLint}}
 
 {{sonarJob}}
   db-types:
-    timeout-minutes: 30
+    timeout-minutes: {{timeoutDbTypes}}
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}

package/templates/app/hooks/husky/pre-push

@@ -4,6 +4,8 @@
 #   refs/backup/*                  allowed: the coordinator backup namespace
 #   refs/heads/main, refs/tags/v*  allowed only when HEAD carries an annotated tag v[0-9]* and the release cut recorded the
 #                                  full suite of HEAD: <git common dir>/starci-release/<HEAD sha>.l4.json names that head and tag
+#   refs/heads/release/candidate-* the release candidate (starci app release push sends the release sha there first and moves main
+#                                  and the tag only when its ci.yml run is green): allowed under the same release gate, never deleted
 #   any other ref, a delete        refused
 common=$(git rev-parse --git-common-dir)
 case "$common" in /* | [A-Za-z]:*) ;; *) common="$(pwd)/$common" ;; esac
@@ -12,7 +14,7 @@ record="$common/starci-release/$head.l4.json"
 status=0
 gate=""
 refuse() {
-  echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main and v* tags) or refs/backup/* (backups)" >&2
+  echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main, v* tags and the release/candidate-* ref) or refs/backup/* (backups)" >&2
   status=1
 }
 # gate: the verdict of the release gate for HEAD, computed once: "ok" or the reason it is closed.
@@ -33,7 +35,7 @@ release_gate() {
 while read -r local_ref local_sha remote_ref remote_sha; do
   case "$remote_ref" in
     refs/backup/*) ;;
-    refs/heads/main | refs/tags/v*)
+    refs/heads/main | refs/tags/v* | refs/heads/release/candidate-*)
       case "$local_sha" in
         *[!0]*) ;;
         *) refuse "refusing to delete $remote_ref"; continue ;;

package/release/ci-red.mjs

@@ -1,102 +0,0 @@
-// ci-red.mjs - the latest completed default-branch CI is a release precondition; unreadable GitHub warns, a red run needs the owner's SHA-bound override.
-import fs from 'node:fs';
-import path from 'node:path';
-import { refusal } from '../stack/errors.mjs';
-
-const FIELDS = 'databaseId,headSha,status,conclusion,url,event,createdAt';
-const SHA = /^[a-f0-9]{40}$/u;
-const RED = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure', 'action_required']);
-
-/** Every process uses the supplied seam; an unavailable executable is an unreadable result. */
-function run(spawn, cwd, command, args) {
-  try { return spawn(command, args, { cwd }); } catch { return { status: null }; }
-}
-
-function runsOf(result) {
-  if (result.error || result.status !== 0) return null;
-  try {
-    const rows = JSON.parse(result.stdout);
-    return Array.isArray(rows) ? rows : null;
-  } catch { return null; }
-}
-
-/** Resolve each available default-branch reference once, including HEAD in detached release worktrees. */
-function referenceTips(spawn, cwd, defaultBranch) {
-  const refs = [`origin/${defaultBranch}`, defaultBranch, 'HEAD'];
-  return refs.flatMap((name) => {
-    const result = run(spawn, cwd, 'git', ['rev-parse', '--verify', '--quiet', `${name}^{commit}`]);
-    const tip = String(result.stdout ?? '').trim();
-    return !result.error && result.status === 0 && SHA.test(tip) ? [{ name, tip }] : [];
-  });
-}
-
-/** Equality proves reachability directly; ancestry is unknown only when every available probe errors. */
-function pushAncestry(spawn, cwd, row, refs) {
-  if (refs.some((ref) => ref.tip === row.headSha)) return { candidate: true, unknown: false };
-  let known = false;
-  for (const ref of refs) {
-    const result = run(spawn, cwd, 'git', ['merge-base', '--is-ancestor', row.headSha, ref.tip]);
-    if (!result.error && result.status === 0) return { candidate: true, unknown: false };
-    if (!result.error && result.status === 1) known = true;
-  }
-  return { candidate: false, unknown: !known };
-}
-
-/** Branch rows remain candidates; push rows must reach a resolved reference, and each databaseId counts once. */
-function candidateRuns(spawn, cwd, branch, pushes, refs) {
-  const candidates = branch.filter((row) => row && SHA.test(row.headSha));
-  let ancestryUnknown = refs.length === 0;
-  for (const row of pushes) {
-    if (!row || !SHA.test(row.headSha) || row.event !== 'push') continue;
-    const ancestry = pushAncestry(spawn, cwd, row, refs);
-    if (ancestry.candidate) candidates.push(row);
-    if (ancestry.unknown) ancestryUnknown = true;
-  }
-  const unique = new Map();
-  for (const row of candidates) if (!unique.has(row.databaseId)) unique.set(row.databaseId, row);
-  return { candidates: [...unique.values()], ancestryUnknown };
-}
-
-/** Reads branch runs plus push/tag runs whose commits are reachable from the default branch; the newest completed run decides, even if a newer run is pending. */
-export function latestDefaultBranchCi({ spawn, cwd, defaultBranch = 'main' }) {
-  const refs = referenceTips(spawn, cwd, defaultBranch);
-  const unknown = (why) => ({ state: 'unknown', why: `${why} (refs: ${refs.map((ref) => ref.name).join(', ') || 'none'})` });
-  const args = ['run', 'list', '--workflow', 'ci.yml'];
-  const tail = ['--limit', '20', '--json', FIELDS];
-  const branch = runsOf(run(spawn, cwd, 'gh', [...args, '--branch', defaultBranch, ...tail]));
-  if (!branch) return unknown('gh branch runs unavailable (missing gh, authentication, or unreadable response)');
-  const pushes = runsOf(run(spawn, cwd, 'gh', [...args, '--event', 'push', ...tail]));
-  if (!pushes) return unknown('gh push runs unavailable (missing gh, authentication, or unreadable response)');
-  const { candidates, ancestryUnknown } = candidateRuns(spawn, cwd, branch, pushes, refs);
-  const completed = candidates.filter((row) => row.status === 'completed' && Number.isFinite(Date.parse(row.createdAt)));
-  completed.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || Number(b.databaseId) - Number(a.databaseId));
-  const latest = completed[0];
-  if (!latest) return unknown(ancestryUnknown ? 'cannot establish push run ancestry on the default branch' : 'no completed CI run on the default branch');
-  if (latest.conclusion === 'success') return { state: 'green', run: latest };
-  if (RED.has(latest.conclusion)) return { state: 'red', run: latest };
-  return { ...unknown('latest completed CI run has no success or red conclusion'), run: latest };
-}
-
-/** Only a complete starci/ci-override@1 record for this exact commit can excuse a red run. */
-function overrideOf(ctx, sha) {
-  const common = run(ctx.spawn, ctx.cwd, 'git', ['rev-parse', '--git-common-dir']);
-  if (common.error || common.status !== 0 || !String(common.stdout ?? '').trim()) return null;
-  const file = path.join(path.resolve(ctx.cwd, String(common.stdout).trim()), 'starci-release', `${sha}.ci-override.json`);
-  try {
-    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (record.schema !== 'starci/ci-override@1' || record.sha !== sha || typeof record.reason !== 'string' || !record.reason.trim() || typeof record.by !== 'string' || !record.by.trim() || typeof record.at !== 'string' || !Number.isFinite(Date.parse(record.at))) return null;
-    return record;
-  } catch { return null; }
-}
-
-/** Warns on unknown CI and refuses red CI unless the owner left a valid override beside the release records. */
-export function requireGreenCi(ctx, ci) {
-  if (ci.state === 'unknown') {
-    ctx.stderr(`RELEASE_CI_UNKNOWN: ${ci.why}\n`);
-    return [];
-  }
-  if (ci.state !== 'red') return [];
-  const record = overrideOf(ctx, ci.run.headSha);
-  if (record) return [`RELEASE_CI_RED overridden by the owner: ${record.reason}`];
-  throw refusal('RELEASE_CI_RED', `CI run ${ci.run.url} for ${ci.run.headSha} concluded ${ci.run.conclusion}; the owner must use starci release ci-override --sha ${ci.run.headSha} --reason <text>`);
-}