@vltpkg/graph 1.0.0-rc.2 → 1.0.0-rc.23

package/README.md

@@ -1,3 +1,7 @@
+---
+title: '@vltpkg/graph'
+---
+
 ![graph](https://github.com/user-attachments/assets/dfbed9e0-8ef0-4a43-993d-d3e5d1e5ae1d)
 
 # @vltpkg/graph
@@ -41,57 +45,87 @@ At a glance:
   `node_modules/.vlt-lock.json` mirroring the current on-disk state to
   accelerate subsequent loads of the Actual graph.
 - Modifiers: Configuration for selectively altering dependency
-  resolution; Ideal/Actual builders support skipping node loads when
-  modifiers change.
+  resolution via DSS queries in `vlt.json`.
+- Peer Contexts: Isolation mechanism for peer dependencies that allows
+  multiple versions of the same package when peer requirements differ.
 
 ## API
 
-### `actual.load({ projectRoot: string }): Graph`
+### `actual.load(options): Graph`
 
 Recursively loads the `node_modules` folder found at `projectRoot` in
 order to create a graph representation of the current installed
 packages.
 
-### `async ideal.build({ projectRoot: string }): Promise<Graph>`
+### `ideal.build(options): Promise<Graph>`
 
-This method returns a new `Graph` object, reading from the
-`package.json` file located at `projectRoot` dir and building up the
-graph representation of nodes and edges from the files read from the
-local file system.
+Builds the ideal dependency graph by loading from lockfile (preferred)
+or actual graph, then expanding dependencies by fetching manifests.
+Requires `packageInfo` and `remover` in addition to standard options.
 
-### `lockfile.load({ mainManifest: Manifest, projectRoot: string }): Graph`
+### `lockfile.load(options): Graph`
 
 Loads the lockfile file found at `projectRoot` and returns the graph.
 
-### `reify(options): Promise<Diff>`
+### `lockfile.save(options): void`
+
+Saves the graph to `vlt-lock.json`.
+
+### `reify(options): Promise<ReifyResult>`
 
 Computes a `Diff` between the Actual and Ideal graphs and applies the
 minimal filesystem changes (creating/deleting links, writing
 lockfiles, hoisting, lifecycle scripts) to make the on-disk install
-match the Ideal graph.
+match the Ideal graph. Returns `{ diff, buildQueue }`.
+
+### `install(options, add?): Promise<{ graph, diff, buildQueue }>`
+
+High-level install orchestration that handles graph building, reify,
+and lockfile management. Supports `--frozen-lockfile`,
+`--clean-install`, and `--lockfile-only` modes.
+
+### `mermaidOutput(graph): string`
+
+Generates Mermaid flowchart syntax from graph data.
+
+### `humanReadableOutput(graph, options): string`
+
+Generates ASCII tree output with optional colors. Used in `vlt ls`.
+
+### `jsonOutput(graph): JSONOutputItem[]`
+
+Returns array of `{name, fromID, spec, type, to, overridden}` items.
 
 ## Usage
 
-Here's a quick example of how to use the `@vltpkg/graph.ideal.build`
-method to build a graph representation of the install defined at the
-`projectRoot` directory.
+### High-Level Install
 
-```
-import { ideal } from '@vltpkg/graph'
+```ts
+import { install } from '@vltpkg/graph'
 
-const graph = await ideal.build({ projectRoot: process.cwd() })
+const { graph, diff, buildQueue } = await install({
+  projectRoot: process.cwd(),
+  packageInfo,
+  packageJson,
+  scurry,
+  allowScripts: '*',
+})
 ```
 
 ### Load Actual Graph and Reify
 
 ```ts
 import { actual, ideal, reify } from '@vltpkg/graph'
+import { RollbackRemove } from '@vltpkg/rollback-remove'
+
+const remover = new RollbackRemove()
 
 // Load current on-disk state
 const from = actual.load({
   projectRoot: process.cwd(),
   packageJson,
   scurry,
+  loadManifests: true,
 })
 
 // Build intended end state (may start from lockfile or actual)
@@ -100,15 +134,18 @@ const to = await ideal.build({
   packageInfo,
   packageJson,
   scurry,
+  remover,
 })
 
 // Apply minimal changes to match Ideal
-await reify({
+const { diff, buildQueue } = await reify({
   graph: to,
   actual: from,
   packageInfo,
   packageJson,
   scurry,
+  remover,
+  allowScripts: '*',
 })
 ```
 
@@ -118,15 +155,48 @@ await reify({
 import { lockfile } from '@vltpkg/graph'
 
 // Load virtual graph from vlt-lock.json
-const g = lockfile.load({
+const graph = lockfile.load({
   projectRoot,
   mainManifest,
   packageJson,
-  scurry,
 })
 
-// Save both lockfile formats
-lockfile.save({ graph: g, projectRoot, packageJson, scurry })
+// Save to vlt-lock.json
+lockfile.save({ graph })
+```
+
+### Graph Visualization
+
+```ts
+import {
+  mermaidOutput,
+  humanReadableOutput,
+  jsonOutput,
+} from '@vltpkg/graph'
+
+// Mermaid flowchart (for docs, dashboards)
+const mermaid = mermaidOutput({
+  edges: [...graph.edges],
+  nodes: [...graph.nodes.values()],
+  importers: graph.importers,
+})
+
+// ASCII tree with colors (used in `vlt ls`)
+const tree = humanReadableOutput(
+  {
+    edges: [...graph.edges],
+    nodes: [...graph.nodes.values()],
+    importers: graph.importers,
+  },
+  { colors: true },
+)
+
+// JSON array of dependency items
+const json = jsonOutput({
+  edges: [...graph.edges],
+  nodes: [...graph.nodes.values()],
+  importers: graph.importers,
+})
 ```
 
 ## Architecture
@@ -137,6 +207,7 @@ Graph construction modes supported by the library:
   - Load and save via `src/lockfile/load.ts` and
     `src/lockfile/save.ts`
   - Hidden lockfile: `node_modules/.vlt-lock.json` for faster loads
+  - 📖 [Lockfile README](./src/lockfile/README.md)
 
 - Actual Graphs (filesystem-based)
   - Loaded by traversing `node_modules` via `src/actual/load.ts`
@@ -150,20 +221,28 @@ Graph construction modes supported by the library:
     `src/ideal/get-importer-specs.ts`
   - Fetches and expands manifests using `@vltpkg/package-info`, reuses
     existing nodes that satisfy specs
+  - 📖 [Ideal README](./src/ideal/README.md)
 
 Finally, `src/diff.ts` computes changes and `src/reify/` applies them
 to the filesystem.
 
+- 📖 [Reify README](./src/reify/README.md)
+- 📖 [Architecture Guide](./ARCHITECTURE.md)
+
 ## Related Workspaces
 
 - `@vltpkg/dep-id`: Unique IDs for packages, ensuring `Node` identity
 - `@vltpkg/spec`: Parse/normalize dependency specifiers and registry
   semantics
 - `@vltpkg/semver`: Semantic version parsing/comparison
+- `@vltpkg/satisfies`: Check if a DepID satisfies a Spec
 - `@vltpkg/package-info`: Fetch remote manifests and artifacts
   (registry, git, tarball)
 - `@vltpkg/package-json`: Read and cache local `package.json` files
 - `@vltpkg/workspaces`: Monorepo workspace discovery and grouping
+- `@vltpkg/rollback-remove`: Safe file removal with rollback
+  capability
+- `@vltpkg/vlt-json`: Load `vlt.json` configuration (modifiers, etc.)
 
 ## References
 

package/package.json

@@ -1,99 +1,87 @@
 {
   "name": "@vltpkg/graph",
   "description": "A library that helps understanding & expressing what happens on an install",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.23",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
     "directory": "src/graph"
   },
-  "author": "vlt technology inc. <support@vlt.sh> (http://vlt.sh)",
-  "tshy": {
-    "selfLink": false,
-    "liveDev": true,
-    "dialects": [
-      "esm"
-    ],
-    "exports": {
-      "./package.json": "./package.json",
-      ".": "./src/index.ts",
-      "./browser": "./src/browser.ts"
-    }
+  "author": {
+    "name": "vlt technology inc.",
+    "email": "support@vlt.sh"
   },
   "dependencies": {
-    "graph-run": "^1.1.0",
-    "path-scurry": "^2.0.0",
-    "promise-call-limit": "^3.0.2",
-    "@vltpkg/cmd-shim": "1.0.0-rc.2",
-    "@vltpkg/dss-breadcrumb": "1.0.0-rc.2",
-    "@vltpkg/dep-id": "1.0.0-rc.2",
-    "@vltpkg/fast-split": "1.0.0-rc.2",
-    "@vltpkg/error-cause": "1.0.0-rc.2",
-    "@vltpkg/package-info": "1.0.0-rc.2",
-    "@vltpkg/init": "1.0.0-rc.2",
-    "@vltpkg/package-json": "1.0.0-rc.2",
-    "@vltpkg/pick-manifest": "1.0.0-rc.2",
-    "@vltpkg/query": "1.0.0-rc.2",
-    "@vltpkg/output": "1.0.0-rc.2",
-    "@vltpkg/rollback-remove": "1.0.0-rc.2",
-    "@vltpkg/run": "1.0.0-rc.2",
-    "@vltpkg/satisfies": "1.0.0-rc.2",
-    "@vltpkg/security-archive": "1.0.0-rc.2",
-    "@vltpkg/spec": "1.0.0-rc.2",
-    "@vltpkg/types": "1.0.0-rc.2",
-    "@vltpkg/vlt-json": "1.0.0-rc.2",
-    "@vltpkg/workspaces": "1.0.0-rc.2"
+    "@vltpkg/cmd-shim": "1.0.0-rc.23",
+    "@vltpkg/dep-id": "1.0.0-rc.23",
+    "@vltpkg/dss-breadcrumb": "1.0.0-rc.23",
+    "@vltpkg/error-cause": "1.0.0-rc.23",
+    "@vltpkg/fast-split": "1.0.0-rc.23",
+    "@vltpkg/graph-run": "1.0.0-rc.23",
+    "@vltpkg/init": "1.0.0-rc.23",
+    "@vltpkg/output": "1.0.0-rc.23",
+    "@vltpkg/package-info": "1.0.0-rc.23",
+    "@vltpkg/package-json": "1.0.0-rc.23",
+    "@vltpkg/pick-manifest": "1.0.0-rc.23",
+    "@vltpkg/query": "1.0.0-rc.23",
+    "@vltpkg/rollback-remove": "1.0.0-rc.23",
+    "@vltpkg/run": "1.0.0-rc.23",
+    "@vltpkg/satisfies": "1.0.0-rc.23",
+    "@vltpkg/security-archive": "1.0.0-rc.23",
+    "@vltpkg/spec": "1.0.0-rc.23",
+    "@vltpkg/types": "1.0.0-rc.23",
+    "@vltpkg/vlt-json": "1.0.0-rc.23",
+    "@vltpkg/workspaces": "1.0.0-rc.23",
+    "path-scurry": "^2.0.1",
+    "promise-call-limit": "^3.0.2"
   },
   "devDependencies": {
-    "@eslint/js": "^9.34.0",
-    "@types/node": "^22.17.2",
-    "eslint": "^9.34.0",
-    "prettier": "^3.6.2",
-    "tap": "^21.1.0",
-    "tar": "^7.4.3",
-    "tshy": "^3.0.2",
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^22.19.2",
+    "@vltpkg/vlt-json": "1.0.0-rc.23",
+    "eslint": "^9.39.1",
+    "prettier": "^3.7.4",
+    "tap": "^21.5.0",
+    "tar": "^7.5.2",
     "typedoc": "~0.27.9",
     "typescript": "5.7.3",
-    "typescript-eslint": "^8.40.0",
-    "@vltpkg/vlt-json": "1.0.0-rc.2"
+    "typescript-eslint": "^8.49.0"
   },
   "license": "BSD-2-Clause-Patent",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.22.0"
+  },
+  "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 .",
+    "prepack": "tsc -p tsconfig.publish.json && ../../scripts/update-dist-exports.ts",
+    "snap": "tap",
+    "test": "tap",
+    "posttest": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
   },
   "tap": {
     "extends": "../../tap-config.yaml"
   },
   "prettier": "../../.prettierrc.js",
-  "module": "./dist/esm/index.js",
+  "module": "./dist/index.js",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "import": {
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
+        "default": "./dist/index.js"
       }
     },
     "./browser": {
       "import": {
-        "types": "./dist/esm/browser.d.ts",
-        "default": "./dist/esm/browser.js"
+        "default": "./dist/browser.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 .",
-    "snap": "tap",
-    "test": "tap",
-    "posttest": "tsc --noEmit",
-    "tshy": "tshy",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  ]
+}

package/dist/esm/actual/load.d.ts

@@ -1,100 +0,0 @@
-import { Spec } from '@vltpkg/spec';
-import { Graph } from '../graph.ts';
-import type { DepID } from '@vltpkg/dep-id';
-import type { PackageJson } from '@vltpkg/package-json';
-import type { SpecOptions } from '@vltpkg/spec';
-import type { NormalizedManifest } from '@vltpkg/types';
-import type { Monorepo } from '@vltpkg/workspaces';
-import type { Path, PathScurry } from 'path-scurry';
-import type { GraphModifier } from '../modifiers.ts';
-export type LoadOptions = SpecOptions & {
-    /**
-     * The project root dirname.
-     */
-    projectRoot: string;
-    /**
-     * The project root manifest.
-     */
-    mainManifest?: NormalizedManifest;
-    /**
-     * The graph modifiers helper object.
-     */
-    modifiers?: GraphModifier;
-    /**
-     * A {@link Monorepo} object, for managing workspaces
-     */
-    monorepo?: Monorepo;
-    /**
-     * A {@link PackageJson} object, for sharing manifest caches
-     */
-    packageJson: PackageJson;
-    /**
-     * A {@link PathScurry} object, for use in globs
-     */
-    scurry: PathScurry;
-    /**
-     * If set to `false`, `actual.load` will not load any `package.json`
-     * files while traversing the file system.
-     *
-     * The resulting {@link Graph} from loading with `loadManifests=false`
-     * has no information on dependency types or the specs defined and
-     * no information on missing and extraneous dependencies.
-     */
-    loadManifests?: boolean;
-    /**
-     * If set to `true`, then do not shortcut the process by reading the
-     * hidden lockfile at `node_modules/.vlt-lock.json`
-     */
-    skipHiddenLockfile?: boolean;
-    /**
-     * Load only importers into the graph if the modifiers have changed.
-     */
-    skipLoadingNodesOnModifiersChange?: boolean;
-    /**
-     * If set to `true`, fail if lockfile is missing or out of date.
-     * Used by ci command to enforce lockfile integrity.
-     */
-    expectLockfile?: boolean;
-    /**
-     * If set to `true`, fail if lockfile is missing or out of sync with package.json.
-     * Prevents any lockfile modifications and is stricter than expectLockfile.
-     */
-    frozenLockfile?: boolean;
-    /**
-     * If set to `true`, only update the lockfile without performing any node_modules
-     * operations. Skips package extraction, filesystem operations, and hidden lockfile saves.
-     */
-    lockfileOnly?: boolean;
-};
-export type ReadEntry = {
-    alias: string;
-    name: string;
-    realpath: Path;
-};
-/**
- * The configuration object type as it is saved in the `.vlt/vlt.json`
- */
-export type StoreConfigObject = {
-    modifiers: Record<string, string> | undefined;
-};
-/**
- * Checks if a given object is a {@link StoreConfigObject}.
- */
-export declare const isStoreConfigObject: (obj: unknown) => obj is StoreConfigObject;
-/**
- * Returns a {@link StoreConfigObject} from a given object.
- * Throws a TypeError if the object can't be converted.
- */
-export declare const asStoreConfigObject: (obj: unknown) => StoreConfigObject;
-/**
- * Returns a {@link DepID} for a given spec and path, if the spec is
- * path-based or a registry spec, otherwise returns `undefined`.
- */
-export declare const getPathBasedId: (spec: Spec, path: Path) => DepID | undefined;
-/**
- * Read the file system looking for `node_modules` folders and
- * returns a new {@link Graph} that represents the relationship
- * between the dependencies found.
- */
-export declare const load: (options: LoadOptions) => Graph;
-//# sourceMappingURL=load.d.ts.map

package/dist/esm/actual/load.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/actual/load.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAQnC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,iBAAiB,CAAA;AAGxB,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACtC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC;;OAEG;IACH,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IACxB;;OAEG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;OAEG;IACH,iCAAiC,CAAC,EAAE,OAAO,CAAA;IAE3C;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;CACf,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;CAC9C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,QACzB,OAAO,KACX,GAAG,IAAI,iBAGe,CAAA;AAEzB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QACzB,OAAO,KACX,iBAKF,CAAA;AAUD;;;GAGG;AACH,eAAO,MAAM,cAAc,SACnB,IAAI,QACJ,IAAI,KACT,KAAK,GAAG,SAGQ,CAAA;AA2RnB;;;;GAIG;AACH,eAAO,MAAM,IAAI,YAAa,WAAW,KAAG,KAkG3C,CAAA"}