@vltpkg/workspaces 0.0.0-0.1730239248325

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) vlt technology, Inc.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+   Subject to the terms and conditions of this license, each copyright holder and contributor hereby grants to those receiving rights under this license a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except for failure to satisfy the conditions of this license) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer this software, where such license applies only to those patent claims, already acquired or hereafter acquired, licensable by such copyright holder or contributor that are necessarily infringed by:
+
+(a) their Contribution(s) (the licensed copyrights of copyright holders and non-copyrightable additions of contributors, in source or binary form) alone; or
+(b) combination of their Contribution(s) with the work of authorship to which such Contribution(s) was added by such copyright holder or contributor, if, at the time the Contribution is added, such addition causes such combination to be necessarily infringed. The patent license shall not apply to any other combinations which include the Contribution.
+Except as expressly stated above, no rights or licenses from any copyright holder or contributor is granted under this license, whether expressly, by implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,110 @@
+# `@vltpkg/workspaces`
+
+Utility for working with vlt workspaces.
+
+## USAGE
+
+```js
+import { Monorepo, Workspace } from '@vltpkg/workspaces'
+
+const m = await Monorepo.load()
+// Can also provide a path option, defaults to process.cwd()
+// m = await Monorepo.load(someOtherPath)
+// Constructor can be used directly, but less convenient:
+//   const m = new Monorepo()
+//   await m.load()
+
+const appWS = m.get('@acme/app')
+console.log(appWS.path) // packages/apps/app
+console.log(appWS.groups) // ['apps', 'frontend']
+console.log(await appWS.manifest()) // { name: "@acme/app", version: etc }
+console.log(appWS.inGroup('frontend')) // true
+console.log(appWS.inGroup('datalayer')) // false
+assert.equal(m.get('packages/apps/app'), appWS) // can get by path
+
+for (const workspace of m) {
+  // iterate over the workspaces in topological dependency order
+}
+
+// run a script or some other async operation, in topological
+// dependency graph order. Eg, for a project containing
+// workspaces a, b, c, d, where a depends on b and c, and b
+// and c both depend on d, it will run first for d, then for b
+// and c in parallel, then for a when c and b are both resolved.
+// depResults is a map of [ws, result] of all dependency
+// workspaces that were completed prior to this one
+// AbortSignal can be used to stop the operation.
+m.run(async (ws, signal, depResults) => {
+  await doSomethingAsync(ws, signal)
+})
+
+// methods that return a set of Workspace objects actually return
+// Monorepo object with all the same methods.
+console.log(m.group('app')) // Monorepo object containing only those keys
+m.group('app').run(async ([name, ws]) => {
+  // logs all the workspaces in the 'app' group
+  console.log(name, ws)
+})
+
+// Since loading everything can be slow, and some actions don't
+// require loading the entire set, you can use this method if you
+// want to just want to load a single workspace or those matching
+// a specific pattern.
+const apps = new Monorepo()
+apps.load({ groups: 'apps' })
+const { manifest } = app.get('packages/my-app')
+
+// get workspace names in no particular order
+for (const name of m.names()) {
+  // @vltpkg/cache, @vltpkg/semver, etc.
+}
+
+// get workspace paths in no particular order
+for (const path of m.paths()) {
+  // apps/webapp, utils/is-even, etc.
+}
+```
+
+Configuration is stored in the project root at
+`vlt-workspaces.json`. The type of the object in the file must
+be:
+
+```ts
+type WorkspaceConfiguration =
+  | string
+  | string[]
+  | { [group: string]: string | string[] }
+```
+
+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 directory containing a `package.json`
+file.
+
+A `string` or `string[]` in the file is interpreted as
+`{"packages": <value>}`. Ie, the default group is `packages`.
+
+Workspaces are allowed to be in multiple groups, so something
+like this is fine:
+
+```json
+{
+  "apps": "apps/*",
+  "frontend": ["utils/frontend", "apps/website"],
+  "utils": ["utils/**"]
+}
+```
+
+If the glob patterns result in a situation where one workspace
+folder is contained within another workspace folder, an error
+will be raised.
+
+## Run Order
+
+The `monorepo.run` method can run an async function for each
+workspace in the project, visiting each exactly once.
+
+When workspaces depend on one another, it will walk dependencies
+before dependents, _unless_ there is a cycle, as that would be
+impossible, and vlt does not prevent workspace dependency cycles.

package/dist/esm/index.d.ts

@@ -0,0 +1,218 @@
+import { DepID } from '@vltpkg/dep-id';
+import { PackageJson } from '@vltpkg/package-json';
+import { Manifest } from '@vltpkg/types';
+import { DepResults } from 'graph-run';
+import { PathScurry } from 'path-scurry';
+export type WorkspacesLoadedConfig = {
+    workspace?: string[];
+    'workspace-group'?: string[];
+};
+/**
+ * The object passed to the constructor or {@link Monorepo#load} to limit which
+ * {@link Workspace Workspaces} get loaded.
+ */
+export type LoadQuery = {
+    /**
+     * A glob pattern string, or an array of them. Only workspaces found
+     * in paths matched will be loaded.
+     */
+    paths?: string[] | string;
+    /**
+     * A string, or an array of strings. If set, only workspaces in the
+     * specified groups named will be included, if set.
+     */
+    groups?: string[] | string;
+};
+/**
+ * Canonical form of the {@link WorkspaceConfig}, used
+ * internally for consistency.
+ */
+export type WorkspaceConfigObject = Record<string, string[]>;
+/**
+ * Allowed datatype in the `vlt-workspaces.json` file.
+ */
+export type WorkspaceConfig = string[] | WorkspaceConfigObject | string;
+/**
+ * Turn a {@link WorkspaceConfig} into a
+ * {@link WorkspaceConfigObject}, or throw if it's not valid.
+ */
+export declare const asWSConfig: (conf: unknown, path?: string) => WorkspaceConfigObject;
+/**
+ * Throw if the provided value is not a valid {@link WorkspaceConfig}
+ */
+export declare const assertWSConfig: (conf: unknown, path?: string) => asserts conf is WorkspaceConfig;
+export type MonorepoOptions = {
+    /**
+     * A {@link PackageJson} object, for sharing manifest caches
+     */
+    packageJson?: PackageJson;
+    /**
+     * A {@link PathScurry} object, for use in globs
+     */
+    scurry?: PathScurry;
+    /** Parsed normalized contents of a `vlt-workspaces.json` file */
+    config?: WorkspaceConfigObject;
+    /**
+     * If set, then {@link Monorepo#load} will be called immediately with
+     * this argument.
+     */
+    load?: LoadQuery;
+};
+/**
+ * Class representing a Monorepo containing multiple workspaces.
+ *
+ * Does not automatically look up the root, but that can be provided by
+ * running `Config.load()`, since it stops seeking the route when a
+ * `vlt-workspaces.json` file is encountered.
+ */
+export declare class Monorepo {
+    #private;
+    /** The project root where vlt-workspaces.json is found */
+    projectRoot: string;
+    /** Scurry object to cache all filesystem calls (mostly globs) */
+    scurry: PathScurry;
+    packageJson: PackageJson;
+    /**
+     * Number of {@link Workspace} objects loaded in this Monorepo
+     */
+    get size(): number;
+    constructor(projectRoot: string, options?: MonorepoOptions);
+    /**
+     * Load the workspace definitions from vlt-workspaces.json,
+     * canonicalizing the result into the effective `{[group:string]:string[]}`
+     * form.
+     *
+     * Eg:
+     * - `"src/*"` => `{packages:["src/*"]}`
+     * - `{"apps": "src/*"}` => `{apps: ["src/*"]}`
+     */
+    get config(): WorkspaceConfigObject;
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    [Symbol.iterator](): Generator<Workspace, void, void>;
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<Workspace, void, void>;
+    /**
+     * By default, loads all workspaces reachable in the Monorepo.
+     *
+     * If provided with one (`string`)or more (`string[]`) group names in
+     * the {@link LoadQuery#groups} field, then only Workspaces in the named
+     * group(s) will be considered. Note that group names are unique string
+     * matches, not globs.
+     *
+     * If provided with a set of arbitrary path arguments, then only paths
+     * patching the provided pattern(s) will be included.
+     *
+     * These two options intersect, so
+     * `load({groups:'foo', paths:'./foo/[xy]*'})` will only load the workspaces
+     * in the group `foo` that match the paths glob.
+     */
+    load(query?: LoadQuery): this;
+    /**
+     * Return the array of workspace dependencies that are found in
+     * the loaded set, for use in calculating dependency graph order for
+     * build operations.
+     *
+     * This does *not* get the full set of dependencies, or expand any
+     * `workspace:` dependencies that are not loaded.
+     *
+     * Call with the `forceLoad` param set to `true` to attempt a full
+     * load if any deps are not currently loaded.
+     */
+    getDeps(ws: Workspace, forceLoad?: boolean): Workspace[];
+    onCycle(_ws: Workspace, _cycle: Workspace[], _depPath: Workspace[]): void;
+    /**
+     * Return the set of workspaces in the named group.
+     * If the group is not one we know about, then undefined is returned.
+     */
+    group(group: string): Set<Workspace> | undefined;
+    /**
+     * Get a loaded workspace by path or name.
+     *
+     * Note that this can only return workspaces that were ingested via a
+     * previous call to {@link Monorepo#load}.
+     */
+    get(nameOrPath: string): Workspace | undefined;
+    /**
+     * get the list of all loaded workspace names used as keys
+     */
+    names(): Generator<string, void, unknown>;
+    /**
+     * get the list of all loaded workspace paths used as keys
+     */
+    paths(): Generator<string, void, unknown>;
+    /**
+     * get the workspace objects in no particular order.
+     * this is ever so slightly faster than iterating, because it doesn't
+     * explore the graph to yield results in topological dependency order,
+     * and should be used instead when order doesn't matter.
+     */
+    values(): Generator<Workspace, void, unknown>;
+    /**
+     * Get all the keys (package names and paths) for loaded workspaces.
+     * Union of {@link Monorepo#names} and {@link Monorepo#paths}
+     */
+    keys(): Generator<string, void, unknown>;
+    /**
+     * Filter the monorepo object yielding the workspace objects that matches
+     * either of the {@link WorkspacesLoadedConfig} options provided, in as close
+     * to topological dependency order as possible.
+     */
+    filter({ workspace: namesOrPaths, 'workspace-group': groupName, }: WorkspacesLoadedConfig): Generator<Workspace, void, unknown>;
+    /**
+     * Run an operation asynchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `run<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    run<R>(operation: (s: Workspace, signal: AbortSignal, depResults: DepResults<Workspace, R>) => Promise<R> | R, forceLoad?: boolean): Promise<Map<Workspace, R>>;
+    /**
+     * Run an operation synchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `runSync<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    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.
+     */
+    static maybeLoad(projectRoot: string, options?: MonorepoOptions): Monorepo | undefined;
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Throws if called on a directory that is not a workspaces root.
+     */
+    static load(projectRoot: string, options?: MonorepoOptions): Monorepo;
+}
+export declare const workspaceCache: Map<string, Workspace>;
+/**
+ * Class representing a single Workspace in a {@link Monorepo}
+ */
+export declare class Workspace {
+    #private;
+    id: DepID;
+    path: string;
+    fullpath: string;
+    manifest: Manifest;
+    groups: string[];
+    name: string;
+    constructor(path: string, manifest: Manifest, fullpath: string);
+    get keys(): string[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -0,0 +1,527 @@
+import { joinDepIDTuple } from '@vltpkg/dep-id';
+import { error } from '@vltpkg/error-cause';
+import { PackageJson } from '@vltpkg/package-json';
+import { readFileSync, statSync } from 'fs';
+import { globSync } from 'glob';
+import { graphRun, graphRunSync } from 'graph-run';
+import { basename, resolve, posix } from 'path';
+import { PathScurry } from 'path-scurry';
+import { parse } from 'polite-json';
+import { minimatch } from 'minimatch';
+/**
+ * Turn a {@link WorkspaceConfig} into a
+ * {@link WorkspaceConfigObject}, or throw if it's not valid.
+ */
+export const asWSConfig = (conf, path) => {
+    assertWSConfig(conf, path);
+    return (typeof conf === 'string' ? { packages: [conf] }
+        : Array.isArray(conf) ? { packages: conf }
+            : conf);
+};
+/**
+ * Throw if the provided value is not a valid {@link WorkspaceConfig}
+ */
+export const assertWSConfig = (conf, path) => {
+    if (typeof conf === 'string')
+        return conf;
+    if (Array.isArray(conf)) {
+        for (const c of conf) {
+            if (typeof c !== 'string') {
+                throw error('Invalid workspace definition', {
+                    path,
+                    found: c,
+                    wanted: 'string',
+                });
+            }
+        }
+        return;
+    }
+    if (conf && typeof conf === 'object') {
+        for (const [group, value] of Object.entries(conf)) {
+            if (typeof value === 'string')
+                continue;
+            if (Array.isArray(value)) {
+                for (const c of value) {
+                    if (typeof c !== 'string') {
+                        throw error('Invalid workspace definition', {
+                            path,
+                            name: group,
+                            found: c,
+                            wanted: 'string',
+                        });
+                    }
+                }
+                continue;
+            }
+            throw error('Invalid workspace definition', {
+                path,
+                name: group,
+                found: value,
+                wanted: 'string | string[]',
+            });
+        }
+        return;
+    }
+    throw error('Invalid workspace definition', {
+        path,
+        found: conf,
+        wanted: 'string | string[] | { [group: string]: string | string[] }',
+    });
+};
+/**
+ * Class representing a Monorepo containing multiple workspaces.
+ *
+ * Does not automatically look up the root, but that can be provided by
+ * running `Config.load()`, since it stops seeking the route when a
+ * `vlt-workspaces.json` file is encountered.
+ */
+export class Monorepo {
+    /** The project root where vlt-workspaces.json is found */
+    projectRoot;
+    /** Scurry object to cache all filesystem calls (mostly globs) */
+    scurry;
+    // maps both name and path to the workspace objects
+    #workspaces = new Map();
+    #groups = new Map();
+    #config;
+    packageJson;
+    /**
+     * Number of {@link Workspace} objects loaded in this Monorepo
+     */
+    get size() {
+        return [...this.values()].length;
+    }
+    constructor(projectRoot, options = {}) {
+        this.projectRoot = resolve(projectRoot);
+        this.scurry = options.scurry ?? new PathScurry(projectRoot);
+        this.packageJson = options.packageJson ?? new PackageJson();
+        this.#config = options.config;
+        if (options.load)
+            this.load(options.load);
+    }
+    /**
+     * Load the workspace definitions from vlt-workspaces.json,
+     * canonicalizing the result into the effective `{[group:string]:string[]}`
+     * form.
+     *
+     * Eg:
+     * - `"src/*"` => `{packages:["src/*"]}`
+     * - `{"apps": "src/*"}` => `{apps: ["src/*"]}`
+     */
+    get config() {
+        if (this.#config)
+            return this.#config;
+        const file = resolve(this.projectRoot, 'vlt-workspaces.json');
+        let confData;
+        try {
+            confData = readFileSync(file, 'utf8');
+        }
+        catch (er) {
+            throw error('Not in a monorepo, no vlt-workspaces.json found', {
+                path: this.projectRoot,
+                cause: er,
+            });
+        }
+        let parsed;
+        try {
+            parsed = parse(confData);
+        }
+        catch (er) {
+            throw error('Invalid vlt-workspaces.json file', {
+                path: this.projectRoot,
+                cause: er,
+            });
+        }
+        this.#config = asWSConfig(parsed, file);
+        return this.#config;
+    }
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    *[Symbol.iterator]() {
+        const [ws] = [...this.values()];
+        if (!ws)
+            return;
+        // leverage the fact that graphRun returns results in
+        // as close to topological order as possible.
+        for (const workspace of this.runSync(() => { }).keys()) {
+            yield workspace;
+        }
+    }
+    /**
+     * Iterating the Monorepo object yields the workspace objects, in as close to
+     * topological dependency order as possible.
+     */
+    async *[Symbol.asyncIterator]() {
+        const [ws] = [...this.values()];
+        if (!ws)
+            return;
+        for (const workspace of (await this.run(() => { })).keys()) {
+            yield workspace;
+        }
+    }
+    /**
+     * By default, loads all workspaces reachable in the Monorepo.
+     *
+     * If provided with one (`string`)or more (`string[]`) group names in
+     * the {@link LoadQuery#groups} field, then only Workspaces in the named
+     * group(s) will be considered. Note that group names are unique string
+     * matches, not globs.
+     *
+     * If provided with a set of arbitrary path arguments, then only paths
+     * patching the provided pattern(s) will be included.
+     *
+     * These two options intersect, so
+     * `load({groups:'foo', paths:'./foo/[xy]*'})` will only load the workspaces
+     * in the group `foo` that match the paths glob.
+     */
+    load(query = {}) {
+        const paths = new Set(typeof query.paths === 'string' ?
+            [query.paths]
+            : (query.paths ?? []));
+        const groups = new Set(typeof query.groups === 'string' ?
+            [query.groups]
+            : (query.groups ?? []));
+        const groupsExpanded = {};
+        for (const [group, pattern] of Object.entries(this.config)) {
+            if (groups.size && !groups.has(group))
+                continue;
+            groupsExpanded[group] = this.#glob(pattern);
+        }
+        const filter = paths.size ? this.#glob([...paths]) : paths;
+        // if we specified paths, but none matched, nothing to do
+        if (paths.size && !filter.size)
+            return this;
+        for (const [group, matches] of Object.entries(groupsExpanded)) {
+            for (const path of matches) {
+                if (filter.size && !filter.has(path))
+                    continue;
+                this.#loadWS(path, group);
+            }
+        }
+        return this;
+    }
+    // Either load a workspace from disk, or from our internal set,
+    // and assign it to the named group
+    #loadWS(path, group) {
+        const fullpath = resolve(this.projectRoot, path);
+        const loaded = this.#workspaces.get(fullpath);
+        if (loaded)
+            return loaded;
+        const fromCache = workspaceCache.get(fullpath);
+        const manifest = fromCache?.manifest ?? this.packageJson.read(fullpath);
+        const ws = fromCache ?? new Workspace(path, manifest, fullpath);
+        if (group)
+            ws.groups.push(group);
+        this.#workspaces.set(ws.fullpath, ws);
+        this.#workspaces.set(ws.path, ws);
+        this.#workspaces.set(ws.name, ws);
+        for (const name of ws.groups) {
+            const group = this.#groups.get(name) ?? new Set();
+            group.add(ws);
+            this.#groups.set(name, group);
+        }
+        return ws;
+    }
+    // can't be cached, because it's dependent on the matches set
+    // but still worthwhile to have it defined in one place
+    #globOptions(matches) {
+        // 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.
+        const inMatches = (p) => {
+            return (!!p?.relativePosix() &&
+                (matches.has(p.relativePosix()) || inMatches(p.parent)));
+        };
+        return {
+            root: this.projectRoot,
+            cwd: this.projectRoot,
+            posix: true,
+            scurry: this.scurry,
+            withFileTypes: false,
+            ignore: {
+                childrenIgnored: p => basename(p.relativePosix()) === 'node_modules' ||
+                    inMatches(p),
+                // ignore if fails to load package.json
+                ignored: p => {
+                    p.lstatSync();
+                    const rel = p.relativePosix();
+                    if (!rel)
+                        return true;
+                    const maybeDelete = [];
+                    for (const m of matches) {
+                        if (rel.startsWith(m + '/'))
+                            return true;
+                        if (m.startsWith(rel + '/')) {
+                            maybeDelete.push(m);
+                        }
+                    }
+                    if (!p.isDirectory())
+                        return true;
+                    const pj = p.resolve('package.json').lstatSync();
+                    if (!pj?.isFile())
+                        return true;
+                    try {
+                        this.packageJson.read(p.fullpath());
+                    }
+                    catch {
+                        return true;
+                    }
+                    for (const m of maybeDelete) {
+                        matches.delete(m);
+                    }
+                    matches.add(rel);
+                    return false;
+                },
+            },
+        };
+    }
+    #glob(pattern) {
+        const matches = new Set();
+        globSync(pattern, this.#globOptions(matches));
+        return matches;
+    }
+    /**
+     * Return the array of workspace dependencies that are found in
+     * the loaded set, for use in calculating dependency graph order for
+     * build operations.
+     *
+     * This does *not* get the full set of dependencies, or expand any
+     * `workspace:` dependencies that are not loaded.
+     *
+     * Call with the `forceLoad` param set to `true` to attempt a full
+     * load if any deps are not currently loaded.
+     */
+    getDeps(ws, forceLoad = false) {
+        // load manifest and find workspace: deps
+        // filter by those loaded
+        const { manifest } = ws;
+        const depWorkspaces = [];
+        let didForceLoad = false;
+        for (const depType of [
+            'dependencies',
+            'devDependencies',
+            'optionalDependencies',
+            'peerDependencies',
+        ]) {
+            const deps = manifest[depType];
+            if (!deps)
+                continue;
+            for (const [dep, spec] of Object.entries(deps)) {
+                if (spec.startsWith('workspace:')) {
+                    let depWS = this.#workspaces.get(dep);
+                    if (!depWS) {
+                        if (!forceLoad)
+                            continue;
+                        if (didForceLoad)
+                            continue;
+                        didForceLoad = true;
+                        this.load();
+                        depWS = this.#workspaces.get(dep);
+                        if (!depWS)
+                            continue;
+                    }
+                    depWorkspaces.push(depWS);
+                }
+            }
+        }
+        return depWorkspaces;
+    }
+    onCycle(_ws, _cycle, _depPath) {
+        // XXX - process logging? Need to say something like:
+        // Cyclical workspace dependency warning!
+        // When evaluating dependency ${ws.name} via ${
+        //   path.map(ws => ws.name).join(' -> ')
+        // }, a dependency cycle was detected: ${
+        //   cycle.map(ws => ws.name).join(' -> ')
+        // }. Operation will continue, but dependency order not guaranteed.`
+    }
+    /**
+     * Return the set of workspaces in the named group.
+     * If the group is not one we know about, then undefined is returned.
+     */
+    group(group) {
+        return this.#groups.get(group);
+    }
+    /**
+     * Get a loaded workspace by path or name.
+     *
+     * Note that this can only return workspaces that were ingested via a
+     * previous call to {@link Monorepo#load}.
+     */
+    get(nameOrPath) {
+        return this.#workspaces.get(nameOrPath);
+    }
+    /**
+     * get the list of all loaded workspace names used as keys
+     */
+    *names() {
+        for (const [key, ws] of this.#workspaces) {
+            if (key === ws.name)
+                yield key;
+        }
+    }
+    /**
+     * get the list of all loaded workspace paths used as keys
+     */
+    *paths() {
+        for (const [key, ws] of this.#workspaces) {
+            if (key === ws.path)
+                yield key;
+        }
+    }
+    /**
+     * get the workspace objects in no particular order.
+     * this is ever so slightly faster than iterating, because it doesn't
+     * explore the graph to yield results in topological dependency order,
+     * and should be used instead when order doesn't matter.
+     */
+    *values() {
+        const seen = new Set();
+        for (const ws of this.#workspaces.values()) {
+            if (seen.has(ws.fullpath))
+                continue;
+            seen.add(ws.fullpath);
+            yield ws;
+        }
+    }
+    /**
+     * Get all the keys (package names and paths) for loaded workspaces.
+     * Union of {@link Monorepo#names} and {@link Monorepo#paths}
+     */
+    *keys() {
+        for (const ws of this.values()) {
+            yield ws.path;
+            if (ws.name !== ws.path)
+                yield ws.name;
+        }
+    }
+    /**
+     * Filter the monorepo object yielding the workspace objects that matches
+     * either of the {@link WorkspacesLoadedConfig} options provided, in as close
+     * to topological dependency order as possible.
+     */
+    *filter({ workspace: namesOrPaths, 'workspace-group': groupName, }) {
+        const globPatternChecks = namesOrPaths?.map(glob => minimatch.filter(posix.join(glob)));
+        for (const ws of this) {
+            // check if any group has any of the provided group names
+            if (groupName?.some(i => ws.groups.includes(i))) {
+                yield ws;
+                continue;
+            }
+            // check if any workspace-provided name directly matches any of the
+            // configured workspaces by either name or file path
+            if (namesOrPaths
+                ?.map(i => posix.join(i))
+                .some(i => ws.keys.includes(i))) {
+                yield ws;
+                continue;
+            }
+            // check if one of the workspace values are matching glob patterns
+            if (ws.keys.some(key => globPatternChecks?.some(fn => fn(key)))) {
+                yield ws;
+            }
+        }
+    }
+    /**
+     * Run an operation asynchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `run<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    async run(operation, forceLoad = false) {
+        const [ws, ...rest] = [...this.#workspaces.values()];
+        if (!ws) {
+            throw error('No workspaces loaded', undefined, this.run);
+        }
+        return graphRun({
+            graph: [ws, ...rest],
+            getDeps: ws => this.getDeps(ws, forceLoad),
+            visit: async (ws, signal, _, depResults) => await operation(ws, signal, depResults),
+            onCycle: (ws, cycle, path) => this.onCycle(ws, cycle, path),
+        });
+    }
+    /**
+     * Run an operation synchronously over all loaded workspaces
+     *
+     * If the `forceLoad` param is true, then it will attempt to do a full load
+     * when encountering a `workspace:` dependency that isn't loaded.
+     *
+     * Note that because the return type appears in the parameters of the
+     * operation function, it must be set explicitly either in the operation
+     * function signature or by calling `runSync<MyType>` or it'll fall back to
+     * `unknown`, similar to `Array.reduce()`, and for the same reason.
+     */
+    runSync(operation, forceLoad = false) {
+        const [ws, ...rest] = [...this.#workspaces.values()];
+        if (!ws) {
+            throw error('No workspaces loaded', undefined, this.run);
+        }
+        return graphRunSync({
+            graph: [ws, ...rest],
+            getDeps: ws => this.getDeps(ws, forceLoad),
+            visit: (ws, signal, _, depResults) => operation(ws, signal, depResults),
+            onCycle: (ws, cycle, path) => this.onCycle(ws, cycle, path),
+        });
+    }
+    /**
+     * 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.
+     */
+    static maybeLoad(projectRoot, options = { load: {} }) {
+        try {
+            if (!statSync(resolve(projectRoot, 'vlt-workspaces.json')).isFile()) {
+                return;
+            }
+        }
+        catch {
+            return;
+        }
+        const { load = {} } = options;
+        return new Monorepo(projectRoot, { ...options, load });
+    }
+    /**
+     * Convenience method to instantiate and load in one call.
+     * Throws if called on a directory that is not a workspaces root.
+     */
+    static load(projectRoot, options = { load: {} }) {
+        const { load = {} } = options;
+        return new Monorepo(projectRoot, { ...options, load });
+    }
+}
+export const workspaceCache = new Map();
+/**
+ * Class representing a single Workspace in a {@link Monorepo}
+ */
+export class Workspace {
+    id;
+    path;
+    fullpath;
+    manifest;
+    groups = [];
+    name;
+    #keys;
+    constructor(path, manifest, fullpath) {
+        this.id = joinDepIDTuple(['workspace', path]);
+        workspaceCache.set(fullpath, this);
+        this.path = path;
+        this.fullpath = fullpath;
+        this.manifest = manifest;
+        this.name = manifest.name ?? path;
+    }
+    get keys() {
+        if (this.#keys) {
+            return this.#keys;
+        }
+        this.#keys = [this.name, this.path, this.fullpath];
+        return this.#keys;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { DepID, joinDepIDTuple } from '@vltpkg/dep-id'\nimport { error } from '@vltpkg/error-cause'\nimport { PackageJson } from '@vltpkg/package-json'\nimport { Manifest } from '@vltpkg/types'\nimport { readFileSync, statSync } from 'fs'\nimport { GlobOptionsWithFileTypesFalse, globSync } from 'glob'\nimport { DepResults, graphRun, graphRunSync } from 'graph-run'\nimport { basename, resolve, posix } from 'path'\nimport { Path, PathScurry } from 'path-scurry'\nimport { parse } from 'polite-json'\nimport { minimatch } from 'minimatch'\n\nexport type WorkspacesLoadedConfig = {\n  workspace?: string[]\n  'workspace-group'?: string[]\n}\n\n/**\n * The object passed to the constructor or {@link Monorepo#load} to limit which\n * {@link Workspace Workspaces} get loaded.\n */\nexport type LoadQuery = {\n  /**\n   * A glob pattern string, or an array of them. Only workspaces found\n   * in paths matched will be loaded.\n   */\n  paths?: string[] | string\n  /**\n   * A string, or an array of strings. If set, only workspaces in the\n   * specified groups named will be included, if set.\n   */\n  groups?: string[] | string\n}\n\n/**\n * Canonical form of the {@link WorkspaceConfig}, used\n * internally for consistency.\n */\nexport type WorkspaceConfigObject = Record<string, string[]>\n\n/**\n * Allowed datatype in the `vlt-workspaces.json` file.\n */\nexport type WorkspaceConfig =\n  | string[]\n  | WorkspaceConfigObject\n  | string\n\n/**\n * Turn a {@link WorkspaceConfig} into a\n * {@link WorkspaceConfigObject}, or throw if it's not valid.\n */\nexport const asWSConfig = (\n  conf: unknown,\n  path?: string,\n): WorkspaceConfigObject => {\n  assertWSConfig(conf, path)\n  return (\n    typeof conf === 'string' ? { packages: [conf] }\n    : Array.isArray(conf) ? { packages: conf }\n    : conf\n  )\n}\n\n/**\n * Throw if the provided value is not a valid {@link WorkspaceConfig}\n */\nexport const assertWSConfig: (\n  conf: unknown,\n  path?: string,\n) => asserts conf is WorkspaceConfig = (\n  conf: unknown,\n  path?: string,\n) => {\n  if (typeof conf === 'string') return conf\n\n  if (Array.isArray(conf)) {\n    for (const c of conf) {\n      if (typeof c !== 'string') {\n        throw error('Invalid workspace definition', {\n          path,\n          found: c,\n          wanted: 'string',\n        })\n      }\n    }\n    return\n  }\n\n  if (conf && typeof conf === 'object') {\n    for (const [group, value] of Object.entries(conf)) {\n      if (typeof value === 'string') continue\n      if (Array.isArray(value)) {\n        for (const c of value) {\n          if (typeof c !== 'string') {\n            throw error('Invalid workspace definition', {\n              path,\n              name: group,\n              found: c,\n              wanted: 'string',\n            })\n          }\n        }\n        continue\n      }\n      throw error('Invalid workspace definition', {\n        path,\n        name: group,\n        found: value,\n        wanted: 'string | string[]',\n      })\n    }\n    return\n  }\n\n  throw error('Invalid workspace definition', {\n    path,\n    found: conf,\n    wanted:\n      'string | string[] | { [group: string]: string | string[] }',\n  })\n}\n\nexport type MonorepoOptions = {\n  /**\n   * A {@link PackageJson} object, for sharing manifest caches\n   */\n  packageJson?: PackageJson\n  /**\n   * A {@link PathScurry} object, for use in globs\n   */\n  scurry?: PathScurry\n  /** Parsed normalized contents of a `vlt-workspaces.json` file */\n  config?: WorkspaceConfigObject\n  /**\n   * If set, then {@link Monorepo#load} will be called immediately with\n   * this argument.\n   */\n  load?: LoadQuery\n}\n\n/**\n * Class representing a Monorepo containing multiple workspaces.\n *\n * Does not automatically look up the root, but that can be provided by\n * running `Config.load()`, since it stops seeking the route when a\n * `vlt-workspaces.json` file is encountered.\n */\nexport class Monorepo {\n  /** The project root where vlt-workspaces.json is found */\n  projectRoot: string\n  /** Scurry object to cache all filesystem calls (mostly globs) */\n  scurry: PathScurry\n\n  // maps both name and path to the workspace objects\n  #workspaces = new Map<string, Workspace>()\n  #groups = new Map<string, Set<Workspace>>()\n  #config?: WorkspaceConfigObject\n  packageJson: PackageJson\n\n  /**\n   * Number of {@link Workspace} objects loaded in this Monorepo\n   */\n  get size(): number {\n    return [...this.values()].length\n  }\n\n  constructor(projectRoot: string, options: MonorepoOptions = {}) {\n    this.projectRoot = resolve(projectRoot)\n    this.scurry = options.scurry ?? new PathScurry(projectRoot)\n    this.packageJson = options.packageJson ?? new PackageJson()\n    this.#config = options.config\n    if (options.load) this.load(options.load)\n  }\n\n  /**\n   * Load the workspace definitions from vlt-workspaces.json,\n   * canonicalizing the result into the effective `{[group:string]:string[]}`\n   * form.\n   *\n   * Eg:\n   * - `\"src/*\"` => `{packages:[\"src/*\"]}`\n   * - `{\"apps\": \"src/*\"}` => `{apps: [\"src/*\"]}`\n   */\n  get config(): WorkspaceConfigObject {\n    if (this.#config) return this.#config\n    const file = resolve(this.projectRoot, 'vlt-workspaces.json')\n    let confData: string\n    try {\n      confData = readFileSync(file, 'utf8')\n    } catch (er) {\n      throw error('Not in a monorepo, no vlt-workspaces.json found', {\n        path: this.projectRoot,\n        cause: er as Error,\n      })\n    }\n    let parsed: unknown\n    try {\n      parsed = parse(confData)\n    } catch (er) {\n      throw error('Invalid vlt-workspaces.json file', {\n        path: this.projectRoot,\n        cause: er as Error,\n      })\n    }\n    this.#config = asWSConfig(parsed, file)\n    return this.#config\n  }\n\n  /**\n   * Iterating the Monorepo object yields the workspace objects, in as close to\n   * topological dependency order as possible.\n   */\n  *[Symbol.iterator](): Generator<Workspace, void, void> {\n    const [ws] = [...this.values()]\n    if (!ws) return\n    // leverage the fact that graphRun returns results in\n    // as close to topological order as possible.\n    for (const workspace of this.runSync(() => {}).keys()) {\n      yield workspace\n    }\n  }\n\n  /**\n   * Iterating the Monorepo object yields the workspace objects, in as close to\n   * topological dependency order as possible.\n   */\n  async *[Symbol.asyncIterator](): AsyncGenerator<\n    Workspace,\n    void,\n    void\n  > {\n    const [ws] = [...this.values()]\n    if (!ws) return\n    for (const workspace of (await this.run(() => {})).keys()) {\n      yield workspace\n    }\n  }\n\n  /**\n   * By default, loads all workspaces reachable in the Monorepo.\n   *\n   * If provided with one (`string`)or more (`string[]`) group names in\n   * the {@link LoadQuery#groups} field, then only Workspaces in the named\n   * group(s) will be considered. Note that group names are unique string\n   * matches, not globs.\n   *\n   * If provided with a set of arbitrary path arguments, then only paths\n   * patching the provided pattern(s) will be included.\n   *\n   * These two options intersect, so\n   * `load({groups:'foo', paths:'./foo/[xy]*'})` will only load the workspaces\n   * in the group `foo` that match the paths glob.\n   */\n  load(query: LoadQuery = {}): this {\n    const paths = new Set(\n      typeof query.paths === 'string' ?\n        [query.paths]\n      : (query.paths ?? []),\n    )\n    const groups = new Set(\n      typeof query.groups === 'string' ?\n        [query.groups]\n      : (query.groups ?? []),\n    )\n\n    const groupsExpanded: Record<string, Set<string>> = {}\n    for (const [group, pattern] of Object.entries(this.config)) {\n      if (groups.size && !groups.has(group)) continue\n      groupsExpanded[group] = this.#glob(pattern)\n    }\n    const filter = paths.size ? this.#glob([...paths]) : paths\n\n    // if we specified paths, but none matched, nothing to do\n    if (paths.size && !filter.size) return this\n\n    for (const [group, matches] of Object.entries(groupsExpanded)) {\n      for (const path of matches) {\n        if (filter.size && !filter.has(path)) continue\n        this.#loadWS(path, group)\n      }\n    }\n\n    return this\n  }\n\n  // Either load a workspace from disk, or from our internal set,\n  // and assign it to the named group\n  #loadWS(path: string, group?: string): Workspace {\n    const fullpath = resolve(this.projectRoot, path)\n    const loaded = this.#workspaces.get(fullpath)\n    if (loaded) return loaded\n    const fromCache = workspaceCache.get(fullpath)\n    const manifest =\n      fromCache?.manifest ?? this.packageJson.read(fullpath)\n    const ws = fromCache ?? new Workspace(path, manifest, fullpath)\n    if (group) ws.groups.push(group)\n    this.#workspaces.set(ws.fullpath, ws)\n    this.#workspaces.set(ws.path, ws)\n    this.#workspaces.set(ws.name, ws)\n    for (const name of ws.groups) {\n      const group = this.#groups.get(name) ?? new Set()\n      group.add(ws)\n      this.#groups.set(name, group)\n    }\n    return ws\n  }\n\n  // can't be cached, because it's dependent on the matches set\n  // but still worthwhile to have it defined in one place\n  #globOptions(matches: Set<string>): GlobOptionsWithFileTypesFalse {\n    // if the entry or any of its parent dirs are already matched,\n    // then we should not explore further down that directory tree.\n    // if we hit the projectRoot then stop searching.\n    const inMatches = (p?: Path): boolean => {\n      return (\n        !!p?.relativePosix() &&\n        (matches.has(p.relativePosix()) || inMatches(p.parent))\n      )\n    }\n\n    return {\n      root: this.projectRoot,\n      cwd: this.projectRoot,\n      posix: true,\n      scurry: this.scurry,\n      withFileTypes: false,\n      ignore: {\n        childrenIgnored: p =>\n          basename(p.relativePosix()) === 'node_modules' ||\n          inMatches(p),\n        // ignore if fails to load package.json\n        ignored: p => {\n          p.lstatSync()\n          const rel = p.relativePosix()\n          if (!rel) return true\n          const maybeDelete: string[] = []\n          for (const m of matches) {\n            if (rel.startsWith(m + '/')) return true\n            if (m.startsWith(rel + '/')) {\n              maybeDelete.push(m)\n            }\n          }\n          if (!p.isDirectory()) return true\n          const pj = p.resolve('package.json').lstatSync()\n          if (!pj?.isFile()) return true\n          try {\n            this.packageJson.read(p.fullpath())\n          } catch {\n            return true\n          }\n          for (const m of maybeDelete) {\n            matches.delete(m)\n          }\n          matches.add(rel)\n          return false\n        },\n      },\n    }\n  }\n\n  #glob(pattern: string[] | string) {\n    const matches = new Set<string>()\n    globSync(pattern, this.#globOptions(matches))\n    return matches\n  }\n\n  /**\n   * Return the array of workspace dependencies that are found in\n   * the loaded set, for use in calculating dependency graph order for\n   * build operations.\n   *\n   * This does *not* get the full set of dependencies, or expand any\n   * `workspace:` dependencies that are not loaded.\n   *\n   * Call with the `forceLoad` param set to `true` to attempt a full\n   * load if any deps are not currently loaded.\n   */\n  getDeps(ws: Workspace, forceLoad = false): Workspace[] {\n    // load manifest and find workspace: deps\n    // filter by those loaded\n    const { manifest } = ws\n    const depWorkspaces: Workspace[] = []\n    let didForceLoad = false\n    for (const depType of [\n      'dependencies',\n      'devDependencies',\n      'optionalDependencies',\n      'peerDependencies',\n    ] as const) {\n      const deps = manifest[depType]\n      if (!deps) continue\n      for (const [dep, spec] of Object.entries(deps)) {\n        if (spec.startsWith('workspace:')) {\n          let depWS = this.#workspaces.get(dep)\n          if (!depWS) {\n            if (!forceLoad) continue\n            if (didForceLoad) continue\n            didForceLoad = true\n            this.load()\n            depWS = this.#workspaces.get(dep)\n            if (!depWS) continue\n          }\n          depWorkspaces.push(depWS)\n        }\n      }\n    }\n    return depWorkspaces\n  }\n\n  onCycle(\n    _ws: Workspace,\n    _cycle: Workspace[],\n    _depPath: Workspace[],\n  ) {\n    // XXX - process logging? Need to say something like:\n    // Cyclical workspace dependency warning!\n    // When evaluating dependency ${ws.name} via ${\n    //   path.map(ws => ws.name).join(' -> ')\n    // }, a dependency cycle was detected: ${\n    //   cycle.map(ws => ws.name).join(' -> ')\n    // }. Operation will continue, but dependency order not guaranteed.`\n  }\n\n  /**\n   * Return the set of workspaces in the named group.\n   * If the group is not one we know about, then undefined is returned.\n   */\n  group(group: string) {\n    return this.#groups.get(group)\n  }\n\n  /**\n   * Get a loaded workspace by path or name.\n   *\n   * Note that this can only return workspaces that were ingested via a\n   * previous call to {@link Monorepo#load}.\n   */\n  get(nameOrPath: string) {\n    return this.#workspaces.get(nameOrPath)\n  }\n\n  /**\n   * get the list of all loaded workspace names used as keys\n   */\n  *names() {\n    for (const [key, ws] of this.#workspaces) {\n      if (key === ws.name) yield key\n    }\n  }\n\n  /**\n   * get the list of all loaded workspace paths used as keys\n   */\n  *paths() {\n    for (const [key, ws] of this.#workspaces) {\n      if (key === ws.path) yield key\n    }\n  }\n\n  /**\n   * get the workspace objects in no particular order.\n   * this is ever so slightly faster than iterating, because it doesn't\n   * explore the graph to yield results in topological dependency order,\n   * and should be used instead when order doesn't matter.\n   */\n  *values() {\n    const seen = new Set<string>()\n    for (const ws of this.#workspaces.values()) {\n      if (seen.has(ws.fullpath)) continue\n      seen.add(ws.fullpath)\n      yield ws\n    }\n  }\n\n  /**\n   * Get all the keys (package names and paths) for loaded workspaces.\n   * Union of {@link Monorepo#names} and {@link Monorepo#paths}\n   */\n  *keys() {\n    for (const ws of this.values()) {\n      yield ws.path\n      if (ws.name !== ws.path) yield ws.name\n    }\n  }\n\n  /**\n   * Filter the monorepo object yielding the workspace objects that matches\n   * either of the {@link WorkspacesLoadedConfig} options provided, in as close\n   * to topological dependency order as possible.\n   */\n  *filter({\n    workspace: namesOrPaths,\n    'workspace-group': groupName,\n  }: WorkspacesLoadedConfig) {\n    const globPatternChecks = namesOrPaths?.map(glob =>\n      minimatch.filter(posix.join(glob)),\n    )\n    for (const ws of this) {\n      // check if any group has any of the provided group names\n      if (groupName?.some(i => ws.groups.includes(i))) {\n        yield ws\n        continue\n      }\n      // check if any workspace-provided name directly matches any of the\n      // configured workspaces by either name or file path\n      if (\n        namesOrPaths\n          ?.map(i => posix.join(i))\n          .some(i => ws.keys.includes(i))\n      ) {\n        yield ws\n        continue\n      }\n      // check if one of the workspace values are matching glob patterns\n      if (\n        ws.keys.some(key => globPatternChecks?.some(fn => fn(key)))\n      ) {\n        yield ws\n      }\n    }\n  }\n\n  /**\n   * Run an operation asynchronously over all loaded workspaces\n   *\n   * If the `forceLoad` param is true, then it will attempt to do a full load\n   * when encountering a `workspace:` dependency that isn't loaded.\n   *\n   * Note that because the return type appears in the parameters of the\n   * operation function, it must be set explicitly either in the operation\n   * function signature or by calling `run<MyType>` or it'll fall back to\n   * `unknown`, similar to `Array.reduce()`, and for the same reason.\n   */\n  async run<R>(\n    operation: (\n      s: Workspace,\n      signal: AbortSignal,\n      depResults: DepResults<Workspace, R>,\n    ) => Promise<R> | R,\n    forceLoad = false,\n  ) {\n    const [ws, ...rest] = [...this.#workspaces.values()]\n    if (!ws) {\n      throw error('No workspaces loaded', undefined, this.run)\n    }\n\n    return graphRun<Workspace, R>({\n      graph: [ws, ...rest],\n      getDeps: ws => this.getDeps(ws, forceLoad),\n      visit: async (ws, signal, _, depResults) =>\n        await operation(ws, signal, depResults),\n      onCycle: (ws, cycle, path) => this.onCycle(ws, cycle, path),\n    })\n  }\n\n  /**\n   * Run an operation synchronously over all loaded workspaces\n   *\n   * If the `forceLoad` param is true, then it will attempt to do a full load\n   * when encountering a `workspace:` dependency that isn't loaded.\n   *\n   * Note that because the return type appears in the parameters of the\n   * operation function, it must be set explicitly either in the operation\n   * function signature or by calling `runSync<MyType>` or it'll fall back to\n   * `unknown`, similar to `Array.reduce()`, and for the same reason.\n   */\n  runSync<R>(\n    operation: (\n      s: Workspace,\n      signal: AbortSignal,\n      depResults: DepResults<Workspace, R>,\n    ) => R,\n    forceLoad = false,\n  ) {\n    const [ws, ...rest] = [...this.#workspaces.values()]\n    if (!ws) {\n      throw error('No workspaces loaded', undefined, this.run)\n    }\n\n    return graphRunSync<Workspace, R>({\n      graph: [ws, ...rest],\n      getDeps: ws => this.getDeps(ws, forceLoad),\n      visit: (ws, signal, _, depResults) =>\n        operation(ws, signal, depResults),\n      onCycle: (ws, cycle, path) => this.onCycle(ws, cycle, path),\n    })\n  }\n\n  /**\n   * Convenience method to instantiate and load in one call.\n   * Returns undefined if the project is not a monorepo workspaces\n   * root, otherwise returns the loaded Monorepo.\n   */\n  static maybeLoad(\n    projectRoot: string,\n    options: MonorepoOptions = { load: {} },\n  ) {\n    try {\n      if (\n        !statSync(\n          resolve(projectRoot, 'vlt-workspaces.json'),\n        ).isFile()\n      ) {\n        return\n      }\n    } catch {\n      return\n    }\n    const { load = {} } = options\n    return new Monorepo(projectRoot, { ...options, load })\n  }\n\n  /**\n   * Convenience method to instantiate and load in one call.\n   * Throws if called on a directory that is not a workspaces root.\n   */\n  static load(\n    projectRoot: string,\n    options: MonorepoOptions = { load: {} },\n  ) {\n    const { load = {} } = options\n    return new Monorepo(projectRoot, { ...options, load })\n  }\n}\n\nexport const workspaceCache = new Map<string, Workspace>()\n\n/**\n * Class representing a single Workspace in a {@link Monorepo}\n */\nexport class Workspace {\n  id: DepID\n  path: string\n  fullpath: string\n  manifest: Manifest\n  groups: string[] = []\n  name: string\n  #keys?: string[]\n\n  constructor(path: string, manifest: Manifest, fullpath: string) {\n    this.id = joinDepIDTuple(['workspace', path])\n    workspaceCache.set(fullpath, this)\n    this.path = path\n    this.fullpath = fullpath\n    this.manifest = manifest\n    this.name = manifest.name ?? path\n  }\n\n  get keys(): string[] {\n    if (this.#keys) {\n      return this.#keys\n    }\n    this.#keys = [this.name, this.path, this.fullpath]\n    return this.#keys\n  }\n}\n"]}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@vltpkg/workspaces",
+  "description": "Utility for working with vlt workspaces",
+  "version": "0.0.0-0.1730239248325",
+  "tshy": {
+    "selfLink": false,
+    "dialects": [
+      "esm"
+    ],
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "glob": "^11.0.0",
+    "graph-run": "^1.0.4",
+    "minimatch": "^10.0.1",
+    "path-scurry": "^2.0.0",
+    "polite-json": "^5.0.0",
+    "walk-up-path": "^4.0.0",
+    "@vltpkg/dep-id": "0.0.0-0.1730239248325",
+    "@vltpkg/types": "0.0.0-0.1730239248325",
+    "@vltpkg/package-json": "0.0.0-0.1730239248325",
+    "@vltpkg/error-cause": "0.0.0-0.1730239248325"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.8.0",
+    "@types/eslint__js": "^8.42.3",
+    "@types/node": "^22.4.1",
+    "eslint": "^9.8.0",
+    "prettier": "^3.3.2",
+    "tap": "^21.0.1",
+    "tshy": "^3.0.2",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.0.1"
+  },
+  "license": "BSD-2-Clause-Patent",
+  "engines": {
+    "node": "20 || >=22"
+  },
+  "tap": {
+    "extends": "../../tap-config.yaml"
+  },
+  "prettier": "../../.prettierrc.js",
+  "module": "./dist/esm/index.js",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "format": "prettier --write . --log-level warn --ignore-path ../../.prettierignore --cache",
+    "format:check": "prettier --check . --ignore-path ../../.prettierignore --cache",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "presnap": "tshy",
+    "snap": "tap",
+    "pretest": "tshy",
+    "test": "tap"
+  }
+}