build-ts: keep a package homepage that points outside the repository (0.86.9) (#34)

* build-ts: keep a package homepage that points outside the repository

orderPackageJson derived homepage from repository.url on every build, so a
package could not link its npm page to its API reference: the build put the
repository readme back and the clean-tree check failed. A homepage inside the
repository, or none, is still derived as before.

* Release dev, dev-test and dev-ts together as 0.86.9

packages/dev-test/package.json

@@ -15,7 +15,7 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.86.8",
+  "version": "0.86.9",
   "main": "./index.js",
   "exports": {
     "./globals.d.ts": "./src/globals.d.ts"

packages/dev-test/src/packageInfo.ts

@@ -3,4 +3,4 @@
 
 // Do not edit, auto-generated by @pezkuwi/dev
 
-export const packageInfo = { name: '@pezkuwi/dev-test', path: 'auto', type: 'auto', version: '0.86.8' };
+export const packageInfo = { name: '@pezkuwi/dev-test', path: 'auto', type: 'auto', version: '0.86.9' };

packages/dev-ts/package.json

@@ -15,7 +15,7 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.86.8",
+  "version": "0.86.9",
   "main": "./index.js",
   "exports": {
     "./globals.d.ts": "./src/globals.d.ts"

packages/dev-ts/src/packageInfo.ts

@@ -3,4 +3,4 @@
 
 // Do not edit, auto-generated by @pezkuwi/dev
 
-export const packageInfo = { name: '@pezkuwi/dev-ts', path: 'auto', type: 'auto', version: '0.86.8' };
+export const packageInfo = { name: '@pezkuwi/dev-ts', path: 'auto', type: 'auto', version: '0.86.9' };

packages/dev/package.json

@@ -15,7 +15,7 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.86.8",
+  "version": "0.86.9",
   "bin": {
     "pezkuwi-ci-ghact-build": "./scripts/pezkuwi-ci-ghact-build.mjs",
     "pezkuwi-ci-ghact-docs": "./scripts/pezkuwi-ci-ghact-docs.mjs",
@@ -52,8 +52,8 @@
   "dependencies": {
     "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
-    "@pezkuwi/dev-test": "^0.86.8",
+    "@pezkuwi/dev-test": "^0.86.9",
-    "@pezkuwi/dev-ts": "^0.86.8",
+    "@pezkuwi/dev-ts": "^0.86.9",
     "@rollup/plugin-alias": "^5.1.1",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-dynamic-import-vars": "^2.1.5",

packages/dev/scripts/pezkuwi-dev-build-ts.mjs

@@ -9,7 +9,7 @@ import path from 'node:path';
 import process from 'node:process';
 import ts from 'typescript';
 
-import { copyDirSync, copyFileSync, DENO_EXT_PRE, DENO_LND_PRE, DENO_POL_PRE, engineVersionCmp, execPm, exitFatal, exitFatalEngine, logBin, mkdirpSync, PATHS_BUILD, readdirSync, rimrafSync } from './util.mjs';
+import { copyDirSync, copyFileSync, DENO_EXT_PRE, DENO_LND_PRE, DENO_POL_PRE, engineVersionCmp, execPm, exitFatal, exitFatalEngine, logBin, mkdirpSync, packageHomepage, PATHS_BUILD, readdirSync, rimrafSync } from './util.mjs';
 
 /** @typedef {'babel' | 'esbuild' | 'swc' | 'tsc'} CompileType */
 /** @typedef {{ bin?: Record<string, string>; browser?: string; bugs?: string; deno?: string; denoDependencies?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string>; electron?: string; engines?: { node?: string }; exports?: Record<string, unknown>; license?: string; homepage?: string; main?: string; module?: string; name?: string; optionalDependencies?: Record<string, string>; peerDependencies?: Record<string, string>; repository?: { directory?: string; type: 'git'; url: string; }; 'react-native'?: string; resolutions?: Record<string, string>; sideEffects?: boolean | string[]; scripts?: Record<string, string>; type?: 'module' | 'commonjs'; types?: string; version?: string; }} PkgJson */
@@ -973,7 +973,7 @@ function repoBaseFromUrl (url) {
  */
 function orderPackageJson (repoBase, dir, json) {
   json.bugs = `${repoBase}/issues`;
-  json.homepage = `${repoBase}${dir ? `/tree/master/packages/${dir}` : ''}#readme`;
+  json.homepage = packageHomepage(repoBase, dir, json.homepage);
   json.license = !json.license || json.license === 'Apache-2'
     ? 'Apache-2.0'
     : json.license;

packages/dev/scripts/util.mjs

@@ -146,6 +146,24 @@ export function engineVersionSplit (ver) {
   return [parseInt(parts[0] || '0', 10), parseInt(parts[1] || '0', 10), parseInt(parts[2] || '0', 10)];
 }
 
+/**
+ * The homepage written into a package.json. One the author pointed outside the
+ * repository (an API reference, a product site) is kept; anything else, and an
+ * absent one, is derived from the repository.
+ *
+ * @param {string} repoBase e.g. https://git.example.org/owner/repo
+ * @param {string | null} dir package directory under packages/, null for the root
+ * @param {string} [current] the homepage the package.json carries now
+ * @returns {string}
+ */
+export function packageHomepage (repoBase, dir, current) {
+  const inRepo = !current || current === repoBase || current.startsWith(`${repoBase}/`) || current.startsWith(`${repoBase}#`);
+
+  return inRepo
+    ? `${repoBase}${dir ? `/tree/master/packages/${dir}` : ''}#readme`
+    : current;
+}
+
 /**
  * Process execution
  *

packages/dev/src/packageHomepage.spec.ts

@@ -0,0 +1,42 @@
+// Copyright 2017-2026 @pezkuwi/dev authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const UTIL = pathToFileURL(path.join(process.cwd(), 'packages/dev/scripts/util.mjs')).href;
+const REPO = 'https://git.example.org/owner/repo';
+
+// util.mjs is plain ESM outside the TypeScript build, so it is called the way
+// pezkuwi-dev-build-ts calls it: from node.
+function homepage (dir: string | null, current?: string): string {
+  const code = `import { packageHomepage } from ${JSON.stringify(UTIL)};
+process.stdout.write(packageHomepage(${JSON.stringify(REPO)}, ${JSON.stringify(dir)}, ${current === undefined ? 'undefined' : JSON.stringify(current)}));`;
+
+  return execFileSync(process.execPath, ['--input-type=module', '-e', code], { encoding: 'utf8' });
+}
+
+describe('packageHomepage', (): void => {
+  it('derives the homepage when there is none', (): void => {
+    expect(homepage('api')).toBe(`${REPO}/tree/master/packages/api#readme`);
+    expect(homepage(null)).toBe(`${REPO}#readme`);
+  });
+
+  it('rewrites a homepage inside the repository', (): void => {
+    expect(homepage('api', `${REPO}/tree/main/packages/api#readme`)).toBe(`${REPO}/tree/master/packages/api#readme`);
+    expect(homepage(null, `${REPO}#readme`)).toBe(`${REPO}#readme`);
+    expect(homepage(null, REPO)).toBe(`${REPO}#readme`);
+  });
+
+  it('keeps a homepage outside the repository', (): void => {
+    expect(homepage('api', 'https://developers.example.org/modules/api.html')).toBe('https://developers.example.org/modules/api.html');
+    expect(homepage(null, 'https://developers.example.org/')).toBe('https://developers.example.org/');
+  });
+
+  it('does not take a sibling repository for this one', (): void => {
+    expect(homepage('api', `${REPO}-docs`)).toBe(`${REPO}-docs`);
+  });
+});

packages/dev/src/packageInfo.ts

@@ -3,4 +3,4 @@
 
 // Do not edit, auto-generated by @pezkuwi/dev
 
-export const packageInfo = { name: '@pezkuwi/dev', path: 'auto', type: 'auto', version: '0.86.8' };
+export const packageInfo = { name: '@pezkuwi/dev', path: 'auto', type: 'auto', version: '0.86.9' };

yarn.lock

@@ -1196,7 +1196,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@pezkuwi/dev-test@npm:^0.86.8, @pezkuwi/dev-test@workspace:packages/dev-test":
+"@pezkuwi/dev-test@npm:^0.86.9, @pezkuwi/dev-test@workspace:packages/dev-test":
   version: 0.0.0-use.local
   resolution: "@pezkuwi/dev-test@workspace:packages/dev-test"
   dependencies:
@@ -1212,7 +1212,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@pezkuwi/dev-ts@npm:^0.86.8, @pezkuwi/dev-ts@workspace:packages/dev-ts":
+"@pezkuwi/dev-ts@npm:^0.86.9, @pezkuwi/dev-ts@workspace:packages/dev-ts":
   version: 0.0.0-use.local
   resolution: "@pezkuwi/dev-ts@workspace:packages/dev-ts"
   dependencies:
@@ -1228,8 +1228,8 @@ __metadata:
   dependencies:
     "@eslint/compat": "npm:^2.1.1"
     "@eslint/js": "npm:^10.0.1"
-    "@pezkuwi/dev-test": "npm:^0.86.8"
+    "@pezkuwi/dev-test": "npm:^0.86.9"
-    "@pezkuwi/dev-ts": "npm:^0.86.8"
+    "@pezkuwi/dev-ts": "npm:^0.86.9"
     "@rollup/plugin-alias": "npm:^5.1.1"
     "@rollup/plugin-commonjs": "npm:^29.0.3"
     "@rollup/plugin-dynamic-import-vars": "npm:^2.1.5"