chore: Use conventional changelog and automate config version bumps

* chore: add the reference change to npm version

* chore: remove unused require

* chore: add conventional-changelog

* chore: add git to pre-release config changes

* style: formatting

* chore: fix commit message

* chore: add no-verify to commit of configs

* chore: no more shellJs

* chore: fixing async

* chore: committing restored

* refactor: move and rename

* chore: remove shelljs devdep and old script

* chore: change npm script ref after refactor

* chore: upgrade-config code improvements

* chore: edit package.json (not package-lock)

* chore(changelog): use conventionalcommits preset

* chore: add conventional changelog config

* chore: use .versionrc directly

* chore: update changelog config

* chore: update .versionrc.json

* chore: use standard-version

* chore: change to standard version

* styling(changelog): remove a tags + formatting

* styling: conventiontal-changelog styling

* chore: postformatting of changelog

* chore: remove unnecessary dependencies

* chore: add upgrade-config to version as backup

* docs: update release.md

* styling: order scripts alphabetically

* docs: requested changes + dry-run explanation

* chore: release script to TS

* chore: use ts-node to execute the TS scripts

* docs: add some documentation comments to script

* docs: remove unnecessary newline

* docs: fix comment linting

* chore: add test/integration and templates configs

* chore: correct automated commit message

* chore: remove fdir dependency

* chore: remove manual-git-changelog dependency

* chore: impl requested changes

* docs: update script comments

* chore: ensure full cov

* chore: review comments

.eslintrc.js

@@ -4,7 +4,7 @@ module.exports = {
   parser: '@typescript-eslint/parser',
   parserOptions: {
     tsconfigRootDir: __dirname,
-    project: [ './tsconfig.json', './test/tsconfig.json' ],
+    project: [ './tsconfig.json', './test/tsconfig.json', './scripts/tsconfig.json' ],
   },
   // Ignoring js files (such as this one) since they seem to conflict with rules that require typing info
   ignorePatterns: [ '*.js' ],

.github/workflows/schedule.yml

@@ -38,10 +38,8 @@ jobs:
           until $(curl --output /dev/null --silent --head --fail -k http://localhost:3000/); do
             sleep 1
           done
-      - name: Build test script
-        run: npx tsc -p test/deploy/tsconfig.json
       - name: Create users
-        run: node test/tmp/cth/createAccountCredentials.js http://localhost:3000/ >> test/deploy/conformance.env
+        run: ts-node test/deploy/createAccountCredentials.ts http://localhost:3000/ >> test/deploy/conformance.env
       - name: Run the test harness
         run: >
           docker run -i --rm

.versionrc.json

@@ -0,0 +1,15 @@
+{
+    "types": [
+        {"type": "feat", "section": "Features"},
+        {"type": "fix", "section": "Fixes"},
+        {"type": "chore", "section": "Chores"},
+        {"type": "chore(deps)", "section": "Dependency updates"},
+        {"type": "docs", "section": "Documentation"},
+        {"type": "style", "section": "Styling"},
+        {"type": "refactor", "section": "Refactors"},
+        {"type": "perf", "section": "Performance"},
+        {"type": "test", "section": "Testing"}
+    ],
+    "header": "# Changelog\n\nAll notable changes to this project will be documented in this file.",
+    "releaseCommitMessageFormat": "chore(release): Release version {{currentTag}} of the npm package"
+}

documentation/release.md

@@ -3,35 +3,35 @@
 This is only relevant if you are a developer with push access responsible for doing a new release.
 
 Steps to follow:
- * Merge `main` into `versions/x.0.0`.
- * Verify if there are issues when upgrading an existing installation to the new version.
+
+* Merge `main` into `versions/x.0.0`.
+* Verify if there are issues when upgrading an existing installation to the new version.
   * Can the data still be accessed?
   * Does authentication still work?
-   * Is there an issue upgrading the recipes at https://github.com/CommunitySolidServer/recipes
+  * Is there an issue upgrading the recipes at <https://github.com/CommunitySolidServer/recipes>
   * None of the above has to be blocking per se, but should be noted in the release notes if relevant.
- * Verify that the RELEASE_NOTES.md are correct.
- * Update all Components.js references to the new version.
-   * All contexts in all configs to 
-     `https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^x.0.0/components/context.jsonld`.
-   * Update all `lsd` entries in `package.json` to the new version.
-   * Commit this with `chore: Update configs to vx.0.0`.
- * `npm version major -m "chore: Release version %s of the npm package"`
-   * This will update the `package.json`, generate a tag, and generate the new entries in `CHANGELOG.md`.
- * Manually edit the `CHANGELOG.md`.
-   * First reverse the list of new entries so they go from old to new.
-   * Put all entries in matching categories, look at the previous release for reference.
-     * Most `chore` and `docs` entries can probably be removed.
+* Verify that the RELEASE_NOTES.md are correct.
+* `npm run release -- -r major` or `npx standard-version -r major`
+  * Automatically updates Components.js references to the new version. Committed with `chore(release): Update configs to vx.0.0`.
+  * Updates the `package.json`, generate a tag, and generate the new entries in `CHANGELOG.md`. Commited with `chore(release): Release version vx0.0 of the npm package`
+  * You can always add `--dry-run` to the above command to preview the commands that will be run and the changes to `CHANGELOG.md`.
+* Manually edit the `CHANGELOG.md`.
+  * All entries are added in separate sections of the new release according to their commit prefixes.
+  * Re-organize the entries accordingly, referencing previous releases.
+    * Most of the entries in Chores and Documentation can be removed.
   * Make sure there are 2 newlines between this and the previous section.
- * `git push --follow-tags`
- * Merge `versions/x.0.0` into `main` and push.
- * Do a GitHub release.
- * `npm publish`
- * Rename the `versions/x.0.0` branch to the next version.
- * Update `.github/workflows/schedule.yml` and `.github/dependabot.yml` to point at the new branch.
- * Potentially upgrade the recipes at https://github.com/CommunitySolidServer/recipes
+  * `git add CHANGELOG.md && git commit --amend --no-edit --no-verify` to add manual changes to the release commit.
+* `git push --follow-tags`
+* Merge `versions/x.0.0` into `main` and push.
+* Do a GitHub release.
+* `npm publish`
+* Rename the `versions/x.0.0` branch to the next version.
+* Update `.github/workflows/schedule.yml` and `.github/dependabot.yml` to point at the new branch.
+* Potentially upgrade the recipes at <https://github.com/CommunitySolidServer/recipes>
 
 Changes when doing a pre-release of a major version:
- * Version with `npm version premajor --preid alpha -m "chore: Release version %s of the npm package"`.
- * Do not merge `versions/x.0.0` into `main`.
- * Publish with `npm publish --tag next`.
- * Do not update the branch or anything related.
+
+* Version with `npm release -- -r major --pre-release alpha`
+* Do not merge `versions/x.0.0` into `main`.
+* Publish with `npm publish --tag next`.
+* Do not update the branch or anything related.

package.json

@@ -51,6 +51,7 @@
     "jest": "jest --coverageReporters text-summary --",
     "lint": "eslint . --cache --ignore-path .gitignore --max-warnings 0",
     "prepare": "npm run build",
+    "release": "standard-version",
     "start": "node ./bin/server.js",
     "start:file": "node ./bin/server.js -c config/file.json -f ./data",
     "test": "npm run test:ts && npm run jest",
@@ -60,7 +61,6 @@
     "test:unit": "jest --config=./jest.coverage.config.js test/unit",
     "test:watch": "jest --coverageReporters none --watch test/unit",
     "validate": "componentsjs-compile-config urn:solid-server:default:Initializer -c config/default.json -f > /dev/null",
-    "version": "manual-git-changelog onversion",
     "watch": "nodemon --watch \"dist/**/*.js\" --exec npm start"
   },
   "husky": {
@@ -69,6 +69,12 @@
       "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
     }
   },
+  "standard-version": {
+    "scripts": {
+      "postbump": "ts-node ./scripts/upgradeConfig.ts",
+      "postchangelog": "ts-node ./scripts/formatChangelog.ts"
+    }
+  },
   "files": [
     "bin",
     "dist",
@@ -160,12 +166,14 @@
     "husky": "^4.3.8",
     "jest": "^27.4.7",
     "jest-rdf": "^1.7.0",
-    "manual-git-changelog": "^1.0.1",
     "node-mocks-http": "^1.11.0",
     "nodemon": "^2.0.15",
     "set-cookie-parser": "^2.4.8",
+    "simple-git": "^3.7.1",
+    "standard-version": "^9.3.2",
     "supertest": "^6.2.2",
     "ts-jest": "^27.1.3",
+    "ts-node": "^10.7.0",
     "typedoc": "^0.22.11",
     "typescript": "^4.5.5"
   }

scripts/formatChangelog.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env ts-node
+/* eslint-disable no-console */
+import { readFile, writeFile } from 'fs-extra';
+
+/**
+ * Script called after the changelog changes of standard-version
+ * This script can be extended to add further custom formatting
+ * to the changelog.
+ * Current automatic changes:
+ *  - Change all version titles to H2 ("### [vX.Y.Z]" to "## [vX.Y.Z]")
+ */
+
+/**
+ * @param from  - Regular expression to search for
+ * @param to    - String to replace to
+ * @param filePath - File to search/replace
+ * @returns Promise
+ */
+async function replaceInFile(from: RegExp, to: string, filePath: string): Promise<void> {
+  const data = await readFile(filePath, 'utf8');
+  const result = data.replace(from, to);
+  return writeFile(filePath, result, 'utf8');
+}
+
+/**
+ * Ends the process and writes out an error in case something goes wrong.
+ */
+function endProcess(error: Error): never {
+  console.error(error);
+  process.exit(1);
+}
+
+replaceInFile(/### \[/gu, '## [', 'CHANGELOG.md').catch(endProcess);

scripts/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../tsconfig.json",
+  "include": [
+    "."
+  ]
+}

scripts/upgradeConfig.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env ts-node
+/* eslint-disable no-console */
+import escapeStringRegexp from 'escape-string-regexp';
+import { readdir, readFile, writeFile } from 'fs-extra';
+import simpleGit from 'simple-git';
+import { joinFilePath, readPackageJson } from '../src/util/PathUtil';
+
+/**
+ * Script: upgradeConfigs.ts
+ * Run with: ts-node scripts/upgradeConfig.ts
+ * ------------------------------------------
+ * Upgrades the lsd:module references to CSS in package.json
+ * and all JSON-LD config files.
+ * This script is run alongside standard-version after the
+ * version bump is done in package.json but before the
+ * release has been committed.
+ */
+
+/**
+ * Search and replace the version of a component with given name
+ * @param  filePath - File to search/replace
+ * @param  regex - RegExp matching the component reference
+ * @param  version - Semantic version to change to
+ */
+async function replaceComponentVersion(filePath: string, regex: RegExp, version: string): Promise<void> {
+  console.log(`Replacing version in ${filePath}`);
+  const data = await readFile(filePath, 'utf8');
+  const result = data.replace(regex, `$1^${version}`);
+  return writeFile(filePath, result, 'utf8');
+}
+
+/**
+ * Recursive search for files that match a given Regex
+ * @param  path - Path of folder to start search in
+ * @param  regex - A regular expression to which file names will be matched
+ * @returns Promise with all file pathss
+ */
+async function getFilePaths(path: string, regex: RegExp): Promise<string[]> {
+  const entries = await readdir(path, { withFileTypes: true });
+
+  const files = entries
+    .filter((file): boolean => !file.isDirectory())
+    .filter((file): boolean => regex.test(file.name))
+    .map((file): string => joinFilePath(path, file.name));
+
+  const folders = entries.filter((folder): boolean => folder.isDirectory());
+
+  for (const folder of folders) {
+    files.push(...await getFilePaths(joinFilePath(path, folder.name), regex));
+  }
+
+  return files;
+}
+
+/**
+ * Changes version of Component references in package.json and
+ * JSON-LD config files (config/) to the current major version of
+ * the NPM package.
+ * Commits changes to config files (not package.json, changes to
+ * that file are included in the release commit).
+ */
+async function upgradeConfig(): Promise<void> {
+  const pkg = await readPackageJson();
+  const major = pkg.version.split('.')[0];
+
+  console.log(`Changing ${pkg['lsd:module']} references to ${major}.0.0\n`);
+
+  const configs = await getFilePaths('config/', /.+\.json/u);
+  configs.push(...await getFilePaths('test/integration/config/', /.+\.json/u));
+  configs.push(...await getFilePaths('templates/config/', /.+\.json/u));
+
+  const escapedName = escapeStringRegexp(pkg['lsd:module']);
+  const regex = new RegExp(`(${escapedName}/)${/\^\d+\.\d+\.\d+/u.source}`, 'gmu');
+
+  for (const config of configs) {
+    await replaceComponentVersion(config, regex, `${major}.0.0`);
+  }
+  await replaceComponentVersion('package.json', regex, `${major}.0.0`);
+
+  await simpleGit().commit(`chore(release): Update configs to v${major}.0.0`, configs, { '--no-verify': null });
+}
+
+/**
+ * Ends the process and writes out an error in case something goes wrong.
+ */
+function endProcess(error: Error): never {
+  console.error(error);
+  process.exit(1);
+}
+
+upgradeConfig().catch(endProcess);

src/init/ModuleVersionVerifier.ts

@@ -1,10 +1,7 @@
-import { readJson } from 'fs-extra';
 import type { KeyValueStorage } from '../storage/keyvalue/KeyValueStorage';
-import { resolveModulePath } from '../util/PathUtil';
+import { readPackageJson } from '../util/PathUtil';
 import { Initializer } from './Initializer';
 
-const PACKAGE_JSON_PATH = resolveModulePath('package.json');
-
 /**
  * This initializer simply writes the version number of the server to the storage.
  * This will be relevant in the future when we look into migration initializers.
@@ -22,7 +19,7 @@ export class ModuleVersionVerifier extends Initializer {
   }
 
   public async handle(): Promise<void> {
-    const pkg = await readJson(PACKAGE_JSON_PATH);
+    const pkg = await readPackageJson();
     await this.storage.set(this.storageKey, pkg.version);
   }
 }

src/util/PathUtil.ts

@@ -1,4 +1,5 @@
 import { posix, win32 } from 'path';
+import { readJson } from 'fs-extra';
 import urljoin from 'url-join';
 import type { TargetExtractor } from '../http/input/identifier/TargetExtractor';
 import type { ResourceIdentifier } from '../http/representation/ResourceIdentifier';
@@ -270,6 +271,13 @@ export function resolveAssetPath(path = modulePathPlaceholder): string {
   return absoluteFilePath(path);
 }
 
+/**
+ * Reads the project package.json and returns it.
+ */
+export async function readPackageJson(): Promise<Record<string, any>> {
+  return readJson(resolveModulePath('package.json'));
+}
+
 /**
  * Concatenates all the given strings into a normalized URL.
  * Will place slashes between input strings if necessary.

test/deploy/createAccountCredentials.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env ts-node
 /* eslint-disable no-console */
 import fetch from 'cross-fetch';
 import urljoin from 'url-join';

test/deploy/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "extends": "@tsconfig/node12/tsconfig.json",
-  "compilerOptions": {
-    "declaration": true,
-    "inlineSources": true,
-    "newLine": "lf",
-    "outDir": "../tmp/cth",
-    "preserveConstEnums": true,
-    "sourceMap": true,
-    "stripInternal": true
-  },
-  "include": [
-    "createAccountCredentials.ts"
-  ]
-}