flagrm 0.3.0 → 0.4.1

package/dist/core/report.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { reusedNote } from "./run-cache.js";
 import { plural, relativePath } from "./util.js";
 /** A path relative to the working directory, with `/` separators on every platform. */
 function rel(file) {
@@ -70,6 +71,9 @@ export function printBaseline(baseline, file) {
         if (c.failure)
             console.log(`    ${pc.yellow("setup problem:")} ${c.failure.message}`);
     }
+    const note = reusedNote(checks ?? [], baseline.createdAt);
+    if (note)
+        console.log(`  ${pc.dim(note)}`);
     if (baseline.names.length) {
         const names = baseline.names.map((n) => n.kind === "literal" ? n.name : `${n.name} (${n.kind}${n.file ? ` in ${n.file}` : ""})`);
         console.log(`  names: ${pc.dim(names.join(", "))}`);
@@ -122,6 +126,9 @@ export function printVerifyReport(report, file) {
     }
     if (report.strict && warned)
         console.log(pc.dim("\n  --strict: warnings count as failures."));
+    const note = reusedNote(report.runs, report.createdAt);
+    if (note)
+        console.log(pc.dim(`\n  ${note}`));
     console.log(pc.dim(`\nResult written to ${rel(file)}.`));
 }
 const STEP_STYLE = {

package/dist/core/run-cache.js

@@ -0,0 +1,147 @@
+/**
+ * Build and test runs a passing full verify saves, so the next baseline or
+ * verify on the same tree with the same commands reuses them instead of
+ * running them again: in a sequential removal, the next flag's baseline
+ * starts on the commit the previous flag's verify passed on.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { globSync } from "tinyglobby";
+import { flagDir, matchingFiles, runChecks } from "./baseline.js";
+import { changeFilter } from "./change-filter.js";
+import { configSnapshot, projectCommands } from "./config-snapshot.js";
+import { treeFingerprint } from "./git.js";
+import { packageVersion } from "./package.js";
+import { JSON_SCHEMA_VERSION, RUN_CHECK_ID } from "./types.js";
+import { readJson } from "./util.js";
+/** `.flagrm/<flag>/verify/runs.json`. */
+export function runsPath(root, flag) {
+    return path.join(flagDir(root, flag), "verify", "runs.json");
+}
+/**
+ * The tree the commands will run on: its fingerprint before they run, without
+ * flagrm's setup files and the test result files the runs themselves rewrite.
+ * Commands are compared on their own, so leaving out the config file is safe.
+ * Unlike the Stop hook's fingerprint, `exclude`d paths count: a build or test
+ * may read them (a lockfile, generated sources), so a change there must rerun.
+ */
+export function runsKey(root, projects) {
+    const ignore = changeFilter();
+    const patterns = projects.flatMap(({ adapter, ctx }) => projectCommands(adapter, ctx).testResults ?? []);
+    const results = matchingFiles(root, patterns);
+    return treeFingerprint(root, (rel) => ignore(rel) || results.has(rel));
+}
+/** The (project, check) pairs a run of `only` would run: those with a command. */
+export function plannedRuns(projects, only) {
+    return projects.flatMap(({ adapter, ctx }) => {
+        const commands = projectCommands(adapter, ctx);
+        return only.filter((check) => commands[check]).map((check) => ({ project: ctx.name, check }));
+    });
+}
+/**
+ * Save a passing full verify's runs; never a set with a setup problem, which would come back on every rerun,
+ * nor runs that were themselves reused: the set they came from keeps its own flag and time.
+ * The logs are copied next to `runs.json`, so a later verify overwriting its own logs leaves the saved set whole.
+ */
+export function saveRuns(root, flag, projects, key, runs, createdAt = new Date().toISOString()) {
+    if (runs.some((r) => r.failure || r.reused))
+        return;
+    const file = runsPath(root, flag);
+    const logDir = path.join(path.dirname(file), "saved");
+    fs.mkdirSync(logDir, { recursive: true });
+    const kept = runs.map(({ reused: _reused, ...run }) => {
+        if (!run.log)
+            return run;
+        const log = path.join(logDir, `${run.project}.${run.check}.log`);
+        fs.copyFileSync(run.log, log);
+        return { ...run, log };
+    });
+    const saved = {
+        schemaVersion: JSON_SCHEMA_VERSION,
+        flagrmVersion: packageVersion(),
+        flag,
+        createdAt,
+        key,
+        commands: configSnapshot(projects).projects,
+        runs: kept,
+    };
+    fs.writeFileSync(file, `${JSON.stringify(saved, null, 2)}\n`, "utf8");
+}
+/** Forget every saved set, of any flag, for this tree: a fresh run on it failed, so they may hide a flaky test or a changed machine. */
+export function dropRuns(root, key) {
+    for (const file of globSync(".flagrm/*/verify/runs.json", {
+        expandDirectories: false,
+        cwd: root,
+        absolute: true,
+        dot: true,
+    })) {
+        if (readJson(file)?.key === key)
+            fs.rmSync(file, { force: true });
+    }
+}
+/** The newest saved set, of any flag, for this tree and these commands that has every `needed` run and its log. */
+export function findRuns(root, projects, key, needed) {
+    if (needed.length === 0)
+        return undefined;
+    const commands = JSON.stringify(configSnapshot(projects).projects);
+    const version = packageVersion();
+    let best;
+    for (const file of globSync(".flagrm/*/verify/runs.json", {
+        expandDirectories: false,
+        cwd: root,
+        absolute: true,
+        dot: true,
+    })) {
+        const saved = readJson(file);
+        if (!saved || !Array.isArray(saved.runs) || typeof saved.createdAt !== "string")
+            continue;
+        if (saved.key !== key || saved.schemaVersion !== JSON_SCHEMA_VERSION)
+            continue;
+        if (saved.flagrmVersion !== version || JSON.stringify(saved.commands) !== commands)
+            continue;
+        const runs = needed.map((n) => saved.runs.find((r) => r.project === n.project && r.check === n.check));
+        if (runs.some((r) => !r || (r.log !== undefined && !fs.existsSync(r.log))))
+            continue;
+        if (!best || saved.createdAt > best.saved.createdAt)
+            best = { saved, runs: runs };
+    }
+    return best;
+}
+/** The found runs as this flag's own: logs copied into `logDir` under their usual names, marked `reused`. */
+export function reuseRuns(found, logDir) {
+    fs.mkdirSync(logDir, { recursive: true });
+    const reused = { flag: found.saved.flag, createdAt: found.saved.createdAt };
+    return found.runs.map((run) => {
+        if (!run.log)
+            return { ...run, reused };
+        const log = path.join(logDir, `${run.project}.${run.check}.log`);
+        if (path.resolve(run.log) !== path.resolve(log))
+            fs.copyFileSync(run.log, log);
+        return { ...run, log, reused };
+    });
+}
+/** A baseline's build, test and lint runs: reused from a passing verify on the same tree and commands, else run. */
+export async function baselineRuns(root, flag, projects, reuse = true) {
+    const logDir = flagDir(root, flag);
+    const key = reuse ? runsKey(root, projects) : undefined;
+    const found = key ? findRuns(root, projects, key, plannedRuns(projects, ["build", "test", "lint"])) : undefined;
+    return found ? reuseRuns(found, logDir) : runChecks(projects, logDir);
+}
+/** One line saying which runs were reused and from where, or undefined when none were. `at`: when they were reused. */
+export function reusedNote(runs, at) {
+    const reused = runs.find((r) => r.reused)?.reused;
+    if (!reused)
+        return undefined;
+    const checks = [...new Set(runs.filter((r) => r.reused).map((r) => RUN_CHECK_ID[r.check]))];
+    const what = checks.length > 1 ? `${checks.slice(0, -1).join(", ")} and ${checks.at(-1)}` : checks[0];
+    return `${what} reused from ${reused.flag}'s verify (same tree and commands, ${age(Date.parse(at) - Date.parse(reused.createdAt))} ago; --no-reuse to run them)`;
+}
+function age(ms) {
+    const min = Math.round(ms / 60_000);
+    if (min < 1)
+        return "under a minute";
+    if (min < 60)
+        return `${min} min`;
+    const hours = Math.round(min / 60);
+    return hours < 48 ? `${hours} h` : `${Math.round(hours / 24)} days`;
+}

package/dist/core/scan.js

@@ -1,5 +1,6 @@
+import fs from "node:fs";
 import path from "node:path";
-import fg from "fast-glob";
+import { globSync, isDynamicPattern } from "tinyglobby";
 export const BACKEND_GLOBS = [
     "**/*.cs",
     "**/*.cshtml",
@@ -19,11 +20,37 @@ export const IGNORE_GLOBS = [
     "**/.angular/**",
     "**/.git/**",
 ];
-/** Absolute paths with the platform's separators (fast-glob returns `/` on Windows too), so they match `path.join`. */
+/**
+ * Files matching an absolute path or glob, such as a `testResults` pattern,
+ * as absolute paths with `/`. The leading directories that exist are taken
+ * literally and become the glob's `cwd`, so a repository path containing
+ * glob characters (`/work/p[x]/TestResults/*.trx`) still matches.
+ */
+export function globAbsolute(pattern) {
+    const segments = (path.sep === "\\" ? pattern.replace(/\\/g, "/") : pattern).split("/");
+    let base = segments[0] === "" ? "/" : `${segments[0]}/`;
+    let i = 1;
+    for (; i < segments.length - 1; i++) {
+        const dir = path.posix.join(base, segments[i]);
+        if (isDynamicPattern(segments[i]) && !isDirectory(dir))
+            break;
+        base = dir;
+    }
+    return globSync(segments.slice(i).join("/"), { expandDirectories: false, cwd: base, absolute: true, dot: true });
+}
+function isDirectory(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Absolute paths with the platform's separators (tinyglobby returns `/` on Windows too), so they match `path.join`. */
 export function listProjectFiles(root, globs, overrides) {
     const patterns = [...globs, ...(overrides?.include ?? [])];
     const ignore = [...IGNORE_GLOBS, ...(overrides?.exclude ?? [])];
-    return fg.sync(patterns, { cwd: root, ignore, absolute: true, dot: false }).map((file) => path.normalize(file));
+    return globSync(patterns, { expandDirectories: false, cwd: root, ignore, absolute: true, dot: false }).map((file) => path.normalize(file));
 }
 export function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

package/dist/core/scope-files.js

@@ -0,0 +1,14 @@
+/**
+ * A file-scoped name (a local, parameter or field) is also used in the files
+ * that share its file's scope, such as an Angular component's template. The
+ * adapter whose project contains the file says which (`Adapter.scopeFiles`).
+ */
+import path from "node:path";
+import { relativePath } from "./util.js";
+/** `rel` (relative to the config `root`) followed by the files sharing its scope, relative too, each once. */
+export function withScopeFiles(projects, root, rel) {
+    const file = path.resolve(root, rel);
+    const owner = projects.find(({ ctx }) => !path.relative(ctx.root, file).startsWith(".."));
+    const more = owner?.adapter.scopeFiles?.(owner.ctx, file) ?? [];
+    return [...new Set([rel, ...more.map((f) => relativePath(root, f))])];
+}

package/dist/core/scope.js

@@ -8,7 +8,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import fg from "fast-glob";
+import { globSync } from "tinyglobby";
 import YAML from "yaml";
 import { sdkProblem, solutionSetup } from "../adapters/dotnet/setup.js";
 import { projectCommands } from "./config-snapshot.js";
@@ -81,8 +81,8 @@ function solutionFor(ctx, commands) {
             return { note: `can't read ${arg}` };
         }
     }
-    const found = fg.sync("*.{sln,slnx}", { cwd: ctx.root, absolute: true });
-    // fast-glob returns forward slashes, also on Windows.
+    const found = globSync("*.{sln,slnx}", { expandDirectories: false, cwd: ctx.root, absolute: true });
+    // tinyglobby returns forward slashes, also on Windows.
     if (found.length === 1)
         return { solution: path.normalize(found[0]) };
     return { note: found.length ? "several solutions: name one in build/test" : "no solution file found" };

package/dist/core/test-runner.js

@@ -0,0 +1,136 @@
+/**
+ * Which JavaScript test runner a project uses, read from `angular.json`'s
+ * test builder, config files and `package.json`, so the Angular adapter can
+ * default to a test command that writes machine-readable results, and
+ * doctor can say how to get them. Reads only; anything unreadable is `unknown`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { globSync } from "tinyglobby";
+import { readJson, relativePath } from "./util.js";
+/** The test target of the first `angular.json` project that has one. */
+function angularTestTarget(root) {
+    const json = readJson(path.join(root, "angular.json"));
+    for (const project of Object.values(json?.projects ?? {})) {
+        const test = (project?.architect ?? project?.targets)?.test;
+        if (test?.builder)
+            return test;
+    }
+    return undefined;
+}
+function dependencies(root) {
+    const pkg = readJson(path.join(root, "package.json"));
+    return new Set([...Object.keys(pkg?.dependencies ?? {}), ...Object.keys(pkg?.devDependencies ?? {})]);
+}
+const hasFile = (root, pattern) => globSync(pattern, { expandDirectories: false, cwd: root, deep: 1 }).length > 0;
+function karma(root, options) {
+    const conf = path.resolve(root, typeof options.karmaConfig === "string" ? options.karmaConfig : "karma.conf.js");
+    let text;
+    try {
+        text = fs.readFileSync(conf, "utf8");
+    }
+    catch {
+        return { kind: "karma" };
+    }
+    const outputDir = /junitReporter\s*:\s*\{[^}]*?\boutputDir\s*:\s*(['"`])([^'"`]+)\1/.exec(text)?.[2];
+    // Without a `plugins` key Karma loads every installed karma-* package.
+    const loaded = text.includes("karma-junit-reporter") ||
+        (!/\bplugins\s*:/.test(text) && dependencies(root).has("karma-junit-reporter"));
+    return loaded && outputDir
+        ? { kind: "karma", junit: { outputDir: path.resolve(path.dirname(conf), outputDir) } }
+        : { kind: "karma" };
+}
+export function detectTestRunner(root) {
+    const target = angularTestTarget(root);
+    const builder = target?.builder ?? "";
+    const options = target?.options ?? {};
+    if (builder === "@angular/build:unit-test")
+        return options.runner === "karma" ? karma(root, options) : { kind: "vitest-ng" };
+    if (builder.endsWith(":karma"))
+        return karma(root, options);
+    if (builder.startsWith("@angular-builders/jest"))
+        return { kind: "jest", viaNg: true };
+    if (hasFile(root, "jest.config.{js,ts,mjs,cjs,json}"))
+        return { kind: "jest", viaNg: false };
+    if (hasFile(root, "vitest.config.{js,ts,mjs,cjs,mts}"))
+        return { kind: "vitest" };
+    const deps = dependencies(root);
+    if (deps.has("jest"))
+        return { kind: "jest", viaNg: false };
+    if (deps.has("vitest"))
+        return { kind: "vitest" };
+    if (hasFile(root, "karma.conf.{js,cjs,ts}"))
+        return karma(root, {});
+    return { kind: "unknown" };
+}
+/** The flags that make each runner write results to `file` (quoted, relative to the project). */
+function resultFlags(runner, file) {
+    switch (runner.kind) {
+        case "vitest-ng":
+            // The unit-test builder's --output-file applies to the first reporter only.
+            return `--reporters=junit --output-file="${file("junit.xml")}"`;
+        case "jest":
+            return runner.viaNg ? undefined : `--json --outputFile="${file("jest.json")}"`;
+        case "vitest":
+            return `--reporter=default --reporter=junit --outputFile.junit="${file("junit.xml")}"`;
+        default:
+            return undefined;
+    }
+}
+const RESULT_FILE = {
+    "vitest-ng": "junit.xml",
+    jest: "jest.json",
+    vitest: "junit.xml",
+};
+/**
+ * A test command for the runner that writes results into `resultsDir`, and
+ * where to read them. Undefined when the runner can't without a setup change
+ * (Karma without a JUnit reporter, Jest through an Angular builder, unknown).
+ */
+export function runnerTestCommands(runner, projectRoot, resultsDir) {
+    if (runner.kind === "karma") {
+        return runner.junit
+            ? {
+                test: "npx ng test --watch=false --reporters=progress --reporters=junit",
+                testResults: path.join(runner.junit.outputDir, "**", "*.xml"),
+            }
+            : undefined;
+    }
+    const flags = resultFlags(runner, (name) => relativePath(projectRoot, path.join(resultsDir, name)));
+    const name = RESULT_FILE[runner.kind];
+    if (!flags || !name)
+        return undefined;
+    const base = runner.kind === "vitest-ng"
+        ? "npx ng test --watch=false"
+        : runner.kind === "jest"
+            ? "npx jest --ci"
+            : "npx vitest run";
+    return { test: `${base} ${flags}`, testResults: path.join(resultsDir, name) };
+}
+/**
+ * How to get test results for a project whose test command has none: one
+ * line for doctor and init. `dirFromProject` is a results directory relative
+ * to the project (for the command), `dirFromConfig` the same relative to the
+ * config file (for `testResults`). `adapterDefault`: the adapter's default
+ * test command writes results for this runner (Angular), so removing `test` is a fix too.
+ * `configRoot`: the config file's directory, for a results directory karma.conf.js names.
+ */
+export function testResultsHint(runner, dirFromProject, dirFromConfig, adapterDefault, configRoot) {
+    const flags = resultFlags(runner, (name) => `${dirFromProject}/${name}`);
+    const name = RESULT_FILE[runner.kind];
+    const fallback = adapterDefault ? " (or remove `test` to use the adapter default)" : "";
+    if (flags && name) {
+        return `add \`${flags}\` to the test command and set testResults: ${dirFromConfig}/${name}${fallback}`;
+    }
+    if (runner.kind === "karma" && runner.junit) {
+        const results = `./${relativePath(configRoot, runner.junit.outputDir)}/**/*.xml`;
+        return `add \`--reporters=progress --reporters=junit\` to the test command and set testResults: ${results}${fallback}`;
+    }
+    if (runner.kind === "karma") {
+        return "npm i -D karma-junit-reporter, add require('karma-junit-reporter') to plugins and junitReporter: { outputDir: 'test-results' } to karma.conf.js; the angular adapter's default test command then writes JUnit";
+    }
+    if (runner.kind === "jest") {
+        return `add \`--json --outputFile="${dirFromProject}/jest.json"\` to the test command if @angular-builders/jest passes them on, and set testResults: ${dirFromConfig}/jest.json`;
+    }
+    return "make the test runner write JUnit XML, TRX or Jest JSON and point testResults at the file";
+}

package/dist/core/types.js

@@ -18,11 +18,16 @@
  *   counts and at most 20 short failed test names (`failedTests`), no
  *   `config`. `baseline.json` itself is unchanged, so version 6 files are
  *   still read.
+ * - 8: `lint` runs (`check: "lint"`) and the `lint` and `coverage` checks;
+ *   `baseline.json` gains the config's `lint` commands and `git.dirtyHashes`.
+ *   Both are optional, so version 6 and 7 files are still read.
  */
-export const JSON_SCHEMA_VERSION = 7;
-/** `baseline.json` versions this flagrm reads: 7 only added optional fields to 6. */
-export const READABLE_BASELINE_VERSIONS = [6, 7];
+export const JSON_SCHEMA_VERSION = 8;
+/** `baseline.json` versions this flagrm reads: 7 and 8 only added optional fields to 6. */
+export const READABLE_BASELINE_VERSIONS = [6, 7, 8];
 // ---------------------------------------------------------------------------
 // verify
 // ---------------------------------------------------------------------------
-export const CHECK_IDS = ["leftovers", "dead-code", "build", "tests"];
+export const CHECK_IDS = ["leftovers", "dead-code", "build", "tests", "lint", "coverage"];
+/** The check that judges each kind of command run. */
+export const RUN_CHECK_ID = { build: "build", test: "tests", lint: "lint" };