repokeeper 0.2.2 → 0.2.3

package/README.md

@@ -36,6 +36,15 @@ alone. Every write command accepts `--dry-run`.
 isn't `main`. The release manifest starts from the latest `vX.Y.Z` tag when the stack has no version
 of its own.
 
+After writing, repokeeper prints what is left to do (installing the git hooks, and
+`git add --renormalize .` when tracked files are stored with CRLF). `init`, `update` and `check` also
+point out what they can't fix: `.gitattributes` lines above the repokeeper block that the block
+overrides, and pull request workflows of your own that run the same tests as the repokeeper ci job.
+
+Stack notes: Python runs `mypy` on the files its config names (`files = …`), or on the whole tree
+otherwise. The dotnet stack needs SDK-style projects; `init` stops with the names of .NET Framework
+projects, which the dotnet CLI can't build.
+
 Requires Node.js 22.12 or newer.
 
 ## CI and releases
@@ -46,8 +55,8 @@ without a pull request. repokeeper owns the `name`, `on` and `permissions` keys
 adds; jobs you add yourself are left alone, and so is the formatting of the rest of the file.
 
 The script stack runs ShellCheck and `shfmt -d` on `*.sh` (format with `shfmt -w` before pushing)
-and PSScriptAnalyzer on `*.ps1`, which fails on warnings too. To relax a rule, add a
-`PSScriptAnalyzerSettings.psd1` at the repository root; PSScriptAnalyzer picks it up on its own:
+and PSScriptAnalyzer on `*.ps1`, which fails on errors and warnings (not on information-level rules). To
+choose the rules yourself, add a `PSScriptAnalyzerSettings.psd1` at the repository root; the job then uses it:
 
 ```powershell
 @{

package/dist/commands/check.js

@@ -6,7 +6,7 @@ import { readLock } from "../sync/lock.js";
 import { computeSync } from "../sync/sync.js";
 import { compareVersions, STANDARD_VERSION } from "../version.js";
 import { buildContext } from "./context.js";
-import { hasDrift, printResult } from "./report.js";
+import { hasDrift, printResult, printWarnings } from "./report.js";
 export function assertSupportedStandard(standard) {
     if (compareVersions(standard, STANDARD_VERSION) > 0) {
         throw new UsageError(`this repository uses standard ${standard}, newer than ${STANDARD_VERSION}; upgrade repokeeper`);
@@ -42,6 +42,7 @@ export async function checkCommand(root, options, io) {
         return clean ? 0 : 1;
     }
     printResult(io, result);
+    await printWarnings(root, ctx, io);
     if (behind)
         io.out(`standard   ${config.standard} applied, ${STANDARD_VERSION} available (run \`repokeeper update\`)`);
     io.out(clean ? "repository matches the standard" : "repository has drifted from the standard");

package/dist/commands/init.js

@@ -15,11 +15,27 @@ import { readCurrent } from "../sync/state.js";
 import { computeSync, pathsToWrite } from "../sync/sync.js";
 import { STANDARD_VERSION } from "../version.js";
 import { buildContext } from "./context.js";
-import { printResult } from "./report.js";
-export async function guardUncommitted(root, result, force) {
+import { nextSteps, printResult, printWarnings } from "./report.js";
+/** A dirty path is still safe to write when every part repokeeper manages in it is exactly what it last wrote. */
+async function onlyRepokeeperChanges(root, path, lock) {
+    const entries = lock?.entries.filter((e) => e.target.path === path) ?? [];
+    if (entries.length === 0)
+        return false;
+    for (const entry of entries) {
+        const current = await readCurrent(root, entry.target);
+        if (current === null || hashText(current) !== entry.hash)
+            return false;
+    }
+    return true;
+}
+export async function guardUncommitted(root, result, force, lock = null) {
     if (force)
         return;
-    const dirty = await dirtyPaths(root, pathsToWrite(result));
+    const dirty = [];
+    for (const d of await dirtyPaths(root, pathsToWrite(result))) {
+        if (!(await onlyRepokeeperChanges(root, d.path, lock)))
+            dirty.push(d);
+    }
     if (dirty.length === 0)
         return;
     const names = dirty.map((d) => (d.untracked ? `${d.path} (untracked)` : d.path)).join(", ");
@@ -62,7 +78,10 @@ export async function initCommand(root, options, io) {
     await writeFile(join(root, CONFIG_FILE), renderConfig(config));
     await applySync(root, result, null, STANDARD_VERSION);
     io.out(`applied standard ${STANDARD_VERSION}; wrote ${CONFIG_FILE}`);
-    io.out(`next: install dependencies (this installs the git hooks), then commit with "chore(repokeeper): apply standard ${STANDARD_VERSION}"`);
+    await printWarnings(root, ctx, io);
+    for (const step of await nextSteps(root, ctx, result))
+        io.out(`next: ${step}`);
+    io.out(`next: commit with "chore(repokeeper): apply standard ${STANDARD_VERSION}"`);
     return 0;
 }
 /** Records the current content of every planned output as repokeeper's own, rebuilding a lost or corrupt lock. */

package/dist/commands/report.js

@@ -1,4 +1,10 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { duplicateTestRuns } from "../duplicates.js";
+import { crlfTrackedFiles } from "../git.js";
 import { describeOutput } from "../model.js";
+import { overriddenAttributes } from "../sync/attributes.js";
+import { TOOL_VERSIONS } from "../version.js";
 /** How to name the output under `owned`: the path, or `path#key` for one key of a shared file. */
 function ownedName(output) {
     if (output.kind === "yaml" || output.kind === "json")
@@ -34,6 +40,39 @@ export function printResult(io, result) {
     }
     io.out(`${unchanged} output(s) already match the standard`);
 }
+const WROTE = ["create", "write", "adopt"];
+/** What the user still has to do after a write: install the hooks, renormalize line endings. */
+export async function nextSteps(root, ctx, result) {
+    const steps = [];
+    const wrote = (path) => result.decisions.some((d) => d.output.path === path && WROTE.includes(d.action));
+    if (ctx.config.modules.hooks && wrote("lefthook.yml")) {
+        steps.push(ctx.stacks.some((s) => s.id === "node")
+            ? "install dependencies; this installs the git hooks"
+            : `run \`npx --yes lefthook@${TOOL_VERSIONS.lefthook} install\` to enable the git hooks`);
+    }
+    if (wrote(".gitattributes")) {
+        const crlf = await crlfTrackedFiles(root);
+        if (crlf.length > 0) {
+            const files = crlf.length === 1 ? "1 file is" : `${crlf.length} files are`;
+            steps.push(`${files} stored with CRLF line endings; run \`git add --renormalize .\` so they follow .gitattributes`);
+        }
+    }
+    return steps;
+}
+/** Problems repokeeper can't fix itself; printed, but not counted as drift. */
+export async function printWarnings(root, ctx, io) {
+    if (ctx.config.modules.ci) {
+        for (const { file, command } of await duplicateTestRuns(root, ctx.stacks)) {
+            io.out(`note: ${file} also runs "${command}", which the repokeeper ci job now runs too; drop one of them to save CI time`);
+        }
+    }
+    if (!ctx.config.modules.editorconfig)
+        return;
+    const text = await readFile(join(root, ".gitattributes"), "utf8").catch(() => "");
+    for (const { line, by } of overriddenAttributes(text, "editorconfig")) {
+        io.out(`warning: .gitattributes: "${line}" has no effect because repokeeper's "${by}" comes later; move it below the repokeeper block to keep it`);
+    }
+}
 export function hasDrift(result) {
     return result.decisions.some((d) => d.action !== "unchanged") || result.removals.some((r) => r.action !== "release");
 }

package/dist/commands/update.js

@@ -10,7 +10,7 @@ import { STANDARD_VERSION } from "../version.js";
 import { assertSupportedStandard } from "./check.js";
 import { buildContext } from "./context.js";
 import { guardUncommitted } from "./init.js";
-import { printResult } from "./report.js";
+import { nextSteps, printResult, printWarnings } from "./report.js";
 export async function updateCommand(root, options, io) {
     const config = await loadConfig(root);
     assertSupportedStandard(config.standard);
@@ -25,13 +25,15 @@ export async function updateCommand(root, options, io) {
         owned: config.owned,
     });
     if (!options.dryRun)
-        await guardUncommitted(root, result, options.force);
+        await guardUncommitted(root, result, options.force, lock);
     printResult(io, result);
     if (options.dryRun) {
         io.out("dry run: nothing written");
         return 0;
     }
     await applySync(root, result, lock, STANDARD_VERSION);
+    const steps = await nextSteps(root, ctx, result);
+    await printWarnings(root, ctx, io);
     if (config.standard !== STANDARD_VERSION) {
         const path = join(root, CONFIG_FILE);
         await writeFile(path, setStandard(await readFile(path, "utf8"), STANDARD_VERSION));
@@ -41,6 +43,8 @@ export async function updateCommand(root, options, io) {
         io.out(`${conflicts.length} file(s) kept because they were edited locally; new versions are beside them as *.repokeeper-new`);
         return 1;
     }
+    for (const step of steps)
+        io.out(`next: ${step}`);
     io.out(`repository is on standard ${STANDARD_VERSION}; commit with "chore(repokeeper): update standard to ${STANDARD_VERSION}"`);
     return 0;
 }

package/dist/duplicates.js

@@ -0,0 +1,36 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { REUSABLE_REPO } from "./version.js";
+const WORKFLOWS = ".github/workflows";
+const calls = (job) => {
+    const uses = job?.uses;
+    return (typeof uses === "string" && (uses.startsWith(`${REUSABLE_REPO}/`) || uses.startsWith("./.github/workflows/stack-")));
+};
+/** Workflows of the user's own that run a stack's test command, which repokeeper's ci job now runs as well. */
+export async function duplicateTestRuns(root, stacks) {
+    const commands = stacks.map((s) => s.test).filter((c) => c !== null);
+    if (commands.length === 0)
+        return [];
+    const names = await readdir(join(root, WORKFLOWS)).catch(() => []);
+    const found = [];
+    for (const name of names.filter((n) => /\.ya?ml$/.test(n)).sort()) {
+        let workflow;
+        try {
+            workflow = parse(await readFile(join(root, WORKFLOWS, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        // only pull request CI overlaps with repokeeper's ci job; a release workflow testing before it publishes doesn't
+        if (!JSON.stringify(workflow?.on ?? "").includes("pull_request"))
+            continue;
+        const jobs = workflow?.jobs ?? {};
+        const own = JSON.stringify(Object.values(jobs).filter((job) => !calls(job)));
+        for (const command of commands) {
+            if (own.includes(command))
+                found.push({ file: `${WORKFLOWS}/${name}`, command });
+        }
+    }
+    return found;
+}

package/dist/git.js

@@ -34,6 +34,14 @@ export async function latestReleaseVersion(root) {
     const tag = tags.split("\n").find((t) => /^v\d+\.\d+\.\d+$/.test(t.trim()));
     return tag ? tag.trim().slice(1) : null;
 }
+/** Tracked files git stores with CRLF line endings; `.gitattributes` only reaches them after a renormalize. */
+export async function crlfTrackedFiles(root) {
+    const out = (await git(root, ["ls-files", "--eol"])) ?? "";
+    return out
+        .split("\n")
+        .filter((line) => line.startsWith("i/crlf"))
+        .map((line) => line.split("\t").pop());
+}
 export async function gitUserName(root) {
     return (await git(root, ["config", "user.name"]))?.trim() || null;
 }

package/dist/platforms/github.js

@@ -99,6 +99,10 @@ export const githubPlatform = {
             directory: "/",
             schedule: { interval: "weekly" },
             groups: { [`${ecosystem}-minor-and-patch`]: { "update-types": ["minor", "patch"] } },
+            // @types/node majors track the Node.js line a project runs on, which the project chooses
+            ...(ecosystem === "npm"
+                ? { ignore: [{ "dependency-name": "@types/node", "update-types": ["version-update:semver-major"] }] }
+                : {}),
         }));
         return [yamlFile("deps", ".github/dependabot.yml", { version: 2, updates })];
     },

package/dist/stacks/dotnet.js

@@ -1,9 +1,23 @@
+import { UsageError } from "../errors.js";
 import { checkKeys, filesMatching, readText, stringList } from "./support.js";
 const OPTION_KEYS = ["versions", "os"];
 const SOLUTIONS = /\.(sln|slnx)$/;
 const PROJECTS = /\.(csproj|fsproj|vbproj)$/;
 const VERSION_XPATH = "//Project/PropertyGroup/Version";
 const versionOf = (xml) => (xml ? (/<Version>\s*([^<\s]+)\s*<\/Version>/.exec(xml)?.[1] ?? null) : null);
+/** Project files the root solutions list, plus projects at the root, as posix paths. */
+async function projectPaths(root, solutions, projects) {
+    const paths = new Set(projects);
+    for (const solution of solutions) {
+        const text = (await readText(root, solution)) ?? "";
+        const pattern = solution.endsWith(".slnx") ? /Path="([^"]+\.[cfv][sb]proj)"/g : /"([^"]+\.[cfv][sb]proj)"/g;
+        for (const match of text.matchAll(pattern))
+            paths.add(match[1].replace(/\\/g, "/"));
+    }
+    return [...paths];
+}
+/** SDK-style projects name an SDK; .NET Framework projects don't, and the dotnet CLI can't build them. */
+const isSdkStyle = (xml) => /<Project[^>]*\sSdk=/.test(xml) || /<Sdk\s+Name=/.test(xml);
 export const dotnetStack = {
     id: "dotnet",
     detect: (root) => filesMatching(root, ".", SOLUTIONS).length + filesMatching(root, ".", PROJECTS).length > 0,
@@ -13,6 +27,15 @@ export const dotnetStack = {
         const projects = filesMatching(root, ".", PROJECTS);
         // with several entries at the root, dotnet stops with MSB1011 unless one is named
         const target = solutions.length + projects.length > 1 ? ` ${solutions[0] ?? projects[0]}` : "";
+        const legacy = [];
+        for (const path of await projectPaths(root, solutions, projects)) {
+            const xml = await readText(root, path);
+            if (xml !== null && /<Project[\s>]/.test(xml) && !isSdkStyle(xml))
+                legacy.push(path);
+        }
+        if (legacy.length > 0) {
+            throw new UsageError(`the dotnet stack needs SDK-style projects, and ${legacy.join(", ")} ${legacy.length > 1 ? "are" : "is"} .NET Framework projects the dotnet CLI can't build; convert them (for example with the .NET Upgrade Assistant) or leave dotnet out of stacks`);
+        }
         let release = { type: "simple", version: null };
         for (const file of ["Directory.Build.props", ...(projects.length === 1 ? projects : [])]) {
             const version = versionOf(await readText(root, file));

package/dist/stacks/python.js

@@ -4,8 +4,11 @@ import { checkKeys, filesMatching, optionalString, readText, stringList } from "
 const OPTION_KEYS = ["versions", "os", "test"];
 /** The `version = "…"` of the `[project]` table, if any. */
 function projectVersion(pyproject) {
-    const table = pyproject.split(/^\[/m).find((section) => section.startsWith("project]"));
-    return table ? (/^version\s*=\s*"([^"]+)"/m.exec(table)?.[1] ?? null) : null;
+    return /^version\s*=\s*"([^"]+)"/m.exec(section(pyproject, "project"))?.[1] ?? null;
+}
+/** The body of the `[name]` table of a TOML file, or "". */
+function section(toml, name) {
+    return toml.split(/^\[/m).find((part) => part.startsWith(`${name}]`)) ?? "";
 }
 export const pythonStack = {
     id: "python",
@@ -15,7 +18,10 @@ export const pythonStack = {
         const has = (path) => existsSync(join(root, path));
         const pyproject = (await readText(root, "pyproject.toml")) ?? "";
         const uv = has("uv.lock");
+        const mypyIni = (await readText(root, "mypy.ini")) ?? "";
         const mypy = has("mypy.ini") || pyproject.includes("[tool.mypy]");
+        // a config that names its files decides what mypy checks; otherwise check the whole tree
+        const mypyFiles = /^files\s*=/m.test(mypyIni) || /^files\s*=/m.test(section(pyproject, "tool.mypy"));
         const hasTests = has("tests") || has("test") || filesMatching(root, ".", /^test_.*\.py$/).length > 0;
         const customTest = optionalString("python", options, "test");
         const pytest = customTest === undefined && hasTests;
@@ -37,7 +43,7 @@ export const pythonStack = {
         const commands = [
             `${run}ruff format --check .`,
             `${run}ruff check .`,
-            ...(mypy ? [`${run}mypy .`] : []),
+            ...(mypy ? [`${run}mypy${mypyFiles ? "" : " ."}`] : []),
             ...(test ? [test] : []),
         ];
         const ruff = uv ? "uvx ruff" : "ruff";

package/dist/sync/attributes.js

@@ -0,0 +1,44 @@
+import { endMarker, startMarker } from "./block.js";
+import { normalizeEol } from "./hash.js";
+/** `eol=lf` → ["eol", "lf"], `-text` → ["text", "unset"], `text` → ["text", "set"]. */
+function attributes(fields) {
+    const map = new Map();
+    for (const field of fields) {
+        if (field.startsWith("-") || field.startsWith("!"))
+            map.set(field.slice(1), "unset");
+        else if (field.includes("="))
+            map.set(field.slice(0, field.indexOf("=")), field.slice(field.indexOf("=") + 1));
+        else
+            map.set(field, "set");
+    }
+    return map;
+}
+const parse = (line) => {
+    const [pattern, ...fields] = line.trim().split(/\s+/);
+    return { raw: line.trim(), pattern: pattern, attrs: attributes(fields) };
+};
+const isRule = (line) => line.trim() !== "" && !line.trim().startsWith("#");
+/**
+ * Lines above repokeeper's block that set an attribute the block sets differently for the same
+ * pattern. gitattributes applies the last match, so those lines have no effect.
+ */
+export function overriddenAttributes(text, blockId) {
+    const lines = normalizeEol(text).split("\n");
+    const start = lines.indexOf(startMarker(blockId, "hash"));
+    const end = lines.indexOf(endMarker(blockId, "hash"), start + 1);
+    if (start < 0 || end < 0)
+        return [];
+    const block = lines
+        .slice(start + 1, end)
+        .filter(isRule)
+        .map(parse);
+    const found = [];
+    for (const line of lines.slice(0, start).filter(isRule)) {
+        const mine = parse(line);
+        const theirs = block.find((rule) => rule.pattern === mine.pattern &&
+            [...mine.attrs].some(([key, value]) => rule.attrs.has(key) && rule.attrs.get(key) !== value));
+        if (theirs)
+            found.push({ line: mine.raw, by: theirs.raw });
+    }
+    return found;
+}

package/dist/version.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 export const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 /** The standard this build of repokeeper applies. Bump it whenever generated output changes. */
-export const STANDARD_VERSION = "1.2.1";
+export const STANDARD_VERSION = "1.2.2";
 export const TOOL_VERSIONS = {
     lefthook: "2.1.14",
     commitlintCli: "21.2.3",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repokeeper",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Keep every repository on one maintained standard: commits, git hooks, CI, releases, dependency updates and repo settings.",
   "type": "module",
   "bin": {