feat: improve --list-csv and --list output

- allowFailure: show exit codes [42,137] instead of just true/false
- needs: empty when not specified, [] when explicitly empty
- description column: only shown when at least one job uses it
- Skip 'id -u' on Windows to avoid error message

Closes #1809

Author: Benoit COUETIL

.gitignore

@@ -9,4 +9,6 @@
 /.gitlab-ci-local/
 .DS_Store
 .vscode
+.history
+/tmp/
 /.gitlab-ci.yml

README.md

@@ -201,25 +201,28 @@ deploy-job               deploy  never       false          [build-job]
 The command `gitlab-ci-local --list-csv` will output the pipeline jobs as csv formatted list and will also filter all
 jobs which are set
 to `when: never`.
-The description will always be wrapped in quotes (even if there is none) to prevent semicolons in the description
-disturb the csv structure.
 
 ```text
-name;description;stage;when;allow_failure;needs
-test-job;"Run Tests";test;on_success;false;[]
-build-job;"";build;on_success;true;[test-job]
+name;stage;when;allowFailure;needs
+test-job;test;on_success;false;
+build-job;build;on_success;true;[test-job]
+deploy-job;deploy;on_success;[99];
 ```
 
+- **description**: only included when at least one job uses it, always wrapped in quotes to prevent semicolons from disturbing the csv structure
+- **allowFailure**: `true`, `false`, or `[exit_code1,exit_code2]` when specific exit codes are allowed to fail
+- **needs**: empty when not specified (job follows stage ordering), `[]` when explicitly set to no dependencies (job starts immediately)
+
 #### --list-csv-all
 
-Same as `--list-csv-all` but will also print out jobs which are set to `when: never` (directly and implicit e.g. via
+Same as `--list-csv` but will also print out jobs which are set to `when: never` (directly and implicit e.g. via
 rules).
 
 ```text
-name;description;stage;when;allow_failure;needs
-test-job;"Run Tests";test;on_success;false;[]
-build-job;"";build;on_success;true;[test-job]
-deploy-job;"";deploy;never;false;[build-job]
+name;stage;when;allowFailure;needs
+test-job;test;on_success;false;
+build-job;build;on_success;true;[test-job]
+deploy-job;deploy;never;false;
 ```
 
 ## Quirks

src/commander.ts

@@ -210,23 +210,34 @@ export class Commander {
         let stagePadEnd = 5;
         stages.forEach(s => stagePadEnd = Math.max(s.length, stagePadEnd));
 
+        const hasDescriptions = jobs.some(j => j.description !== "");
+
         let descriptionPadEnd = 11;
-        jobs.forEach(j => descriptionPadEnd = Math.max(j.description.length, descriptionPadEnd));
+        if (hasDescriptions) {
+            jobs.forEach(j => descriptionPadEnd = Math.max(j.description.length, descriptionPadEnd));
+        }
 
         const jobNamePad = parser.jobNamePad;
 
         if (!listAll) {
             jobs = jobs.filter(j => j.when !== "never");
         }
 
-        writeStreams.stdout(chalk`{grey ${"name".padEnd(jobNamePad)}  ${"description".padEnd(descriptionPadEnd)}}  `);
+        if (hasDescriptions) {
+            writeStreams.stdout(chalk`{grey ${"name".padEnd(jobNamePad)}  ${"description".padEnd(descriptionPadEnd)}}  `);
+        } else {
+            writeStreams.stdout(chalk`{grey ${"name".padEnd(jobNamePad)}}  `);
+        }
         writeStreams.stdout(chalk`{grey ${"stage".padEnd(stagePadEnd)}  ${"when".padEnd(whenPadEnd)}}  `);
         writeStreams.stdout(chalk`{grey allow_failure  needs}\n`);
 
         const renderLine = (job: Job) => {
             const needs = job.needs?.filter(n => !n.project && !n.pipeline).map(n => n.job);
             const allowFailure = job.allowFailure ? "true " : "false ";
-            let jobLine = chalk`{blueBright ${job.name.padEnd(jobNamePad)}}  ${job.description.padEnd(descriptionPadEnd)}  `;
+            let jobLine = chalk`{blueBright ${job.name.padEnd(jobNamePad)}}  `;
+            if (hasDescriptions) {
+                jobLine += `${job.description.padEnd(descriptionPadEnd)}  `;
+            }
             jobLine += chalk`{yellow ${job.stage.padEnd(stagePadEnd)}}  ${job.when.padEnd(whenPadEnd)}  ${allowFailure.padEnd(11)}`;
             if (needs) {
                 jobLine += chalk`    [{blueBright ${needs}}]`;
@@ -267,10 +278,23 @@ export class Commander {
             jobs = jobs.filter(j => j.when !== "never");
         }
 
-        writeStreams.stdout("name;description;stage;when;allowFailure;needs\n");
+        const hasDescriptions = jobs.some(j => j.description !== "");
+
+        const header = ["name", hasDescriptions ? "description" : null, "stage", "when", "allowFailure", "needs"].filter(Boolean).join(";");
+        writeStreams.stdout(`${header}\n`);
+
         jobs.forEach((job) => {
-            const needs = job.needs?.filter(n => !n.project && !n.pipeline).map(n => n.job).join(",") ?? [];
-            writeStreams.stdout(`${job.name};"${job.description}";${job.stage};${job.when};${job.allowFailure ? "true" : "false"};[${needs}]\n`);
+            const needs = job.needs === null ? "" : `[${job.needs.filter(n => !n.project && !n.pipeline).map(n => n.job).join(",")}]`;
+            let allowFailure: string;
+            if (typeof job.allowFailure === "object") {
+                const codes = Array.isArray(job.allowFailure.exit_codes) ? job.allowFailure.exit_codes : [job.allowFailure.exit_codes];
+                allowFailure = `[${codes.join(",")}]`;
+            } else {
+                allowFailure = job.allowFailure ? "true" : "false";
+            }
+
+            const row = [job.name, hasDescriptions ? `"${job.description}"` : null, job.stage, job.when, allowFailure, needs].filter(v => v !== null).join(";");
+            writeStreams.stdout(`${row}\n`);
         });
     }
 

src/git-data.ts

@@ -172,12 +172,19 @@ export class GitData {
         });
         promises.push(gitEmailPromise);
 
-        const osUidPromise = Utils.spawn(["id", "-u"], cwd).then(({stdout}) => {
-            this.user.GITLAB_USER_ID = stdout.trimEnd();
-        }).catch((e) => {
-            writeStreams.stderr(chalk`{yellow Using fallback linux user id}\n`);
-            writeStreams.stderr(chalk`{yellow   ${e.message}\n}`);
-        });
+        const osUidPromise = (async () => {
+            if (process.platform === "win32") {
+                // GITLAB_USER_ID is a Unix UID concept; keep default on Windows
+                return;
+            }
+            try {
+                const {stdout} = await Utils.spawn(["id", "-u"], cwd);
+                this.user.GITLAB_USER_ID = stdout.trimEnd();
+            } catch (e: any) {
+                writeStreams.stderr(chalk`{yellow Using fallback linux user id}\n`);
+                writeStreams.stderr(chalk`{yellow   ${e.message}\n}`);
+            }
+        })();
         promises.push(osUidPromise);
 
         await Promise.all(promises);

tests/test-cases/list-case/integration.test.ts

@@ -23,3 +23,21 @@ test.concurrent("list-case --list", async () => {
     ];
     expect(writeStreams.stdoutLines).toEqual(expect.arrayContaining(expected));
 });
+
+test.concurrent("list-case --list no description column when unused", async () => {
+    const writeStreams = new WriteStreamsMock();
+    await handler({
+        cwd: "tests/test-cases/list-csv-case/",
+        file: ".gitlab-ci-no-description.yml",
+        list: true,
+        stateDir: ".gitlab-ci-local-list-case-no-description",
+    }, writeStreams);
+
+    const expected = [
+        chalk`{grey ${"name".padEnd(9)}}  {grey stage  when      }  {grey allow_failure  needs}`,
+        chalk`{blueBright ${"test-job".padEnd(9)}}  {yellow test }  on_success  false      `,
+        chalk`{blueBright build-job}  {yellow build}  on_success  true           [{blueBright test-job}]`,
+    ];
+    expect(writeStreams.stdoutLines).toEqual(expect.arrayContaining(expected));
+    expect(writeStreams.stdoutLines.join("\n")).not.toContain("description");
+});

tests/test-cases/list-csv-case/.gitlab-ci-no-description.yml

@@ -0,0 +1,14 @@
+---
+stages: [test, build]
+
+test-job:
+  stage: test
+  script:
+    - echo test
+
+build-job:
+  stage: build
+  needs: [test-job]
+  allow_failure: true
+  script:
+    - echo build

tests/test-cases/list-csv-case/.gitlab-ci.yml

@@ -1,5 +1,5 @@
 ---
-stages: [test, build]
+stages: [test, build, deploy]
 
 # @Description Run Tests
 test-job:
@@ -14,3 +14,18 @@ build-job:
   allow_failure: true
   script:
     - 'echo "Build something"'
+
+exit-codes-job:
+  stage: build
+  needs: []
+  allow_failure:
+    exit_codes: [42, 137]
+  script:
+    - 'echo "Exit codes"'
+
+deploy-job:
+  stage: deploy
+  allow_failure:
+    exit_codes: 1
+  script:
+    - 'echo "Deploy"'

tests/test-cases/list-csv-case/integration.test.ts

@@ -1,7 +1,7 @@
-import {WriteStreamsMock} from "../../../src/write-streams.js";
-import {handler} from "../../../src/handler.js";
-import {initSpawnSpy} from "../../mocks/utils.mock.js";
-import {WhenStatics} from "../../mocks/when-statics.js";
+import { WriteStreamsMock } from "../../../src/write-streams.js";
+import { handler } from "../../../src/handler.js";
+import { initSpawnSpy } from "../../mocks/utils.mock.js";
+import { WhenStatics } from "../../mocks/when-statics.js";
 
 beforeAll(() => {
     initSpawnSpy(WhenStatics.all);
@@ -17,8 +17,10 @@ test.concurrent("list-csv-case --list-csv", async () => {
 
     const expected = [
         "name;description;stage;when;allowFailure;needs",
-        "test-job;\"Run Tests\";test;on_success;false;[]",
+        "test-job;\"Run Tests\";test;on_success;false;",
         "build-job;\"\";build;on_success;true;[test-job]",
+        "exit-codes-job;\"\";build;on_success;[42,137];[]",
+        "deploy-job;\"\";deploy;on_success;[1];",
     ];
     expect(writeStreams.stdoutLines).toEqual(expect.arrayContaining(expected));
 });
@@ -35,9 +37,28 @@ test.concurrent("list-csv-case --list-csv colon should add process descriptors w
 
     const expected = [
         "name;description;stage;when;allowFailure;needs",
-        "test-job;\"Run;Tests\";test;on_success;false;[]",
+        "test-job;\"Run;Tests\";test;on_success;false;",
         "build-job;\"\";build;on_success;true;[test-job]",
     ];
     expect(writeStreams.stdoutLines).toEqual(expect.arrayContaining(expected));
 });
 
+
+test.concurrent("list-csv-case --list-csv no description column when unused", async () => {
+    const writeStreams = new WriteStreamsMock();
+    await handler({
+        cwd: "tests/test-cases/list-csv-case/",
+        file: ".gitlab-ci-no-description.yml",
+        listCsv: true,
+        stateDir: ".gitlab-ci-local-list-csv-case-list-csv-no-description",
+    }, writeStreams);
+
+    const expected = [
+        "name;stage;when;allowFailure;needs",
+        "test-job;test;on_success;false;",
+        "build-job;build;on_success;true;[test-job]",
+    ];
+    expect(writeStreams.stdoutLines).toEqual(expect.arrayContaining(expected));
+    expect(writeStreams.stdoutLines.join("\n")).not.toContain("description");
+});
+