@vltpkg/workspaces 1.1.1 → 1.3.0

package/README.md

@@ -79,6 +79,24 @@ type VltProject = {
 }
 ```
 
+If `vlt.json` has no `workspaces` field, the npm/yarn-style
+`workspaces` field of the project root's `package.json` is used
+instead, so an existing npm or yarn monorepo works without a
+`vlt.json`. Only the shapes npm and yarn understand are accepted there
+-- a glob string, an array of them, or `{packages: [...]}` (plus
+yarn-classic's `nohoist`, which is parsed and ignored). Named groups
+are rejected in `package.json`, because a `package.json` using them
+would be meaningless to every other package manager.
+
+Note the precedence is keyed on the _field_, not the file: a
+`vlt.json` that exists but says nothing about workspaces still falls
+through to `package.json`. The two are never merged.
+
+In either file, a pattern beginning with `!` excludes the paths it
+matches, following npm's semantics: `!a/b` excludes only that
+directory, `!a/b/**` excludes the subtree, and a later positive
+pattern overrides an earlier exclusion.
+
 If it's an object, each key is a group name, and each value is a path,
 glob, or array of paths and globs, which specify the location of the
 workspace projects. Glob matches are only considered if they are a

package/dist/index.d.ts

@@ -41,6 +41,54 @@ export declare const asWSConfig: (conf: unknown, path?: string) => WorkspaceConf
  * Throw if the provided value is not a valid {@link WorkspaceConfig}
  */
 export declare const assertWSConfig: (conf: unknown, path?: string) => asserts conf is WorkspaceConfig;
+/**
+ * Turn the `workspaces` field of a root `package.json` into a
+ * {@link WorkspaceConfigObject}.
+ *
+ * Only the shapes npm and yarn-classic actually understand are
+ * accepted: a glob string, an array of them, or `{packages: [...]}`.
+ * vlt's named workspace groups are deliberately *not* accepted here --
+ * a `package.json` using them would be meaningless to every other
+ * package manager, so they have to live in `vlt.json`.
+ */
+export declare const asManifestWSConfig: (conf: unknown, path: string) => WorkspaceConfigObject;
+/**
+ * Which file a project's workspace definitions came from.
+ */
+export type WorkspaceConfigSource = 'vlt.json' | 'package.json';
+export type ResolvedWorkspaceConfig = {
+    config: WorkspaceConfigObject;
+    /**
+     * The file the config came from, or `undefined` when neither
+     * `vlt.json` nor the root `package.json` declares any workspaces at
+     * all -- ie, when the project is not a monorepo.
+     */
+    source?: WorkspaceConfigSource;
+};
+/**
+ * Resolve the effective workspace definitions for a project.
+ *
+ * `vlt.json` wins whenever it has a `workspaces` field; otherwise the
+ * npm/yarn-style `workspaces` field of the project root's
+ * `package.json` is used. Note the precedence is keyed on the *field*,
+ * not the file: a `vlt.json` that exists but says nothing about
+ * workspaces still falls through to `package.json`.
+ */
+export declare const resolveWSConfig: (projectRoot: string, packageJson?: PackageJson) => ResolvedWorkspaceConfig;
+/**
+ * Split a list of glob patterns into the positive patterns and the
+ * npm-compatible `!`-negated ones, which become ignore patterns.
+ *
+ * Follows npm's `map-workspaces` rules: an even number of leading `!`
+ * is a positive pattern (`!!foo` means `foo`), a leading `./` or `/` is
+ * stripped, and a later positive pattern un-negates any earlier
+ * negation it matches, so `['a/**', '!a/b/**', 'a/b/c']` keeps
+ * `a/b/c`.
+ */
+export declare const splitNegatedPatterns: (all: string[]) => {
+    patterns: string[];
+    ignore: string[];
+};
 export type MonorepoOptions = {
     /**
      * A {@link PackageJson} object, for sharing manifest caches
@@ -51,8 +99,9 @@ export type MonorepoOptions = {
      */
     scurry?: PathScurry;
     /**
-     * Parsed normalized contents of the workspaces from a `vlt.json`
-     * file
+     * Parsed normalized contents of the workspaces, from either a
+     * `vlt.json` or a `package.json` file. If set, the file is not read
+     * again.
      */
     config?: WorkspaceConfigObject;
     /**
@@ -81,9 +130,9 @@ export declare class Monorepo {
     get size(): number;
     constructor(projectRoot: string, options?: MonorepoOptions);
     /**
-     * Load the workspace definitions from vlt.json,
-     * canonicalizing the result into the effective `{[group:string]:string[]}`
-     * form.
+     * Load the workspace definitions from vlt.json, or from the root
+     * package.json when vlt.json declares none, canonicalizing the result
+     * into the effective `{[group:string]:string[]}` form.
      *
      * Eg:
      * - `"src/*"` => `{packages:["src/*"]}`
@@ -124,6 +173,12 @@ export declare class Monorepo {
      * This does *not* get the full set of dependencies, or expand any
      * `workspace:` dependencies that are not loaded.
      *
+     * Bare semver specs are matched by name, and linked only when the
+     * local workspace version satisfies the range -- the same test
+     * `@vltpkg/satisfies` applies at resolution time, so the two agree on
+     * which deps are local. Specs that aren't parseable ranges, such as
+     * dist-tags, still match by name alone.
+     *
      * Call with the `forceLoad` param set to `true` to attempt a full
      * load if any deps are not currently loaded.
      */
@@ -193,8 +248,9 @@ export declare class Monorepo {
     runSync<R>(operation: (s: Workspace, signal: AbortSignal, depResults: DepResults<Workspace, R>) => R, forceLoad?: boolean): Map<Workspace, R>;
     /**
      * Convenience method to instantiate and load in one call.
-     * Returns undefined if the project is not a monorepo workspaces
-     * root, otherwise returns the loaded Monorepo.
+     * Returns undefined if the project is not a monorepo workspaces root,
+     * meaning neither `vlt.json` nor the root `package.json` declares any
+     * workspaces. Otherwise returns the loaded Monorepo.
      */
     static maybeLoad(projectRoot: string, options?: MonorepoOptions): Monorepo | undefined;
     /**

package/dist/index.js

@@ -1,8 +1,9 @@
 import { joinDepIDTuple } from '@vltpkg/dep-id';
 import { error } from '@vltpkg/error-cause';
 import { PackageJson } from '@vltpkg/package-json';
+import { parseRange, satisfies } from '@vltpkg/semver';
 import { load } from '@vltpkg/vlt-json';
-import { globSync } from 'glob';
+import { globSync, Ignore } from 'glob';
 import { graphRun, graphRunSync } from '@vltpkg/graph-run';
 import { minimatch } from 'minimatch';
 import { basename, posix, resolve } from 'node:path';
@@ -89,6 +90,92 @@ export const assertWSConfig = (conf, path) => {
         wanted: 'string | string[] | { [group: string]: string | string[] }',
     });
 };
+/**
+ * Keys that yarn-classic allows alongside `packages` in the
+ * `workspaces` field of a `package.json`, which vlt parses and ignores
+ * rather than rejecting an otherwise valid yarn v1 project.
+ */
+const manifestWSIgnoredKeys = new Set(['nohoist']);
+/**
+ * Turn the `workspaces` field of a root `package.json` into a
+ * {@link WorkspaceConfigObject}.
+ *
+ * Only the shapes npm and yarn-classic actually understand are
+ * accepted: a glob string, an array of them, or `{packages: [...]}`.
+ * vlt's named workspace groups are deliberately *not* accepted here --
+ * a `package.json` using them would be meaningless to every other
+ * package manager, so they have to live in `vlt.json`.
+ */
+export const asManifestWSConfig = (conf, path) => {
+    if (conf && typeof conf === 'object' && !Array.isArray(conf)) {
+        const groups = Object.keys(conf).filter(k => k !== 'packages' && !manifestWSIgnoredKeys.has(k));
+        if (groups.length) {
+            throw error('Named workspace groups are not supported in package.json. ' +
+                'Move them to the "workspaces" field of vlt.json to use them.', {
+                path,
+                found: groups,
+                wanted: 'string | string[] | { packages: string[] }',
+            });
+        }
+        const { packages } = conf;
+        if (packages === undefined)
+            return {};
+        return asWSConfig({ packages }, path);
+    }
+    return asWSConfig(conf, path);
+};
+/**
+ * Resolve the effective workspace definitions for a project.
+ *
+ * `vlt.json` wins whenever it has a `workspaces` field; otherwise the
+ * npm/yarn-style `workspaces` field of the project root's
+ * `package.json` is used. Note the precedence is keyed on the *field*,
+ * not the file: a `vlt.json` that exists but says nothing about
+ * workspaces still falls through to `package.json`.
+ */
+export const resolveWSConfig = (projectRoot, packageJson = new PackageJson()) => {
+    const fromVltJson = load('workspaces', assertWSConfig);
+    if (fromVltJson !== undefined) {
+        return { config: asWSConfig(fromVltJson), source: 'vlt.json' };
+    }
+    // maybeRead, because a project root need not have a package.json at
+    // all, and an unreadable one is not this module's error to report.
+    const workspaces = packageJson.maybeRead(projectRoot)?.workspaces;
+    if (workspaces === undefined)
+        return { config: {} };
+    return {
+        config: asManifestWSConfig(workspaces, resolve(projectRoot, 'package.json')),
+        source: 'package.json',
+    };
+};
+/**
+ * Split a list of glob patterns into the positive patterns and the
+ * npm-compatible `!`-negated ones, which become ignore patterns.
+ *
+ * Follows npm's `map-workspaces` rules: an even number of leading `!`
+ * is a positive pattern (`!!foo` means `foo`), a leading `./` or `/` is
+ * stripped, and a later positive pattern un-negates any earlier
+ * negation it matches, so `['a/**', '!a/b/**', 'a/b/c']` keeps
+ * `a/b/c`.
+ */
+export const splitNegatedPatterns = (all) => {
+    const patterns = [];
+    let ignore = [];
+    for (const orig of all) {
+        const excl = /^!+/.exec(orig);
+        const stripped = excl ? orig.slice(excl[0].length) : orig;
+        // `./foo` and `/foo` both just mean `foo`
+        const pattern = stripped.replace(/^\.?\/+/, '');
+        if (excl && excl[0].length % 2 === 1) {
+            ignore.push(pattern);
+            continue;
+        }
+        // a positive pattern un-negates any earlier negation matching it
+        ignore = ignore.filter(ign => !minimatch(pattern, ign));
+        patterns.push(pattern);
+    }
+    return { patterns, ignore };
+};
 /**
  * Class representing a Monorepo containing multiple workspaces.
  *
@@ -121,9 +208,9 @@ export class Monorepo {
             this.load(options.load);
     }
     /**
-     * Load the workspace definitions from vlt.json,
-     * canonicalizing the result into the effective `{[group:string]:string[]}`
-     * form.
+     * Load the workspace definitions from vlt.json, or from the root
+     * package.json when vlt.json declares none, canonicalizing the result
+     * into the effective `{[group:string]:string[]}` form.
      *
      * Eg:
      * - `"src/*"` => `{packages:["src/*"]}`
@@ -132,7 +219,7 @@ export class Monorepo {
     get config() {
         if (this.#config)
             return this.#config;
-        this.#config = asWSConfig(load('workspaces', assertWSConfig) ?? {});
+        this.#config = resolveWSConfig(this.projectRoot, this.packageJson).config;
         return this.#config;
     }
     /**
@@ -236,7 +323,7 @@ export class Monorepo {
     }
     // can't be cached, because it's dependent on the matches set
     // but still worthwhile to have it defined in one place
-    #globOptions(matches, parseErrors) {
+    #globOptions(matches, ignore, parseErrors) {
         // if the entry or any of its parent dirs are already matched,
         // then we should not explore further down that directory tree.
         // if we hit the projectRoot then stop searching.
@@ -252,6 +339,9 @@ export class Monorepo {
             withFileTypes: false,
             ignore: {
                 childrenIgnored: p => basename(p.relativePosix()) === 'node_modules' ||
+                    // only prunes the subtree for a `!foo/**` style negation,
+                    // matching npm -- a bare `!foo` still gets walked into
+                    !!ignore?.childrenIgnored(p) ||
                     inMatches(p),
                 // ignore if fails to load package.json
                 ignored: p => {
@@ -259,6 +349,11 @@ export class Monorepo {
                     const rel = p.relativePosix();
                     if (!rel)
                         return true;
+                    // checked before the `matches` bookkeeping below, so a negated
+                    // path never lands in `matches` and therefore never suppresses
+                    // its own descendants
+                    if (ignore?.ignored(p))
+                        return true;
                     const maybeDelete = [];
                     for (const m of matches) {
                         if (rel.startsWith(m + '/'))
@@ -294,10 +389,16 @@ export class Monorepo {
             },
         };
     }
+    // patterns are always an array: asWSConfig normalizes every
+    // WorkspaceConfig shape to string[], and the path filter is a Set
     #glob(pattern) {
+        const { patterns, ignore } = splitNegatedPatterns(pattern);
         const matches = new Set();
+        // nothing but negations can never match anything
+        if (!patterns.length)
+            return matches;
         const parseErrors = new Map();
-        globSync(pattern, this.#globOptions(matches, parseErrors));
+        globSync(patterns, this.#globOptions(matches, ignore.length ? new Ignore(ignore, {}) : undefined, parseErrors));
         // After the glob completes, check for JSON parse errors in paths
         // that are NOT nested inside an already-matched workspace.
         // Nested directories (like app/bar/badjson inside workspace app/bar)
@@ -328,6 +429,12 @@ export class Monorepo {
      * This does *not* get the full set of dependencies, or expand any
      * `workspace:` dependencies that are not loaded.
      *
+     * Bare semver specs are matched by name, and linked only when the
+     * local workspace version satisfies the range -- the same test
+     * `@vltpkg/satisfies` applies at resolution time, so the two agree on
+     * which deps are local. Specs that aren't parseable ranges, such as
+     * dist-tags, still match by name alone.
+     *
      * Call with the `forceLoad` param set to `true` to attempt a full
      * load if any deps are not currently loaded.
      */
@@ -347,8 +454,17 @@ export class Monorepo {
             if (!deps)
                 continue;
             for (const [dep, spec] of Object.entries(deps)) {
-                if (spec.startsWith('workspace:')) {
+                // `workspace:` specs, plus any spec with no protocol -- bare
+                // semver ranges and dist-tags, which are how npm/yarn monorepos
+                // reference each other. Anything with a protocol (`npm:`,
+                // `file:`, `git:`, `catalog:`, ...) names something other than a
+                // local workspace, or aliases a different package entirely.
+                if (spec.startsWith('workspace:') || !spec.includes(':')) {
                     let depWS = this.#workspaces.get(dep);
+                    // #workspaces is keyed by name *and* path, so a path that
+                    // happens to equal a dependency name is not a match
+                    if (depWS && depWS.name !== dep)
+                        depWS = undefined;
                     if (!depWS) {
                         if (!forceLoad)
                             continue;
@@ -357,9 +473,22 @@ export class Monorepo {
                         didForceLoad = true;
                         this.load();
                         depWS = this.#workspaces.get(dep);
-                        if (!depWS)
+                        if (depWS?.name !== dep)
                             continue;
                     }
+                    // A bare spec only refers to the local workspace when its
+                    // version actually satisfies the range -- otherwise the dep
+                    // resolves to the registry, and linking it here would add an
+                    // edge that isn't real. That matters beyond ordering: paired
+                    // with a genuine dep the other way it fabricates a cycle,
+                    // and onCycle drops an edge to break it. Ranges we can't
+                    // parse (dist-tags, `user/repo` shorthands) keep matching by
+                    // name, as before.
+                    const range = spec.includes(':') ? undefined : parseRange(spec);
+                    if (range &&
+                        !satisfies(depWS.manifest.version ?? '', range)) {
+                        continue;
+                    }
                     depWorkspaces.push(depWS);
                 }
             }
@@ -510,14 +639,20 @@ export class Monorepo {
     }
     /**
      * Convenience method to instantiate and load in one call.
-     * Returns undefined if the project is not a monorepo workspaces
-     * root, otherwise returns the loaded Monorepo.
+     * Returns undefined if the project is not a monorepo workspaces root,
+     * meaning neither `vlt.json` nor the root `package.json` declares any
+     * workspaces. Otherwise returns the loaded Monorepo.
      */
     static maybeLoad(projectRoot, options = { load: {} }) {
-        const config = load('workspaces', assertWSConfig);
-        if (!config)
+        if (options.config) {
+            return new Monorepo(projectRoot, { load: {}, ...options });
+        }
+        const { config, source } = resolveWSConfig(projectRoot, options.packageJson);
+        if (!source)
             return;
-        return new Monorepo(projectRoot, { load: {}, ...options });
+        // hand the resolved config to the instance so the file that
+        // declared it isn't read a second time
+        return new Monorepo(projectRoot, { load: {}, ...options, config });
     }
     /**
      * Convenience method to instantiate and load in one call.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/workspaces",
   "description": "Utility for working with vlt workspaces",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,12 +13,13 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/dep-id": "1.1.1",
-    "@vltpkg/error-cause": "1.1.1",
-    "@vltpkg/graph-run": "1.1.1",
-    "@vltpkg/package-json": "1.1.1",
-    "@vltpkg/types": "1.1.1",
-    "@vltpkg/vlt-json": "1.1.1",
+    "@vltpkg/dep-id": "1.3.0",
+    "@vltpkg/error-cause": "1.3.0",
+    "@vltpkg/graph-run": "1.3.0",
+    "@vltpkg/package-json": "1.3.0",
+    "@vltpkg/semver": "1.3.0",
+    "@vltpkg/types": "1.3.0",
+    "@vltpkg/vlt-json": "1.3.0",
     "glob": "^13.0.0",
     "minimatch": "^10.1.1",
     "path-scurry": "^2.0.1"
@@ -28,7 +29,7 @@
     "@types/node": "^22.19.2",
     "eslint": "^9.39.1",
     "prettier": "^3.7.4",
-    "tap": "^21.5.0",
+    "tap": "^21.8.0",
     "typedoc": "~0.27.9",
     "typescript": "5.7.3",
     "typescript-eslint": "^8.49.0"