cli: switch repo lint --cache option to --successCache and --successCacheDir

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/small-donkeys-attack.md

@@ -2,4 +2,6 @@
 '@backstage/cli': patch
 ---
 
-Added a new `--cache [path]` option to the `backstage-cli repo lint` command. The cache keeps track of successful lint runs and avoids re-running linting of individual packages if they haven't changed. This option is primarily intended to be used in CI.
+Added a new `--successCache` option to the `backstage-cli repo lint` command. The cache keeps track of successful lint runs and avoids re-running linting of individual packages if they haven't changed. This option is primarily intended to be used in CI.
+
+In addition a `--successCacheDir` option has also been added to be able to override the default cache directory.

.github/workflows/ci.yml

@@ -234,7 +234,7 @@ jobs:
         run: node scripts/verify-release.js
 
       - name: lint changed packages
-        run: yarn backstage-cli repo lint --since origin/master --cache
+        run: yarn backstage-cli repo lint --since origin/master --successCache
 
       - name: test changed packages
         run: yarn backstage-cli repo test --maxWorkers=3 --workerIdleMemoryLimit=1300M --since origin/master

.github/workflows/deploy_packages.yml

@@ -94,7 +94,7 @@ jobs:
         run: yarn backstage-cli config:check --lax
 
       - name: lint
-        run: yarn backstage-cli repo lint --cache
+        run: yarn backstage-cli repo lint --successCache
 
       - name: type checking and declarations
         run: yarn tsc:full

.github/workflows/verify_windows.yml

@@ -46,7 +46,7 @@ jobs:
         run: yarn install --immutable
 
       - name: lint
-        run: yarn backstage-cli repo lint --cache
+        run: yarn backstage-cli repo lint --successCache
 
       - name: type checking and declarations
         run: yarn tsc:full

docs/tooling/cli/02-build-system.md

@@ -564,7 +564,7 @@ The overrides in a single `package.json` may for example look like this:
 Caching is used sparingly throughout the Backstage build system. It is always used as a way to squeeze out a little bit of extra performance, rather than requirement to keep things fast. The following is a list of places where optional caching is available:
 
 - **TypeScript** - The default `tsconfig.json` used by Backstage projects has `incremental` set to `true`, which enables local caching of type checking results. It is however generally not recommended in CI, where `yarn tsc:full` is preferred, which sets `--incremental false`.
-- **Linting** - The `backstage-cli repo lint` command has a `--cache` flag that enables caching of successful linting results. This is done at the package level, meaning that if a package has not been changed since the last lint run and it was successful, the linting will be skipped. This is recommended to be used in CI, but not during local development.
+- **Linting** - The `backstage-cli repo lint` command has a `--successCache` flag that enables caching of successful linting results. This is done at the package level, meaning that if a package has not been changed since the last lint run and it was successful, the linting will be skipped. This is recommended to be used in CI, but not during local development.
 - **Webpack** - It is possible to enable experimental caching of frontend package builds using the `BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE` environment variable. This will enable the Webpack filesystem cache.
 
 ### Debugging Jest Tests

packages/cli/cli-report.md

@@ -446,7 +446,8 @@ Usage: backstage-cli repo lint [options]
 Options:
   --format <format>
   --since <ref>
-  --cache [path]
+  --successCache
+  --successCacheDir <path>
   --fix
   -h, --help
 ```

packages/cli/src/commands/index.ts

@@ -62,8 +62,12 @@ export function registerRepoCommand(program: Command) {
       'Only lint packages that changed since the specified ref',
     )
     .option(
-      '--cache [path]',
-      'Enable caching, storing it in node_modules/.cache/backstage-cli by default, or at the provided directory',
+      '--successCache',
+      'Enable success caching, which skips running tests for unchanged packages that were successful in the previous run',
+    )
+    .option(
+      '--successCacheDir <path>',
+      'Set the success cache location, (default: node_modules/.cache/backstage-cli)',
     )
     .option('--fix', 'Attempt to automatically fix violations')
     .action(lazy(() => import('./repo/lint').then(m => m.command)));

packages/cli/src/commands/repo/lint.ts

@@ -63,11 +63,10 @@ async function writeCache(dir: string, cache: Cache) {
 export async function command(opts: OptionValues, cmd: Command): Promise<void> {
   let packages = await PackageGraph.listTargetPackages();
 
-  const cacheDir =
-    opts.cache === true
-      ? paths.resolveTargetRoot('node_modules/.cache/backstage-cli')
-      : opts.cache;
-  const cacheContext = cacheDir
+  const cacheDir = resolvePath(
+    opts.successCacheDir ?? 'node_modules/.cache/backstage-cli',
+  );
+  const cacheContext = opts.successCache
     ? {
         cache: await readCache(cacheDir),
         lockfile: await Lockfile.load(paths.resolveTargetRoot('yarn.lock')),
@@ -136,7 +135,7 @@ export async function command(opts: OptionValues, cmd: Command): Promise<void> {
     workerData: {
       fix: Boolean(opts.fix),
       format: opts.format as string | undefined,
-      shouldCache: Boolean(cacheDir),
+      shouldCache: Boolean(cacheContext),
       successCache: cacheContext?.cache,
     },
     workerFactory: async ({ fix, format, shouldCache, successCache }) => {
@@ -252,7 +251,7 @@ export async function command(opts: OptionValues, cmd: Command): Promise<void> {
     }
   }
 
-  if (cacheDir) {
+  if (cacheContext) {
     await writeCache(cacheDir, outputSuccessCache);
   }