@opentermsarchive/engine 0.37.1 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentermsarchive/engine",
-  "version": "0.37.1",
+  "version": "1.0.0",
   "description": "Tracks and makes visible changes to the terms of online services",
   "homepage": "https://github.com/OpenTermsArchive/engine#readme",
   "bugs": {
@@ -30,6 +30,8 @@
     ".eslintrc.yaml"
   ],
   "scripts": {
+    "changelog": "node scripts/changelog/index.js",
+    "commit-messages:lint": "commitlint --from=main --to=HEAD",
     "dataset:generate": "node bin/ota.js dataset",
     "dataset:release": "node bin/ota.js dataset --publish --remove-local-copy",
     "dataset:scheduler": "npm run dataset:release -- --schedule",
@@ -100,10 +102,13 @@
     "winston-mail": "^2.0.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^19.0.3",
     "dir-compare": "^4.0.0",
+    "keep-a-changelog": "^2.5.3",
     "nock": "^13.2.1",
     "node-stream-zip": "^1.15.0",
     "prettier": "^2.2.1",
+    "semver": "^7.6.0",
     "sinon": "^12.0.1",
     "sinon-chai": "^3.7.0",
     "supertest": "^6.3.3"

package/scripts/changelog/changelog.js

@@ -0,0 +1,95 @@
+import { parser as keepAChangelogParser } from 'keep-a-changelog';
+import semver from 'semver';
+
+import ChangelogValidationError from './changelogValidationError.js';
+
+export default class Changelog {
+  static NO_CODE_CHANGES_REGEX = /^_No code changes were made in this release(.+)_$/m;
+  static FUNDER_REGEX = /^> Development of this release was (?:supported|made on a volunteer basis) by (.+)\.$/m;
+  static UNRELEASED_REGEX = /## Unreleased[ ]+\[(major|minor|patch)\]/i;
+  static CHANGESET_LINK_REGEX = /^_Full changeset and discussions: (.+)._$/m;
+  static CHANGESET_LINK_TEMPLATE = PRNumber => `_Full changeset and discussions: [#${PRNumber}](https://github.com/OpenTermsArchive/engine/pull/${PRNumber})._`;
+  static CHANGELOG_INTRO = '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).';
+
+  constructor(rawContent) {
+    this.rawContent = rawContent;
+    this.changelog = keepAChangelogParser(this.rawContent);
+    this.changelog.description = Changelog.CHANGELOG_INTRO;
+    this.changelog.format = 'markdownlint';
+    this.releaseType = this.extractReleaseType();
+  }
+
+  extractReleaseType() {
+    const match = this.rawContent.match(Changelog.UNRELEASED_REGEX);
+
+    if (match && match[1]) {
+      return match[1].toLowerCase();
+    }
+
+    return null;
+  }
+
+  cleanUnreleased() {
+    const index = this.changelog.releases.findIndex(release => !release.version);
+
+    this.changelog.releases.splice(index, 1);
+  }
+
+  getVersionContent(version) {
+    const release = this.changelog.findRelease(version);
+
+    if (!release) {
+      throw new Error(`Version ${version} not found in changelog`);
+    }
+
+    return release.toString(this.changelog);
+  }
+
+  release(PRNumber) {
+    const unreleased = this.changelog.findRelease();
+
+    if (!unreleased) {
+      throw new Error('Missing "Unreleased" section');
+    }
+
+    const latestVersion = semver.maxSatisfying(this.changelog.releases.map(release => release.version), '*');
+    const newVersion = semver.inc(latestVersion, this.releaseType);
+
+    unreleased.setVersion(newVersion);
+    unreleased.date = new Date();
+
+    if (PRNumber && !Changelog.CHANGESET_LINK_REGEX.test(unreleased.description)) {
+      unreleased.description = `${Changelog.CHANGESET_LINK_TEMPLATE(PRNumber)}\n\n${unreleased.description}`;
+    }
+  }
+
+  validateUnreleased() {
+    const unreleased = this.changelog.findRelease();
+    const errors = [];
+
+    if (!unreleased) {
+      errors.push(new Error('Missing "Unreleased" section'));
+      throw new ChangelogValidationError(errors);
+    }
+
+    if (!this.releaseType) {
+      errors.push(new Error('Invalid or missing release type for "Unreleased" section. Please ensure the section contains a valid release type (major, minor, or patch)'));
+    }
+
+    if (!Changelog.FUNDER_REGEX.test(unreleased.description)) {
+      errors.push(new Error('Missing funder in the "Unreleased" section'));
+    }
+
+    if (!Changelog.NO_CODE_CHANGES_REGEX.test(unreleased.description) && (!unreleased.changes || Array.from(unreleased.changes.values()).every(change => !change.length))) {
+      errors.push(new Error('Missing or malformed changes in the "Unreleased" section'));
+    }
+
+    if (errors.length) {
+      throw new ChangelogValidationError(errors);
+    }
+  }
+
+  toString() {
+    return this.changelog.toString();
+  }
+}

package/scripts/changelog/changelog.test.js

@@ -0,0 +1,144 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { expect } from 'chai';
+
+import Changelog from './changelog.js';
+import ChangelogValidationError from './changelogValidationError.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+describe('Changelog', () => {
+  let changelog;
+
+  describe('#releaseType', () => {
+    context('with a properly formed changelog', () => {
+      it('returns the correct release type', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog.md'), 'UTF-8'));
+        expect(changelog.releaseType).to.equal('major');
+      });
+    });
+
+    context('when "Unreleased" section does not exist', () => {
+      it('returns null', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-without-unreleased.md'), 'UTF-8'));
+        expect(changelog.releaseType).to.be.null;
+      });
+    });
+    context('when "Unreleased" section has a malformed release type', () => {
+      it('returns null', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-with-unreleased-malformed.md'), 'UTF-8'));
+        expect(changelog.releaseType).to.be.null;
+      });
+    });
+  });
+
+  describe('#getVersionContent', () => {
+    context('when getting an exisiting version', () => {
+      it('returns the content of the specified version', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog.md'), 'UTF-8'));
+        const versionContent = changelog.getVersionContent('0.0.1');
+
+        expect(versionContent).to.equal(`## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was made on a volunteer basis by a contributor.
+
+### Added
+
+- Initial release`);
+      });
+    });
+
+    context('when getting a non-existing version', () => {
+      it('throws an error', () => {
+        expect(() => changelog.getVersionContent('2.0.0')).to.throw(Error);
+      });
+    });
+  });
+
+  describe('#cleanUnreleased', () => {
+    context('when "Unreleased" section exists', () => {
+      it('removes the section', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-with-unreleased-no-release.md'), 'UTF-8'));
+        changelog.cleanUnreleased();
+        const updatedChangelog = changelog.toString();
+
+        expect(updatedChangelog).to.not.include('## Unreleased');
+      });
+    });
+
+    context('when "Unreleased" section does not exist', () => {
+      it('does not throw any error', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-without-unreleased.md'), 'UTF-8'));
+        expect(() => changelog.cleanUnreleased()).to.not.throw();
+      });
+    });
+  });
+
+  describe('#release', () => {
+    context('with a properly formed changelog', () => {
+      it('returns an updated version of the changelog', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog.md'), 'UTF-8'));
+        changelog.release();
+        let expectedResult = await fs.readFile(path.resolve(__dirname, './fixtures/changelog-released.md'), 'UTF-8');
+
+        expectedResult = expectedResult.replace('<DATE_OF_THE_DAY_PLACEHOLDER>', `${new Date().getFullYear()}-${String(new Date().getMonth() + 1).padStart(2, '0')}-${String(new Date().getDate()).padStart(2, '0')}`);
+        expect(changelog.toString()).to.equal(expectedResult);
+      });
+    });
+
+    context('when there is a validation error on the "Unreleased" section', () => {
+      it('throws an error', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-without-unreleased.md'), 'UTF-8'));
+        expect(() => changelog.release(124)).to.throw(Error, 'Missing "Unreleased" section');
+      });
+    });
+  });
+
+  describe('#validateUnreleased', () => {
+    context('with a properly formed "Unreleased" section', () => {
+      it('does not throw any error', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog.md'), 'UTF-8'));
+        expect(() => changelog.validateUnreleased()).to.not.throw();
+      });
+    });
+
+    context('when "Unreleased" section is missing', () => {
+      it('throws a ChangelogValidationError error with proper message', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-without-unreleased.md'), 'UTF-8'));
+        expect(() => changelog.validateUnreleased()).to.throw(ChangelogValidationError, 'Missing "Unreleased" section');
+      });
+    });
+
+    context('when release type is invalid or missing', () => {
+      it('throws a ChangelogValidationError error with proper message', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-with-unreleased-malformed.md'), 'UTF-8'));
+        expect(() => changelog.validateUnreleased()).to.throw(ChangelogValidationError, 'Invalid or missing release type for "Unreleased" section. Please ensure the section contains a valid release type (major, minor, or patch)');
+      });
+    });
+
+    context('when funder is missing', () => {
+      it('throws a ChangelogValidationError error with proper message', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-without-funder.md'), 'UTF-8'));
+        expect(() => changelog.validateUnreleased()).to.throw(ChangelogValidationError, 'Missing funder in the "Unreleased" section');
+      });
+    });
+
+    context('when changes are missing', () => {
+      it('throws a ChangelogValidationError error with proper message', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-without-changes.md'), 'UTF-8'));
+        expect(() => changelog.validateUnreleased()).to.throw(ChangelogValidationError, 'Missing or malformed changes in the "Unreleased" section');
+      });
+    });
+
+    context('when changes are malformed', () => {
+      it('throws a ChangelogValidationError error with proper message', async () => {
+        changelog = new Changelog(await fs.readFile(path.resolve(__dirname, './fixtures/changelog-without-changes.md'), 'UTF-8'));
+        expect(() => changelog.validateUnreleased()).to.throw(ChangelogValidationError, 'Missing or malformed changes in the "Unreleased" section');
+      });
+    });
+  });
+});

package/scripts/changelog/changelogValidationError.js

@@ -0,0 +1,9 @@
+export default class ChangelogValidationError extends Error {
+  constructor(errorOrErrors) {
+    const errors = [].concat(errorOrErrors);
+
+    super(`Invalid Unreleased section:${`\n - ${errors.join('\n - ')}`}`);
+    this.name = 'ChangelogValidationError';
+    this.errors = errors;
+  }
+}

package/scripts/changelog/fixtures/changelog-released.md

@@ -0,0 +1,23 @@
+# Changelog
+
+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).
+
+## 1.0.0 - <DATE_OF_THE_DAY_PLACEHOLDER>
+
+_Full changeset and discussions: #123._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- New feature 1
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was made on a volunteer basis by a contributor.
+
+### Added
+
+- Initial release

package/scripts/changelog/fixtures/changelog-with-changes-malformed.md

@@ -0,0 +1,21 @@
+# Changelog
+
+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]
+
+_Full changeset and discussions: #123._
+
+> Development of this release was supported by a funder.
+
+- New feature 1
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- Initial release

package/scripts/changelog/fixtures/changelog-with-unreleased-malformed.md

@@ -0,0 +1,23 @@
+# Changelog
+
+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
+
+_Full changeset and discussions: #123._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- New feature 1
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- Initial release

package/scripts/changelog/fixtures/changelog-with-unreleased-no-release.md

@@ -0,0 +1,21 @@
+# Changelog
+
+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 [no-release]
+
+_Modifications made in this changeset do not alter its behavior or functionality from the perspective of the end user or other interacting systems. It does not add new features, do not enhance existing features, or alter the behavior of the software in a way that affects its use._
+
+### Added
+
+- New feature 1
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- Initial release

package/scripts/changelog/fixtures/changelog-without-changes.md

@@ -0,0 +1,19 @@
+# Changelog
+
+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]
+
+_Full changeset and discussions: #123._
+
+> Development of this release was supported by a funder.
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- Initial release

package/scripts/changelog/fixtures/changelog-without-funder.md

@@ -0,0 +1,21 @@
+# Changelog
+
+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]
+
+_Full changeset and discussions: #123._
+
+### Added
+
+- New feature 1
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- Initial release

package/scripts/changelog/fixtures/changelog-without-unreleased.md

@@ -0,0 +1,13 @@
+# Changelog
+
+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).
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- Initial release

package/scripts/changelog/fixtures/changelog.md

@@ -0,0 +1,23 @@
+# Changelog
+
+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]
+
+_Full changeset and discussions: #123._
+
+> Development of this release was supported by a funder.
+
+### Added
+
+- New feature 1
+
+## 0.0.1 - 2024-02-20
+
+_Full changeset and discussions: #122._
+
+> Development of this release was made on a volunteer basis by a contributor.
+
+### Added
+
+- Initial release

package/scripts/changelog/index.js

@@ -0,0 +1,59 @@
+#! /usr/bin/env node
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { program } from 'commander';
+
+import Changelog from './changelog.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+program
+  .name('changelog')
+  .description('A command-line utility for managing the changelog file')
+  .option('--validate', 'Validate the changelog, ensuring it follows the expected format and contains required information')
+  .option('--release [PRNumber]', 'Convert the Unreleased section into a new release in the changelog, optionally linking to a pull request with the provided PRNumber')
+  .option('--clean-unreleased', 'Remove the Unreleased section')
+  .option('--get-release-type', 'Get the release type of the Unreleased section in the changelog')
+  .option('--get-version-content <version>', 'Get the content of the given version in the changelog');
+
+const options = program.parse(process.argv).opts();
+
+let changelog;
+
+const CHANGELOG_PATH = path.resolve(__dirname, '../../CHANGELOG.md');
+const ENCODING = 'UTF-8';
+
+try {
+  const changelogContent = await fs.readFile(CHANGELOG_PATH, ENCODING);
+
+  changelog = new Changelog(changelogContent);
+} catch (error) {
+  console.log(error.message);
+}
+
+if (options.validate) {
+  changelog.validateUnreleased();
+}
+
+if (options.getReleaseType) {
+  process.stdout.write(changelog.releaseType || 'No release type found');
+}
+
+if (options.getVersionContent) {
+  process.stdout.write(changelog.getVersionContent(options.getVersionContent));
+}
+
+if (options.release) {
+  const PRNumber = typeof options.release == 'boolean' ? null : options.release;
+
+  changelog.release(PRNumber);
+  await fs.writeFile(CHANGELOG_PATH, changelog.toString(), ENCODING);
+}
+
+if (options.cleanUnreleased) {
+  changelog.cleanUnreleased();
+  await fs.writeFile(CHANGELOG_PATH, changelog.toString(), ENCODING);
+}