@opentermsarchive/engine 2.5.0 → 2.7.0

package/src/reporter/index.js

@@ -1,8 +1,9 @@
 import mime from 'mime';
 
 import { toISODateWithoutMilliseconds } from '../archivist/utils/date.js';
+import logger from '../logger/index.js';
 
-import GitHub from './github.js';
+import { createReporter } from './factory.js';
 
 const CONTRIBUTION_TOOL_URL = 'https://contribute.opentermsarchive.org/en/service';
 const DOC_URL = 'https://docs.opentermsarchive.org';
@@ -33,28 +34,65 @@ function getLabelNameFromError(error) {
 // In the following class, it is assumed that each issue is managed using its title as a unique identifier
 export default class Reporter {
   constructor(config) {
-    const { repositories } = config.githubIssues;
+    const normalizedConfig = Reporter.normalizeConfig(config);
 
-    for (const repositoryType of Object.keys(repositories)) {
-      if (!repositories[repositoryType].includes('/') || repositories[repositoryType].includes('https://')) {
-        throw new Error(`Configuration entry "reporter.githubIssues.repositories.${repositoryType}" is expected to be a string in the format <owner>/<repo>, but received: "${repositories[repositoryType]}"`);
-      }
+    Reporter.validateConfiguration(normalizedConfig.repositories);
+
+    this.reporter = createReporter(normalizedConfig);
+    this.repositories = normalizedConfig.repositories;
+  }
+
+  /**
+   * Support for legacy config format where reporter configuration was nested under `githubIssues`
+   * Example:
+   *
+   * ```json
+   * {
+   *   "githubIssues": {
+   *     "repositories": {
+   *       "declarations": "OpenTermsArchive/sandbox-declarations"
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * @deprecated
+   */
+  static normalizeConfig(config) {
+    if (config.githubIssues) {
+      logger.warn('The "reporter.githubIssues" key is deprecated; please see configuration documentation for the new format: https://docs.opentermsarchive.org/#configuring');
+
+      return {
+        type: 'github',
+        repositories: config.githubIssues.repositories,
+      };
+    }
+
+    return config;
+  }
+
+  static validateConfiguration(repositories) {
+    if (!repositories?.declarations) {
+      throw new Error('Required configuration key "reporter.repositories.declarations" was not found; issues on the declarations repository cannot be created');
     }
 
-    this.github = new GitHub(repositories.declarations);
-    this.repositories = repositories;
+    for (const [ type, repo ] of Object.entries(repositories)) {
+      if (!repo.includes('/') || repo.includes('https://')) {
+        throw new Error(`Configuration entry "reporter.repositories.${type}" is expected to be a string in the format <owner>/<repo>, but received: "${repo}"`);
+      }
+    }
   }
 
   initialize() {
-    return this.github.initialize();
+    return this.reporter.initialize();
   }
 
   onTrackingStarted() {
-    return this.github.clearCache();
+    return this.reporter.clearCache();
   }
 
   async onVersionRecorded(version) {
-    await this.github.closeIssueWithCommentIfExists({
+    await this.reporter.closeIssueWithCommentIfExists({
       title: Reporter.generateTitleID(version.serviceId, version.termsType),
       comment: `### Tracking resumed
 
@@ -63,7 +101,7 @@ A new version has been recorded.`,
   }
 
   async onVersionNotChanged(version) {
-    await this.github.closeIssueWithCommentIfExists({
+    await this.reporter.closeIssueWithCommentIfExists({
       title: Reporter.generateTitleID(version.serviceId, version.termsType),
       comment: `### Tracking resumed
 
@@ -76,7 +114,7 @@ No changes were found in the last run, so no new version has been recorded.`,
   }
 
   async onInaccessibleContent(error, terms) {
-    await this.github.createOrUpdateIssue({
+    await this.reporter.createOrUpdateIssue({
       title: Reporter.generateTitleID(terms.service.id, terms.type),
       description: this.generateDescription({ error, terms }),
       label: getLabelNameFromError(error),
@@ -97,9 +135,9 @@ No changes were found in the last run, so no new version has been recorded.`,
     });
     const contributionToolUrl = `${CONTRIBUTION_TOOL_URL}?${contributionToolParams}`;
 
-    const latestDeclarationLink = `[Latest declaration](https://github.com/${this.repositories.declarations}/blob/main/declarations/${encodeURIComponent(terms.service.name)}.json)`;
-    const latestVersionLink = `[Latest version](https://github.com/${this.repositories.versions}/blob/main/${encodeURIComponent(terms.service.name)}/${encodeURIComponent(terms.type)}.md)`;
-    const snapshotsBaseUrl = `https://github.com/${this.repositories.snapshots}/blob/main/${encodeURIComponent(terms.service.name)}/${encodeURIComponent(terms.type)}`;
+    const latestDeclarationLink = `[Latest declaration](${this.reporter.generateDeclarationURL(terms.service.name)})`;
+    const latestVersionLink = `[Latest version](${this.reporter.generateVersionURL(terms.service.name, terms.type)})`;
+    const snapshotsBaseUrl = this.reporter.generateSnapshotsBaseUrl(terms.service.name, terms.type);
     const latestSnapshotsLink = terms.hasMultipleSourceDocuments
       ? `Latest snapshots:\n  - ${terms.sourceDocuments.map(sourceDocument => `[${sourceDocument.id}](${snapshotsBaseUrl}.%20#${sourceDocument.id}.${mime.getExtension(sourceDocument.mimeType)})`).join('\n  - ')}`
       : `[Latest snapshot](${snapshotsBaseUrl}.${mime.getExtension(terms.sourceDocuments[0].mimeType)})`;

package/src/reporter/index.test.js

@@ -0,0 +1,63 @@
+import { expect } from 'chai';
+
+import Reporter from './index.js';
+
+describe('Reporter', () => {
+  describe('#normalizeConfig', () => {
+    context('with current config format', () => {
+      it('returns the config as is', () => {
+        const config = { repositories: { declarations: 'owner/repo' } };
+        const normalizedConfig = Reporter.normalizeConfig(config);
+
+        expect(normalizedConfig).to.deep.equal(config);
+      });
+    });
+
+    context('with old config format where githubIssues is nested under reporter', () => {
+      it('returns a normalized config', () => {
+        const config = { githubIssues: { repositories: { declarations: 'owner/repo' } } };
+        const expectedConfig = {
+          type: 'github',
+          repositories: { declarations: 'owner/repo' },
+        };
+        const normalizedConfig = Reporter.normalizeConfig(config);
+
+        expect(normalizedConfig).to.deep.equal(expectedConfig);
+      });
+    });
+  });
+
+  describe('#validateConfiguration', () => {
+    context('with valid configuration', () => {
+      it('does not throw an error', () => {
+        const repositories = { declarations: 'owner/repo' };
+
+        expect(() => {
+          Reporter.validateConfiguration(repositories);
+        }).not.to.throw();
+      });
+    });
+
+    context('with invalid configuration', () => {
+      context('when declarations key is missing', () => {
+        it('throws an error', () => {
+          const repositories = {};
+
+          expect(() => {
+            Reporter.validateConfiguration(repositories);
+          }).to.throw().and.have.property('message').that.match(/Required configuration key.*was not found/);
+        });
+      });
+
+      context('when repository format is incorrect', () => {
+        it('throws an error', () => {
+          const repositories = { declarations: 'invalidFormat' };
+
+          expect(() => {
+            Reporter.validateConfiguration(repositories);
+          }).to.throw('Configuration entry "reporter.repositories.declarations" is expected to be a string in the format <owner>/<repo>, but received: "invalidFormat"');
+        });
+      });
+    });
+  });
+});