@fuman/build 0.0.1 → 0.0.3

package/ci/github-actions.d.ts

@@ -1,3 +1,6 @@
+/** are we running in github actions? */
 export declare function isRunningInGithubActions(): boolean;
+/** get the value of a github actions input */
 export declare function getGithubActionsInput(name: string): string | undefined;
+/** set the value of a github actions output */
 export declare function writeGithubActionsOutput(name: string, value: string): void;

package/cli/commands/build.d.ts

@@ -1,10 +1,22 @@
 import { WorkspacePackage } from '../../package-json/collect-package-jsons.js';
 import { bc } from './_utils.js';
+/**
+ * build a single package using vite
+ *
+ * tiny wrapper on top of `vite build`
+ */
 export declare function buildPackage(params: {
+    /** path to the workspace root */
     workspaceRoot: string;
+    /**
+     * list of workspace packages **including root**
+     */
     workspace?: WorkspacePackage[];
+    /** name of the package to build */
     packageName: string;
+    /** path to the `build.config.js` file */
     configPath?: string;
+    /** "fixed" version to use when building the package */
     fixedVersion?: string;
 }): Promise<void>;
 export declare const buildPackageCli: bc.Command<{

package/cli/commands/bump-version.js

@@ -16,8 +16,8 @@ function formatBumpVersionResult(result, withReleaseType) {
   lines.push(`next version: ${result.nextVersion}`);
   lines.push("");
   lines.push("list of changed packages:");
-  for (const { package: pkg, because } of result.changedPackages) {
-    lines.push(`  ${pkg.json.name}${because ? ` (because of ${because.join(", ")})` : ""}: ${pkg.json.version} → ${result.nextVersion}`);
+  for (const { package: pkg, because, prevVersion } of result.changedPackages) {
+    lines.push(`  ${pkg.json.name}${because ? ` (because of ${because.join(", ")})` : ""}: ${prevVersion} → ${pkg.json.version}`);
   }
   return lines.join("\n");
 }

package/cli/commands/docs.d.ts

@@ -0,0 +1,11 @@
+import { bc } from './_utils.js';
+/** generate documentation using typedoc for the workspace */
+export declare function generateDocs(params: {
+    /** path to the workspace root */
+    workspaceRoot: string;
+}): Promise<void>;
+export declare const generateDocsCli: bc.Command<{
+    root: string | undefined;
+}, {
+    root: string | undefined;
+}>;

package/cli/commands/docs.js

@@ -0,0 +1,132 @@
+import process from "node:process";
+import { asNonNull } from "@fuman/utils";
+import * as td from "typedoc";
+import { loadBuildConfig } from "../../misc/_config.js";
+import { collectPackageJsons } from "../../package-json/collect-package-jsons.js";
+import { processPackageJson } from "../../package-json/process-package-json.js";
+import * as bc from "@drizzle-team/brocli";
+const CUSTOM_ROOT_FIELDS = [
+  "includePackages",
+  "excludePackages"
+];
+const DEFAULT_CONFIG = {
+  includeVersion: true,
+  validation: {
+    notExported: true,
+    invalidLink: true,
+    notDocumented: false
+  },
+  excludePrivate: true,
+  excludeExternals: true,
+  excludeInternal: true,
+  exclude: [
+    "**/*/node_modules",
+    "**/*.test.ts",
+    "**/*.test-utils.ts"
+  ]
+};
+class FumanTypedocReader {
+  constructor(workspaceRoot) {
+    this.workspaceRoot = workspaceRoot;
+  }
+  name = "@fuman/build";
+  order = 0;
+  // before any other readers
+  supportsPackages = true;
+  _workspace;
+  _rootConfig;
+  _forwardOptions(options, config, cwd) {
+    for (const [key, val] of Object.entries(config)) {
+      if (CUSTOM_ROOT_FIELDS.includes(key)) continue;
+      options.setValue(key, val, cwd);
+    }
+  }
+  async read(options, logger, cwd) {
+    if (cwd === this.workspaceRoot) {
+      const config = await loadBuildConfig(cwd);
+      this._rootConfig = config;
+      const data2 = config?.typedoc;
+      if (data2 != null) this._forwardOptions(options, data2, cwd);
+      options.setValue("entryPointStrategy", "packages");
+      this._workspace = await collectPackageJsons(cwd);
+      const entrypoints2 = [];
+      for (const pkg2 of this._workspace) {
+        const pkgName = asNonNull(pkg2.json.name);
+        if (data2?.includePackages && !data2.includePackages.includes(pkgName)) continue;
+        if (data2?.excludePackages?.includes(pkgName)) continue;
+        if (pkg2.json.exports != null && !data2?.includePackages?.includes(pkgName)) continue;
+        entrypoints2.push(pkg2.path);
+      }
+      options.setValue("entryPoints", entrypoints2, cwd);
+      return;
+    }
+    const rootConfig = asNonNull(this._rootConfig);
+    if (rootConfig.typedoc != null) this._forwardOptions(options, rootConfig.typedoc, cwd);
+    const pkg = asNonNull(this._workspace?.find((pkg2) => pkg2.path.replace(/\/$/, "") === cwd.replace(/\/$/, "")));
+    const pkgConfig = await loadBuildConfig(cwd);
+    const hookContext = {
+      outDir: "",
+      packageDir: pkg.path,
+      packageName: asNonNull(pkg.json.name),
+      packageJson: pkg.json,
+      jsr: false,
+      typedoc: true
+    };
+    pkgConfig?.preparePackageJson?.(hookContext);
+    const { entrypoints } = processPackageJson({ packageJson: pkg.json, onlyEntrypoints: true });
+    options.setValue("entryPoints", Object.values(entrypoints), cwd);
+    if (!pkgConfig?.typedoc) return;
+    let data = pkgConfig.typedoc;
+    if (typeof data === "function") {
+      data = data(options.getRawValues());
+    }
+    this._forwardOptions(options, data, cwd);
+  }
+}
+async function generateDocs(params) {
+  const app = await td.Application.bootstrapWithPlugins(DEFAULT_CONFIG, [
+    new FumanTypedocReader(params.workspaceRoot),
+    new td.TSConfigReader(),
+    new td.TypeDocReader()
+  ]);
+  const project = await app.convert();
+  if (!project) {
+    throw new Error("Could not convert to typedoc project");
+  }
+  if (app.options.getValue("treatWarningsAsErrors") && app.logger.hasWarnings()) {
+    throw new Error("There were warnings while converting the project");
+  }
+  const preValidationWarnCount = app.logger.warningCount;
+  app.validate(project);
+  const hadValidationWarnings = app.logger.warningCount !== preValidationWarnCount;
+  if (app.logger.hasErrors()) {
+    throw new Error("There were errors while validating the project");
+  }
+  if (hadValidationWarnings && (app.options.getValue("treatWarningsAsErrors") || app.options.getValue("treatValidationWarningsAsErrors"))) {
+    throw new Error("There were warnings while validating the project");
+  }
+  if (app.options.getValue("emit") === "none") return;
+  await app.generateOutputs(project);
+  if (app.logger.hasErrors()) {
+    throw new Error("There were errors while generating the outputs");
+  }
+  if (app.options.getValue("treatWarningsAsErrors") && app.logger.hasWarnings()) {
+    throw new Error("There were warnings while generating the outputs");
+  }
+}
+const generateDocsCli = bc.command({
+  name: "typedoc",
+  desc: "generate docs using typedoc",
+  options: {
+    root: bc.string().desc("path to the root of the workspace (default: cwd)")
+  },
+  handler: async (args) => {
+    await generateDocs({
+      workspaceRoot: args.root ?? process.cwd()
+    });
+  }
+});
+export {
+  generateDocs,
+  generateDocsCli
+};

package/cli/commands/gen-deps-graph.d.ts

@@ -1,7 +1,11 @@
 import { bc } from './_utils.js';
+/** generate a graphviz dot file of the workspace dependencies */
 export declare function generateDepsGraph(params: {
+    /** path to the workspace root */
     workspaceRoot: string | URL;
+    /** whether to include the root package.json in the graph */
     includeRoot?: boolean;
+    /** whether to include external dependencies in the graph */
     includeExternal?: boolean;
 }): Promise<string>;
 export declare const generateDepsGraphCli: bc.Command<{

package/cli/commands/release.d.ts

@@ -4,6 +4,7 @@ export declare const releaseCli: bc.Command<{
     withGithubRelease: boolean;
     githubToken: string | undefined;
     githubRepo: string | undefined;
+    githubApiUrl: string | undefined;
     withJsr: boolean;
     jsrRegistry: string | undefined;
     jsrToken: string | undefined;
@@ -20,6 +21,7 @@ export declare const releaseCli: bc.Command<{
     withGithubRelease: boolean;
     githubToken: string | undefined;
     githubRepo: string | undefined;
+    githubApiUrl: string | undefined;
     withJsr: boolean;
     jsrRegistry: string | undefined;
     jsrToken: string | undefined;

package/cli/commands/release.js

@@ -5,7 +5,7 @@ import { nodeReadableToWeb } from "@fuman/node";
 import { asNonNull, notImplemented } from "@fuman/utils";
 import { sort } from "semver";
 import { createGithubRelease } from "../../git/github.js";
-import { getLatestTag, getFirstCommit } from "../../git/utils.js";
+import { getLatestTag, getFirstCommit, gitTagExists } from "../../git/utils.js";
 import { jsrCreatePackages } from "../../jsr/create-packages.js";
 import { generateDenoWorkspace } from "../../jsr/generate-workspace.js";
 import { exec } from "../../misc/exec.js";
@@ -24,6 +24,7 @@ const releaseCli = bc.command({
     withGithubRelease: bc.boolean("with-github-release").desc("whether to create a github release (requires GITHUB_TOKEN env var). if false, will only create a commit with the release notes").default(false),
     githubToken: bc.string("github-token").desc("github token to use for creating a release (defaults to GITHUB_TOKEN env var)"),
     githubRepo: bc.string("github-repo").desc("github repo to create a release for (defaults to GITHUB_REPOSITORY env var)"),
+    githubApiUrl: bc.string("github-api-url").desc("github api url to use for creating a release (for github-compatible apis)"),
     withJsr: bc.boolean("with-jsr").desc("whether to publish to jsr").default(false),
     jsrRegistry: bc.string("jsr-registry").desc("URL of the jsr registry to publish to"),
     jsrToken: bc.string("jsr-token").desc("jsr token to use for publishing"),
@@ -63,14 +64,32 @@ const releaseCli = bc.command({
         dryRun: args.dryRun
       });
       changedPackages = bumpVersionResult.changedPackages.map((pkg) => pkg.package);
-      if (bumpVersionResult.changedPackages.length === 0) {
+      if (changedPackages.length === 0) {
         console.log("🤔 no packages changed, nothing to do");
         process.exit(1);
       }
       console.log(formatBumpVersionResult(bumpVersionResult, args.kind === "auto"));
+      for (const pkg of changedPackages) {
+        const inWorkspace = asNonNull(workspace.find((it) => it.json.name === pkg.json.name));
+        inWorkspace.json.version = pkg.json.version;
+      }
     } else {
       changedPackages = workspace;
     }
+    let tagName;
+    if (!bumpVersionResult) {
+      const versions = sort(workspace.map((pkg) => asNonNull(pkg.json.version)));
+      tagName = `v${versions[versions.length - 1]}`;
+    } else {
+      tagName = `v${bumpVersionResult.nextVersion}`;
+    }
+    if (await gitTagExists(tagName, root)) {
+      console.log(`❗ tag ${tagName} already exists. did the previous release complete successfully?`);
+      console.log("❗ if so, please verify versions in package.json and try again");
+      if (!args.dryRun) {
+        process.exit(1);
+      }
+    }
     console.log("");
     console.log("📝 generating changelog...");
     const changelog = prevTag != null ? await generateChangelog({
@@ -154,17 +173,10 @@ const releaseCli = bc.command({
       });
       console.log("\x1B[;32m✅ published to jsr\x1B[;0m");
     }
-    let tagName;
-    if (!bumpVersionResult) {
-      const versions = sort(workspace.map((pkg) => asNonNull(pkg.json.version)));
-      tagName = `v${versions[versions.length - 1]}`;
-    } else {
-      tagName = `v${bumpVersionResult.nextVersion}`;
-    }
     if (args.dryRun) {
       console.log("dry run, skipping release commit and tag");
     } else {
-      let message = tagName;
+      let message = `chore(release): ${tagName}`;
       if (!args.withGithubRelease) {
         message += `
 

package/cli/commands/validate-workspace-deps.d.ts

@@ -1,4 +1,5 @@
 import { bc } from './_utils.js';
+/** information about a mismatch between a package and its dependencies */
 export interface WorkspaceDepsError {
     /** package name where the mismatch occurred */
     package: string;
@@ -13,7 +14,12 @@ export interface WorkspaceDepsError {
     /** original version of the dependency */
     otherVersion: string;
 }
-export declare function validateWorkspaceDeps(workspaceRoot: string | URL, params?: {
+/**
+ * validate the external dependencies of a workspace
+ */
+export declare function validateWorkspaceDeps(params: {
+    /** path to the workspace root */
+    workspaceRoot: string | URL;
     /**
      * whether to also validate the root package.json
      *

package/cli/commands/validate-workspace-deps.js

@@ -2,8 +2,12 @@ import process from "node:process";
 import { satisfies } from "semver";
 import { collectPackageJsons } from "../../package-json/collect-package-jsons.js";
 import * as bc from "@drizzle-team/brocli";
-async function validateWorkspaceDeps(workspaceRoot, params) {
-  const { includeRoot = true, skipWorkspaceDeps = true } = params || {};
+async function validateWorkspaceDeps(params) {
+  const {
+    workspaceRoot,
+    includeRoot = true,
+    skipWorkspaceDeps = true
+  } = params;
   const pjs = await collectPackageJsons(workspaceRoot, includeRoot);
   const workspacePackages = new Set(skipWorkspaceDeps ? pjs.map((pj) => pj.json.name) : []);
   const versions = {};
@@ -48,7 +52,8 @@ const validateWorkspaceDepsCli = bc.command({
     root: bc.string().desc("path to the root of the workspace (default: cwd)")
   },
   handler: async (args) => {
-    const errors = await validateWorkspaceDeps(args.root ?? process.cwd(), {
+    const errors = await validateWorkspaceDeps({
+      workspaceRoot: args.root ?? process.cwd(),
       includeRoot: args.includeRoot,
       skipWorkspaceDeps: !args.noSkipWorkspaceDeps
     });

package/cli/index.d.ts

@@ -1,3 +1,4 @@
 export { buildPackage } from './commands/build.js';
+export { generateDocs } from './commands/docs.js';
 export { generateDepsGraph } from './commands/gen-deps-graph.js';
-export { validateWorkspaceDeps } from './commands/validate-workspace-deps.js';
+export { validateWorkspaceDeps, type WorkspaceDepsError } from './commands/validate-workspace-deps.js';

package/config.d.ts

@@ -1,6 +1,9 @@
+import { AnyToNever } from '@fuman/utils';
+import { TypeDocOptions } from 'typedoc';
 import { JsrConfig } from './jsr/config.js';
 import { PackageJson } from './package-json/types.js';
 import { VersioningOptions } from './versioning/types.js';
+/** context object that is passed to each build hook */
 export interface BuildHookContext {
     /** full path to the output directory */
     outDir: string;
@@ -15,7 +18,10 @@ export interface BuildHookContext {
     packageJson: PackageJson;
     /** whether this is a jsr build */
     jsr: boolean;
+    /** whether this is a documentation build */
+    typedoc: boolean;
 }
+/** root configuration object */
 export interface RootConfigObject {
     /**
      * path to vite config to use when building using fuman-build cli,
@@ -28,5 +34,21 @@ export interface RootConfigObject {
     jsr?: JsrConfig;
     /** configuration for the changelog generator */
     versioning?: VersioningOptions;
+    /** base configuration for typedoc */
+    typedoc?: AnyToNever<Omit<Partial<TypeDocOptions>, 'entryPoints' | 'entryPointStrategy' | 'extends'> & {
+        /**
+         * **note**: fuman-specific option
+         *
+         * if passed, docs will be generated for the specified packages only
+         */
+        includePackages?: string[];
+        /**
+         * **note**: fuman-specific option
+         *
+         * list of packages for which the docs should *not* be generated
+         */
+        excludePackages?: string[];
+    }>;
 }
+/** root configuration (either an object or a function that returns an object) */
 export type RootConfig = RootConfigObject | (() => RootConfigObject);

package/fuman-build.js

@@ -4,6 +4,7 @@ import * as bc from "@drizzle-team/brocli";
 import { buildPackageCli } from "./cli/commands/build.js";
 import { bumpVersionCli } from "./cli/commands/bump-version.js";
 import { runContinuousReleaseCli } from "./cli/commands/cr.js";
+import { generateDocsCli } from "./cli/commands/docs.js";
 import { findChangedPackagesCli } from "./cli/commands/find-changed-packages.js";
 import { generateChangelogCli } from "./cli/commands/gen-changelog.js";
 import { generateDepsGraphCli } from "./cli/commands/gen-deps-graph.js";
@@ -21,7 +22,8 @@ await bc.run([
   bumpVersionCli,
   publishPackagesCli,
   releaseCli,
-  runContinuousReleaseCli
+  runContinuousReleaseCli,
+  generateDocsCli
 ], {
   theme: (event) => {
     if (event.type === "error" && event.violation === "unknown_error") {

package/git/github.d.ts

@@ -11,4 +11,5 @@ export declare function createGithubRelease(params: {
         type: string;
         body: BodyInit;
     }[];
+    apiUrl?: string;
 }): Promise<number>;

package/git/github.js

@@ -4,7 +4,7 @@ import { asyncPool } from "@fuman/utils";
 import { z } from "zod";
 async function createGithubRelease(params) {
   const ffetch = ffetchBase.extend({
-    baseUrl: "https://api.github.com",
+    baseUrl: params.apiUrl ?? "https://api.github.com",
     addons: [
       ffetchAddons.retry(),
       ffetchAddons.parser(ffetchZodAdapter())

package/git/utils.d.ts

@@ -1,38 +1,94 @@
+/**
+ * get the latest tag in the repository
+ * @param cwd  override the current working directory
+ */
 export declare function getLatestTag(cwd?: string | URL): Promise<string | null>;
+/**
+ * get hash of the first commit in the repository
+ * @param cwd  override the current working directory
+ */
 export declare function getFirstCommit(cwd?: string | URL): Promise<string>;
+/**
+ * get hash of the current commit
+ * @param cwd  override the current working directory
+ */
 export declare function getCurrentCommit(cwd?: string | URL): Promise<string>;
+/**
+ * get name of the current branch
+ * @param cwd  override the current working directory
+ */
 export declare function getCurrentBranch(cwd?: string | URL): Promise<string>;
+export declare function gitTagExists(tag: string, cwd?: string | URL): Promise<boolean>;
+/**
+ * find changed files between two commits
+ *
+ * @returns  list of changed files, relative to the repository root
+ */
 export declare function findChangedFiles(params: {
+    /** starting point for the diff */
     since: string;
-    /** @default  'HEAD' */
+    /**
+     * ending point for the diff
+     *
+     * @default  'HEAD'
+     */
     until?: string;
+    /** override the current working directory */
     cwd?: string | URL;
 }): Promise<string[]>;
+/** information about a commit */
 export interface CommitInfo {
+    /** full hash of the commit */
     hash: string;
+    /** author of the commit */
     author: {
+        /** name of the author */
         name: string;
+        /** email of the author */
         email: string;
+        /** date of the commit */
         date: Date;
     };
+    /** committer of the commit */
     committer: {
+        /** name of the committer */
         name: string;
+        /** email of the committer */
         email: string;
+        /** date of the commit */
         date: Date;
     };
+    /** commit message */
     message: string;
+    /** commit description */
     description: string;
 }
+/**
+ * get information about commits between two commits (both ends inclusive)
+ *
+ * @returns  list of commits, in reverse chronological order
+ */
 export declare function getCommitsBetween(params: {
+    /** starting point for the diff */
     since: string;
-    /** @default  'HEAD' */
+    /**
+     * ending point for the diff
+     * @default  'HEAD'
+     */
     until?: string;
+    /** override the current working directory */
     cwd?: string | URL;
 }): Promise<CommitInfo[]>;
+/** information about a conventional commit */
 export interface ConventionalCommit {
+    /** type of the commit (e.g. `feat`, `fix`, etc) */
     type: string;
+    /** scope of the commit (i.e. "scope" in `feat(scope): subject`) */
     scope?: string;
+    /** whether the commit is marked as breaking with an exclamation mark */
     breaking: boolean;
+    /** subject of the commit */
     subject: string;
 }
+/** parse a conventional commit message */
 export declare function parseConventionalCommit(msg: string): ConventionalCommit | null;

package/git/utils.js

@@ -30,6 +30,13 @@ async function getCurrentBranch(cwd) {
   });
   return res.stdout.trim();
 }
+async function gitTagExists(tag, cwd) {
+  const res = await exec(["git", "tag", "--list", tag], {
+    cwd,
+    throwOnError: true
+  });
+  return res.stdout.trim() !== "";
+}
 async function findChangedFiles(params) {
   const { since, until = "HEAD", cwd } = params;
   const res = await exec(["git", "diff", "--name-only", since, until], {
@@ -106,5 +113,6 @@ export {
   getCurrentCommit,
   getFirstCommit,
   getLatestTag,
+  gitTagExists,
   parseConventionalCommit
 };

package/index.d.ts

@@ -5,3 +5,4 @@ export * from './git/index.js';
 export * from './misc/index.js';
 export * from './npm/index.js';
 export * from './package-json/index.js';
+export * from './versioning/index.js';

package/index.js

@@ -1,8 +1,9 @@
 import { getGithubActionsInput, isRunningInGithubActions, writeGithubActionsOutput } from "./ci/github-actions.js";
 import { buildPackage } from "./cli/commands/build.js";
+import { generateDocs } from "./cli/commands/docs.js";
 import { generateDepsGraph } from "./cli/commands/gen-deps-graph.js";
 import { validateWorkspaceDeps } from "./cli/commands/validate-workspace-deps.js";
-import { findChangedFiles, getCommitsBetween, getCurrentBranch, getCurrentCommit, getFirstCommit, getLatestTag, parseConventionalCommit } from "./git/utils.js";
+import { findChangedFiles, getCommitsBetween, getCurrentBranch, getCurrentCommit, getFirstCommit, getLatestTag, gitTagExists, parseConventionalCommit } from "./git/utils.js";
 import { exec } from "./misc/exec.js";
 import { normalizeFilePath } from "./misc/path.js";
 import { determinePublishOrder, sortWorkspaceByPublishOrder } from "./misc/publish-order.js";
@@ -13,17 +14,25 @@ import { findPackageJson } from "./package-json/find-package-json.js";
 import { parsePackageJson, parsePackageJsonFile, parseWorkspaceRootPackageJson } from "./package-json/parse.js";
 import { processPackageJson } from "./package-json/process-package-json.js";
 import { PackageJsonSchema } from "./package-json/types.js";
+import { bumpVersion } from "./versioning/bump-version.js";
+import { findProjectChangedFiles, findProjectChangedPackages } from "./versioning/collect-files.js";
+import { generateChangelog } from "./versioning/generate-changelog.js";
 export {
   NPM_PACKAGE_NAME_REGEX,
   PackageJsonSchema,
   buildPackage,
+  bumpVersion,
   collectPackageJsons,
   determinePublishOrder,
   exec,
   filterPackageJsonsForPublish,
   findChangedFiles,
   findPackageJson,
+  findProjectChangedFiles,
+  findProjectChangedPackages,
+  generateChangelog,
   generateDepsGraph,
+  generateDocs,
   getCommitsBetween,
   getCurrentBranch,
   getCurrentCommit,
@@ -32,6 +41,7 @@ export {
   getLatestTag,
   getTsconfigFiles,
   getTsconfigFor,
+  gitTagExists,
   isRunningInGithubActions,
   normalizeFilePath,
   npmCheckVersion,

package/jsr/build-jsr.js

@@ -103,7 +103,8 @@ ${badImports.join("\n")}`);
     packageDir: ourPackage.path,
     packageName: asNonNull(ourPackage.json.name),
     packageJson: ourPackage.json,
-    jsr: true
+    jsr: true,
+    typedoc: false
   };
   packageConfig?.preparePackageJson?.(hookContext);
   const workspaceVersions = collectVersions(workspacePackages);

package/jsr/generate-workspace.js

@@ -125,7 +125,8 @@ async function generateDenoWorkspace(params) {
       packageDir: packageOutRoot,
       packageName: pkg.json.name,
       packageJson: pkg.json,
-      jsr: true
+      jsr: true,
+      typedoc: false
     };
     packageConfig?.preparePackageJson?.(hookContext);
     const workspaceVersions = collectVersions(workspacePackages);

package/misc/exec.d.ts

@@ -1,9 +1,23 @@
 import { SpawnOptions } from 'node:child_process';
+/** result of {@link exec} */
 export interface ExecResult {
+    /** stdout of the command */
     stdout: string;
+    /** stderr of the command */
     stderr: string;
+    /** exit code of the command */
     exitCode: number;
 }
+/**
+ * execute a command and return its result
+ *
+ * **differences from node's `child_process.exec()`**:
+ * - if `options.stdio` is set to `'inherit'`, the command will be printed to the console (unless `options.quiet` is set to `true`)
+ * - on non-zero exit code, the promise will be rejected with an error if `options.throwOnError` is set to `true`
+ *
+ * @param cmd  command to execute (first element is the command itself, the rest are arguments to it)
+ */
 export declare function exec(cmd: string[], options?: SpawnOptions & {
     throwOnError?: boolean;
+    quiet?: boolean;
 }): Promise<ExecResult>;

package/misc/exec.js

@@ -1,8 +1,18 @@
-import { spawn } from "node:child_process";
+import path__default from "node:path";
+import process from "node:process";
+import { spawn } from "cross-spawn";
+import { normalizeFilePath } from "./path.js";
 function exec(cmd, options) {
   return new Promise((resolve, reject) => {
-    if (options?.stdio === "inherit") {
-      console.log("\x1B[;34m$\x1B[;0m", cmd.map((it) => it.includes(" ") ? `"${it.replace(/"/g, '\\"')}"` : it).join(" "));
+    if (options?.stdio === "inherit" && !options.quiet) {
+      const cmdStr = cmd.map((it) => it.includes(" ") ? `"${it.replace(/"/g, '\\"')}"` : it).join(" ");
+      let cwdStr = "";
+      if (options?.cwd != null) {
+        const normCwd = path__default.resolve(normalizeFilePath(options.cwd));
+        const showCwd = normCwd !== process.cwd();
+        cwdStr = showCwd ? `\x1B[;3m${path__default.relative(process.cwd(), normCwd)}\x1B[;23m ` : "";
+      }
+      console.log(`${cwdStr}\x1B[;34m$\x1B[;0m ${cmdStr}`);
     }
     const proc = spawn(cmd[0], cmd.slice(1), {
       stdio: "pipe",

package/misc/path.d.ts

@@ -1 +1,2 @@
-export declare function normalizeFilePath(filePath: string | URL): string;
+import { URL as NodeURL } from 'node:url';
+export declare function normalizeFilePath(filePath: string | URL | NodeURL): string;

package/misc/path.js

@@ -1,6 +1,6 @@
-import { fileURLToPath } from "node:url";
+import { URL as URL$1, fileURLToPath } from "node:url";
 function normalizeFilePath(filePath) {
-  if (filePath instanceof URL) {
+  if (filePath instanceof URL || filePath instanceof URL$1) {
     return fileURLToPath(filePath);
   } else if (filePath.startsWith("file://")) {
     return fileURLToPath(new URL(filePath));

package/misc/publish-order.d.ts

@@ -1,3 +1,12 @@
 import { WorkspacePackage } from '../package-json/collect-package-jsons.js';
+/** sort a workspace by the publish order (i.e. dependencies first, then dependants) */
 export declare function sortWorkspaceByPublishOrder(packages: WorkspacePackage[]): WorkspacePackage[];
+/**
+ * determine the publish order of a workspace
+ *
+ * publish order is determined by the dependencies of the packages,
+ * so that for each package, all its dependencies are to be published before it
+ *
+ * @throws  if there's a cycle in the dependencies
+ */
 export declare function determinePublishOrder(dependencies: Record<string, string[]>): string[];

package/misc/tsconfig.d.ts

@@ -1,2 +1,6 @@
+/** get a full tsconfig for the given directory */
 export declare function getTsconfigFor(cwd: string): Promise<unknown>;
+/**
+ * get the list of files that are included in the tsconfig
+ */
 export declare function getTsconfigFiles(cwd: string): Promise<string[]>;

package/package-json/collect-package-jsons.d.ts

@@ -1,8 +1,17 @@
 import { PackageJson } from './types.js';
+/** information about a package in a workspace */
 export interface WorkspacePackage {
+    /** path to the package root */
     path: string;
+    /** whether this is the root package */
     root: boolean;
+    /** package.json of the package */
     json: PackageJson;
 }
+/** collect package.jsons from a workspace */
 export declare function collectPackageJsons(workspaceRoot: string | URL, includeRoot?: boolean): Promise<WorkspacePackage[]>;
+/**
+ * filter packages to only include the ones that are to be published
+ * to the given registry
+ */
 export declare function filterPackageJsonsForPublish(packages: WorkspacePackage[], registry: 'jsr' | 'npm'): WorkspacePackage[];

package/package-json/parse.d.ts

@@ -1,4 +1,7 @@
 import { PackageJson } from './types.js';
+/** parse a package.json from string */
 export declare function parsePackageJson(packageJson: string): PackageJson;
+/** parse a package.json file */
 export declare function parsePackageJsonFile(packageJsonPath: string | URL): Promise<PackageJson>;
+/** parse the package.json file at the root of the workspace */
 export declare function parseWorkspaceRootPackageJson(workspaceRoot: string | URL): Promise<PackageJson>;

package/package-json/parse.js

@@ -26,10 +26,19 @@ async function parseWorkspaceRootPackageJson(workspaceRoot) {
     if (!workspace.packages) {
       throw new Error("No packages found in pnpm-workspace.yaml");
     }
-    return {
-      ...parsed,
-      workspaces: workspace.packages
-    };
+    if (workspace.catalog || workspace.catalogs) {
+      const catalogs = {};
+      if (workspace.catalog) {
+        catalogs[""] = workspace.catalog;
+      }
+      if (workspace.catalogs) {
+        for (const [name, catalog] of Object.entries(workspace.catalogs)) {
+          catalogs[name] = catalog;
+        }
+      }
+      parsed.catalogs = catalogs;
+    }
+    parsed.workspaces = workspace.packages;
   }
   return parsed;
 }

package/package-json/process-package-json.d.ts

@@ -1,6 +1,7 @@
 import { PackageJson } from './types.js';
 export declare function processPackageJson(params: {
     packageJson: PackageJson;
+    onlyEntrypoints?: boolean;
     workspaceVersions?: Record<string, string>;
     bundledWorkspaceDeps?: RegExp[];
     rootPackageJson?: PackageJson;

package/package-json/process-package-json.js

@@ -2,6 +2,7 @@ const DEFAULT_FIELDS_TO_COPY_ROOT = ["license", "author", "contributors", "homep
 function processPackageJson(params) {
   const {
     packageJson: packageJsonOrig,
+    onlyEntrypoints = false,
     workspaceVersions,
     rootPackageJson,
     rootFieldsToCopy = DEFAULT_FIELDS_TO_COPY_ROOT,
@@ -10,71 +11,81 @@ function processPackageJson(params) {
   } = params;
   const packageJson = structuredClone(packageJsonOrig);
   const entrypoints = {};
-  for (const field of rootFieldsToCopy) {
-    if (rootPackageJson?.[field] != null && packageJson[field] == null) {
-      packageJson[field] = rootPackageJson[field];
-    }
-  }
-  const newScripts = {};
-  if (packageJson.scripts && Array.isArray(packageJson.fuman?.keepScripts)) {
-    for (const script of packageJson.fuman.keepScripts) {
-      if (typeof script !== "string") continue;
-      if (script in packageJson.scripts) continue;
-      newScripts[script] = packageJson.scripts[script];
-    }
-    delete packageJson.keepScripts;
-  }
-  packageJson.scripts = newScripts;
-  delete packageJson.devDependencies;
-  delete packageJson.private;
-  if (packageJson.fuman?.distOnlyFields) {
-    Object.assign(packageJson, packageJson.fuman.distOnlyFields);
-    delete packageJson.distOnlyFields;
-  }
-  function replaceWorkspaceDependencies(field) {
-    if (packageJson[field] == null) return;
-    const dependencies = packageJson[field];
-    for (const name of Object.keys(dependencies)) {
-      const value = dependencies[name];
-      if (value.startsWith("workspace:")) {
-        if (bundledWorkspaceDeps) {
-          let found = false;
-          for (const dep of bundledWorkspaceDeps) {
-            if (dep.test(name)) {
-              delete dependencies[name];
-              found = true;
-              break;
+  if (!onlyEntrypoints) {
+    let replaceCustomDependencies = function(field) {
+      if (packageJson[field] == null) return;
+      const dependencies = packageJson[field];
+      for (const name of Object.keys(dependencies)) {
+        const value = dependencies[name];
+        if (value.startsWith("workspace:")) {
+          if (bundledWorkspaceDeps) {
+            let found = false;
+            for (const dep of bundledWorkspaceDeps) {
+              if (dep.test(name)) {
+                delete dependencies[name];
+                found = true;
+                break;
+              }
             }
+            if (found) continue;
           }
-          if (found) continue;
-        }
-        if (value !== "workspace:^" && value !== "workspace:*") {
-          throw new Error(
-            `Cannot replace workspace dependency ${name} with ${value} - only workspace:^ and * are supported`
-          );
-        }
-        if (workspaceVersions?.[name] == null) {
-          throw new Error(`Cannot replace workspace: dependency ${name} not found in workspace`);
+          if (value !== "workspace:^" && value !== "workspace:*") {
+            throw new Error(
+              `Cannot replace workspace dependency ${name} with ${value} - only workspace:^ and * are supported`
+            );
+          }
+          if (workspaceVersions?.[name] == null) {
+            throw new Error(`Cannot replace workspace: dependency ${name} not found in workspace`);
+          }
+          if (fixedVersion != null) {
+            dependencies[name] = fixedVersion;
+            continue;
+          }
+          const workspaceVersion = workspaceVersions?.[name];
+          const depVersion = value === "workspace:*" ? workspaceVersion : `^${workspaceVersion}`;
+          dependencies[name] = depVersion;
         }
-        if (fixedVersion != null) {
-          dependencies[name] = fixedVersion;
-          continue;
+        if (value.startsWith("catalog:")) {
+          if (!rootPackageJson?.catalogs) throw new Error("catalogs are not available in the workspace root");
+          const catalogName = value.slice("catalog:".length);
+          const catalog = rootPackageJson.catalogs[catalogName];
+          if (catalog == null) throw new Error(`catalog ${catalogName} not found in the workspace root`);
+          if (catalog[name] == null) throw new Error(`catalog ${catalogName} does not contain ${name}`);
+          dependencies[name] = catalog[name];
         }
-        const workspaceVersion = workspaceVersions?.[name];
-        const depVersion = value === "workspace:*" ? workspaceVersion : `^${workspaceVersion}`;
-        dependencies[name] = depVersion;
       }
+    };
+    for (const field of rootFieldsToCopy) {
+      if (rootPackageJson?.[field] != null && packageJson[field] == null) {
+        packageJson[field] = rootPackageJson[field];
+      }
+    }
+    const newScripts = {};
+    if (packageJson.scripts && Array.isArray(packageJson.fuman?.keepScripts)) {
+      for (const script of packageJson.fuman.keepScripts) {
+        if (typeof script !== "string") continue;
+        if (script in packageJson.scripts) continue;
+        newScripts[script] = packageJson.scripts[script];
+      }
+      delete packageJson.keepScripts;
+    }
+    packageJson.scripts = newScripts;
+    delete packageJson.devDependencies;
+    delete packageJson.private;
+    if (packageJson.fuman?.distOnlyFields) {
+      Object.assign(packageJson, packageJson.fuman.distOnlyFields);
+      delete packageJson.distOnlyFields;
     }
+    replaceCustomDependencies("dependencies");
+    replaceCustomDependencies("devDependencies");
+    replaceCustomDependencies("peerDependencies");
+    replaceCustomDependencies("optionalDependencies");
+    delete packageJson.typedoc;
+    delete packageJson.eslintConfig;
+    delete packageJson.eslintIgnore;
+    delete packageJson.prettier;
+    delete packageJson.fuman;
   }
-  replaceWorkspaceDependencies("dependencies");
-  replaceWorkspaceDependencies("devDependencies");
-  replaceWorkspaceDependencies("peerDependencies");
-  replaceWorkspaceDependencies("optionalDependencies");
-  delete packageJson.typedoc;
-  delete packageJson.eslintConfig;
-  delete packageJson.eslintIgnore;
-  delete packageJson.prettier;
-  delete packageJson.fuman;
   if (packageJson.exports != null) {
     let exports = packageJson.exports;
     if (typeof exports === "string") {

package/package-json/types.d.ts

@@ -13,6 +13,7 @@ export interface PackageJson {
         url: string;
     });
     keywords?: string[];
+    catalogs?: Record<string, Record<string, string>>;
     workspaces?: string[];
     scripts?: Record<string, string>;
     dependencies?: Record<string, string>;

package/package.json

@@ -1,27 +1,28 @@
 {
     "name": "@fuman/build",
     "type": "module",
-    "version": "0.0.1",
+    "version": "0.0.3",
     "description": "utils for building packages and managing monorepos",
     "license": "MIT",
     "scripts": {},
     "dependencies": {
         "@drizzle-team/brocli": "^0.10.2",
-        "@fuman/fetch": "^0.0.1",
-        "@fuman/io": "^0.0.1",
-        "@fuman/node": "^0.0.1",
-        "@fuman/utils": "^0.0.1",
+        "@fuman/fetch": "^0.0.3",
+        "@fuman/io": "^0.0.3",
+        "@fuman/node": "^0.0.3",
+        "@fuman/utils": "^0.0.3",
         "cross-spawn": "^7.0.5",
         "detect-indent": "^7.0.1",
         "js-yaml": "^4.1.0",
         "picomatch": "^4.0.2",
         "semver": "^7.6.3",
         "tinyglobby": "^0.2.6",
-        "zod": "^3.23.8"
+        "zod": "^3.0.0"
     },
     "peerDependencies": {
+        "typedoc": ">=0.24.0",
         "typescript": "^5.2.2",
-        "vite": "^5.4.0"
+        "vite": "^5.4.0 || ^6.0.0"
     },
     "exports": {
         ".": {
@@ -59,6 +60,11 @@
     "bin": {
         "fuman-build": "fuman-build.js"
     },
+    "peerDependenciesMeta": {
+        "typedoc": {
+            "optional": true
+        }
+    },
     "author": "",
     "repository": {
         "type": "git",

package/versioning/bump-version.d.ts

@@ -4,6 +4,8 @@ import { VersioningOptions } from './types.js';
 export interface BumpVersionPackage {
     /** info about the package */
     package: WorkspacePackage;
+    /** version before the bump */
+    prevVersion: string;
     /**
      * if the package was not changed by itself,
      * but the bump is required because of another package

package/versioning/bump-version.js

@@ -72,7 +72,10 @@ async function bumpVersion(params) {
   const result = [];
   for (const pkg of changedPackages) {
     if (pkg.json.fuman?.ownVersioning) continue;
-    result.push({ package: pkg });
+    result.push({
+      package: pkg,
+      prevVersion: asNonNull(pkg.json.version)
+    });
   }
   for (const pkg of changedPackages) {
     if (pkg.json.fuman?.ownVersioning) continue;
@@ -96,6 +99,7 @@ async function bumpVersion(params) {
           } else {
             result.push({
               package: otherPkg,
+              prevVersion: asNonNull(otherPkg.json.version),
               because: [pkgName]
             });
           }
@@ -104,8 +108,8 @@ async function bumpVersion(params) {
       }
     }
   }
-  if (!dryRun) {
-    for (const { package: pkg } of result) {
+  for (const { package: pkg } of result) {
+    if (!dryRun) {
       const pkgJsonPath = join(pkg.path, "package.json");
       const pkgJsonText = await fsp.readFile(pkgJsonPath, "utf8");
       const indent = detectIndent(pkgJsonText).indent || "    ";
@@ -114,6 +118,7 @@ async function bumpVersion(params) {
       await fsp.writeFile(pkgJsonPath, `${JSON.stringify(pkgJson, null, indent)}
 `);
     }
+    pkg.json.version = nextVersion;
   }
   return {
     maxVersion,

package/versioning/index.d.ts

@@ -0,0 +1,4 @@
+export * from './bump-version.js';
+export * from './collect-files.js';
+export * from './generate-changelog.js';
+export * from './types.js';

package/versioning/types.d.ts

@@ -9,6 +9,7 @@ export interface ChangelogGeneratorParams {
     commitFormatter?: (commit: CommitInfo, parsed: ConventionalCommit, files: string[]) => string;
     packageCommitsFormatter?: (packageName: string, commits: Record<string, string>) => string;
 }
+/** settings for versioning manager */
 export interface VersioningOptions {
     /**
      * globs of files changes to which to white-list (relative to package root)

package/vite/build-plugin.js

@@ -52,7 +52,8 @@ async function fumanBuild(params) {
     packageDir: packageRoot,
     packageName: asNonNull(ourPackageJson.name),
     packageJson: ourPackageJson,
-    jsr: false
+    jsr: false,
+    typedoc: false
   };
   params.preparePackageJson?.(hookContext);
   packageConfig?.preparePackageJson?.(hookContext);

package/vite/config.d.ts

@@ -1,4 +1,5 @@
-import { MaybePromise } from '@fuman/utils';
+import { AnyToNever, MaybePromise } from '@fuman/utils';
+import { TypeDocOptions } from 'typedoc';
 import { Plugin, UserConfig } from 'vite';
 import { BuildHookContext } from '../config.js';
 import { JsrConfig } from '../jsr/config.js';
@@ -30,5 +31,7 @@ export interface CustomBuildConfigObject {
      * time to do any final modifications to the package contents
      */
     finalize?: (ctx: BuildHookContext) => MaybePromise<void>;
+    /** package-specific configuration for typedoc */
+    typedoc?: AnyToNever<Partial<TypeDocOptions>> | ((current: AnyToNever<Partial<TypeDocOptions>>) => AnyToNever<Partial<TypeDocOptions>>);
 }
 export type CustomBuildConfig = CustomBuildConfigObject | (() => CustomBuildConfigObject);