bun-workspaces 1.8.1 → 1.9.0

package/README.md

@@ -2,25 +2,29 @@
 <img src="./workspaces/web/documentation-website/src/pages/public/images/png/bwunster-bg-banner-wide_3000x900.png" alt="bun-workspaces" width="100%" />
 </a>
 
-# bun-workspaces
+<br/>
 
-### [**See Full Documentation Here**: _https://bunworkspaces.com_](https://bunworkspaces.com)
+Full Documentation: [https://bunworkspaces.com](https://bunworkspaces.com)
 
-This is a CLI and TypeScript API to enhance your monorepo development with Bun's [native workspaces](https://bun.sh/docs/install/workspaces) feature for nested JavaScript/TypeScript packages.
+Changelog: [GitHub Releases](https://github.com/bun-workspaces/bun-workspaces/releases)
 
-- Works right away, with no boilerplate required 🍔🍴
-- Get metadata about your monorepo 🤖
-- Orchestrate your workspaces' `package.json` scripts 📋
-- Run inline [Bun Shell](https://bun.com/docs/runtime/shell) scripts in workspaces 🐚
-- Use the [MCP server](https://bunworkspaces.com/ai/mcp) for your AI tooling to learn how to use `bun-workspaces` and add project metadata to context! 🛠️
+# bun-workspaces
 
-This is a tool to help manage a Bun monorepo, offering features beyond what [Bun's --filter feature](https://bun.com/docs/pm/filter) can do. It can be used to get a variety of metadata about your project and run scripts across your workspaces with advanced control.
+A [monorepo](http://sonarsource.com/resources/library/monorepo/) tool that enhances native [Bun workspaces](https://bun.sh/docs/install/workspaces).
 
-To get started, all you need is a repo using [Bun's workspaces feature](https://bun.sh/docs/install/workspaces) for nested JavaScript/TypeScript packages.
+- Works right away, with **no boilerplate required** 🍽️
+- Get **rich metadata** about your monorepo 🤖
+- **Orchestrate** your workspaces' package.json scripts 🎻
+- Run one-off [**Bun Shell**](https://bun.com/docs/runtime/shell) commands in your workspaces 🐚
+- Use with Bun as your package manager for **Node** projects 🎁
+- Determine **affected workspaces** based on changed files 🕸️
+- Use the [MCP server](https://bunworkspaces.com/ai/mcp) to make your AI tooling aware of `bun-workspaces` and its documentation resources! 🛠️
 
-This package is unopinionated and works with any project structure you want. Think of this as a power suit you can snap onto native workspaces, rather than whole new monorepo framework.
+To get started, all you need is a repo using Bun's workspaces feature for nested JavaScript/TypeScript packages. This adds enhanced features on top of plain workspaces.
 
-Start running some [CLI commands](https://bunworkspaces.com/cli) right away in your repo, or take full advantage of the [scripting API](https://bunworkspaces.com/api) and its features.
+Start running some [CLI commands](https://bunworkspaces.com/cli) right away in your repo, or take full advantage of the [TypeScript API](https://bunworkspaces.com/api) and its features.
+
+This package is unopinionated and works with any project structure you want. Think of this as a power suit you can snap onto native workspaces, rather than whole new monorepo framework.
 
 ## Quick Start
 
@@ -101,6 +105,18 @@ bw run my-script --output-style=prefixed
 # Use the plain output style (no workspace prefixes)
 bw run my-script --output-style=plain
 
+# List affected workspaces based on git diff (main vs. HEAD when not configured)
+bw list-affected
+
+# Set the git base and head for comparison
+bw list-affected --base=my-branch-a --head=my-branch-b
+
+# See detailed reasons for affected workspaces
+bw list-affected --explain --detailed
+
+# Run a script across the workspaces affected by a change
+bw run-affected my-script
+
 # Silence all output of the run command
 bw --log-level=silent run my-script --output-style=none
 
@@ -262,9 +278,26 @@ import { defineWorkspaceConfig } from "bun-workspaces/config";
 export default defineWorkspaceConfig({
   alias: "my-web-app", // shorthand name; use array for multiple
   tags: ["app", "frontend"],
+  // Optional, for configuring affected workspace resolution inputs
+  // Applies to all scripts that don't configure their own inputs
+  defaultInputs: {
+    // File paths, directory paths, or globs relative to the workspace's path.
+    // Default is all git-trackable files in the workspace directory.
+    files: ["src/**/*.ts", "!src/**/*.test.ts"],
+    // Workspaces to treat like dependencies that aren't package.json dependencies
+    workspacePatterns: ["tag:lib"],
+    // Dependency names (e.g. "react") to treat as dependencies (default: all)
+    externalDependencies: ["react"],
+  },
   scripts: {
     // lower order runs first in sequenced script execution
-    build: { order: 1 },
+    build: {
+      // Optional, for setting the default script execution order
+      order: 1,
+      // Optional, for configuring affected workspace resolution inputs
+      // Applies to the build script only
+      inputs: { files: ["src/**/*.ts"] },
+    },
     test: { order: 2 },
   },
   rules: {
@@ -320,6 +353,11 @@ export default defineRootConfig({
       // "tag:app" matches because the first entry added it
       patterns: ["tag:app"],
       config: {
+        // Inputs always override previous entries instead of deep merging
+        defaultInputs: { files: ["src/**/*.ts"] },
+        scripts: {
+          build: { order: 1, inputs: { files: ["src/**/*.ts"] } },
+        },
         rules: {
           workspaceDependencies: {
             allowPatterns: ["tag:lib"], // apps may only depend on libs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "A monorepo management tool for Bun, with a CLI and API to enhance Bun's native workspaces.",
   "license": "MIT",
   "exports": {

package/src/2392.mjs

@@ -28,7 +28,8 @@ const CLI_COMMANDS_CONFIG = {
     options: {
       workspacePatterns: {
         flags: ["-W", "--workspace-patterns <patterns>"],
-        description: "Workspace patterns to match, separated by spaces",
+        description:
+          "Workspace patterns to match, separated by whitespace. Use backslashes to escape spaces if needed.",
       },
       nameOnly: {
         flags: ["-n", "--name-only"],
@@ -144,6 +145,79 @@ const CLI_COMMANDS_CONFIG = {
       "Start the bun-workspaces MCP (Model Context Protocol) server over stdio",
     options: {},
   },
+  listAffected: {
+    command: "list-affected",
+    isGlobal: false,
+    aliases: ["ls-affected"],
+    description:
+      "List workspaces affected by a set of changed files (git or file list)",
+    options: {
+      base: {
+        flags: ["-B", "--base <ref>"],
+        description:
+          "Git base ref to diff against (default is main if not configured). Cannot be used with --files",
+      },
+      head: {
+        flags: ["-H", "--head <ref>"],
+        description:
+          "Git head ref to diff against (default: HEAD). Cannot be used with --files",
+      },
+      files: {
+        flags: ["-F", "--files <files>"],
+        description:
+          "Changed files (paths/dirs/globs, '!' to exclude), separated by spaces. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.",
+      },
+      script: {
+        flags: ["-S", "--script <script>"],
+        description: "Resolve inputs for the named script",
+      },
+      ignoreUntracked: {
+        flags: ["--ignore-untracked"],
+        description: "Exclude untracked files",
+      },
+      ignoreUnstaged: {
+        flags: ["--ignore-unstaged"],
+        description: "Exclude unstaged files",
+      },
+      ignoreStaged: {
+        flags: ["--ignore-staged"],
+        description: "Exclude staged files",
+      },
+      ignoreUncommitted: {
+        flags: ["--ignore-uncommitted"],
+        description:
+          "Exclude all uncommitted changes (staged, unstaged, untracked)",
+      },
+      ignoreWorkspaceDeps: {
+        flags: ["--ignore-workspace-deps"],
+        description:
+          "Ignore workspace dependencies derived from package.json files",
+      },
+      ignoreExternalDeps: {
+        flags: ["--ignore-external-deps"],
+        description:
+          "Ignore changes to external dependencies (e.g. npm packages) versions in bun.lock",
+      },
+      explain: {
+        flags: ["-e", "--explain"],
+        description:
+          "Include changed-file counts and dependency reasons. With --json, outputs the full result object",
+      },
+      detailed: {
+        flags: ["-D", "--detailed"],
+        description:
+          "With --explain, render full per-file data and dependency edge chains",
+      },
+      json: {
+        flags: JSON_FLAGS,
+        description: "Output as JSON",
+      },
+      pretty: {
+        flags: PRETTY_FLAGS,
+        description: "Pretty print JSON",
+      },
+    },
+  },
   runScript: {
     command: "run-script [script] [workspacePatterns...]",
     isGlobal: false,
@@ -153,11 +227,118 @@ const CLI_COMMANDS_CONFIG = {
     options: {
       script: {
         flags: ["-S", "--script <script>"],
-        description: "The script to run.",
+        description: "The script to run. (Alternative to positional argument)",
       },
       workspacePatterns: {
         flags: ["-W", "--workspace-patterns <patterns>"],
-        description: "Workspace patterns to match, separated by spaces.",
+        description:
+          "Workspace patterns to match, separated by spaces. (Alternative to positional arguments)",
+      },
+      parallel: {
+        flags: ["-P", "--parallel [max]"],
+        description:
+          'Run the scripts in parallel. Pass "false" for series, or a concurrency limit as a number, percentage ("50%"), "auto", "default", or"unbounded"',
+      },
+      args: {
+        flags: ["-a", "--args <args>"],
+        description: "Args to append to the script command",
+      },
+      outputStyle: {
+        flags: ["-o", "--output-style <style>"],
+        description: "The output style to use",
+        values: [...OUTPUT_STYLE_VALUES],
+      },
+      groupedLines: {
+        flags: ["-L", "--grouped-lines <count>"],
+        description: `With grouped output, the max preview lines (number or "auto", default "auto")`,
+      },
+      noPrefix: {
+        flags: ["-N", "--no-prefix"],
+        description: "(DEPRECATED) Use --output-style=plain instead",
+        deprecated: true,
+      },
+      inline: {
+        flags: ["-i", "--inline"],
+        description:
+          "Run the script as an inline command from the workspace directory",
+      },
+      inlineName: {
+        flags: ["-I", "--inline-name <name>"],
+        description: "An optional name for the script when --inline is passed",
+      },
+      shell: {
+        flags: ["-s", "--shell <shell>"],
+        values: [...SCRIPT_SHELL_OPTIONS, "default"],
+        description: `When using --inline, the shell to use to run the script`,
+      },
+      depOrder: {
+        flags: ["-d", "--dep-order"],
+        description:
+          "Scripts for dependent workspaces run only after their dependencies",
+      },
+      ignoreDepFailure: {
+        flags: ["-f", "--ignore-dep-failure"],
+        description:
+          "In dependency order, continue running scripts even if a dependency fails",
+      },
+      jsonOutfile: {
+        flags: ["-j", "--json-outfile <file>"],
+        description: "Output results in a JSON file",
+      },
+    },
+  },
+  runAffected: {
+    command: "run-affected [script]",
+    isGlobal: false,
+    aliases: [],
+    description:
+      "Run a script across the workspaces affected by a set of changed files (git or file list)",
+    options: {
+      script: {
+        flags: ["-S", "--script <script>"],
+        description: "The script to run. (Alternative to positional argument)",
+      },
+      base: {
+        flags: ["-B", "--base <ref>"],
+        description:
+          "Git base ref to diff against (default is main if not configured). Cannot be used with --files",
+      },
+      head: {
+        flags: ["-H", "--head <ref>"],
+        description:
+          'Git head ref to diff against (default "HEAD"). Cannot be used with --files',
+      },
+      files: {
+        flags: ["-F", "--files <files>"],
+        description:
+          "Changed files (paths/dirs/globs, '!' to exclude), separated by whitespace. Use backslashes to escape spaces if needed. Bypasses git, so cannot be used with --base or --head.",
+      },
+      ignoreUntracked: {
+        flags: ["--ignore-untracked"],
+        description: "Exclude untracked files",
+      },
+      ignoreUnstaged: {
+        flags: ["--ignore-unstaged"],
+        description: "Exclude unstaged files",
+      },
+      ignoreStaged: {
+        flags: ["--ignore-staged"],
+        description: "Exclude staged files",
+      },
+      ignoreUncommitted: {
+        flags: ["--ignore-uncommitted"],
+        description:
+          "Exclude all uncommitted changes (staged, unstaged, untracked)",
+      },
+      ignoreWorkspaceDeps: {
+        flags: ["--ignore-workspace-deps"],
+        description:
+          "Ignore workspace dependencies derived from package.json files",
+      },
+      ignoreExternalDeps: {
+        flags: ["--ignore-external-deps"],
+        description:
+          "Ignore changes to external dependencies (e.g. npm packages) versions in bun.lock",
       },
       parallel: {
         flags: ["-P", "--parallel [max]"],

package/src/5166.mjs

@@ -2,6 +2,7 @@ const USER_ENV_VARS = {
   parallelMaxDefault: "BW_PARALLEL_MAX_DEFAULT",
   scriptShellDefault: "BW_SHELL_DEFAULT",
   includeRootWorkspaceDefault: "BW_INCLUDE_ROOT_WORKSPACE_DEFAULT",
+  affectedBaseRefDefault: "BW_AFFECTED_BASE_REF_DEFAULT",
 };
 const getUserEnvVarName = (key) => USER_ENV_VARS[key];
 

package/src/8529.mjs

@@ -16,8 +16,18 @@ const CONFIG_LOCATION_PATHS = {
   jsonFile: (name) => `${name}.json`,
   packageJson: (_, packageJsonKey) => `package.json["${packageJsonKey}"]`,
 };
+const CONFIG_LOCATION_DESCRIPTIONS =
+  /* unused pure expression or super */ null && {
+    tsFile: "TypeScript file",
+    jsFile: "JavaScript file",
+    jsoncFile: "JSONC file",
+    jsonFile: "JSON file",
+    packageJson: "package.json key",
+  };
 const createConfigLocationPath = (locationType, name, packageJsonKey) =>
   CONFIG_LOCATION_PATHS[locationType](name, packageJsonKey);
+const createConfigLocationDescription = (locationType) =>
+  CONFIG_LOCATION_DESCRIPTIONS[locationType];
 
 export {
   CONFIG_LOCATION_TYPES,

package/src/affected/affectedBaseRef.mjs

@@ -0,0 +1,12 @@
+import { getUserEnvVar } from "../config/userEnvVars/index.mjs";
+
+const DEFAULT_AFFECTED_BASE_REF = "main";
+/**
+ * Resolves the default base ref for affected workspace resolution.
+ *
+ * Precedence: explicit value (typically from root config defaults) >
+ * `BW_AFFECTED_BASE_REF_DEFAULT` env var > `"main"`.
+ */ const resolveDefaultAffectedBaseRef = (value) =>
+  value || getUserEnvVar("affectedBaseRefDefault") || DEFAULT_AFFECTED_BASE_REF;
+
+export { DEFAULT_AFFECTED_BASE_REF, resolveDefaultAffectedBaseRef };

package/src/affected/externalDependencyChanges.mjs

@@ -0,0 +1,47 @@
+/**
+ * Resolve a dep's version for a specific workspace. bun.lock encodes
+ * divergent per-workspace resolutions under a `<workspaceName>/<depName>` key
+ * when the workspace's range can't dedupe with the hoisted version. Always
+ * consult that namespaced key first; fall back to the bare key for the
+ * common (hoisted) case.
+ */ const resolveWorkspaceDepVersion = ({ lock, workspaceName, depName }) =>
+  lock.get(`${workspaceName}/${depName}`) ?? lock.get(depName) ?? null;
+/**
+ * Given each workspace's declared external deps and lockfile version maps
+ * at base vs head, emit per-workspace change entries for any external dep
+ * whose resolved version differs (including added/removed).
+ *
+ * Pure function. No I/O.
+ */ const computeExternalDependencyChanges = ({
+  workspaces,
+  baseLock,
+  headLock,
+}) => {
+  const result = new Map();
+  for (const workspace of workspaces) {
+    const changes = [];
+    for (const { name, source } of workspace.externalDependencies) {
+      const baseVersion = resolveWorkspaceDepVersion({
+        lock: baseLock,
+        workspaceName: workspace.name,
+        depName: name,
+      });
+      const headVersion = resolveWorkspaceDepVersion({
+        lock: headLock,
+        workspaceName: workspace.name,
+        depName: name,
+      });
+      if (baseVersion === headVersion) continue;
+      changes.push({
+        name,
+        source,
+        baseVersion,
+        headVersion,
+      });
+    }
+    if (changes.length) result.set(workspace.name, changes);
+  }
+  return result;
+};
+
+export { computeExternalDependencyChanges };