@elench/testkit 0.1.44 → 0.1.45

package/README.md

@@ -161,12 +161,29 @@ If `reporting.knownFailuresFile` is configured, `testkit` enriches
 - per-file `triage` metadata (issue, classification, description)
 - top-level `triageSummary` counts for known vs untriaged failures
 
+Known-failure entry authoring uses this contract:
+
+- `title`
+  - exact issue-tracker title for the linked issue
+  - shared issues may reuse the same title across multiple local entries
+- `description`
+  - product-local bug slice or route-family summary
+  - this is where file-specific nuance belongs
+- `whyFailing`
+  - underlying technical cause of the failure
+
 If `reporting.issueValidation` is also configured, `testkit` validates known-failure
 issue references against GitHub and adds top-level `knownFailuresIssueValidation`
 data to the run/status artifacts. The most important stale-triage signal is:
 
 - a known-failure test still fails, but the linked GitHub issue is closed
 
+In `mode: "error"`, exact GitHub metadata drift is also treated as a validation
+failure:
+
+- title does not match the linked issue title
+- local open/closed state does not match the linked issue state
+
 ## Authoring
 
 HTTP suites:

package/lib/known-failures/github.mjs

@@ -436,7 +436,7 @@ function buildIssueValidationEntry({ entry, observed, issueData }) {
   if (issueData?.exists && issueData.title && issueData.title !== entry.title) {
     findings.push({
       code: "title_mismatch",
-      severity: "warning",
+      severity: "error",
       message: `Known failure ${entry.id} title does not match issue #${entry.issue.number}`,
     });
   }
@@ -444,7 +444,7 @@ function buildIssueValidationEntry({ entry, observed, issueData }) {
   if (issueData?.exists && normalizedIssueState && normalizedIssueState !== entry.state) {
     findings.push({
       code: "state_mismatch",
-      severity: "warning",
+      severity: "error",
       message: `Known failure ${entry.id} state ${entry.state} does not match issue #${entry.issue.number} state ${normalizedIssueState}`,
     });
   }

package/lib/known-failures/github.test.mjs

@@ -25,7 +25,7 @@ describe("known failures GitHub validation", () => {
     expect(parseGitHubRepoSlug("https://gitlab.com/acme/repo.git")).toBe(null);
   });
 
-  it("flags closed issues that still reproduce and title mismatches", async () => {
+  it("fails validation for title/state drift and closed issues that still reproduce", async () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-gh-issues-"));
     tempDirs.push(tempDir);
     const document = normalizeKnownFailuresDocument({
@@ -98,11 +98,114 @@ describe("known failures GitHub validation", () => {
 
     expect(result.summary.byCode.closed_but_failing).toBe(1);
     expect(result.summary.byCode.title_mismatch).toBe(1);
+    expect(result.summary.byCode.state_mismatch).toBe(1);
     expect(result.summary.errors).toBeGreaterThan(0);
     expect(result.entries[0].status).toBe("closed_but_failing");
     expect(shouldFailKnownFailureIssueValidation(result)).toBe(true);
   });
 
+  it("allows multiple local entries to share one issue title while keeping distinct descriptions", async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-gh-shared-title-"));
+    tempDirs.push(tempDir);
+    const document = normalizeKnownFailuresDocument({
+      schemaVersion: 1,
+      issueRepo: "acme/repo",
+      entries: [
+        {
+          id: "route-a-invalid-uuid",
+          title: "UUID path params reach Postgres and return 500 instead of 400",
+          classification: "product_bug",
+          state: "open",
+          issue: {
+            repo: "acme/repo",
+            number: 77,
+            url: "https://github.com/acme/repo/issues/77",
+          },
+          description: "Route A leaks Postgres UUID parse errors on malformed ids.",
+          whyFailing: "Route A is missing UUID param validation.",
+          lastReviewedAt: "2026-04-27",
+          matches: [
+            {
+              service: "api",
+              type: "int",
+              path: "src/api/routes/__testkit__/route-a.int.testkit.ts",
+            },
+          ],
+        },
+        {
+          id: "route-b-invalid-uuid",
+          title: "UUID path params reach Postgres and return 500 instead of 400",
+          classification: "product_bug",
+          state: "open",
+          issue: {
+            repo: "acme/repo",
+            number: 77,
+            url: "https://github.com/acme/repo/issues/77",
+          },
+          description: "Route B leaks Postgres UUID parse errors on malformed ids.",
+          whyFailing: "Route B is missing UUID param validation.",
+          lastReviewedAt: "2026-04-27",
+          matches: [
+            {
+              service: "api",
+              type: "int",
+              path: "src/api/routes/__testkit__/route-b.int.testkit.ts",
+            },
+          ],
+        },
+      ],
+    });
+
+    const result = await validateKnownFailureIssues({
+      productDir: tempDir,
+      document,
+      statusArtifact: {
+        tests: [
+          {
+            service: "api",
+            type: "int",
+            path: "src/api/routes/__testkit__/route-a.int.testkit.ts",
+            status: "failed",
+          },
+          {
+            service: "api",
+            type: "int",
+            path: "src/api/routes/__testkit__/route-b.int.testkit.ts",
+            status: "failed",
+          },
+        ],
+      },
+      config: {
+        provider: "github",
+        mode: "error",
+      },
+      transport: {
+        async fetchRepoIssues(repo, numbers) {
+          const map = new Map();
+          map.set(numbers[0], {
+            repo,
+            number: numbers[0],
+            exists: true,
+            title: "UUID path params reach Postgres and return 500 instead of 400",
+            state: "OPEN",
+            url: `https://github.com/${repo}/issues/${numbers[0]}`,
+            checkedAt: "2026-04-27T00:00:00.000Z",
+            source: "github",
+          });
+          return map;
+        },
+      },
+    });
+
+    expect(result.summary.byCode.title_mismatch).toBeUndefined();
+    expect(result.summary.errors).toBe(0);
+    expect(result.entries).toHaveLength(2);
+    expect(result.entries[0].findings).toEqual([]);
+    expect(result.entries[1].findings).toEqual([]);
+    expect(result.entries[0].status).toBe("open_and_failing");
+    expect(result.entries[1].status).toBe("open_and_failing");
+  });
+
   it("warns when an open issue is not reproduced", async () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-gh-open-"));
     tempDirs.push(tempDir);

package/lib/known-failures/index.d.ts

@@ -23,11 +23,14 @@ export interface KnownFailureMatch {
 
 export interface KnownFailureEntry {
   id: string;
+  /** Exact issue-tracker title for the linked issue. */
   title: string;
   classification: KnownFailureClassification;
   state: KnownFailureState;
   issue: KnownFailureIssueRef;
+  /** Product-local bug slice or route-family summary. */
   description: string;
+  /** Underlying technical cause of the failure. */
   whyFailing: string;
   lastReviewedAt: string;
   matches: KnownFailureMatch[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",