apify-test-tools 0.10.2-beta.3 → 0.10.2-beta.5

package/bin/affected-actors.ts

@@ -1,27 +1,31 @@
 import { type ChangedActors, getChangedActors } from './diff-changes.js';
 import {
-    getBranchOnlyChangedFiles,
+    findCommitSha,
     getChangedFilesBetween,
     getChangelogAdditions,
-    getCommits,
     getCommitsBetween,
-    hasMergeFromTarget,
-    resolveBranchName,
+    getMergeBase,
     resolveCommitSha,
     resolveReleaseBaseCommit,
 } from './git.js';
 import { logger } from './logger.js';
-import type { ActorConfig, Commit } from './types.js';
+import type { ActorConfig, Commit, GitRange } from './types.js';
 import { readConfigFile } from './utils/config/load-config.js';
 
+// The range always ends at the checked-out commit: check out what you want to inspect
+const HEAD = 'HEAD';
+
 interface AffectedActorsOptions {
-    /** End of the range. */
-    head: string;
-    /** Only the commits on head that are not on base count, i.e. the branch's own changes. */
+    /**
+     * Base usually points to the master branch
+     * Only what HEAD changes compared to base counts, like `git diff base...HEAD` or GitHub's "Files changed" tab:
+     * the branch's own changes, not what it merged in from base.
+     */
     base?: string;
     /**
-     * Only changes after this commit count. With `base` it's the last validated commit of the branch and is
-     * ignored when it isn't on the branch. Without `base` it must be an ancestor of head (e.g. the last release).
+     * With `base` it's the last validated commit of the branch: Actors that didn't change after it are left out.
+     * It's ignored when it is HEAD (a rerun) or isn't in the local history. Without `base` everything after it
+     * counts, and it must be an ancestor of HEAD (e.g. the last release).
      */
     since?: string;
     /** Glob relative to the repo root. Matching files count as changes even when .dockerignore lists them. */
@@ -30,83 +34,115 @@ interface AffectedActorsOptions {
     ignore: string[];
 }
 
+/** The JSON document `get-affected-actors` prints. Versioned, since other commands and workflows consume it. */
 interface AffectedActors {
-    headSha: string;
-    /** Branch head points to, which is what git builds are made from. Null for a SHA or a detached HEAD. */
-    ref: string | null;
+    version: 1;
+    head: string;
+    /** The commits, changed files and changelog describe the whole range, `--since` with `--base` only narrows the Actors. */
     commits: Commit[];
     changedFiles: string[];
     changelog: string | null;
-    /** Actors with at least one functional change. They need a new build and tests. */
-    functionallyChangedActors: ActorConfig[];
+    /**
+     * Actors with at least one functional change. They need a new build and tests. Only the names: the config file
+     * stays the source of truth for the rest.
+     */
+    functionallyChangedActors: { actorFullName: string }[];
     /** Actors whose changes are all cosmetic (README, CHANGELOG, cosmetic .actor JSON). They only need a release build. */
-    cosmeticallyChangedActors: ActorConfig[];
+    cosmeticallyChangedActors: { actorFullName: string }[];
 }
 
-interface CommitRange {
-    commits: Commit[];
-    fromRef: string;
-    toRef: string;
-}
-
-/** The branch's own commits, after `since` when it is on the branch (see getCommits). */
-const getBranchRange = async (head: string, base: string, since: string | undefined): Promise<CommitRange> => {
-    const commits = await getCommits({ sourceBranch: head, targetBranch: base, baseCommit: since });
-    return { commits, fromRef: `${commits[0].sha}~`, toRef: commits[commits.length - 1].sha };
-};
+const names = (configs: ActorConfig[]) => configs.map(({ actorFullName }) => ({ actorFullName }));
 
-/** Everything after `since` up to head. Unlike on a branch, `since` must be an ancestor of head. */
-const getRangeSince = async (head: string, headSha: string, since: string): Promise<CommitRange> => {
-    const sinceSha = await resolveReleaseBaseCommit(since, head);
-    const commits = sinceSha === headSha ? [] : await getCommitsBetween(sinceSha, headSha);
-    return { commits, fromRef: sinceSha, toRef: headSha };
+/** The branch's last validated commit, unless it can't narrow anything down. */
+const findValidatedSha = async (since: string, headSha: string): Promise<string | undefined> => {
+    const sinceSha = await findCommitSha(since);
+    if (!sinceSha) {
+        logger.info(
+            `Last validated commit ${since} is not in the local history (force-push?), checking the whole branch`,
+        );
+        return undefined;
+    }
+    if (sinceSha === headSha) {
+        logger.info('Last validated commit is HEAD, so this is a rerun: checking the whole branch from scratch');
+        return undefined;
+    }
+    return sinceSha;
 };
 
 /**
- * This is an optimization for the common case where a branch only has cosmetic changes but had to merge in
- * functional changes from base (being up-to-date is a CI requirement). Base is already validated, and
- * since the branch has no functional changes of its own, there is nothing new to validate.
- * Exception: if the branch has any functional changes alongside the merge, we must re-test — even
- * individually validated changes can have novel interactions when combined.
- * Returns the Actors the branch's own commits changed, or undefined when it didn't merge base in.
+ * This is Juan's magical algorithm where we need just 2 git diffs to determine functional changes on Actors.
+ *
+ * Naively, we could just check branch HEAD changes vs base or parent of first commit and be done but
+ * we do this jiu-jitsu code to apply 2 optimizations:
+ * 1. On our PR branch, we track last validated commit (since) that was tested and so we only need to test new commits.
+ * 2. We also merge changes from the base branch (usually master) and we can consider those already validated as well.
+ *
+ * But there is annoying problem: even if both our branch and base are validated, they could have novel interactions and
+ * we need to retest those.
  *
- * TODO: Apply this per Actor instead of to the whole branch. Changes merged in from base only interact with the
- * branch's own changes in Actors whose context both touch, so an Actor that only base changed is already validated
- * and can be skipped even when the branch changes other Actors functionally. Today any functional change of the
- * branch's own keeps every Actor, and the log messages below describe the whole branch.
+ * So we look at:
+ * 1. The changes introduced by our branch since the last validated commit (`since..HEAD`).
+ * 2. The changes introduced by the branch compared to the base branch (`base...HEAD`). The important part is that this
+ * diff does check the whole branch, discarding the last validated commit (since) so it checks those novel interactions problem.
+ *
+ * The magic is that both need to contain changes for an Actor to be retested:
+ * 1. If we have changes only in since..HEAD (and not in base...HEAD), it means those changes came from merging the base alone
+ * which is already validated and there were actually no real changes introduced by our branch alone.
+ * 2. If we have changes only in base...HEAD (and not in since..HEAD), it means there are no new changes on our branch
+ * since it was last validated. base...HEAD has changes that we already validated.
+ *
+ * This enables to simply do those 2 diffs for each Actor's context separately and only Actors that have changes
+ * in both diffs need to be retested.
+ *
+ * THIS ASSUMES BRANCH IS UP TO DATE WITH BASE WHEN IT MERGES, which we currently require. Only then is HEAD what lands on
+ * base, and base's commits validated. Otherwise what lands is HEAD combined with base's newer commits, which nobody
+ * tested, however the Actors are picked.
+ *
+ * In each example the branch's functional change to Actor A was validated at `since`, then one more push follows:
+ *
+ * Example scenarios:
+ * - Our own branch only: a commit changes A's README and B's code.
+ *   `since..HEAD`: A cosmetic, B functional. `base...HEAD`: A and B functional.
+ *   → A cosmetic, B functional: only B is tested, A's code is still the validated one.
+ * - Cosmetic merge: the branch merges base, which only changed READMEs and the CHANGELOG.
+ *   `since..HEAD`: every Actor cosmetic (CHANGELOG counts for all). `base...HEAD`: A functional, since the merged
+ *   files now match base and drop out of it.
+ *   → A cosmetic, the other Actors left out: nothing is tested.
+ * - Functional merge: the branch merges base, which changed code of A and of C.
+ *   `since..HEAD`: A and C functional. `base...HEAD`: A functional.
+ *   → A functional, C left out: A is tested, since base's change can interact with the branch's, while C only has
+ *   base's change, which base already validated.
  */
-const getOwnChangesIfMergedFromBase = async (
-    head: string,
-    base: string,
-    actorConfigs: ActorConfig[],
-    testFilesGlob: string | undefined,
-): Promise<ChangedActors | undefined> => {
-    if (!(await hasMergeFromTarget(head, base))) return undefined;
+const intersectChangedInBranchVsSince = (branch: ChangedActors, sinceValidated: ChangedActors): ChangedActors => {
+    const narrowed: ChangedActors = { functional: [], cosmetic: [] };
+    // All checks are done for each Actor separately, that's cleanest and most accurate
+    for (const actor of [...branch.functional, ...branch.cosmetic]) {
+        // base...HEAD
+        const changedFunctionallyOnBranch = branch.functional.includes(actor);
+        // since..HEAD
+        const changedFunctionallySince = sinceValidated.functional.includes(actor);
+
+        // changedSince is used for release. Release cares also about cosmetic.
+        const changedSince = changedFunctionallySince || sinceValidated.cosmetic.includes(actor);
 
-    logger.info(
-        '[MERGE-FROM-TARGET-OPTIMIZATION]: There is merge from target branch, checking if there are no functional changes in our own branch. If so, we can skip tests',
-    );
-    const own = await getChangedActors({
-        filepathsChanged: await getBranchOnlyChangedFiles(head, base),
-        actorConfigs,
-        // Omit since to get full branch history. Validated functional commits can still interact with merged ones
-        commits: await getCommits({ sourceBranch: head, targetBranch: base }),
-        testFilesGlob,
-    });
-    logger.info(
-        own.functional.length > 0
-            ? `[MERGE-FROM-TARGET-OPTIMIZATION]: Branch has ${own.functional.length} functional changes, cannot optimize, we continue with full check`
-            : '[MERGE-FROM-TARGET-OPTIMIZATION]: Branch itself has no functional changes, skipping tests',
-    );
-    return own;
+        // Nothing changed since the last validation, so the branch's change to this Actor is already validated
+        if (!changedSince) continue;
+
+        // As we said, only intersection counts as functional, otherwise it's cosmetic
+        if (changedFunctionallyOnBranch && changedFunctionallySince) {
+            narrowed.functional.push(actor);
+        } else {
+            narrowed.cosmetic.push(actor);
+        }
+    }
+    return narrowed;
 };
 
 /**
- * Finds the Actors whose context changed in the given range. `base` selects the branch's own commits
- * (a PR), `since` the commits after a known one (a release, or the last validated commit of a PR).
+ * Finds the Actors whose context changed in the given range. `base` selects the branch's own changes
+ * (a PR), `since` the changes after a known commit (a release, or the last validated commit of a PR).
  */
 export const getAffectedActors = async ({
-    head,
     base,
     since: sinceOption,
     testFilesGlob,
@@ -119,48 +155,44 @@ export const getAffectedActors = async ({
         throw new Error('Pass --base, --since, or both to select the commits to inspect.');
     }
 
-    const headSha = await resolveCommitSha(head);
-    const { commits, fromRef, toRef } = base
-        ? await getBranchRange(head, base, since)
-        : await getRangeSince(head, headSha, since!);
     const actorConfigs = await readConfigFile({ actors, ignore });
+    const getChangedInRange = async (range: GitRange) => {
+        const changedFiles = await getChangedFilesBetween(range.fromRef, range.toRef);
+        return {
+            changedFiles,
+            changedActors: await getChangedActors({
+                filepathsChanged: changedFiles,
+                actorConfigs,
+                range,
+                testFilesGlob,
+            }),
+        };
+    };
 
-    // What the branch only merged in from base is already validated. Without functional changes of its own
-    // the branch has nothing to test, and without any changes of its own nothing to release either.
-    const own = base ? await getOwnChangesIfMergedFromBase(head, base, actorConfigs, testFilesGlob) : undefined;
-    const changedFiles = await getChangedFilesBetween(fromRef, toRef);
-    const changed = await getChangedActors({ filepathsChanged: changedFiles, actorConfigs, commits, testFilesGlob });
-
-    return {
-        headSha,
-        ref: await resolveBranchName(head),
-        commits,
-        changedFiles,
-        changelog: await getChangelogAdditions(fromRef, toRef, changedFiles),
-        functionallyChangedActors: own && own.functional.length === 0 ? [] : changed.functional,
-        cosmeticallyChangedActors: own && own.functional.length + own.cosmetic.length === 0 ? [] : changed.cosmetic,
+    const headSha = await resolveCommitSha(HEAD);
+    const rangeVsBase: GitRange = {
+        // merge base = PR, release base = push to master (release)
+        fromRef: base ? await getMergeBase(base, HEAD) : await resolveReleaseBaseCommit(since!),
+        toRef: headSha,
     };
-};
 
-/** The JSON document `get-affected-actors` prints. Versioned, since other commands and workflows consume it. */
-export const toAffectedActorsDocument = ({
-    headSha,
-    ref,
-    commits,
-    changedFiles,
-    changelog,
-    functionallyChangedActors,
-    cosmeticallyChangedActors,
-}: AffectedActors) => {
-    const names = (configs: ActorConfig[]) => configs.map(({ actorFullName }) => ({ actorFullName }));
+    // Falls back to rangeVsBase.fromRef when there's no (usable) last validated commit — same as
+    // intersecting the branch's changes with themselves, which is a no-op (see this function's docs).
+    const validatedSha = base && since ? await findValidatedSha(since, headSha) : undefined;
+    const sinceFromRef = validatedSha ?? rangeVsBase.fromRef;
+
+    const { changedFiles, changedActors: changedVsBase } = await getChangedInRange(rangeVsBase);
+    const { changedActors: changedSinceActors } = await getChangedInRange({ fromRef: sinceFromRef, toRef: headSha });
+    // See this function's docs to understand the algorithm: only intersection counts as functional, otherwise it's cosmetic.
+    const changedActors = intersectChangedInBranchVsSince(changedVsBase, changedSinceActors);
+
     return {
         version: 1,
-        ref,
         head: headSha,
-        commits,
+        commits: await getCommitsBetween(rangeVsBase.fromRef, rangeVsBase.toRef),
         changedFiles,
-        changelog,
-        functionallyChangedActors: names(functionallyChangedActors),
-        cosmeticallyChangedActors: names(cosmeticallyChangedActors),
+        changelog: await getChangelogAdditions(rangeVsBase.fromRef, rangeVsBase.toRef, changedFiles),
+        functionallyChangedActors: names(changedActors.functional),
+        cosmeticallyChangedActors: names(changedActors.cosmetic),
     };
 };

package/bin/build.ts

@@ -1,22 +1,21 @@
 import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType, ApifyClient } from 'apify-client';
 
-import { normalizeRepoUrl } from './git.js';
+import { getCurrentBranch, normalizeRepoUrl, resolveRepoUrl } from './git.js';
 import { logger } from './logger.js';
 import type { ActorConfig, BuildData, DryRunPlan } from './types.js';
 
 type BuildPrActorOptions = {
-    buildTag?: string;
     versionNumber: string;
     gitRepoUrl: string;
     actorConfig: ActorConfig;
     actorInfo: ApifyClientTypes.Actor;
-    useDockerCache: boolean;
 };
 
 // Fixed version number used to build from local source files, since there is no real version to track.
 export const LOCAL_SOURCE_VERSION_NUMBER = '0.98';
-const DEFAULT_TEST_VERSION_NUMBER = '0.99';
+// Stands for each Actor's default version: the one its default build tag points to
+export const DEFAULT_VERSION_KEYWORD = 'default';
 
 // Shown whenever an Actor isn't set up the way CI builds need it
 const ACTOR_SETUP_REQUIREMENT =
@@ -319,20 +318,18 @@ export const runAndSummarizeBuilds = async (
 type GitBuildPlan = {
     actorFullName: string;
     versionNumber: string;
-    buildTag?: string;
     gitRepoUrl: string;
-    useDockerCache: boolean;
 };
 
 type RunBuildsOptions = {
     actorConfigs: ActorConfig[];
-    isLatest?: boolean;
+    // A version number like "0.99", or DEFAULT_VERSION_KEYWORD for each Actor's default version
+    versionNumber: string;
     repoUrl: string;
     // False when the repo URL was passed explicitly, see assertRepoUrlMatchesDefaultVersion
     shouldVerifyRepoUrl: boolean;
     branch: string;
     dryRun: boolean;
-    useDockerCache: boolean;
 };
 
 export const runBuilds = async ({
@@ -340,9 +337,8 @@ export const runBuilds = async ({
     shouldVerifyRepoUrl,
     branch,
     actorConfigs,
-    isLatest = false,
+    versionNumber,
     dryRun,
-    useDockerCache,
 }: RunBuildsOptions): Promise<BuildData[] | DryRunPlan<GitBuildPlan>> => {
     // Fetched once per Actor and reused for the checks, the version numbers and the build itself
     const buildConfigs: BuildPrActorOptions[] = await Promise.all(
@@ -352,6 +348,15 @@ export const runBuilds = async ({
                 actorConfig.actorFullName,
                 actorInfo,
             );
+            // Builds keep the tags their version gives them, so a default version without the default build tag
+            // would build fine but leave users on the previous build
+            if (versionNumber === DEFAULT_VERSION_KEYWORD && defaultVersion?.buildTag !== defaultBuildTag) {
+                logger.warn(
+                    `[${actorConfig.actorFullName}] Default version ${defaultVersionNumber} has build tag ` +
+                        `"${defaultVersion?.buildTag ?? 'none'}", not "${defaultBuildTag}", so users keep running the previous build. ` +
+                        'Set the build tag of the version on the platform to change that.',
+                );
+            }
             if (shouldVerifyRepoUrl) {
                 assertRepoUrlMatchesDefaultVersion(actorConfig.actorFullName, defaultVersion, repoUrl);
             }
@@ -365,9 +370,7 @@ export const runBuilds = async ({
                 actorConfig,
                 actorInfo,
                 gitRepoUrl,
-                versionNumber: isLatest ? defaultVersionNumber : DEFAULT_TEST_VERSION_NUMBER,
-                buildTag: isLatest ? defaultBuildTag : undefined,
-                useDockerCache,
+                versionNumber: versionNumber === DEFAULT_VERSION_KEYWORD ? defaultVersionNumber : versionNumber,
             };
         }),
     );
@@ -375,21 +378,15 @@ export const runBuilds = async ({
     // Everything above only reads, so a dry run has checked what the real run would, short of writing
     if (dryRun) {
         logger.info('[DRY RUN] Would build:');
-        for (const { actorConfig, versionNumber, gitRepoUrl } of buildConfigs) {
-            logger.info(`  ${actorConfig.actorFullName} (${versionNumber}) from ${gitRepoUrl}`);
+        const builds = buildConfigs.map((buildConfig) => ({
+            actorFullName: buildConfig.actorConfig.actorFullName,
+            versionNumber: buildConfig.versionNumber,
+            gitRepoUrl: buildConfig.gitRepoUrl,
+        }));
+        for (const build of builds) {
+            logger.info(`  ${build.actorFullName} (${build.versionNumber}) from ${build.gitRepoUrl}`);
         }
-        return {
-            dryRun: true,
-            builds: buildConfigs.map(
-                ({ actorConfig, versionNumber, buildTag, gitRepoUrl, useDockerCache: useCache }) => ({
-                    actorFullName: actorConfig.actorFullName,
-                    versionNumber,
-                    buildTag,
-                    gitRepoUrl,
-                    useDockerCache: useCache,
-                }),
-            ),
-        };
+        return { dryRun: true, builds };
     }
 
     const buildConfigsByActorFullName = new Map(
@@ -397,20 +394,38 @@ export const runBuilds = async ({
     );
 
     return runAndSummarizeBuilds(actorConfigs, 'BUILDS', async (actorConfig, builder) => {
-        const {
-            actorInfo,
-            buildTag,
-            versionNumber,
-            gitRepoUrl,
-            useDockerCache: useCache,
-        } = buildConfigsByActorFullName.get(actorConfig.actorFullName)!;
+        const buildConfig = buildConfigsByActorFullName.get(actorConfig.actorFullName)!;
+        // No buildTag: the version keeps the one it has, so its build gets the tag the version already gives it
         const actorVersion: ApifyClientTypes.ActorVersion = {
-            buildTag,
-            versionNumber,
-            gitRepoUrl,
+            versionNumber: buildConfig.versionNumber,
+            gitRepoUrl: buildConfig.gitRepoUrl,
             sourceType: ActorSourceType.GitRepo,
         };
-        return builder.createVersionAndBuild(versionNumber, actorVersion, useCache, actorInfo);
+        // Always with the Docker cache: CI always asked for it, and a clean build can still be started on the platform
+        return builder.createVersionAndBuild(buildConfig.versionNumber, actorVersion, true, buildConfig.actorInfo);
+    });
+};
+
+type BuildActorsOptions = Omit<RunBuildsOptions, 'repoUrl' | 'shouldVerifyRepoUrl' | 'branch'> & {
+    // Defaults to the `origin` remote, see resolveRepoUrl
+    repoUrl?: string;
+};
+
+/**
+ * Builds exactly the given Actors from the checked-out Git branch, as it is on the remote. Fails on a detached HEAD,
+ * where there is no branch to build. Used by `build` and the commands built on top of it.
+ */
+export const buildActors = async ({ actorConfigs, repoUrl, ...options }: BuildActorsOptions) => {
+    if (actorConfigs.length === 0) {
+        logger.info('No Actors to build');
+        // Still the dry-run shape in a dry run, so it can't pass for a real (empty) result
+        return options.dryRun ? { dryRun: true as const, builds: [] } : [];
+    }
+    return runBuilds({
+        ...options,
+        ...(await resolveRepoUrl(repoUrl)),
+        actorConfigs,
+        branch: await getCurrentBranch(),
     });
 };
 

package/bin/diff-changes.ts

@@ -3,13 +3,14 @@ import picomatch from 'picomatch';
 import { isCosmeticOnlyJsonSchemaChange } from './diff-json-schema.js';
 import { type DockerIgnoreMatcher, loadDockerIgnore } from './dockerignore.js';
 import { logger } from './logger.js';
-import type { ActorConfig, Commit } from './types.js';
+import type { ActorConfig, GitRange } from './types.js';
 import { type RelativeDir, RelativeFile } from './utils/path/repo-relative.js';
 
 interface ShouldBuildAndTestOptions {
     filepathsChanged: string[];
     actorConfigs: ActorConfig[];
-    commits: Commit[];
+    /** The range the files changed in, to compare `.actor` JSON files across. */
+    range: GitRange;
     // Glob relative to the repo root. Matching files count as changes even when .dockerignore lists them.
     testFilesGlob?: string;
 }
@@ -52,7 +53,7 @@ type FileChangeForActor =
 const classifyFileChange = async (
     changedFile: RelativeFile,
     actorConfig: ActorConfig,
-    commits: Commit[],
+    range: GitRange,
     dockerIgnoreMatcher: DockerIgnoreMatcher,
     isTestFile: (filePath: string) => boolean,
 ): Promise<FileChangeForActor> => {
@@ -91,7 +92,7 @@ const classifyFileChange = async (
     }
 
     if (lowercaseFilePath.endsWith('.json') && isUnderActorDotDir) {
-        const isCosmetic = await isCosmeticOnlyJsonSchemaChange(commits, changedFile.path);
+        const isCosmetic = await isCosmeticOnlyJsonSchemaChange(range, changedFile.path);
         if (isCosmetic) return { impact: 'cosmetic', semanticallyVerified: true };
     }
 
@@ -175,7 +176,7 @@ export interface ChangedActors {
 export const getChangedActors = async ({
     filepathsChanged,
     actorConfigs,
-    commits,
+    range,
     testFilesGlob,
 }: ShouldBuildAndTestOptions): Promise<ChangedActors> => {
     const actorsChangedMap = new Map<string, ActorChangeEntry>();
@@ -192,7 +193,7 @@ export const getChangedActors = async ({
                 continue;
             }
 
-            const change = await classifyFileChange(filePath, actorConfig, commits, dockerIgnoreMatcher, isTestFile);
+            const change = await classifyFileChange(filePath, actorConfig, range, dockerIgnoreMatcher, isTestFile);
             if (change.impact !== 'outside-context' && isTestFile(originalFilePath)) {
                 testFilesInContext.add(originalFilePath);
             }

package/bin/diff-json-schema.ts

@@ -1,5 +1,5 @@
 import { logger } from './logger.js';
-import type { Commit } from './types.js';
+import type { GitRange } from './types.js';
 import { runGitCommand } from './utils.js';
 
 const COSMETIC_JSON_FIELD_NAMES = new Set([
@@ -29,11 +29,10 @@ const isCosmeticObjectChange = (oldVal: unknown, newVal: unknown, currentKey?: s
  * Returns true if the two JSON strings differ only in cosmetic fields
  * (title, description, example, enumTitles, sectionCaption, sectionDescription).
  */
-export const isCosmeticOnlyJsonSchemaChange = async (commits: Commit[], changedFilepath: string): Promise<boolean> => {
-    // TODO: validate this is the right commit range
-    const oldRef = `${commits[0].sha}~`;
-    const newRef = commits[commits.length - 1].sha;
-
+export const isCosmeticOnlyJsonSchemaChange = async (
+    { fromRef: oldRef, toRef: newRef }: GitRange,
+    changedFilepath: string,
+): Promise<boolean> => {
     const [oldJson, newJson] = await Promise.all([
         runGitCommand(['show', `${oldRef}:${changedFilepath}`])
             .then(JSON.parse)