fix(cli): lint with multiple api files results in invalid output

.changeset/empty-cities-sink.md

@@ -0,0 +1,5 @@
+---
+'@redocly/cli': patch
+---
+
+Fixed `lint --format=checkstyle` to produce a single combined XML document when multiple APIs are passed to the command, instead of concatenated per-file documents.

docs/@v2/commands/lint.md

@@ -130,11 +130,7 @@ However, if you have a configuration file, but it doesn't include any rules or e
 ### Specify output format
 
 The standard `codeframe` output format works well in most situations, but `redocly` can also produce output to integrate with other tools.
-
-{% admonition type="warning" name="Lint one API at a time" %}
-Some formats, such as `checkstyle` or `json`, don't work well when multiple APIs are linted in a single command.
-Try linting each API separately when you pass the command output to another tool.
-{% /admonition %}
+When multiple APIs are linted in a single command, the `checkstyle` format produces a single combined XML document with one `<file>` element per API.
 
 #### Codeframe (default)
 

packages/cli/src/__tests__/commands/lint.test.ts

@@ -52,7 +52,7 @@ describe('handleLint', () => {
       return {
         ...actual,
         lint: vi.fn(async (): Promise<NormalizedProblem[]> => []),
-        getTotals: vi.fn(() => ({ errors: 0 }) as Totals),
+        getTotals: vi.fn(() => ({ errors: 0, warnings: 0, ignored: 0 }) as Totals),
         doesYamlFileExist: vi.fn((path) => path === 'redocly.yaml'),
         logger: {
           info: vi.fn(),
@@ -211,13 +211,29 @@ describe('handleLint', () => {
       expect(formatProblems).toHaveBeenCalledWith(['problem'], {
         format: 'stylish',
         maxProblems: 2,
-        totals: { errors: 0 },
+        totals: { errors: 0, warnings: 0, ignored: 0 },
         version: '2.0.0',
         command: 'lint',
       });
       expect(getExecutionTime).toHaveBeenCalledWith(42);
     });
 
+    it('should aggregate problems from multiple APIs into a single formatProblems call', async () => {
+      vi.mocked(lint)
+        .mockResolvedValueOnce(['problem-a'] as any)
+        .mockResolvedValueOnce(['problem-b'] as any);
+      await commandWrapper(handleLint)({
+        ...argvMock,
+        apis: ['a.yaml', 'b.yaml'],
+        format: 'checkstyle',
+      });
+      expect(formatProblems).toHaveBeenCalledTimes(1);
+      expect(formatProblems).toHaveBeenCalledWith(
+        ['problem-a', 'problem-b'],
+        expect.objectContaining({ format: 'checkstyle' })
+      );
+    });
+
     it('should catch error in handleError if something fails', async () => {
       vi.mocked(lint).mockRejectedValueOnce('error');
       await commandWrapper(handleLint)(argvMock);

packages/cli/src/commands/lint.ts

@@ -49,6 +49,8 @@ export async function handleLint({
 
   const totals: Totals = { errors: 0, warnings: 0, ignored: 0 };
   let totalIgnored = 0;
+  const isCheckstyle = argv.format === 'checkstyle';
+  const checkstyleResults: Awaited<ReturnType<typeof lint>> = [];
 
   // TODO: use shared externalRef resolver, blocked by preprocessors now as they can mutate documents
   for (const { path, alias } of apis) {
@@ -93,6 +95,8 @@ export async function handleLint({
           config.addIgnore(m);
           totalIgnored++;
         }
+      } else if (isCheckstyle) {
+        checkstyleResults.push(...results);
       } else {
         formatProblems(results, {
           format: argv.format,
@@ -110,6 +114,16 @@ export async function handleLint({
     }
   }
 
+  if (isCheckstyle && !argv['generate-ignore-file']) {
+    formatProblems(checkstyleResults, {
+      format: argv.format,
+      maxProblems: argv['max-problems'],
+      totals,
+      version,
+      command: 'lint',
+    });
+  }
+
   if (argv['generate-ignore-file']) {
     config.saveIgnore();
     logger.info(`Explicitly ignored ${totalIgnored} ${pluralize('problem', totalIgnored)}.\n\n`);