Center labels on maintainers usage (#1170)

Author: Ndpnt

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All changes that impact users of this module are documented in this file, in the [Common Changelog](https://common-changelog.org) format with some additional specifications defined in the CONTRIBUTING file. This codebase adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased [major]
+
+> Development of this release was supported by the [French Ministry for Foreign Affairs](https://www.diplomatie.gouv.fr/fr/politique-etrangere-de-la-france/diplomatie-numerique/) through its ministerial [State Startups incubator](https://beta.gouv.fr/startups/open-terms-archive.html) under the aegis of the Ambassador for Digital Affairs.
+
+### Changed
+
+- **Breaking:** Replace generic issue labels with more descriptive names to better understand why terms tracking was interrupted; existing labels will be automatically updated on the first run
+- Add `⚠ needs intervention` label to highlight critical issues requiring manual action to restore terms tracking
+
 ## 5.7.0 - 2025-06-30
 
 _Full changeset and discussions: [#1169](https://github.com/OpenTermsArchive/engine/pull/1169)._

src/reporter/github/index.js

@@ -3,15 +3,15 @@ import { createRequire } from 'module';
 import { Octokit } from 'octokit';
 
 import logger from '../../logger/index.js';
+import { LABELS, MANAGED_BY_OTA_MARKER, DEPRECATED_MANAGED_BY_OTA_MARKER } from '../labels.js';
 
 const require = createRequire(import.meta.url);
 
-export const MANAGED_BY_OTA_MARKER = '[managed by OTA]';
-
 export default class GitHub {
   static ISSUE_STATE_CLOSED = 'closed';
   static ISSUE_STATE_OPEN = 'open';
   static ISSUE_STATE_ALL = 'all';
+  static MAX_LABEL_DESCRIPTION_LENGTH = 100;
 
   constructor(repository) {
     const { version } = require('../../../package.json');
@@ -49,9 +49,19 @@ export default class GitHub {
   }
 
   async initialize() {
-    this.MANAGED_LABELS = require('./labels.json');
+    this.MANAGED_LABELS = Object.values(LABELS);
     try {
       const existingLabels = await this.getRepositoryLabels();
+      const labelsToRemove = existingLabels.filter(label => label.description && label.description.includes(DEPRECATED_MANAGED_BY_OTA_MARKER));
+
+      if (labelsToRemove.length) {
+        logger.info(`Removing labels with deprecated markers: ${labelsToRemove.map(label => `"${label.name}"`).join(', ')}`);
+
+        for (const label of labelsToRemove) {
+          await this.deleteLabel(label.name); /* eslint-disable-line no-await-in-loop */
+        }
+      }
+
       const existingLabelsNames = existingLabels.map(label => label.name);
       const missingLabels = this.MANAGED_LABELS.filter(label => !existingLabelsNames.includes(label.name));
 
@@ -116,6 +126,13 @@ export default class GitHub {
     });
   }
 
+  async deleteLabel(name) {
+    await this.octokit.request('DELETE /repos/{owner}/{repo}/labels/{name}', {
+      ...this.commonParams,
+      name,
+    });
+  }
+
   async getIssue(title) {
     return (await this.issues).get(title);
   }
@@ -174,25 +191,25 @@ export default class GitHub {
     }
   }
 
-  async createOrUpdateIssue({ title, description, label }) {
+  async createOrUpdateIssue({ title, description, labels }) {
     try {
       const issue = await this.getIssue(title);
 
       if (!issue) {
-        const createdIssue = await this.createIssue({ title, description, labels: [label] });
+        const createdIssue = await this.createIssue({ title, description, labels });
 
         return logger.info(`Created issue #${createdIssue.number} "${title}": ${createdIssue.html_url}`);
       }
 
       const managedLabelsNames = this.MANAGED_LABELS.map(label => label.name);
       const labelsNotManagedToKeep = issue.labels.map(label => label.name).filter(label => !managedLabelsNames.includes(label));
-      const [managedLabel] = issue.labels.filter(label => managedLabelsNames.includes(label.name)); // It is assumed that only one specific reason for failure is possible at a time, making managed labels mutually exclusive
+      const managedLabels = issue.labels.filter(label => managedLabelsNames.includes(label.name));
 
-      if (issue.state !== GitHub.ISSUE_STATE_CLOSED && managedLabel?.name === label) {
-        return;
+      if (issue.state !== GitHub.ISSUE_STATE_CLOSED && labels.every(label => managedLabels.some(managedLabel => managedLabel.name === label))) {
+        return; // if all requested labels are already assigned to the issue, the error is redundant with the one already reported and no further action is necessary
       }
 
-      const updatedIssue = await this.updateIssue(issue, { state: GitHub.ISSUE_STATE_OPEN, labels: [ label, ...labelsNotManagedToKeep ] });
+      const updatedIssue = await this.updateIssue(issue, { state: GitHub.ISSUE_STATE_OPEN, labels: [ ...labels, ...labelsNotManagedToKeep ] });
 
       await this.addCommentToIssue({ issue, comment: description });
 

src/reporter/github/index.test.js

@@ -1,22 +1,20 @@
-import { createRequire } from 'module';
-
 import { expect } from 'chai';
 import nock from 'nock';
 
-import GitHub from './index.js';
+import { LABELS } from '../labels.js';
 
-const require = createRequire(import.meta.url);
+import GitHub from './index.js';
 
 describe('GitHub', function () {
   this.timeout(5000);
 
   let MANAGED_LABELS;
   let github;
-  const EXISTING_OPEN_ISSUE = { number: 1, title: 'Opened issue', description: 'Issue description', state: GitHub.ISSUE_STATE_OPEN, labels: [{ name: 'location' }] };
-  const EXISTING_CLOSED_ISSUE = { number: 2, title: 'Closed issue', description: 'Issue description', state: GitHub.ISSUE_STATE_CLOSED, labels: [{ name: '403' }] };
+  const EXISTING_OPEN_ISSUE = { number: 1, title: 'Opened issue', description: 'Issue description', state: GitHub.ISSUE_STATE_OPEN, labels: [{ name: 'page access restriction' }, { name: 'server error' }] };
+  const EXISTING_CLOSED_ISSUE = { number: 2, title: 'Closed issue', description: 'Issue description', state: GitHub.ISSUE_STATE_CLOSED, labels: [{ name: 'empty content' }] };
 
   before(async () => {
-    MANAGED_LABELS = require('./labels.json');
+    MANAGED_LABELS = Object.values(LABELS);
     github = new GitHub('owner/repo');
     nock('https://api.github.com')
       .get('/repos/owner/repo/issues')
@@ -274,23 +272,23 @@ describe('GitHub', function () {
 
   describe('#createOrUpdateIssue', () => {
     before(() => {
-      github.MANAGED_LABELS = require('./labels.json');
+      github.MANAGED_LABELS = Object.values(LABELS);
     });
 
     context('when the issue does not exist', () => {
       let createIssueScope;
       const ISSUE_TO_CREATE = {
         title: 'New Issue',
         description: 'Description of the new issue',
-        label: 'bug',
+        labels: ['empty response'],
       };
 
       before(async () => {
         createIssueScope = nock('https://api.github.com')
           .post('/repos/owner/repo/issues', {
             title: ISSUE_TO_CREATE.title,
             body: ISSUE_TO_CREATE.description,
-            labels: [ISSUE_TO_CREATE.label],
+            labels: ISSUE_TO_CREATE.labels,
           })
           .reply(200, { number: 123 });
 
@@ -313,14 +311,14 @@ describe('GitHub', function () {
 
         before(async () => {
           updateIssueScope = nock('https://api.github.com')
-            .patch(`/repos/owner/repo/issues/${EXISTING_CLOSED_ISSUE.number}`, { state: GitHub.ISSUE_STATE_OPEN, labels: ['location'] })
+            .patch(`/repos/owner/repo/issues/${EXISTING_CLOSED_ISSUE.number}`, { state: GitHub.ISSUE_STATE_OPEN, labels: ['page access restriction'] })
             .reply(200);
 
           addCommentScope = nock('https://api.github.com')
             .post(`/repos/owner/repo/issues/${EXISTING_CLOSED_ISSUE.number}/comments`, { body: EXISTING_CLOSED_ISSUE.description })
             .reply(200);
 
-          await github.createOrUpdateIssue({ title: EXISTING_CLOSED_ISSUE.title, description: EXISTING_CLOSED_ISSUE.description, label: 'location' });
+          await github.createOrUpdateIssue({ title: EXISTING_CLOSED_ISSUE.title, description: EXISTING_CLOSED_ISSUE.description, labels: ['page access restriction'] });
         });
 
         after(() => {
@@ -344,14 +342,14 @@ describe('GitHub', function () {
 
           before(async () => {
             updateIssueScope = nock('https://api.github.com')
-              .patch(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}`, { state: GitHub.ISSUE_STATE_OPEN, labels: ['404'] })
+              .patch(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}`, { state: GitHub.ISSUE_STATE_OPEN, labels: ['empty content'] })
               .reply(200);
 
             addCommentScope = nock('https://api.github.com')
               .post(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}/comments`, { body: EXISTING_OPEN_ISSUE.description })
               .reply(200);
 
-            await github.createOrUpdateIssue({ title: EXISTING_OPEN_ISSUE.title, description: EXISTING_OPEN_ISSUE.description, label: '404' });
+            await github.createOrUpdateIssue({ title: EXISTING_OPEN_ISSUE.title, description: EXISTING_OPEN_ISSUE.description, labels: ['empty content'] });
           });
 
           after(() => {
@@ -367,25 +365,27 @@ describe('GitHub', function () {
             expect(addCommentScope.isDone()).to.be.true;
           });
         });
-        context('when the reason did not change', () => {
+
+        context('when all requested labels are already present', () => {
           let addCommentScope;
           let updateIssueScope;
 
           before(async () => {
             updateIssueScope = nock('https://api.github.com')
-              .patch(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}`, { state: GitHub.ISSUE_STATE_OPEN, labels: EXISTING_OPEN_ISSUE.labels })
+              .patch(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}`)
               .reply(200);
 
             addCommentScope = nock('https://api.github.com')
-              .post(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}/comments`, { body: EXISTING_OPEN_ISSUE.description })
+              .post(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}/comments`)
               .reply(200);
 
-            await github.createOrUpdateIssue({ title: EXISTING_OPEN_ISSUE.title, description: EXISTING_OPEN_ISSUE.description, label: EXISTING_OPEN_ISSUE.labels[0].name });
+            await github.createOrUpdateIssue({ title: EXISTING_OPEN_ISSUE.title, description: EXISTING_OPEN_ISSUE.description, labels: [ 'page access restriction', 'server error' ] });
           });
 
           after(() => {
-            github.issuesCache.delete(EXISTING_OPEN_ISSUE.title);
             github.issuesCache.set(EXISTING_OPEN_ISSUE.title, EXISTING_OPEN_ISSUE);
+
+            nock.cleanAll();
           });
 
           it('does not attempt to updates the issue’s labels', () => {
@@ -396,6 +396,37 @@ describe('GitHub', function () {
             expect(addCommentScope.isDone()).to.be.false;
           });
         });
+
+        context('when some but not all requested labels are present', () => {
+          let addCommentScope;
+          let updateIssueScope;
+
+          before(async () => {
+            updateIssueScope = nock('https://api.github.com')
+              .patch(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}`, { state: GitHub.ISSUE_STATE_OPEN, labels: [ 'page access restriction', 'empty content' ] })
+              .reply(200);
+
+            addCommentScope = nock('https://api.github.com')
+              .post(`/repos/owner/repo/issues/${EXISTING_OPEN_ISSUE.number}/comments`, { body: EXISTING_OPEN_ISSUE.description })
+              .reply(200);
+
+            await github.createOrUpdateIssue({ title: EXISTING_OPEN_ISSUE.title, description: EXISTING_OPEN_ISSUE.description, labels: [ 'page access restriction', 'empty content' ] });
+          });
+
+          after(() => {
+            github.issuesCache.set(EXISTING_OPEN_ISSUE.title, EXISTING_OPEN_ISSUE);
+
+            nock.cleanAll();
+          });
+
+          it("updates the issue's labels", () => {
+            expect(updateIssueScope.isDone()).to.be.true;
+          });
+
+          it('adds a comment to the issue', () => {
+            expect(addCommentScope.isDone()).to.be.true;
+          });
+        });
       });
     });
   });