address review: derive constant, add invariant docs, exact assertion, e2e test

- MAX_FILENAME_LENGTH now shows derivation (255 - 17) instead of magic 238
- Added invariant comment: \w without /u guarantees ASCII, so .length == bytes
- Noted why we hash jobName not encoded (encoding isn't injective)
- Changed toContain('Lw') to toBe('jobLwname') for exact assertion
- Added tests/test-cases/parallel-matrix-long-name/ integration fixture
  that exercises the actual crash path end-to-end (regression guard for #1862)

Author: Gyan Ranjan A

src/utils.ts

@@ -50,9 +50,13 @@ export class Utils {
         return url.replace(/^https:\/\//g, "").replace(/^http:\/\//g, "");
     }
 
-    static readonly MAX_FILENAME_LENGTH = 238; // 255 (NAME_MAX) - 17 (longest suffix: "gcl-" + "-" + jobId + "-build")
+    // gcl-${safeJobName}-${jobId}-build → wrapper is 17 chars (jobId max 6 digits)
+    static readonly MAX_FILENAME_LENGTH = 255 - 17; // NAME_MAX (bytes) - wrapper
 
     static safeDockerString (jobName: string) {
+        // INVARIANT: \w without /u is ASCII-only ([A-Za-z0-9_]), so `encoded` is pure ASCII
+        // and .length === byte length. NAME_MAX is a byte limit — adding /u would break this.
+        // We hash `jobName` (not `encoded`) because base64url encoding isn't injective.
         const encoded = jobName.replace(/[^\w-]+/g, (match) => {
             return base64url.encode(match);
         });

tests/test-cases/parallel-matrix-long-name/.gitignore

@@ -0,0 +1 @@
+.gitlab-ci-local-*

tests/test-cases/parallel-matrix-long-name/.gitlab-ci.yml

@@ -0,0 +1,10 @@
+---
+build-job:
+  stage: build
+  script:
+    - echo "APP='${APP}' $CI_NODE_INDEX/$CI_NODE_TOTAL"
+  parallel:
+    matrix:
+      - APP:
+          - "my-app-controller,My app controller to be used as reference for development teams,python311,controller,common,controller/setup.py,controller/setup_c.py,controller/setup_n.py,controller/tests/**/*,controller/coverage/*,controller/build/**/*,controller/coverage/coverage-unit.xml,75,true"
+          - short

tests/test-cases/parallel-matrix-long-name/integration.test.ts

@@ -0,0 +1,17 @@
+import {WriteStreamsMock} from "../../../src/write-streams.js";
+import {handler} from "../../../src/handler.js";
+
+test.concurrent("parallel-matrix-long-name - completes without ENAMETOOLONG", async () => {
+    const writeStreams = new WriteStreamsMock();
+    await handler({
+        cwd: "tests/test-cases/parallel-matrix-long-name",
+        shellIsolation: true,
+        stateDir: ".gitlab-ci-local-parallel-matrix-long-name",
+    }, writeStreams);
+
+    // Both matrix entries must complete — the long one would crash with ENAMETOOLONG before the fix
+    const passing = writeStreams.stdoutLines.filter(l => l.includes(" PASS "));
+    expect(passing.length).toBe(2);
+    expect(writeStreams.stdoutLines.some(l => l.includes("build-job: [short]"))).toBe(true);
+    expect(writeStreams.stdoutLines.some(l => l.includes("build-job: [my-app-controller,"))).toBe(true);
+});

tests/utils.test.ts

@@ -275,7 +275,7 @@ describe("safeDockerString", () => {
 
     it("should encode non-alphanumeric characters", () => {
         const result = Utils.safeDockerString("job/name");
-        expect(result).toContain("Lw"); // '/' encodes to base64url
+        expect(result).toBe("jobLwname"); // '/' → 'Lw'
     });
 
     it("should truncate and hash when encoded name exceeds MAX_FILENAME_LENGTH", () => {