repokeeper 0.5.0 → 0.7.0

package/dist/gitlab/settings.js

@@ -0,0 +1,181 @@
+import { ApiError } from "../errors.js";
+export const ACCESS_LEVELS = { none: 0, developers: 30, maintainers: 40 };
+/** Description of the pipeline schedule repokeeper owns; a schedule under another name is never touched. */
+export const RENOVATE_SCHEDULE = "repokeeper: renovate";
+const MERGE_FIELDS = {
+    method: "merge_method",
+    squash: "squash_option",
+    delete_source_branch: "remove_source_branch_after_merge",
+    pipeline_must_succeed: "only_allow_merge_if_pipeline_succeeds",
+    discussions_must_be_resolved: "only_allow_merge_if_all_discussions_are_resolved",
+};
+function expect2xx(response, what, project) {
+    if (response.status < 400)
+        return response;
+    const data = response.data;
+    const said = data?.message ?? data?.error;
+    const message = typeof said === "string" ? said : said ? JSON.stringify(said) : `HTTP ${response.status}`;
+    const access = response.status === 401 || response.status === 403 || response.status === 404
+        ? `; this needs the Maintainer role on ${project} and a token with the api scope`
+        : "";
+    throw new ApiError(`${what} failed: ${message}${access}`);
+}
+const show = (value) => value === undefined || value === null || value === ""
+    ? "(none)"
+    : Array.isArray(value)
+        ? value.join(", ") || "(none)"
+        : String(value);
+const levels = (list) => (list ?? []).map((entry) => entry.access_level ?? -1).sort((a, b) => a - b);
+const levelName = (level) => Object.entries(ACCESS_LEVELS).find(([, value]) => value === level)?.[0] ??
+    // a user, a group or a deploy key allowed by name (paid tiers), or a level repokeeper has no word for
+    (level === -1 ? "named members" : `level ${level}`);
+const describeLevels = (list) => (list.length === 0 ? "none" : list.map(levelName).join(" + "));
+function describeProtection(protection) {
+    if (protection === null)
+        return "(not protected)";
+    return [
+        `push: ${describeLevels(protection.push)}`,
+        `merge: ${describeLevels(protection.merge)}`,
+        protection.forcePush ? "force push allowed" : "no force push",
+    ].join("; ");
+}
+const branchOf = (ref) => ref.replace(/^refs\/heads\//, "");
+const describeSchedule = (schedule) => schedule === undefined
+    ? "(none)"
+    : `${schedule.cron} on ${branchOf(schedule.ref)}${schedule.active ? "" : " (inactive)"}`;
+/**
+ * Reads the project's current settings and lists what differs from `settings`. Reads only.
+ *
+ * @param secrets CI/CD variables the generated jobs wait for; a missing one is reported, never created.
+ */
+export async function planGitlab(api, path, settings, secrets = []) {
+    const base = `/projects/${encodeURIComponent(path)}`;
+    const get = async (suffix, what, missingOk = false) => {
+        const response = await api.request("GET", `${base}${suffix}`);
+        return missingOk && response.status === 404 ? response : expect2xx(response, what, path);
+    };
+    const send = async (method, suffix, what, body) => {
+        expect2xx(await api.request(method, `${base}${suffix}`, body), what, path);
+    };
+    const changes = [];
+    const current = (await get("", `reading ${path}`)).data;
+    for (const [key, field] of Object.entries(MERGE_FIELDS)) {
+        const want = settings.merge?.[key];
+        if (want === undefined || current[field] === want)
+            continue;
+        changes.push({
+            setting: `merge.${key}`,
+            from: show(current[field]),
+            to: show(want),
+            apply: () => send("PUT", "", `setting merge.${key}`, { [field]: want }),
+        });
+    }
+    if (settings.description !== undefined && (current.description ?? "") !== settings.description) {
+        const description = settings.description;
+        changes.push({
+            setting: "description",
+            from: show(current.description),
+            to: show(description),
+            apply: () => send("PUT", "", "setting the description", { description }),
+        });
+    }
+    if (settings.topics !== undefined) {
+        const have = (current.topics ?? []).slice().sort();
+        const want = [...settings.topics].sort();
+        if (JSON.stringify(have) !== JSON.stringify(want)) {
+            changes.push({
+                setting: "topics",
+                from: show(have),
+                to: show(want),
+                apply: () => send("PUT", "", "setting topics", { topics: want }),
+            });
+        }
+    }
+    const branch = settings.default_branch ?? current.default_branch ?? "main";
+    if (settings.protect !== undefined) {
+        const rule = `/protected_branches/${encodeURIComponent(branch)}`;
+        const response = await get(rule, `reading the protection of ${branch}`, true);
+        const existing = response.status === 404 ? null : response.data;
+        const have = existing && {
+            push: levels(existing.push_access_levels),
+            merge: levels(existing.merge_access_levels),
+            forcePush: existing.allow_force_push === true,
+        };
+        if (settings.protect === false) {
+            if (have) {
+                changes.push({
+                    setting: `protect ${branch}`,
+                    from: describeProtection(have),
+                    to: describeProtection(null),
+                    apply: () => send("DELETE", rule, `removing the protection of ${branch}`),
+                });
+            }
+        }
+        else {
+            const want = {
+                push: [ACCESS_LEVELS[settings.protect.push ?? "maintainers"]],
+                merge: [ACCESS_LEVELS[settings.protect.merge ?? "maintainers"]],
+                forcePush: settings.protect.allow_force_push ?? false,
+            };
+            if (JSON.stringify(have) !== JSON.stringify(want)) {
+                changes.push({
+                    setting: `protect ${branch}`,
+                    from: describeProtection(have),
+                    to: describeProtection(want),
+                    // a protection is replaced as a whole: changing its access levels in place needs the id of each one
+                    apply: async () => {
+                        if (have)
+                            await send("DELETE", rule, `removing the protection of ${branch}`);
+                        await send("POST", "/protected_branches", `protecting ${branch}`, {
+                            name: branch,
+                            push_access_level: want.push[0],
+                            merge_access_level: want.merge[0],
+                            allow_force_push: want.forcePush,
+                        });
+                    },
+                });
+            }
+        }
+    }
+    if (settings.renovate_schedule !== undefined) {
+        const list = (await get("/pipeline_schedules", "reading the pipeline schedules")).data;
+        const existing = list.find((schedule) => schedule.description === RENOVATE_SCHEDULE);
+        const cron = settings.renovate_schedule;
+        if (cron === false) {
+            if (existing) {
+                changes.push({
+                    setting: "renovate_schedule",
+                    from: describeSchedule(existing),
+                    to: describeSchedule(undefined),
+                    apply: () => send("DELETE", `/pipeline_schedules/${existing.id}`, "removing the renovate schedule"),
+                });
+            }
+        }
+        else if (!existing || existing.cron !== cron || branchOf(existing.ref) !== branch || !existing.active) {
+            const want = { cron, ref: branch, active: true };
+            changes.push({
+                setting: "renovate_schedule",
+                from: describeSchedule(existing),
+                to: describeSchedule(want),
+                apply: () => existing
+                    ? send("PUT", `/pipeline_schedules/${existing.id}`, "updating the renovate schedule", want)
+                    : send("POST", "/pipeline_schedules", "creating the renovate schedule", {
+                        description: RENOVATE_SCHEDULE,
+                        cron_timezone: "UTC",
+                        ...want,
+                    }),
+            });
+        }
+    }
+    const notes = [];
+    for (const { key, job } of secrets) {
+        const response = await api.request("GET", `${base}/variables/${key}`);
+        if (response.status === 404) {
+            notes.push(`no CI/CD variable ${key} in ${path}: the ${job} job stays inactive until one is set, here or in a group above`);
+        }
+        else if (response.status >= 400) {
+            notes.push(`could not read the CI/CD variables of ${path} (HTTP ${response.status}); ${key} was not checked`);
+        }
+    }
+    return { changes, notes };
+}

package/dist/model.js

@@ -23,3 +23,11 @@ export function describeOutput(output) {
         return `${output.path} (block ${output.id})`;
     return `${output.path} (${output.keyPath.join(".")})`;
 }
+/** `command`, run from the stack's folder when it has one. */
+export function inDirectory(stack, command) {
+    return stack.directory ? `cd ${stack.directory} && ${command}` : command;
+}
+/** Whether the Node.js project is the repository itself, so its package.json can carry repokeeper's tools. */
+export function nodeAtRoot(stacks) {
+    return stacks.some((stack) => stack.id === "node" && !stack.directory);
+}

package/dist/modules/commits.js

@@ -1,4 +1,4 @@
-import { MANAGED_HEADER } from "../model.js";
+import { MANAGED_HEADER, nodeAtRoot } from "../model.js";
 import { TOOL_VERSIONS } from "../version.js";
 const COMMITLINT_CONFIG = `// ${MANAGED_HEADER}
 export default {
@@ -15,7 +15,8 @@ export const commitsModule = {
         const outputs = [
             { kind: "file", module: "commits", path: "commitlint.config.mjs", content: COMMITLINT_CONFIG },
         ];
-        if (ctx.stacks.some((s) => s.id === "node")) {
+        // a package.json in a folder of its own is the project's, not the place for the repository's tools
+        if (nodeAtRoot(ctx.stacks)) {
             outputs.push({
                 kind: "json",
                 module: "commits",

package/dist/modules/deps.js

@@ -1,5 +1,5 @@
 export const depsModule = {
     id: "deps",
     enabled: (config) => config.modules.deps,
-    outputs: (ctx) => ctx.platform.dependencyUpdates(ctx.stacks.flatMap((s) => s.dependabot)),
+    outputs: (ctx) => ctx.platform.dependencyUpdates(ctx.stacks.flatMap((stack) => stack.dependabot.map((ecosystem) => ({ ecosystem, directory: stack.directory ? `/${stack.directory}` : "/" }))), ctx),
 };

package/dist/modules/health.js

@@ -1,6 +1,6 @@
 import { defaultBranch } from "../config/types.js";
 import { UsageError } from "../errors.js";
-import { MANAGED_HEADER } from "../model.js";
+import { inDirectory, MANAGED_HEADER, nodeAtRoot } from "../model.js";
 import { readTemplate } from "../templates.js";
 import { TOOL_VERSIONS } from "../version.js";
 const MIT = (holder) => `MIT License
@@ -42,9 +42,9 @@ export const healthModule = {
         }
         const report = ctx.platform.securityReport(ctx.repo);
         outputs.push(md("SECURITY.md", `# Security Policy\n\n<!-- ${MANAGED_HEADER} -->\n\n## Supported versions\n\nSecurity fixes are released for the latest published version.\n\n## Reporting a vulnerability\n\nPlease do not open a public issue. Report the vulnerability privately ${report}.\nThe maintainers will acknowledge it as soon as possible and keep you informed until it is resolved.\n`));
-        const install = ctx.stacks.map((s) => s.install).filter((c) => c !== null);
+        const install = ctx.stacks.flatMap((s) => (s.install === null ? [] : [inDirectory(s, s.install)]));
         const run = install.length ? `Run ${install.map((c) => `\`${c}\``).join(" and ")}.` : "";
-        const hooks = ctx.stacks.some((s) => s.id === "node")
+        const hooks = nodeAtRoot(ctx.stacks)
             ? "Installing the dependencies also installs the git hooks (lefthook)."
             : `${run ? "Then run" : "Run"} \`npx --yes lefthook@${TOOL_VERSIONS.lefthook} install\` once to enable the git hooks (they need Node.js 22 or newer).`;
         const setup = [run, hooks].filter(Boolean).join(" ");

package/dist/modules/hooks.js

@@ -1,22 +1,24 @@
 import { stringify } from "yaml";
-import { MANAGED_HEADER } from "../model.js";
+import { MANAGED_HEADER, nodeAtRoot } from "../model.js";
 import { TOOL_VERSIONS } from "../version.js";
+/** lefthook runs a job from `root` and hands it only the staged files under it. */
+const rootOf = (stack) => (stack.directory ? { root: `${stack.directory}/` } : {});
 export const hooksModule = {
     id: "hooks",
     enabled: (config) => config.modules.hooks,
     outputs(ctx) {
         const config = {};
-        const preCommit = ctx.stacks.flatMap((s) => s.staged).map((job) => ({ ...job, stage_fixed: true }));
+        const preCommit = ctx.stacks.flatMap((s) => s.staged.map((job) => ({ ...job, ...rootOf(s), stage_fixed: true })));
         if (preCommit.length > 0)
             config["pre-commit"] = { parallel: true, jobs: preCommit };
         if (ctx.config.modules.commits) {
-            const node = ctx.stacks.some((s) => s.id === "node");
+            const node = nodeAtRoot(ctx.stacks);
             const commitlint = node
                 ? "npx --no-install commitlint --edit {1}"
                 : `npx --yes --package @commitlint/cli@${TOOL_VERSIONS.commitlintCli} --package @commitlint/config-conventional@${TOOL_VERSIONS.commitlintConventional} -- commitlint --edit {1}`;
             config["commit-msg"] = { jobs: [{ name: "commitlint", run: commitlint }] };
         }
-        const prePush = ctx.stacks.flatMap((s) => (s.test ? [{ name: `${s.id}:test`, run: s.test }] : []));
+        const prePush = ctx.stacks.flatMap((s) => (s.test ? [{ name: `${s.id}:test`, run: s.test, ...rootOf(s) }] : []));
         if (prePush.length > 0)
             config["pre-push"] = { jobs: prePush };
         const outputs = [
@@ -27,7 +29,7 @@ export const hooksModule = {
                 content: `# ${MANAGED_HEADER}\n${stringify(config, { lineWidth: 0 })}`,
             },
         ];
-        if (ctx.stacks.some((s) => s.id === "node")) {
+        if (nodeAtRoot(ctx.stacks)) {
             outputs.push({
                 kind: "json",
                 module: "hooks",

package/dist/modules/release.js

@@ -1,16 +1,29 @@
 /** One release per repository: the first stack with a language release type wins, otherwise the first stack's `simple` release (which may name extra files). */
+export function pickReleaseStack(stacks) {
+    return stacks.find((stack) => stack.release.type !== "simple") ?? stacks[0];
+}
 export function pickRelease(stacks) {
-    const language = stacks.find((stack) => stack.release.type !== "simple");
-    return language?.release ?? stacks[0]?.release ?? { type: "simple", version: null };
+    return pickReleaseStack(stacks)?.release ?? { type: "simple", version: null };
 }
 export const releaseModule = {
     id: "release",
     enabled: (config) => config.modules.release,
     outputs: (ctx) => {
-        const release = pickRelease(ctx.stacks);
+        const stack = pickReleaseStack(ctx.stacks);
+        const release = stack?.release ?? { type: "simple", version: null };
+        const directory = stack?.directory;
+        // the markers go into a file of the repository, so its path starts at the root
+        const markerPath = (path) => (directory ? `${directory}/${path}` : path);
         const markers = release.versionLine
-            ? [{ kind: "marker", module: "release", path: release.versionLine.path, line: release.versionLine.line }]
+            ? [
+                {
+                    kind: "marker",
+                    module: "release",
+                    path: markerPath(release.versionLine.path),
+                    line: release.versionLine.line,
+                },
+            ]
             : [];
-        return [...ctx.platform.releaseAutomation(ctx, release), ...markers];
+        return [...ctx.platform.releaseAutomation(ctx, release, directory), ...markers];
     },
 };

package/dist/platforms/github.js

@@ -1,7 +1,10 @@
 import { stringify } from "yaml";
+import { CONFIG_FILE } from "../config/load.js";
 import { defaultBranch, STACK_IDS } from "../config/types.js";
-import { MANAGED_HEADER } from "../model.js";
-import { PACKAGE_VERSION, REUSABLE_REPO, WORKFLOW_REF } from "../version.js";
+import { ConfigError } from "../errors.js";
+import { MANAGED_HEADER, } from "../model.js";
+import { readWorkflow } from "../templates.js";
+import { EXACT_WORKFLOW_REF, PACKAGE_VERSION, REUSABLE_REPO, WORKFLOW_REF } from "../version.js";
 const yamlFile = (module, path, data) => ({
     kind: "file",
     module,
@@ -9,10 +12,47 @@ const yamlFile = (module, path, data) => ({
     content: `# ${MANAGED_HEADER}\n${stringify(data)}`,
 });
 const WORKFLOW_KEYS = ["name", "on", "permissions", "concurrency", "env", "defaults", "jobs"];
-/** Reference to a reusable workflow; local inside the repository that hosts them. */
+function workflowOrigin(ctx) {
+    // the repository that hosts the workflows calls its own files
+    if (ctx.repo.owner !== null && `${ctx.repo.owner}/${ctx.repo.name}` === REUSABLE_REPO)
+        return { local: true, self: true };
+    const { source, ref } = ctx.config.github?.workflows ?? {};
+    if (source === "local")
+        return { local: true, self: false };
+    const repo = source ?? REUSABLE_REPO;
+    if (ref === "exact") {
+        if (repo !== REUSABLE_REPO) {
+            throw new ConfigError(`${CONFIG_FILE}: github.workflows.ref: exact follows repokeeper's own releases; for ${repo}, name a tag, a branch or a commit`);
+        }
+        return { local: false, repo, ref: EXACT_WORKFLOW_REF, pinned: true };
+    }
+    // a copy in a repository of your own has no release tags of repokeeper's to follow
+    return {
+        local: false,
+        repo,
+        ref: ref ?? (repo === REUSABLE_REPO ? WORKFLOW_REF : "main"),
+        pinned: ref !== undefined,
+    };
+}
+/** Reference to a reusable workflow, as the `uses` of a caller job. */
 function workflowRef(ctx, file) {
-    const self = ctx.repo.owner !== null && `${ctx.repo.owner}/${ctx.repo.name}` === REUSABLE_REPO;
-    return self ? `./.github/workflows/${file}` : `${REUSABLE_REPO}/.github/workflows/${file}@${WORKFLOW_REF}`;
+    const origin = workflowOrigin(ctx);
+    return origin.local ? `./.github/workflows/${file}` : `${origin.repo}/.github/workflows/${file}@${origin.ref}`;
+}
+/**
+ * The reusable workflows themselves, for a repository that keeps its own copies. Seeds: written
+ * once and from then on the repository's, so its owners decide when a copy changes.
+ */
+function localWorkflows(ctx, module, files) {
+    const origin = workflowOrigin(ctx);
+    if (!origin.local || origin.self)
+        return [];
+    return [...new Set(files)].map((file) => ({
+        kind: "seed",
+        module,
+        path: `.github/workflows/${file}`,
+        content: `# Copied from repokeeper ${PACKAGE_VERSION} (https://github.com/${REUSABLE_REPO}). This copy is yours: repokeeper does not update it.\n${readWorkflow(file)}`,
+    }));
 }
 const workflowKey = (module, path, keyPath, value) => ({
     kind: "yaml",
@@ -122,10 +162,18 @@ export const githubPlatform = {
         }
         return outputs;
     },
-    dependencyUpdates(ecosystems) {
-        const updates = [...new Set([...ecosystems, "github-actions"])].map((ecosystem) => ({
+    dependencyUpdates(requested, ctx) {
+        // a pinned reference is moved by `repokeeper update` or by its owner in .repokeeper.yml; a
+        // Dependabot bump of it would edit a key repokeeper manages and show up as drift every time
+        const origin = workflowOrigin(ctx);
+        const pinnedWorkflows = !origin.local && origin.pinned ? [{ "dependency-name": `${origin.repo}*` }] : [];
+        // workflows always live at the root, whatever folders the stacks are in
+        const all = [...requested, { ecosystem: "github-actions", directory: "/" }];
+        const unique = all.filter((update, index) => all.findIndex((other) => other.ecosystem === update.ecosystem && other.directory === update.directory) ===
+            index);
+        const updates = unique.map(({ ecosystem, directory }) => ({
             "package-ecosystem": ecosystem,
-            directory: "/",
+            directory,
             schedule: { interval: "weekly" },
             groups: { [`${ecosystem}-minor-and-patch`]: { "update-types": ["minor", "patch"] } },
             // Dependabot infers a Conventional Commits prefix only from history; young repositories fail commitlint
@@ -134,6 +182,7 @@ export const githubPlatform = {
             ...(ecosystem === "npm"
                 ? { ignore: [{ "dependency-name": "@types/node", "update-types": ["version-update:semver-major"] }] }
                 : {}),
+            ...(ecosystem === "github-actions" && pinnedWorkflows.length > 0 ? { ignore: pinnedWorkflows } : {}),
         }));
         return [yamlFile("deps", ".github/dependabot.yml", { version: 2, updates })];
     },
@@ -144,7 +193,7 @@ export const githubPlatform = {
             if (stack.ci) {
                 jobs.push(workflowKey("ci", path, ["jobs", stack.id], {
                     uses: workflowRef(ctx, stack.ci.workflow),
-                    with: stack.ci.with,
+                    with: stack.directory ? { ...stack.ci.with, "working-directory": stack.directory } : stack.ci.with,
                 }));
             }
         }
@@ -159,7 +208,13 @@ export const githubPlatform = {
         }
         if (jobs.length === 0)
             return [];
+        const called = [
+            ...ctx.stacks.flatMap((stack) => (stack.ci ? [stack.ci.workflow] : [])),
+            ...(ctx.config.modules.commits ? ["commitlint.yml"] : []),
+            ...(ctx.config.modules.drift ? ["repokeeper-check.yml"] : []),
+        ];
         return [
+            ...localWorkflows(ctx, "ci", called),
             workflowKey("ci", path, ["name"], "ci"),
             workflowKey("ci", path, ["on"], { pull_request: null, push: { branches: [defaultBranch(ctx.config)] } }),
             workflowKey("ci", path, ["permissions"], { contents: "read" }),
@@ -173,9 +228,11 @@ export const githubPlatform = {
             ...jobs,
         ];
     },
-    releaseAutomation(ctx, release) {
+    releaseAutomation(ctx, release, directory) {
         const path = ".github/workflows/release.yml";
         const seed = release.version ?? ctx.repo.releasedVersion ?? "0.0.0";
+        // release-please names a package by its folder; its changelog and extra files are relative to it
+        const packagePath = directory ?? ".";
         return [
             {
                 kind: "file",
@@ -184,7 +241,7 @@ export const githubPlatform = {
                 content: json({
                     $schema: RELEASE_PLEASE_SCHEMA,
                     packages: {
-                        ".": {
+                        [packagePath]: {
                             "release-type": release.type,
                             "changelog-path": "CHANGELOG.md",
                             "bump-minor-pre-major": true,
@@ -206,8 +263,9 @@ export const githubPlatform = {
                 kind: "seed",
                 module: "release",
                 path: ".release-please-manifest.json",
-                content: json({ ".": seed }),
+                content: json({ [packagePath]: seed }),
             },
+            ...localWorkflows(ctx, "release", ["release-please.yml"]),
             workflowKey("release", path, ["name"], "release"),
             workflowKey("release", path, ["on"], { push: { branches: [defaultBranch(ctx.config)] } }),
             workflowKey("release", path, ["permissions"], { contents: "read" }),

package/dist/platforms/gitlab-jobs.js

@@ -0,0 +1,191 @@
+export const NOT_SCHEDULED = '$CI_PIPELINE_SOURCE != "schedule"';
+/** The checks of a change: merge requests and the default branch, not schedules and not tag pipelines. */
+export const FOR_CHANGES = `${NOT_SCHEDULED} && $CI_COMMIT_TAG == null`;
+const list = (input, key) => JSON.parse(input[key] ?? "[]");
+/** A job per version: the image is named with the matrix variable, so each run pulls its own. */
+function perVersion(image, variable, versions, script, more = {}) {
+    return {
+        stage: "test",
+        image,
+        parallel: { matrix: [{ [variable]: versions }] },
+        rules: [{ if: FOR_CHANGES }],
+        ...more,
+        script,
+    };
+}
+/** A job that runs once. */
+const once = (image, script, more = {}) => ({
+    stage: "test",
+    image,
+    rules: [{ if: FOR_CHANGES }],
+    ...more,
+    script,
+});
+/** The version of shfmt the script stack checks with; the same as in .github/workflows/stack-script.yml. */
+export const SHFMT_VERSION = "3.14.1";
+/** The version of PSScriptAnalyzer the script stack checks with; the same as in stack-script.yml. */
+export const SCRIPT_ANALYZER_VERSION = "1.25.0";
+const SHFMT = `wget -q -O /usr/local/bin/shfmt https://github.com/mvdan/sh/releases/download/v${SHFMT_VERSION}/shfmt_v${SHFMT_VERSION}_linux_amd64
+chmod +x /usr/local/bin/shfmt
+git ls-files -z '*.sh' | xargs -0 -r shfmt -d
+`;
+// the settings file is the repository's own choice of rules; without one, errors and warnings fail the job.
+// Stop on the first error: an analyzer that fails to load would otherwise report no issues and pass
+const SCRIPT_ANALYZER = `pwsh -NoProfile -Command '
+$ErrorActionPreference = "Stop"
+Set-PSRepository PSGallery -InstallationPolicy Trusted
+Install-Module PSScriptAnalyzer -RequiredVersion ${SCRIPT_ANALYZER_VERSION} -Force -Scope CurrentUser
+$issues = if (Test-Path PSScriptAnalyzerSettings.psd1) {
+  Invoke-ScriptAnalyzer -Path . -Recurse -Settings PSScriptAnalyzerSettings.psd1
+} else {
+  Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning
+}
+$issues | Format-Table -AutoSize
+if ($issues) { exit 1 }
+'
+`;
+/** Composer is not in the php image; neither are the git and unzip it fetches packages with. */
+const COMPOSER = `apt-get update -qq && apt-get install -y -qq git unzip > /dev/null
+php -r "copy('https://getcomposer.org/installer', '/tmp/composer-setup.php');"
+php /tmp/composer-setup.php --quiet --install-dir=/usr/local/bin --filename=composer
+`;
+/**
+ * PowerShell for Linux. Not `mcr.microsoft.com/powershell`: its `latest` stopped at 7.4.2, older than
+ * PSScriptAnalyzer loads on. The .NET SDK image carries a PowerShell that is kept current.
+ */
+const POWERSHELL_IMAGE = "mcr.microsoft.com/dotnet/sdk:10.0";
+/** Newest first, so the image is the newest SDK and the older ones are installed beside it. */
+const newestFirst = (versions) => [...versions].sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+/**
+ * The CI jobs of a stack on GitLab: the inputs its GitHub reusable workflow receives, run in a
+ * container image instead of on a runner that a setup action prepares. node and go are in gitlab.ts.
+ */
+export function stackJobs(stack) {
+    const input = stack.ci?.with;
+    if (input === undefined)
+        return [];
+    const commands = list(input, "commands");
+    const install = input["install-command"] ? [input["install-command"]] : [];
+    if (stack.id === "python") {
+        const uv = input.manager === "uv";
+        return [
+            {
+                key: "python",
+                job: perVersion(
+                // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+                "python:${PYTHON_VERSION}", "PYTHON_VERSION", list(input, "python-versions"), [...(uv ? ["python -m pip install uv"] : []), ...install, ...commands], 
+                // uv then runs the image's interpreter instead of fetching one of its own choice
+                { variables: { PIP_ROOT_USER_ACTION: "ignore", ...(uv ? { UV_PYTHON: "$PYTHON_VERSION" } : {}) } }),
+            },
+        ];
+    }
+    if (stack.id === "rust") {
+        return [
+            {
+                key: "rust",
+                // the toolchain is installed by name, as on GitHub, so "stable", "beta" and "1.80" all work
+                job: perVersion("rust:latest", "RUST_VERSION", list(input, "rust-versions"), [
+                    'rustup toolchain install "$RUST_VERSION" --profile minimal --component rustfmt,clippy',
+                    'rustup default "$RUST_VERSION"',
+                    ...commands,
+                ]),
+            },
+        ];
+    }
+    if (stack.id === "ruby") {
+        return [
+            {
+                key: "ruby",
+                // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+                job: perVersion("ruby:${RUBY_VERSION}", "RUBY_VERSION", list(input, "ruby-versions"), [
+                    ...install,
+                    ...commands,
+                ]),
+            },
+        ];
+    }
+    if (stack.id === "php") {
+        return [
+            {
+                key: "php",
+                // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+                job: perVersion("php:${PHP_VERSION}-cli", "PHP_VERSION", list(input, "php-versions"), [
+                    COMPOSER,
+                    ...install,
+                    ...commands,
+                ]),
+            },
+        ];
+    }
+    if (stack.id === "dart") {
+        const flutter = input.flutter === "true";
+        return [
+            {
+                key: "dart",
+                job: perVersion(
+                // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+                flutter ? "ghcr.io/cirruslabs/flutter:${SDK_VERSION}" : "dart:${SDK_VERSION}", "SDK_VERSION", list(input, "sdk-versions"), [...install, ...commands]),
+            },
+        ];
+    }
+    if (stack.id === "java" || stack.id === "kotlin") {
+        const image = input["build-tool"] === "maven"
+            ? // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+                "maven:3-eclipse-temurin-${JAVA_VERSION}"
+            : input["gradle-version"] === ""
+                ? // the project's own wrapper fetches its Gradle
+                    // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+                    "eclipse-temurin:${JAVA_VERSION}-jdk"
+                : // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+                    "gradle:jdk${JAVA_VERSION}";
+        return [{ key: stack.id, job: perVersion(image, "JAVA_VERSION", list(input, "java-versions"), commands) }];
+    }
+    if (stack.id === "dotnet") {
+        const [newest = "9.0", ...older] = newestFirst(list(input, "dotnet-versions"));
+        return [
+            {
+                key: "dotnet",
+                // one job with every SDK side by side, as on GitHub: a project may target several of them
+                job: once(`mcr.microsoft.com/dotnet/sdk:${newest}`, [
+                    ...older.map((version) => `curl -fsSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel ${version} --install-dir /usr/share/dotnet`),
+                    ...commands,
+                ], { variables: { DOTNET_CLI_TELEMETRY_OPTOUT: "1", DOTNET_NOLOGO: "1" } }),
+            },
+        ];
+    }
+    if (stack.id === "script") {
+        const jobs = [];
+        if (input["shell-scripts"] === "true") {
+            jobs.push({
+                key: "shell",
+                job: once("koalaman/shellcheck-alpine:stable", [
+                    "apk add --no-cache git > /dev/null",
+                    "git ls-files -z '*.sh' | xargs -0 -r shellcheck",
+                    SHFMT,
+                ]),
+            });
+        }
+        if (input["powershell-scripts"] === "true") {
+            jobs.push({ key: "powershell", job: once(POWERSHELL_IMAGE, [SCRIPT_ANALYZER]) });
+        }
+        // the image has both bash and pwsh, whichever the test command is written for
+        if (input["test-command"])
+            jobs.push({ key: "script-test", job: once(POWERSHELL_IMAGE, [input["test-command"]]) });
+        return jobs;
+    }
+    return [];
+}
+/** Every key `stackJobs` can write, in the order they appear in .gitlab-ci.yml. */
+export const STACK_JOB_KEYS = [
+    "python",
+    "dart",
+    "shell",
+    "powershell",
+    "script-test",
+    "java",
+    "dotnet",
+    "rust",
+    "kotlin",
+    "php",
+    "ruby",
+];