repokeeper 0.4.7 → 0.6.0

package/dist/platforms/gitlab.js

@@ -0,0 +1,233 @@
+import { defaultBranch } from "../config/types.js";
+import { MANAGED_HEADER } from "../model.js";
+import { PACKAGE_VERSION, TOOL_VERSIONS } from "../version.js";
+const md = (path, body) => ({
+    kind: "file",
+    module: "health",
+    path,
+    content: `<!-- ${MANAGED_HEADER} -->\n\n${body}`,
+});
+/** Web address of the GitLab instance the repository lives on. */
+const baseUrl = (repo) => `https://${repo.host ?? "gitlab.com"}`;
+const CI_FILE = ".gitlab-ci.yml";
+const CI_KEYS = ["workflow", "node", "go", "commits", "repokeeper", "renovate", "release"];
+/** One managed top-level key of .gitlab-ci.yml; keys the user adds are left alone. */
+const ciKey = (module, key, value) => ({
+    kind: "yaml",
+    module,
+    path: CI_FILE,
+    keyPath: [key],
+    value,
+    order: CI_KEYS,
+});
+const NOT_SCHEDULED = '$CI_PIPELINE_SOURCE != "schedule"';
+/** The checks of a change: merge requests and the default branch, not schedules and not tag pipelines. */
+const FOR_CHANGES = `${NOT_SCHEDULED} && $CI_COMMIT_TAG == null`;
+/** Image of the jobs that only run tools, whatever Node.js versions the project tests on. */
+const TOOL_IMAGE = "node:24";
+/** The node stack's CI inputs, as the GitHub reusable workflow receives them, as a GitLab job. */
+function nodeJob(input) {
+    const pm = input["package-manager"] ?? "npm";
+    const cached = input.cache === "npm";
+    const scripts = JSON.parse(input.scripts ?? "[]");
+    return {
+        stage: "test",
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+        image: "node:${NODE_VERSION}",
+        parallel: { matrix: [{ NODE_VERSION: JSON.parse(input["node-versions"] ?? '["22","24"]') }] },
+        rules: [{ if: FOR_CHANGES }],
+        variables: {
+            COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+            ...(cached ? { npm_config_cache: "$CI_PROJECT_DIR/.npm" } : {}),
+        },
+        ...(cached ? { cache: { key: { files: ["package-lock.json"] }, paths: [".npm/"] } } : {}),
+        script: [
+            ...(pm === "npm" ? [] : ["corepack enable"]),
+            input["install-command"] ?? "npm ci",
+            ...scripts.map((script) => `${pm} run ${script}`),
+        ],
+    };
+}
+/**
+ * The go stack's CI inputs as a GitLab job. No module cache: it would have to live inside the project
+ * folder, where `gofmt -l .` would read it as the project's own code.
+ */
+function goJob(input) {
+    // setup-go's "stable" is the image's `latest` tag
+    const versions = JSON.parse(input["go-versions"] ?? '["stable"]').map((version) => version === "stable" ? "latest" : version);
+    return {
+        stage: "test",
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: a GitLab CI variable
+        image: "golang:${GO_VERSION}",
+        parallel: { matrix: [{ GO_VERSION: versions }] },
+        rules: [{ if: FOR_CHANGES }],
+        script: JSON.parse(input.commands ?? "[]"),
+    };
+}
+/** commitlint from a scratch directory, so the project needs no commitlint of its own. */
+const COMMITLINT = `dir="$(mktemp -d)"
+(cd "$dir" && echo '{ "private": true }' > package.json && npm install --no-audit --no-fund @commitlint/cli@${TOOL_VERSIONS.commitlintCli} @commitlint/config-conventional@${TOOL_VERSIONS.commitlintConventional})
+cat > "$dir/commitlint.config.mjs" <<'EOF'
+export default { extends: ["@commitlint/config-conventional"], rules: { "header-max-length": [2, "always", 100] } };
+EOF
+lint() { "$dir/node_modules/.bin/commitlint" --config "$dir/commitlint.config.mjs" --verbose "$@"; }
+# a merged results pipeline runs on a merge commit; the commits to lint end at the source branch
+head="$CI_MERGE_REQUEST_SOURCE_BRANCH_SHA"
+[ -n "$head" ] || head="$CI_COMMIT_SHA"
+if [ -n "$CI_MERGE_REQUEST_DIFF_BASE_SHA" ]; then
+  lint --from "$CI_MERGE_REQUEST_DIFF_BASE_SHA" --to "$head"
+else
+  lint --last
+fi
+`;
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/**
+ * semantic-release and the plugins it does not bundle, from a scratch directory. It resolves plugins next to
+ * itself before it looks in the project, so the project needs none of them installed.
+ */
+const SEMANTIC_RELEASE = `dir="$(mktemp -d)"
+(cd "$dir" && echo '{ "private": true }' > package.json && npm install --no-audit --no-fund semantic-release@${TOOL_VERSIONS.semanticRelease} @semantic-release/changelog@${TOOL_VERSIONS.semanticReleaseChangelog} @semantic-release/git@${TOOL_VERSIONS.semanticReleaseGit} @semantic-release/gitlab@${TOOL_VERSIONS.semanticReleaseGitlab} conventional-changelog-conventionalcommits@${TOOL_VERSIONS.conventionalCommitsPreset})
+"$dir/node_modules/.bin/semantic-release"
+`;
+export const gitlabPlatform = {
+    id: "gitlab",
+    stacks: ["node", "go"],
+    changeRequest: "merge request",
+    profileUrl: (repo) => (repo.owner ? `${baseUrl(repo)}/${repo.owner}` : null),
+    securityReport: (repo) => repo.owner
+        ? `by opening a [confidential issue](${baseUrl(repo)}/${repo.owner}/${repo.name}/-/issues/new?issue%5Bconfidential%5D=true)`
+        : "by opening a confidential issue in the repository",
+    communityFiles(ctx) {
+        const outputs = [
+            md(".gitlab/issue_templates/Bug.md", "## What happened?\n\n<!-- Include the steps to reproduce it. -->\n\n## What did you expect?\n\n## Version\n\n/label ~bug\n"),
+            md(".gitlab/issue_templates/Feature.md", "## What problem would this solve?\n\n## What do you propose?\n\n/label ~enhancement\n"),
+            md(".gitlab/merge_request_templates/Default.md", "## Summary\n\n## Testing\n\n- [ ] Tests added or updated\n- [ ] Commit messages follow Conventional Commits\n"),
+        ];
+        const health = ctx.config.modules.health;
+        if (health && health.codeowners.length > 0) {
+            outputs.push({
+                kind: "file",
+                module: "health",
+                path: ".gitlab/CODEOWNERS",
+                content: `# ${MANAGED_HEADER}\n* ${health.codeowners.join(" ")}\n`,
+            });
+        }
+        return outputs;
+    },
+    // Renovate finds the package managers itself, so the Dependabot ecosystem names are not needed
+    dependencyUpdates() {
+        return [
+            {
+                kind: "file",
+                module: "deps",
+                path: "renovate.json",
+                content: json({
+                    $schema: "https://docs.renovatebot.com/renovate-schema.json",
+                    // chore commits pass commitlint, as the Dependabot prefix does on GitHub. No schedule preset: the
+                    // pipeline schedule sets the cadence, and a Renovate schedule would skip runs outside its own window
+                    extends: ["config:recommended", ":semanticCommits", ":semanticCommitTypeAll(chore)"],
+                    packageRules: [
+                        { matchUpdateTypes: ["minor", "patch"], groupName: "minor and patch updates" },
+                        // @types/node majors track the Node.js line a project runs on, which the project chooses
+                        { matchPackageNames: ["@types/node"], matchUpdateTypes: ["major"], enabled: false },
+                    ],
+                }),
+            },
+            // runs from a pipeline schedule of the repository; without the token or a schedule it never starts
+            ciKey("deps", "renovate", {
+                stage: "test",
+                image: `renovate/renovate:${TOOL_VERSIONS.renovate}`,
+                rules: [{ if: '$CI_PIPELINE_SOURCE == "schedule" && $RENOVATE_TOKEN' }],
+                variables: {
+                    RENOVATE_PLATFORM: "gitlab",
+                    RENOVATE_ENDPOINT: "$CI_API_V4_URL",
+                    RENOVATE_AUTODISCOVER: "false",
+                    RENOVATE_ONBOARDING: "false",
+                },
+                script: ['renovate "$CI_PROJECT_PATH"'],
+            }),
+        ];
+    },
+    ciWorkflow(ctx) {
+        const jobs = [];
+        const node = ctx.stacks.find((stack) => stack.id === "node")?.ci;
+        if (node)
+            jobs.push(ciKey("ci", "node", nodeJob(node.with)));
+        const go = ctx.stacks.find((stack) => stack.id === "go")?.ci;
+        if (go)
+            jobs.push(ciKey("ci", "go", goJob(go.with)));
+        if (ctx.config.modules.commits) {
+            jobs.push(ciKey("ci", "commits", {
+                stage: "test",
+                image: TOOL_IMAGE,
+                rules: [{ if: FOR_CHANGES }],
+                variables: { GIT_DEPTH: "0" },
+                script: [COMMITLINT],
+            }));
+        }
+        if (ctx.config.modules.drift) {
+            jobs.push(ciKey("ci", "repokeeper", {
+                stage: "test",
+                image: TOOL_IMAGE,
+                rules: [{ if: FOR_CHANGES }],
+                script: [`npx --yes repokeeper@${PACKAGE_VERSION} check`],
+            }));
+        }
+        if (jobs.length === 0)
+            return [];
+        return [
+            // one pipeline per merge request, per push to the default branch and per schedule; none for other branches.
+            // Tags are let through for jobs of the user's own, such as publishing: no managed job runs on one
+            ciKey("ci", "workflow", {
+                rules: [
+                    { if: '$CI_PIPELINE_SOURCE == "merge_request_event"' },
+                    { if: '$CI_PIPELINE_SOURCE == "schedule"' },
+                    { if: `$CI_COMMIT_BRANCH == "${defaultBranch(ctx.config)}"` },
+                    { if: "$CI_COMMIT_TAG" },
+                ],
+            }),
+            ...jobs,
+        ];
+    },
+    releaseAutomation(ctx) {
+        const branch = defaultBranch(ctx.config);
+        // a Go module's version is its tag: there is no file to bump, so the release is the changelog and the tag
+        const npm = ctx.stacks.some((stack) => stack.release.type === "node");
+        return [
+            {
+                kind: "file",
+                module: "release",
+                path: ".releaserc.json",
+                content: json({
+                    branches: [branch],
+                    // biome-ignore lint/suspicious/noTemplateCurlyInString: a semantic-release template
+                    tagFormat: "v${version}",
+                    plugins: [
+                        ["@semantic-release/commit-analyzer", { preset: "conventionalcommits" }],
+                        ["@semantic-release/release-notes-generator", { preset: "conventionalcommits" }],
+                        ["@semantic-release/changelog", { changelogFile: "CHANGELOG.md" }],
+                        // bumps package.json and the npm lock file; publishing stays the project's own business
+                        ...(npm ? [["@semantic-release/npm", { npmPublish: false }]] : []),
+                        [
+                            "@semantic-release/git",
+                            {
+                                assets: ["CHANGELOG.md", ...(npm ? ["package.json", "package-lock.json", "npm-shrinkwrap.json"] : [])],
+                                // biome-ignore lint/suspicious/noTemplateCurlyInString: a semantic-release template
+                                message: "chore(release): ${nextRelease.version} [skip ci]",
+                            },
+                        ],
+                        "@semantic-release/gitlab",
+                    ],
+                }),
+            },
+            // semantic-release pushes a commit and a tag, which the job token cannot do; without GITLAB_TOKEN the job is absent
+            ciKey("release", "release", {
+                stage: "deploy",
+                image: TOOL_IMAGE,
+                rules: [{ if: `${NOT_SCHEDULED} && $CI_COMMIT_BRANCH == "${branch}" && $GITLAB_TOKEN` }],
+                variables: { GIT_DEPTH: "0" },
+                script: [SEMANTIC_RELEASE],
+            }),
+        ];
+    },
+};

package/dist/platforms/index.js

@@ -0,0 +1,5 @@
+import { githubPlatform } from "./github.js";
+import { gitlabPlatform } from "./gitlab.js";
+export function platformFor(id) {
+    return id === "gitlab" ? gitlabPlatform : githubPlatform;
+}

package/dist/stacks/index.js

@@ -1,3 +1,5 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
 import { STACK_IDS } from "../config/types.js";
 import { dartStack } from "./dart.js";
 import { dotnetStack } from "./dotnet.js";
@@ -34,3 +36,57 @@ export async function detectStacks(root) {
     // scripts beside another stack belong to that stack; the script pack is for script-only repositories
     return found.length > 1 ? found.filter((id) => id !== "script") : found;
 }
+/** Folders that hold a project's by-products or samples rather than a project of the repository. */
+const NOT_A_PROJECT = new Set([
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "target",
+    "out",
+    "bin",
+    "obj",
+    "coverage",
+    "example",
+    "examples",
+    "test",
+    "tests",
+    "fixtures",
+    "doc",
+    "docs",
+]);
+/**
+ * The stacks of a repository and where they are: at the root or, when the root holds no project
+ * (a monorepo such as frontend/ and backend/), in its immediate folders.
+ */
+export async function detectStackLayout(root) {
+    const atRoot = await detectStacks(root);
+    const rooted = { stacks: atRoot, directories: {}, skipped: [] };
+    // loose scripts at the root do not make it a project: a monorepo often keeps some beside its folders
+    if (atRoot.some((id) => id !== "script"))
+        return rooted;
+    const directories = {};
+    const skipped = [];
+    const folders = readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !NOT_A_PROJECT.has(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+    for (const folder of folders) {
+        for (const id of await detectStacks(join(root, folder))) {
+            if (directories[id] === undefined)
+                directories[id] = folder;
+            else
+                skipped.push({ stack: id, directory: folder });
+        }
+    }
+    let stacks = STACK_IDS.filter((id) => directories[id] !== undefined);
+    // nothing but scripts in the folders either: the root's own answer stands
+    if (atRoot.length > 0 && stacks.every((id) => id === "script"))
+        return rooted;
+    // as at the root: a folder of scripts beside real projects is tooling, not a stack
+    if (stacks.length > 1 && directories.script !== undefined) {
+        stacks = stacks.filter((id) => id !== "script");
+        delete directories.script;
+    }
+    return { stacks, directories, skipped: skipped.filter((entry) => stacks.includes(entry.stack)) };
+}

package/dist/stacks/support.js

@@ -10,6 +10,25 @@ export function checkKeys(stack, options, keys) {
         }
     }
 }
+/**
+ * The `directory` option every stack takes: the folder of a monorepo the stack lives in.
+ * Returns it with forward slashes and no trailing slash, or undefined for the repository root.
+ */
+export function stackDirectory(stack, options) {
+    const value = options.directory;
+    if (value === undefined)
+        return undefined;
+    const key = `${CONFIG_FILE}: stack_options.${stack}.directory`;
+    if (typeof value !== "string" || value.trim() === "")
+        throw new ConfigError(`${key} must be a folder name`);
+    const directory = value.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    if (directory === "" || directory === ".")
+        return undefined;
+    if (directory.startsWith("/") || /^[A-Za-z]:/.test(directory) || directory.split("/").includes("..")) {
+        throw new ConfigError(`${key} must be a folder inside the repository, such as backend or apps/api`);
+    }
+    return directory;
+}
 /** A list option; YAML numbers such as `[22, 24]` count as strings. */
 export function stringList(stack, options, key) {
     const value = options[key];

package/dist/templates.js

@@ -1,6 +1,18 @@
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
 import { normalizeEol } from "./sync/hash.js";
 /** Reads a bundled template with LF endings; works from src/ (tests) and dist/ (package). */
 export function readTemplate(relativePath) {
     return normalizeEol(readFileSync(new URL(`../templates/${relativePath}`, import.meta.url), "utf8"));
 }
+/** File names of the reusable workflows generated CI and release files can call. */
+export const REUSABLE_WORKFLOW = /^(stack-[a-z]+|commitlint|release-please|repokeeper-check)\.yml$/;
+/** Reads one of the reusable workflows shipped with the package, with LF endings. */
+export function readWorkflow(file) {
+    return normalizeEol(readFileSync(new URL(`../.github/workflows/${file}`, import.meta.url), "utf8"));
+}
+/** Every reusable workflow shipped with the package, by file name. */
+export function listWorkflows() {
+    return readdirSync(new URL("../.github/workflows/", import.meta.url))
+        .filter((name) => REUSABLE_WORKFLOW.test(name))
+        .sort();
+}

package/dist/version.js

@@ -6,11 +6,20 @@ export const TOOL_VERSIONS = {
     lefthook: "2.1.14",
     commitlintCli: "21.2.3",
     commitlintConventional: "21.2.3",
+    semanticRelease: "25.0.9",
+    semanticReleaseChangelog: "7.0.0",
+    semanticReleaseGit: "11.0.1",
+    semanticReleaseGitlab: "13.3.3",
+    // 10.x needs conventional-changelog-writer 9, and semantic-release 25's notes generator bundles 8
+    conventionalCommitsPreset: "9.3.1",
+    renovate: "44.128.1",
 };
 /** Repository hosting the reusable workflows that generated CI files call. */
 export const REUSABLE_REPO = "vannt-dev/repokeeper";
 /** Moving tag callers pin to: the major version of this repokeeper (v0 during 0.x). */
 export const WORKFLOW_REF = `v${PACKAGE_VERSION.split(".")[0]}`;
+/** The tag of this release, for callers that pin to it instead of following the major tag. */
+export const EXACT_WORKFLOW_REF = `v${PACKAGE_VERSION}`;
 export function compareVersions(a, b) {
     const pa = a.split(".").map(Number);
     const pb = b.split(".").map(Number);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repokeeper",
-  "version": "0.4.7",
+  "version": "0.6.0",
   "description": "Keep every repository on one maintained standard: commits, git hooks, CI, releases, dependency updates and repo settings.",
   "type": "module",
   "bin": {
@@ -8,7 +8,11 @@
   },
   "files": [
     "dist/",
-    "templates/"
+    "templates/",
+    ".github/workflows/stack-*.yml",
+    ".github/workflows/commitlint.yml",
+    ".github/workflows/release-please.yml",
+    ".github/workflows/repokeeper-check.yml"
   ],
   "engines": {
     "node": ">=22.12.0"