@opentermsarchive/engine 12.0.0 → 12.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 This codebase is a Node.js module enabling downloading, archiving and publishing versions of terms obtained online. It can be used independently from the Open Terms Archive ecosystem. For a high-level overview of Open Terms Archive’s wider goals and processes, please read its [public homepage](https://opentermsarchive.org).
 
+[![DPG Badge](https://img.shields.io/badge/Verified-DPG-3333AB?logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iMzEiIGhlaWdodD0iMzMiIHZpZXdCb3g9IjAgMCAzMSAzMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTE0LjIwMDggMjEuMzY3OEwxMC4xNzM2IDE4LjAxMjRMMTEuNTIxOSAxNi40MDAzTDEzLjk5MjggMTguNDU5TDE5LjYyNjkgMTIuMjExMUwyMS4xOTA5IDEzLjYxNkwxNC4yMDA4IDIxLjM2NzhaTTI0LjYyNDEgOS4zNTEyN0wyNC44MDcxIDMuMDcyOTdMMTguODgxIDUuMTg2NjJMMTUuMzMxNCAtMi4zMzA4MmUtMDVMMTEuNzgyMSA1LjE4NjYyTDUuODU2MDEgMy4wNzI5N0w2LjAzOTA2IDkuMzUxMjdMMCAxMS4xMTc3TDMuODQ1MjEgMTYuMDg5NUwwIDIxLjA2MTJMNi4wMzkwNiAyMi44Mjc3TDUuODU2MDEgMjkuMTA2TDExLjc4MjEgMjYuOTkyM0wxNS4zMzE0IDMyLjE3OUwxOC44ODEgMjYuOTkyM0wyNC44MDcxIDI5LjEwNkwyNC42MjQxIDIyLjgyNzdMMzAuNjYzMSAyMS4wNjEyTDI2LjgxNzYgMTYuMDg5NUwzMC42NjMxIDExLjExNzdMMjQuNjI0MSA5LjM1MTI3WiIgZmlsbD0id2hpdGUiLz4KPC9zdmc+Cg==)](https://digitalpublicgoods.net/r/open-terms-archive)
+
 For documentation, visit [docs.opentermsarchive.org](https://docs.opentermsarchive.org/)
 
 ## Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentermsarchive/engine",
-  "version": "12.0.0",
+  "version": "12.0.1",
   "description": "Tracks and makes visible changes to the terms of online services",
   "homepage": "https://opentermsarchive.org",
   "bugs": {

package/src/reporter/index.js

@@ -137,7 +137,11 @@ 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](${this.reporter.generateDeclarationURL(terms.service.name)})`;
+    const declarationFileUrl = this.reporter.generateDeclarationURL(terms.service.name);
+    const updateDeclarationLink = terms.hasMultipleSourceDocuments ? `[on GitHub](${declarationFileUrl})` : `[on the contribution tool](${contributionToolUrl})`;
+    const multiDocumentsUpdateInfo = terms.hasMultipleSourceDocuments ? ' (the contribution tool does not support multi-document)' : '';
+
+    const latestDeclarationLink = `[Latest declaration](${declarationFileUrl})`;
     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
@@ -163,13 +167,13 @@ First of all, check if the source documents are accessible through a web browser
 
 #### If the source documents are accessible through a web browser
 
-[Edit the declaration](${contributionToolUrl}):
+Edit the declaration ${updateDeclarationLink}${multiDocumentsUpdateInfo}:
 - Try updating the selectors.
 - Try switching client scripts on with expert mode.
 
 #### If the source documents are not accessible anymore
 
-- If the source documents have moved, find their new location and [update it](${contributionToolUrl}).
+- If the source documents have moved, find their new location and update it ${updateDeclarationLink}.
 - If these terms have been removed, move them from the declaration to its [history file](${DOC_URL}/terms/explanation/declarations-maintenance/#service-history-reference), using \`${validUntil}\` as the \`validUntil\` value.
 - If the service has closed, move the entire contents of the declaration to its [history file](${DOC_URL}/contributing-terms/#service-history), using \`${validUntil}\` as the \`validUntil\` value.
 

package/src/reporter/index.test.js

@@ -60,4 +60,66 @@ describe('Reporter', () => {
       });
     });
   });
+
+  describe('#generateDescription', () => {
+    const buildReporter = () => new Reporter({
+      type: 'github',
+      repositories: { declarations: 'OpenTermsArchive/test-declarations' },
+    });
+
+    const buildTerms = ({ sourceCount = 1 } = {}) => {
+      const sourceDocuments = Array.from({ length: sourceCount }, (_, index) => ({
+        id: `source-${index}`,
+        location: `https://example.com/source-${index}`,
+        mimeType: 'text/html',
+        snapshotId: `snapshot-${index}`,
+        toPersistence: () => ({ fetch: `https://example.com/source-${index}` }),
+      }));
+
+      return {
+        service: { id: 'TestService', name: 'TestService' },
+        type: 'Terms of Service',
+        sourceDocuments,
+        hasMultipleSourceDocuments: sourceCount > 1,
+        toPersistence: () => ({
+          name: 'TestService',
+          terms: {
+            'Terms of Service': sourceCount > 1
+              ? { combine: sourceDocuments.map(sourceDocument => sourceDocument.toPersistence()) }
+              : sourceDocuments[0].toPersistence(),
+          },
+        }),
+      };
+    };
+
+    const error = { reasons: ['HTTP code 404'] };
+
+    context('when the terms has a single source document', () => {
+      it('deep-links to the contribution tool with the serialized declaration as the edit target', () => {
+        const description = buildReporter().generateDescription({ error, terms: buildTerms({ sourceCount: 1 }) });
+
+        expect(description).to.match(/\(https:\/\/contribute\.opentermsarchive\.org\/[^)]*\bjson=[^)]*\)/);
+      });
+    });
+
+    context('when the terms has multiple source documents (combine)', () => {
+      it('does not deep-link to the contribution tool because it cannot edit multi-source declarations', () => {
+        const description = buildReporter().generateDescription({ error, terms: buildTerms({ sourceCount: 5 }) });
+
+        expect(description).to.not.include('json=');
+      });
+
+      it('links to the declaration file on GitHub as the edit target', () => {
+        const description = buildReporter().generateDescription({ error, terms: buildTerms({ sourceCount: 5 }) });
+
+        expect(description).to.include('github.com/OpenTermsArchive/test-declarations/blob/main/declarations/TestService.json');
+      });
+
+      it('keeps the description below the GitHub 65,536-character issue body limit even with many sources', () => {
+        const description = buildReporter().generateDescription({ error, terms: buildTerms({ sourceCount: 50 }) });
+
+        expect(description.length).to.be.lessThan(65000);
+      });
+    });
+  });
 });