fix(issues): address area-label review findings

Omit Documentation Area→kind collision, restrict heuristics to semantic
sections, feed translation text into area detection, and update the
issue-quality workflow invariant test for the backfill guard.

Author: Wibias

.github/scripts/issue-quality.cjs

@@ -316,12 +316,31 @@ const AREA_FIELD_TO_LABELS = {
   "service lifecycle": ["service"],
   "service lifecycle (config injection)": ["service"],
   "platform (windows / macos / linux)": ["platform"],
-  documentation: ["documentation"],
+  // Do not map to kind label `documentation` — that collides with labelBasedKind
+  // when a feature/bug form picks Area: Documentation. Docs form already seeds
+  // the kind label; Area selection alone does not add an area tag.
+  documentation: [],
   // No dedicated label; heuristics still run in detectAreaLabels.
   "multiple areas": [],
   other: [],
 };
 
+/** Body headings used for area heuristics (excludes Environment / OS metadata). */
+const AREA_HEURISTIC_BODY_HEADINGS = [
+  "Summary",
+  "Reproduction",
+  "What are you trying to accomplish?",
+  "What prevents this today?",
+  "What should OpenCodex do?",
+  "Example usage or interface",
+  "Current behaviour",
+  "Expected behaviour",
+  "Minimal redacted request or reproduction",
+  "What is wrong or missing?",
+  "Documentation problem type",
+  "Documentation location",
+];
+
 /**
  * Heuristic rules. `scope: "title"` avoids false hits from template Environment /
  * OS fields in the body; `scope: "full"` is for distinctive technical tokens.
@@ -431,11 +450,28 @@ function mapAreaFieldToLabels(areaText) {
   return AREA_FIELD_TO_LABELS[key] ? [...AREA_FIELD_TO_LABELS[key]] : [];
 }
 
+/**
+ * Build heuristic text from title-relevant semantic sections only — never from
+ * Operating system / Version / Checks metadata that every template includes.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+function bodyForAreaHeuristics(body) {
+  if (typeof body !== "string" || !body.trim()) return "";
+  const parts = [];
+  for (const heading of AREA_HEURISTIC_BODY_HEADINGS) {
+    const section = extractSection(body, heading);
+    if (section) parts.push(section);
+  }
+  return parts.join("\n\n");
+}
+
 /**
  * Conservative title/body heuristics for orthogonal area labels.
  *
  * @param {string} title
- * @param {string} body
+ * @param {string} body semantic body text (already filtered)
  * @returns {string[]}
  */
 function heuristicAreaLabels(title, body) {
@@ -456,17 +492,25 @@ function heuristicAreaLabels(title, body) {
  * Detect additive product-area labels from Area field, form defaults, and
  * title/body heuristics. Never invents per-provider labels.
  *
- * @param {{ title?: string, body?: string, labels?: string[] }} issue
+ * @param {{
+ *   title?: string,
+ *   body?: string,
+ *   labels?: string[],
+ *   heuristicBody?: string,
+ * }} issue
+ *   `body` is the source form (for Area / provider headings).
+ *   `heuristicBody` may include English translation text for heuristics only.
  * @returns {string[]}
  */
 function detectAreaLabels(issue) {
   const title = typeof issue?.title === "string" ? issue.title : "";
   const body = typeof issue?.body === "string" ? issue.body : "";
   const labels = Array.isArray(issue?.labels) ? issue.labels : [];
+  const heuristicSource = typeof issue?.heuristicBody === "string" ? issue.heuristicBody : body;
 
   const areaSection = extractSection(body, "Area");
   const fromArea = mapAreaFieldToLabels(areaSection);
-  const fromHeur = heuristicAreaLabels(title, body);
+  const fromHeur = heuristicAreaLabels(title, bodyForAreaHeuristics(heuristicSource));
   const fromForm = [];
   if (labels.includes("provider-compatibility")) fromForm.push("provider");
   // Provider-compat form uses this heading instead of Area.
@@ -478,8 +522,7 @@ function detectAreaLabels(issue) {
   const out = [];
   for (const label of [...fromArea, ...fromForm, ...fromHeur]) {
     if (!label || seen.has(label)) continue;
-    // `documentation` is a kind label and also an Area mapping target.
-    if (label !== "documentation" && !AREA_LABELS[label]) continue;
+    if (!AREA_LABELS[label]) continue;
     seen.add(label);
     out.push(label);
   }
@@ -1183,6 +1226,7 @@ module.exports = {
   AREA_LABELS,
   AREA_FIELD_TO_LABELS,
   mapAreaFieldToLabels,
+  bodyForAreaHeuristics,
   heuristicAreaLabels,
   detectAreaLabels,
   hasSubstantialStructuredContent,

.github/scripts/issue-quality.test.cjs

@@ -1672,7 +1672,7 @@ describe("mapAreaFieldToLabels", () => {
     assert.deepEqual(mapAreaFieldToLabels("Installation or packaging"), ["install"]);
     assert.deepEqual(mapAreaFieldToLabels("Service lifecycle"), ["service"]);
     assert.deepEqual(mapAreaFieldToLabels("Platform (Windows / macOS / Linux)"), ["platform"]);
-    assert.deepEqual(mapAreaFieldToLabels("Documentation"), ["documentation"]);
+    assert.deepEqual(mapAreaFieldToLabels("Documentation"), []);
   });
 
   it("maps legacy Service lifecycle wording and ignores Other / Multiple areas", () => {
@@ -1749,13 +1749,47 @@ describe("detectAreaLabels", () => {
     assert.equal(labels.includes("windows"), false);
   });
 
-  it("maps Documentation Area to documentation and does not invent docs", () => {
+  it("does not map Documentation Area onto the documentation kind label", () => {
     const labels = detectAreaLabels({
       title: "Codex Auth UI/docs conflate usage-based switching",
       body: ["### Area", "Documentation", "### Summary", "Docs misdefine new session."].join("\n"),
-      labels: [],
+      labels: ["enhancement"],
     });
-    assert.ok(labels.includes("documentation"));
+    assert.equal(labels.includes("documentation"), false);
     assert.equal(labels.includes("docs"), false);
   });
+
+  it("ignores Operating system metadata for platform heuristics", () => {
+    const labels = detectAreaLabels({
+      title: "Dashboard shows empty providers tab",
+      body: [
+        "### Area",
+        "Dashboard",
+        "### Summary",
+        "Providers tab is blank after login.",
+        "### Operating system",
+        "Windows 11",
+        "### Reproduction",
+        "1. Open the dashboard",
+      ].join("\n"),
+      labels: ["bug"],
+    });
+    assert.ok(labels.includes("gui"));
+    assert.equal(labels.includes("platform"), false);
+  });
+
+  it("uses heuristicBody translation text when Area is Other", () => {
+    const labels = detectAreaLabels({
+      title: "问题报告",
+      body: ["### Area", "Other", "### Summary", "原始描述"].join("\n"),
+      heuristicBody: [
+        "### Area",
+        "Other",
+        "### Summary",
+        "Account pool failover fails when refresh token is already used.",
+      ].join("\n"),
+      labels: ["bug"],
+    });
+    assert.ok(labels.includes("account-pool"), `got ${labels.join(",")}`);
+  });
 });

.github/workflows/enforce-issue-quality.yml

@@ -734,7 +734,7 @@ jobs:
               rejectsWorkflowDispatchPullRequest,
               rejectsWorkflowDispatchNonDefaultBranch,
             } = require(path.join(process.cwd(), ".github", "scripts", "issue-quality.cjs"));
-            const { stripTranslationBlock } = require(
+            const { stripTranslationBlock, splitTranslationBlock } = require(
               path.join(process.cwd(), ".github", "scripts", "issue-translation.cjs"),
             );
 
@@ -756,6 +756,17 @@ jobs:
             } else {
               issue_number = context.payload.issue.number;
             }
+
+            function translationPlainText(block) {
+              if (!block) return "";
+              return String(block)
+                .replace(/<!--[\s\S]*?-->/g, " ")
+                .replace(/<\/?details[^>]*>/gi, "\n")
+                .replace(/<\/?summary[^>]*>/gi, "\n")
+                .replace(/<[^>]+>/g, " ")
+                .replace(/[ \t]+\n/g, "\n")
+                .trim();
+            }
             const actor = context.actor;
             const eventType = context.eventName === "issues"
               ? context.payload.action
@@ -791,7 +802,12 @@ jobs:
               return;
             }
 
-            const issueBody = stripTranslationBlock(issue.body || "");
+            const translationSplit = splitTranslationBlock(issue.body || "");
+            const issueBody = translationSplit.sourceBody;
+            const areaHeuristicBody = [
+              issueBody,
+              translationPlainText(translationSplit.block),
+            ].filter(Boolean).join("\n\n");
 
             // -----------------------------------------------------------------
             // Trusted-user exemption
@@ -909,14 +925,10 @@ jobs:
                 }
               }
               const meta = AREA_LABELS[name];
-              const color = meta?.color || (name === "documentation" ? "0075ca" : "EDEDED");
-              const description = meta?.description
-                || (name === "documentation"
-                  ? "Improvements or additions to documentation"
-                  : name);
+              if (!meta) return;
               try {
                 await github.rest.issues.createLabel({
-                  owner, repo, name, color, description,
+                  owner, repo, name, color: meta.color, description: meta.description,
                 });
                 core.info(`Created label "${name}".`);
               } catch (err) {
@@ -931,6 +943,7 @@ jobs:
             const areaLabels = detectAreaLabels({
               title: issue.title,
               body: issueBody,
+              heuristicBody: areaHeuristicBody,
               labels,
             });
             const areaLabelsToAdd = areaLabels.filter((name) => !labels.includes(name));
@@ -1139,7 +1152,7 @@ jobs:
               AREA_LABELS,
               rejectsWorkflowDispatchNonDefaultBranch,
             } = require(path.join(process.cwd(), ".github", "scripts", "issue-quality.cjs"));
-            const { stripTranslationBlock } = require(
+            const { splitTranslationBlock } = require(
               path.join(process.cwd(), ".github", "scripts", "issue-translation.cjs"),
             );
 
@@ -1155,6 +1168,17 @@ jobs:
 
             const { owner, repo } = context.repo;
 
+            function translationPlainText(block) {
+              if (!block) return "";
+              return String(block)
+                .replace(/<!--[\s\S]*?-->/g, " ")
+                .replace(/<\/?details[^>]*>/gi, "\n")
+                .replace(/<\/?summary[^>]*>/gi, "\n")
+                .replace(/<[^>]+>/g, " ")
+                .replace(/[ \t]+\n/g, "\n")
+                .trim();
+            }
+
             async function ensureLabel(name) {
               try {
                 await github.rest.issues.getLabel({ owner, repo, name });
@@ -1166,14 +1190,10 @@ jobs:
                 }
               }
               const meta = AREA_LABELS[name];
-              const color = meta?.color || (name === "documentation" ? "0075ca" : "EDEDED");
-              const description = meta?.description
-                || (name === "documentation"
-                  ? "Improvements or additions to documentation"
-                  : name);
+              if (!meta) return;
               try {
                 await github.rest.issues.createLabel({
-                  owner, repo, name, color, description,
+                  owner, repo, name, color: meta.color, description: meta.description,
                 });
                 core.info(`Created label "${name}".`);
               } catch (err) {
@@ -1197,10 +1217,16 @@ jobs:
               const labels = (issue.labels || []).map((l) =>
                 typeof l === "string" ? l : l.name,
               );
-              const issueBody = stripTranslationBlock(issue.body || "");
+              const translationSplit = splitTranslationBlock(issue.body || "");
+              const issueBody = translationSplit.sourceBody;
+              const areaHeuristicBody = [
+                issueBody,
+                translationPlainText(translationSplit.block),
+              ].filter(Boolean).join("\n\n");
               const areaLabels = detectAreaLabels({
                 title: issue.title,
                 body: issueBody,
+                heuristicBody: areaHeuristicBody,
                 labels,
               });
               const toAdd = areaLabels.filter((name) => !labels.includes(name));

docs-site/src/content/docs/contributing.md

@@ -78,10 +78,11 @@ GitHub Actions intentionally stay small:
 - **Issue quality** (`.github/workflows/enforce-issue-quality.yml`) validates template structure on
   new and edited issues, applies kind labels (`bug`, `enhancement`, `provider-compatibility`,
   `documentation`), and adds orthogonal **area** labels from the form Area field plus light
-  title/body heuristics: `provider`, `account-pool`, `catalog`, `gui`, `cli`, `proxy`, `platform`,
-  `streaming`, `tools`, `install`, and `service`. Kind/process labels stay separate so you can
-  filter `bug` + `account-pool` without collapsing those axes. Prefer the Area dropdown over
-  inventing per-provider labels. Maintainers can re-apply area labels to all open issues with
+  title/Summary heuristics: `provider`, `account-pool`, `catalog`, `gui`, `cli`, `proxy`,
+  `platform`, `streaming`, `tools`, `install`, and `service`. Kind/process labels stay separate so
+  you can filter `bug` + `account-pool` without collapsing those axes. Prefer the Area dropdown
+  over inventing per-provider labels. Area: Documentation does not add a second area tag (the docs
+  form already seeds `documentation`). Maintainers can re-apply area labels to all open issues with
   workflow_dispatch `backfill_open_areas` after the workflow is on the default branch.
 
 Use the helper for releases:

tests/ci-workflows.test.ts

@@ -1974,11 +1974,16 @@ describe("GitHub Actions hardening", () => {
     expect(workflow).toContain("group: issue-translation-${{ github.event.issue.number }}");
     expect(workflow).not.toContain("issue-comment-translation-${{ github.event.comment.id }}");
     expect(workflow).toContain("if: github.event_name == 'issue_comment'");
+    // translate/validate skip open-area backfill; backfill job is area-only.
+    expect(workflow).toContain("backfill_open_areas");
+    expect(workflow).toContain("backfill-open-areas:");
+    expect(workflow).toMatch(/inputs\.backfill_open_areas != true/);
+    expect(workflow).toMatch(/inputs\.backfill_open_areas == true/);
     expect(workflow).toMatch(
-      /translate:\s*\n\s*name: Translate non-English issues\s*\n\s*if: github\.event_name == 'issues' \|\| github\.event_name == 'workflow_dispatch'/,
+      /translate:\s*\n\s*name: Translate non-English issues\s*\n\s*if: >\s*\n\s*github\.event_name == 'issues' \|\|\s*\n\s*\(github\.event_name == 'workflow_dispatch' &&\s*\n\s*inputs\.backfill_open_areas != true &&\s*\n\s*inputs\.issue_number != ''\)/,
     );
     expect(workflow).toMatch(
-      /validate:\s*\n\s*if: github\.event_name == 'issues' \|\| github\.event_name == 'workflow_dispatch'/,
+      /validate:\s*\n\s*if: >\s*\n\s*github\.event_name == 'issues' \|\|\s*\n\s*\(github\.event_name == 'workflow_dispatch' &&\s*\n\s*inputs\.backfill_open_areas != true &&\s*\n\s*inputs\.issue_number != ''\)/,
     );
 
     const commentJob = workflow.split(/\n {2}translate-comment:\n/)[1]!.split(/\n {2}[a-zA-Z]/)[0]!;
@@ -2024,7 +2029,9 @@ describe("GitHub Actions hardening", () => {
     expect(beforeJobs).not.toMatch(/^\s*permissions:/m);
 
     // Non-cancelling per-issue concurrency at workflow and translate-job scope.
-    expect(workflow).toContain("group: issue-quality-${{ github.event.issue.number || inputs.issue_number }}");
+    expect(workflow).toContain(
+      "group: issue-quality-${{ github.event.issue.number || inputs.issue_number || (inputs.backfill_open_areas && 'backfill-open-areas') || 'manual' }}",
+    );
     expect(workflow).toContain("group: issue-translation-${{ github.event.issue.number || inputs.issue_number }}");
     const workflowConcurrency = workflow.split(/jobs:\s*\n/)[0]!;
     expect(workflowConcurrency).toMatch(