Inline deprecation warnings and fix package lint parameters

Remove the central warnDeprecatedFlags helper and replace with
module-specific deprecation checks at each call site. This avoids
cross-module dependencies and makes the deprecated flag mappings
explicit where they are consumed.

Also fix buildWorkspace.ts to emit the deprecation warning during
flag normalization (where the old flags are actually intercepted),
and add positional parameter declaration to package lint so that
directories show in help output.

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

packages/cli/cli-report.md

@@ -273,7 +273,7 @@ Options:
 ### `backstage-cli package lint`
 
 ```
-Usage: backstage-cli package lint
+Usage: backstage-cli package lint [directories...]
 
 Options:
   --fix

packages/cli/src/lib/warnDeprecatedFlags.ts

@@ -1,38 +0,0 @@
-/*
- * Copyright 2026 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-/**
- * Scans args for deprecated camelCase flag names and logs a warning for each
- * match. Since type-flag accepts both camelCase and kebab-case, the old names
- * still work — this just nudges users toward the new spelling.
- */
-export function warnDeprecatedFlags(
-  args: string[],
-  flags: Record<string, unknown>,
-) {
-  for (const key of Object.keys(flags)) {
-    const kebab = key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`);
-    if (kebab === key) {
-      continue;
-    }
-    const deprecated = `--${key}`;
-    if (args.some(a => a === deprecated || a.startsWith(`${deprecated}=`))) {
-      process.stderr.write(
-        `DEPRECATION WARNING: ${deprecated} has been renamed to --${kebab}\n`,
-      );
-    }
-  }
-}

packages/cli/src/modules/build/commands/buildWorkspace.ts

@@ -17,33 +17,22 @@
 import fs from 'fs-extra';
 import { cli } from 'cleye';
 import { createDistWorkspace } from '../lib/packager';
-import { warnDeprecatedFlags } from '../../../lib/warnDeprecatedFlags';
 import type { CommandContext } from '../../../wiring/types';
 
 export default async ({ args, info }: CommandContext) => {
   // Support legacy --alwaysYarnPack and --alwaysPack aliases (including =value form)
   const normalizedArgs = args.map(a => {
     for (const old of ['--alwaysYarnPack', '--alwaysPack']) {
-      if (a === old) {
-        return '--always-pack';
-      }
-      if (a.startsWith(`${old}=`)) {
+      if (a === old || a.startsWith(`${old}=`)) {
+        process.stderr.write(
+          `DEPRECATION WARNING: ${old} has been renamed to --always-pack\n`,
+        );
         return `--always-pack${a.substring(old.length)}`;
       }
     }
     return a;
   });
 
-  const flagDefs = {
-    alwaysPack: {
-      type: Boolean,
-      description:
-        'Force workspace output to be a result of running `yarn pack` on each package (warning: very slow)',
-    },
-  };
-
-  warnDeprecatedFlags(args, flagDefs);
-
   const {
     flags: { alwaysPack },
     _: positionals,
@@ -51,7 +40,13 @@ export default async ({ args, info }: CommandContext) => {
     {
       help: { ...info, usage: `${info.usage} <workspace-dir> [packages...]` },
       parameters: ['<workspace-dir>', '[packages...]'],
-      flags: flagDefs,
+      flags: {
+        alwaysPack: {
+          type: Boolean,
+          description:
+            'Force workspace output to be a result of running `yarn pack` on each package (warning: very slow)',
+        },
+      },
     },
     undefined,
     normalizedArgs,

packages/cli/src/modules/lint/commands/package/lint.ts

@@ -26,7 +26,8 @@ export default async ({ args, info }: CommandContext) => {
     _: directories,
   } = cli(
     {
-      help: info,
+      help: { ...info, usage: `${info.usage} [directories...]` },
+      parameters: ['[directories...]'],
       flags: {
         fix: {
           type: Boolean,

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

@@ -29,7 +29,6 @@ import {
 import { targetPaths } from '@backstage/cli-common';
 
 import { createScriptOptionsParser } from '../../lib/optionsParser';
-import { warnDeprecatedFlags } from '../../../../lib/warnDeprecatedFlags';
 import type { CommandContext } from '../../../../wiring/types';
 
 function depCount(pkg: BackstagePackageJson) {
@@ -76,7 +75,18 @@ export default async ({ args, info }: CommandContext) => {
     },
   };
 
-  warnDeprecatedFlags(args, flagDefs);
+  for (const [old, replacement] of Object.entries({
+    '--outputFile': '--output-file',
+    '--successCache': '--success-cache',
+    '--successCacheDir': '--success-cache-dir',
+    '--maxWarnings': '--max-warnings',
+  })) {
+    if (args.some(a => a === old || a.startsWith(`${old}=`))) {
+      process.stderr.write(
+        `DEPRECATION WARNING: ${old} has been renamed to ${replacement}\n`,
+      );
+    }
+  }
 
   const {
     flags: {

packages/cli/src/modules/new/commands/new.ts

@@ -16,7 +16,6 @@
 
 import { cli } from 'cleye';
 import { createNewPackage } from '../lib/createNewPackage';
-import { warnDeprecatedFlags } from '../../../lib/warnDeprecatedFlags';
 import type { CommandContext } from '../../../wiring/types';
 
 export default async ({ args, info }: CommandContext) => {
@@ -58,7 +57,17 @@ export default async ({ args, info }: CommandContext) => {
     },
   };
 
-  warnDeprecatedFlags(args, flagDefs);
+  for (const [old, replacement] of Object.entries({
+    '--skipInstall': '--skip-install',
+    '--npmRegistry': '--npm-registry',
+    '--baseVersion': '--base-version',
+  })) {
+    if (args.some(a => a === old || a.startsWith(`${old}=`))) {
+      process.stderr.write(
+        `DEPRECATION WARNING: ${old} has been renamed to ${replacement}\n`,
+      );
+    }
+  }
 
   const {
     flags: {

packages/cli/src/modules/test/commands/repo/test.ts

@@ -31,7 +31,6 @@ import {
   findOwnPaths,
   isChildPath,
 } from '@backstage/cli-common';
-import { warnDeprecatedFlags } from '../../../../lib/warnDeprecatedFlags';
 import type { CommandContext } from '../../../../wiring/types';
 
 type JestProject = {
@@ -156,7 +155,17 @@ export default async ({ args, info }: CommandContext) => {
     },
   };
 
-  warnDeprecatedFlags(args, flagDefs);
+  for (const [old, replacement] of Object.entries({
+    '--successCache': '--success-cache',
+    '--successCacheDir': '--success-cache-dir',
+    '--jestHelp': '--jest-help',
+  })) {
+    if (args.some(a => a === old || a.startsWith(`${old}=`))) {
+      process.stderr.write(
+        `DEPRECATION WARNING: ${old} has been renamed to ${replacement}\n`,
+      );
+    }
+  }
 
   const { flags: opts } = cli(
     {