@git.zone/tspublish 1.11.6 → 1.12.1

package/ts/classes.publishmodule.ts

@@ -2,7 +2,7 @@ import * as plugins from './plugins.js';
 import * as paths from './paths.js';
 import { logger, logInfo, logSuccess, logWarn, logError, logBuild, logPublish, logOngoing, logStart, logDone } from './logging.js';
 
-import { type ITsPublishJson } from './interfaces/index.js';
+import { type ITsPublishJson, type ITsPublishModulePlan } from './interfaces/index.js';
 import type { TsPublish } from './classes.tspublish.js';
 
 export interface IPublishModuleOptions {
@@ -14,6 +14,7 @@ export interface IPublishModuleOptions {
   name?: string;
   version?: string;
   dependencies?: { [key: string]: string };
+  modulePlan?: ITsPublishModulePlan;
 }
 
 export interface IResolvedRegistry {
@@ -48,20 +49,10 @@ export class PublishModule {
     const packageJsonContent = await plugins.smartfs.file(packageJsonPath).encoding('utf8').read();
     const monoRepoPackageJson = JSON.parse(packageJsonContent as string);
 
-    this.options.dependencies = {
-      ...this.options.dependencies,
-      ...(() => {
-        const resultDependencies: Record<string, string> = {};
-        for (const dependency of this.options.tsPublishJson!.dependencies) {
-          if (monoRepoPackageJson.dependencies[dependency]) {
-            resultDependencies[dependency] = monoRepoPackageJson.dependencies[dependency];
-          } else {
-            resultDependencies[dependency] = monoRepoPackageJson.version;
-          }
-        }
-        return resultDependencies;
-      })(),
-    };
+    this.options.modulePlan ??= (await this.tsPublishRef.plan(this.options.monoRepoDir)).modules
+      .find((module) => module.folder === this.options.packageSubFolder);
+    if (!this.options.modulePlan) throw new Error('Missing publish module plan.');
+    this.options.dependencies = this.options.modulePlan.manifest.dependencies;
     this.options.name = this.options.name || this.options.tsPublishJson!.name;
     this.options.version = monoRepoPackageJson.version;
 
@@ -81,7 +72,7 @@ export class PublishModule {
         logError(
           `Package ${this.options.name} already exists with version ${this.options.version}`
         );
-        process.exit(1);
+        throw new Error(`Package ${this.options.name} already exists with version ${this.options.version}.`);
       }
     }
   }
@@ -126,44 +117,18 @@ export class PublishModule {
   }
 
   public async createPackageJson() {
+    if (!this.options.modulePlan) throw new Error('Publish module must be initialized first.');
+    const rootManifest = JSON.parse(await plugins.fs.readFile(plugins.path.join(this.options.monoRepoDir, 'package.json'), 'utf8'));
+    const buildVersion = rootManifest.devDependencies?.['@git.zone/tsbuild'] ?? rootManifest.dependencies?.['@git.zone/tsbuild'];
+    if (typeof buildVersion !== 'string' || !buildVersion) throw new Error('Publishing requires a declared @git.zone/tsbuild version.');
     const packageJson = {
-      name: this.options.name,
-      version: this.options.version,
-      type: 'module',
-      description: '',
-      exports: {
-        '.': {
-          import: `./dist_${this.options.packageSubFolder}/index.js`,
-        },
-      },
+      ...this.options.modulePlan.manifest,
       scripts: {
         build: 'tsbuild tsfolders',
       },
-      dependencies: this.options.dependencies,
       devDependencies: {
-        '@git.zone/tsbuild': await this.getLatestVersionOfPackage('@git.zone/tsbuild'),
+        '@git.zone/tsbuild': buildVersion,
       },
-      files: [
-        'ts/**/*',
-        'ts_*/**/*',
-        'dist/**/*',
-        'dist_*/**/*',
-        'dist_ts/**/*',
-        'dist_ts_web/**/*',
-        'assets/**/*',
-        'cli.js',
-        '.smartconfig.json',
-        'readme.md',
-      ],
-      ...this.options.tsPublishJson?.bin ? {
-        bin: (() => {
-          const binObject: {[key: string]: string} = {};
-          for (const bin of this.options.tsPublishJson!.bin) {
-            binObject[bin] = `./cli.js`;
-          }
-          return binObject;
-        })()
-      } : {},
     };
     return JSON.stringify(packageJson, null, 2);
   }
@@ -191,8 +156,13 @@ export class PublishModule {
     await plugins.smartfs.file(tsconfigJsonPath).encoding('utf8').write(await this.createTsconfigJson());
 
     // ts subfolder, the folder that contains the source code and is being transpiled
-    const destSubFolder = plugins.path.join(this.options.publishModDirFullPath, this.options.packageSubFolder);
-    await plugins.smartfs.directory(this.options.packageSubFolderFullPath!).recursive().copy(destSubFolder);
+    for (const folder of this.options.modulePlan!.folders) {
+      await plugins.smartfs.directory(plugins.path.join(this.options.monoRepoDir, folder)).recursive()
+        .copy(plugins.path.join(this.options.publishModDirFullPath, folder));
+    }
+    for (const path of this.options.modulePlan!.include) {
+      await plugins.fs.cp(plugins.path.join(this.options.monoRepoDir, path), plugins.path.join(this.options.publishModDirFullPath, path), { recursive: true });
+    }
 
     // readme
     const readmeSrc = plugins.path.join(this.options.packageSubFolderFullPath!, 'readme.md');
@@ -200,12 +170,12 @@ export class PublishModule {
     await plugins.smartfs.file(readmeSrc).copy(readmeDest);
 
     // license
-    const licenseSrc = plugins.path.join(this.options.monoRepoDir, 'license');
-    const licenseDest = plugins.path.join(this.options.publishModDirFullPath, 'license');
+    const licenseSrc = plugins.path.join(this.options.monoRepoDir, this.options.modulePlan!.licenseFile);
+    const licenseDest = plugins.path.join(this.options.publishModDirFullPath, this.options.modulePlan!.licenseFile);
     await plugins.smartfs.file(licenseSrc).copy(licenseDest);
 
     // cli stuff
-    this.createBinCliSetup();
+    await this.createBinCliSetup();
   }
 
   public async build() {
@@ -222,13 +192,9 @@ export class PublishModule {
       !!this.options.tsPublishJson?.bin &&
       Array.isArray(this.options.tsPublishJson!.bin) &&
       this.options.tsPublishJson!.bin.length > 0;
-    const files = await this.tsPublishRef.giteaAssetsInstance.getFiles(
-      'git.zone',
-      'cli',
-      'assets/templates/cli/cli.js'
-    );
+    if (!binSetupApplies) return;
     const indexPath = `./dist_${this.options.packageSubFolder}/index.js`;
-    const fileContent = atob(files[0].base64Content!).replace('./dist_ts/index.js', indexPath);
+    const fileContent = `#!/usr/bin/env node\nprocess.env.CLI_CALL = 'true';\nconst cliTool = await import(${JSON.stringify(indexPath)});\nawait cliTool.runCli();\n`;
     const cliJsPath = plugins.path.join(this.options.publishModDirFullPath!, 'cli.js');
     await plugins.smartfs.file(cliJsPath).encoding('utf8').write(fileContent);
   }
@@ -258,8 +224,8 @@ export class PublishModule {
     if (hasUseBase || hasExtendBase) {
       const smartconfigInstance = new plugins.smartconfig.Smartconfig(this.options.monoRepoDir);
       const gitzoneConfig = smartconfigInstance.dataFor<any>('@git.zone/cli', {});
-      baseRegistries = gitzoneConfig?.release?.registries || [];
-      baseAccessLevel = gitzoneConfig?.release?.accessLevel || 'public';
+      baseRegistries = gitzoneConfig?.release?.targets?.npm?.registries ?? gitzoneConfig?.release?.registries ?? [];
+      baseAccessLevel = gitzoneConfig?.release?.targets?.npm?.accessLevel ?? gitzoneConfig?.release?.accessLevel ?? 'public';
 
       if (baseRegistries.length === 0) {
         throw new Error(

package/ts/classes.tspublish.ts

@@ -4,6 +4,8 @@ import * as interfaces from './interfaces/index.js';
 
 import { PublishModule } from './classes.publishmodule.js';
 import { GiteaAssets } from './classes.giteaassets.js';
+import { createPackagePlan, orderPublishModules } from './functions.packageplan.js';
+import { PackagePreparer } from './classes.packagepreparer.js';
 
 export class TsPublish {
   public giteaAssetsInstance: GiteaAssets;
@@ -17,6 +19,7 @@ export class TsPublish {
   public async publish(monorepoDirArg: string) {
     logHeader('TSPublish - Module Publisher');
     const publishModules = await this.getModuleSubDirs(monorepoDirArg);
+    const plan = await createPackagePlan(monorepoDirArg, publishModules);
     logInfo(`Found ${Object.keys(publishModules).length} publish modules`);
     logSeparator();
     for (const publishModule of Object.keys(publishModules)) {
@@ -31,6 +34,7 @@ export class TsPublish {
       const publishModuleInstance = new PublishModule(this, {
         monoRepoDir: monorepoDirArg,
         packageSubFolder: publishModule,
+        modulePlan: plan.modules.find((module) => module.folder === publishModule),
       });
       const moduleCount = Object.keys(publishModules).indexOf(publishModule) + 1;
       const totalCount = Object.keys(publishModules).length;
@@ -42,6 +46,17 @@ export class TsPublish {
     }
   }
 
+  /** Read-only package discovery, dependency ordering and manifest validation. */
+  public async plan(directory: string): Promise<interfaces.ITsPublishPlan> {
+    return createPackagePlan(directory, await this.getModuleSubDirs(directory));
+  }
+
+  /** Prepare built modules for a release owner; never publishes or contacts a registry. */
+  public async prepare(directory: string, outputDirectory: string): Promise<interfaces.ITsPublishPreparedModule[]> {
+    const plan = await this.plan(directory);
+    return new PackagePreparer(directory).prepare(plan, outputDirectory);
+  }
+
   public async getModuleSubDirs(dirArg: string) {
     // List all directories
     const dirContents = await plugins.smartfs.directory(dirArg).list();
@@ -68,6 +83,6 @@ export class TsPublish {
     logSuccess(`Found ${Object.keys(publishModules).length} publish modules`);
     logInfo('Ordering publish modules...');
 
-    return publishModules;
+    return orderPublishModules(publishModules);
   }
 }

package/ts/functions.packageplan.ts

@@ -0,0 +1,182 @@
+import * as plugins from './plugins.js';
+import type { ITsPublishJson, ITsPublishManifest, ITsPublishPlan, TTsPublishExport } from './interfaces/index.js';
+
+const packageNamePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const folderPattern = /^ts(?:_[a-z0-9_]+)?$/;
+
+export const assertPackagePath = (value: string): void => {
+  if (typeof value !== 'string' || !value || value.includes('\\')
+    || value.split('/').some((part) => !part || part === '.' || part === '..')
+    || /[\x00-\x1f\x7f*?]/.test(value) || plugins.path.isAbsolute(value)) {
+    throw new Error(`Invalid package-relative path: ${value}`);
+  }
+};
+
+const record = (value: unknown, label: string): Record<string, unknown> => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Invalid ${label}.`);
+  return value as Record<string, unknown>;
+};
+
+const dependencyNames = (value: unknown, label: string): string[] => {
+  if (!Array.isArray(value) || value.some((name) => typeof name !== 'string' || !packageNamePattern.test(name))
+    || new Set(value).size !== value.length) throw new Error(`Invalid ${label}.`);
+  return value;
+};
+
+const assertVersionReference = (value: unknown, name: string): string => {
+  if (typeof value !== 'string' || !value.trim() || /^(?:file|link|workspace):/.test(value)) {
+    throw new Error(`Missing or unsupported published dependency version for ${name}.`);
+  }
+  return value;
+};
+
+const stringRecord = (value: unknown, label: string): Record<string, string> => {
+  const result = record(value, label);
+  if (Object.values(result).some((entry) => typeof entry !== 'string' || !entry.trim())) throw new Error(`Invalid ${label}.`);
+  return result as Record<string, string>;
+};
+
+const legacyEntry = (value: TTsPublishExport, kind: 'main' | 'types'): string | undefined => {
+  if (typeof value === 'string') return kind === 'main' ? value : undefined;
+  if (value === null) return undefined;
+  if (kind === 'types' && typeof value.types === 'string') return value.types;
+  for (const condition of ['node', 'import', 'default']) {
+    if (value[condition] !== undefined) {
+      const result = legacyEntry(value[condition], kind);
+      if (result) return result;
+    }
+  }
+  return undefined;
+};
+
+export const orderPublishModules = (
+  modules: Record<string, ITsPublishJson>,
+): Record<string, ITsPublishJson> => {
+  const names = new Map<string, string>();
+  for (const [folder, config] of Object.entries(modules)) {
+    if (config.order !== undefined && !Number.isFinite(config.order)) throw new Error(`Invalid order for ${folder}.`);
+    if (config.name) {
+      if (!packageNamePattern.test(config.name) || names.has(config.name)) throw new Error(`Invalid or duplicate package name: ${config.name}`);
+      names.set(config.name, folder);
+    }
+  }
+  const pending = new Set(Object.keys(modules));
+  const ordered: Record<string, ITsPublishJson> = {};
+  while (pending.size) {
+    const ready = [...pending].filter((folder) =>
+      [...(modules[folder].dependencies ?? []), ...(modules[folder].optionalDependencies ?? [])]
+        .every((name) => !names.has(name) || !pending.has(names.get(name)!)),
+    ).sort((a, b) => (modules[a].order ?? Number.MAX_SAFE_INTEGER) - (modules[b].order ?? Number.MAX_SAFE_INTEGER)
+      || a.localeCompare(b, 'en'));
+    if (!ready.length) throw new Error(`Cyclic publish dependencies: ${[...pending].join(', ')}`);
+    const folder = ready[0];
+    ordered[folder] = modules[folder];
+    pending.delete(folder);
+  }
+  return ordered;
+};
+
+const validateExport = (value: TTsPublishExport, folders: string[]): void => {
+  if (value === null) return;
+  if (typeof value === 'string') {
+    if (!value.startsWith('./')) throw new Error('Package export targets must be relative.');
+    assertPackagePath(value.slice(2));
+    if (!folders.some((folder) => value.startsWith(`./dist_${folder}/`))) {
+      throw new Error(`Export target is outside this package's compiled folders: ${value}`);
+    }
+    return;
+  }
+  for (const child of Object.values(record(value, 'export conditions'))) validateExport(child as TTsPublishExport, folders);
+};
+
+export const createPackagePlan = async (
+  directory: string,
+  discovered: Record<string, ITsPublishJson>,
+): Promise<ITsPublishPlan> => {
+  const root = record(JSON.parse(await plugins.fs.readFile(plugins.path.join(directory, 'package.json'), 'utf8')), 'root manifest');
+  if (typeof root.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(root.version)) {
+    throw new Error('The repository requires a concrete package version.');
+  }
+  const ordered = orderPublishModules(discovered);
+  const names = new Set(Object.values(ordered).map((config) => config.name).filter(Boolean));
+  const owners = new Set<string>();
+  const rootDependencies = record(root.dependencies ?? {}, 'root dependencies');
+  const version = root.version;
+  let licenseFile = 'license.md';
+  try { await plugins.fs.access(plugins.path.join(directory, licenseFile)); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    licenseFile = 'license';
+    await plugins.fs.access(plugins.path.join(directory, licenseFile));
+  }
+  const modules: ITsPublishPlan['modules'] = [];
+  for (const [folder, config] of Object.entries(ordered)) {
+    if (!config.name) continue; // tsbuild also consumes order-only descriptors.
+    const folders = [folder, ...(config.folders ?? [])];
+    if (folders.some((name) => !folderPattern.test(name) || owners.has(name)) || new Set(folders).size !== folders.length) {
+      throw new Error(`Invalid or multiply owned source folder for ${config.name}.`);
+    }
+    folders.forEach((name) => owners.add(name));
+    const resolveDependencies = (value: unknown, label: string): Record<string, string> => Object.fromEntries(
+      dependencyNames(value, label).map((name) => [name, names.has(name)
+        ? version : assertVersionReference(rootDependencies[name], name)]),
+    );
+    const dependencies = resolveDependencies(config.dependencies ?? [], `${config.name} dependencies`);
+    const optionalDependencies = config.optionalDependencies
+      ? resolveDependencies(config.optionalDependencies, `${config.name} optional dependencies`) : undefined;
+    for (const [name, range] of Object.entries(stringRecord(config.peerDependencies ?? {}, 'peer dependencies'))) {
+      if (!packageNamePattern.test(name)) throw new Error(`Invalid peer dependency: ${name}`);
+      assertVersionReference(range, name);
+    }
+    for (const [name, metadataValue] of Object.entries(record(config.peerDependenciesMeta ?? {}, 'peer metadata'))) {
+      const metadata = record(metadataValue, 'peer metadata');
+      if (!(name in (config.peerDependencies ?? {})) || Object.keys(record(metadata, 'peer metadata')).some((key) => key !== 'optional')
+        || (metadata.optional !== undefined && typeof metadata.optional !== 'boolean')) throw new Error(`Invalid peer metadata for ${name}.`);
+    }
+    const exports = record(config.exports ?? { '.': { types: `./dist_${folder}/index.d.ts`, import: `./dist_${folder}/index.js` } }, 'package exports') as Record<string, TTsPublishExport>;
+    for (const [key, target] of Object.entries(exports)) {
+      if (key !== '.' && !key.startsWith('./')) throw new Error(`Invalid package export: ${key}`);
+      if (key !== '.') assertPackagePath(key.slice(2));
+      validateExport(target, folders);
+    }
+    if (!exports['.']) throw new Error(`${config.name} requires a root export.`);
+    const include = config.include ?? [];
+    if (!Array.isArray(include) || new Set(include).size !== include.length) throw new Error('Invalid package include paths.');
+    include.forEach(assertPackagePath);
+    if (include.some((path) => ['package.json', 'readme.md', 'cli.js', 'node_modules', '.git'].includes(path.split('/')[0])
+      || folderPattern.test(path.split('/')[0]) || /^dist_ts(?:_[a-z0-9_]+)?$/.test(path.split('/')[0])
+      || folders.some((folder) => path === folder || path.startsWith(`${folder}/`) || path === `dist_${folder}` || path.startsWith(`dist_${folder}/`)))) {
+      throw new Error('Explicit includes cannot replace generated package files or source folders.');
+    }
+    const bin = config.bin ?? [];
+    if (!Array.isArray(bin) || bin.some((name) => typeof name !== 'string' || !/^[a-z0-9][a-z0-9._-]*$/.test(name))) throw new Error('Invalid package binaries.');
+    const metadata = Object.fromEntries(['author', 'license', 'repository', 'homepage', 'bugs', 'keywords', 'funding'].filter((key) => root[key] !== undefined).map((key) => [key, root[key]]));
+    const description = config.description ?? root.description ?? '';
+    if (typeof description !== 'string') throw new Error('Invalid package description.');
+    const engines = config.engines ?? root.engines;
+    if (engines !== undefined) stringRecord(engines, 'package engines');
+    if (config.sideEffects !== undefined && typeof config.sideEffects !== 'boolean'
+      && (!Array.isArray(config.sideEffects) || config.sideEffects.some((value) => typeof value !== 'string' || !value.trim()))) {
+      throw new Error('Invalid sideEffects metadata.');
+    }
+    const main = legacyEntry(exports['.'], 'main');
+    const types = legacyEntry(exports['.'], 'types');
+    const manifest: ITsPublishManifest = {
+      ...metadata, name: config.name, version, type: 'module', description,
+      ...(main ? { main } : {}), ...(types ? { types } : {}), exports, dependencies,
+      ...(optionalDependencies ? { optionalDependencies } : {}),
+      ...(config.peerDependencies ? { peerDependencies: config.peerDependencies } : {}),
+      ...(config.peerDependenciesMeta ? { peerDependenciesMeta: config.peerDependenciesMeta } : {}),
+      ...(engines !== undefined ? { engines: engines as Record<string, string> } : {}),
+      ...(config.sideEffects !== undefined ? { sideEffects: config.sideEffects } : {}),
+      ...(bin.length ? { bin: Object.fromEntries(bin.map((name) => [name, './cli.js'])) } : {}),
+      files: [...folders.flatMap((name) => [name, `dist_${name}`]), ...include, 'readme.md', licenseFile, ...(bin.length ? ['cli.js'] : [])],
+    };
+    if (config.registries !== undefined && (!Array.isArray(config.registries) || config.registries.some((registry) => typeof registry !== 'string' || !registry.trim() || registry !== registry.trim() || /[\x00-\x1f\x7f]/.test(registry)))) {
+      throw new Error(`Invalid registry declarations for ${config.name}.`);
+    }
+    modules.push({ folder, folders, name: config.name, version, order: modules.length, manifest, include, licenseFile, registries: config.registries ?? [] });
+  }
+  if (!modules.length) throw new Error('No named tspublish modules were found.');
+  return { schemaVersion: 1, version, modules };
+};

package/ts/index.ts

@@ -3,9 +3,19 @@ import { TsPublish } from './classes.tspublish.js';
 import { logStart } from './logging.js';
 
 export * from './classes.tspublish.js';
+export type * from './interfaces/index.js';
 
 export const runCli = async () => {
   logStart('tspublish');
   const tspublish = new TsPublish();
-  await tspublish.publish(paths.cwd);
+  const args = process.argv.slice(2);
+  if (args[0] === 'plan' && args.length === 1) {
+    console.log(JSON.stringify(await tspublish.plan(paths.cwd), null, 2));
+  } else if (args[0] === 'prepare' && args.length === 2) {
+    console.log(JSON.stringify(await tspublish.prepare(paths.cwd, args[1]), null, 2));
+  } else if (args.length === 0) {
+    await tspublish.publish(paths.cwd);
+  } else {
+    throw new Error('Usage: tspublish [plan | prepare <new-output-directory>]');
+  }
 };

package/ts/interfaces/tspublish.ts

@@ -10,4 +10,59 @@ export interface ITsPublishJson {
    * allows the sepcification of bin names that invoke cli scripts
    */
   bin: string[];
+  description?: string;
+  /** Additional source folders owned by this package, for example subpath exports. */
+  folders?: string[];
+  exports?: Record<string, TTsPublishExport>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  optionalDependencies?: string[];
+  engines?: Record<string, string>;
+  sideEffects?: boolean | string[];
+  /** Explicit repository-relative asset files/directories to include unchanged. */
+  include?: string[];
+}
+
+export type TTsPublishExport = string | null | { [condition: string]: TTsPublishExport };
+
+export interface ITsPublishManifest {
+  name: string;
+  version: string;
+  type: 'module';
+  description: string;
+  main?: string;
+  types?: string;
+  exports: Record<string, TTsPublishExport>;
+  dependencies: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  engines?: Record<string, string>;
+  sideEffects?: boolean | string[];
+  bin?: Record<string, string>;
+  files: string[];
+  [key: string]: unknown;
+}
+
+export interface ITsPublishModulePlan {
+  folder: string;
+  folders: string[];
+  name: string;
+  version: string;
+  /** Position in the deterministic dependency order. */
+  order: number;
+  manifest: ITsPublishManifest;
+  include: string[];
+  licenseFile: string;
+  registries: string[];
+}
+
+export interface ITsPublishPlan {
+  schemaVersion: 1;
+  version: string;
+  modules: ITsPublishModulePlan[];
+}
+
+export interface ITsPublishPreparedModule extends ITsPublishModulePlan {
+  directory: string;
 }

package/ts/plugins.ts

@@ -1,6 +1,9 @@
 // node native scope
-import * as path from 'path';
-export { path };
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { isBuiltin } from 'node:module';
+import * as typescript from 'typescript';
+export { path, fs, isBuiltin, typescript };
 
 // @push.rocks scope
 import * as consolecolor from '@push.rocks/consolecolor';