@decohere/forge 0.0.1-dev.121 → 0.0.1-dev.123

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 Typesmiths
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -136,6 +136,15 @@ export default {
 
 Design record: [ADR 0006](../../docs/adr/0006-forge-package-deployables.md).
 
+## `forge dependencies`: package manifests from imports
+
+There is one install, from the root `package.json`, and it owns every version. `forge dependencies sync` writes each package's `dependencies` and `devDependencies` from what its code imports, using the root's ranges. `forge dependencies report --fail-on-drift` fails when a manifest differs from what sync would write; CI runs it.
+
+- **Peers** are declared by name in the package's own `peerDependencies`. Sync sets the root's range and keeps them out of the other two lists, even when no code imports them. Mark optional ones in `peerDependenciesMeta` by hand.
+- **Under the release configuration**, which scans only shipped code, importing a package the root lists only as a devDependency is an error unless the package declares it a peer.
+
+Design record: [ADR 0017](../../docs/adr/0017-dependency-manifests-from-imports.md).
+
 ## `forge link` clears `dist`
 
 `forge link` is a development tool: it symlinks build output into a consumer's `node_modules`. Like `forge build`, it cleans `dist` first. Without `--build` it then links an output folder holding only `package.json` files, so run it with `--build` (or build again afterwards). It is not a way to make a release build runnable; use `forge package` for that.

package/commonjs/src/actions/copy.action.js

@@ -51,11 +51,30 @@ class Copy {
                 cwd
             });
             await Promise.all(rootFiles.map((file)=>this.copyFileToOut(file, root)));
+            await this.copyWorkspaceLicense(proj, rootFiles, root);
             // Configuration-only globs → each pack target outDir (next to emitted JS).
             await this.copyColocatedPackAssets(proj, cwd);
         }));
         return _cli.ActionResponse.Success(Copy.name);
     };
+    /**
+	 * A package without a LICENSE of its own ships the workspace's, so a monorepo
+	 * licensed once at the root still puts the license text in every tarball.
+	 */ async copyWorkspaceLicense(proj, rootFiles, outDir) {
+        if (!proj.configuration.pack) {
+            return;
+        }
+        if (rootFiles.some((file)=>/^LICEN[CS]E/i.test(file.relativePath))) {
+            return;
+        }
+        const licenses = await (0, _io1.findFiles)([
+            "LICENSE*",
+            "LICENCE*"
+        ], {
+            cwd: this.workspace.rootDir
+        });
+        await Promise.all(licenses.map((file)=>this.copyFileToOut(file, outDir)));
+    }
     /**
 	 * Packed builds emit JS under `<out>/<target>/` (e.g. `es6/`). Assets listed on
 	 * the *configuration* `copyFiles` (not the workspace defaults) are also copied

package/commonjs/src/services/dependency-resolver.service.js

@@ -21,24 +21,22 @@ function _ts_decorate(decorators, target, key, desc) {
 }
 class DependencyResolver {
     computeDrift(current, computed) {
-        const sortKeys = (obj)=>Object.fromEntries(Object.entries(obj).sort());
-        const currentDeps = sortKeys(current.dependencies ?? {});
-        const computedDeps = sortKeys(computed.dependencies ?? {});
-        const currentDevDeps = sortKeys(current.devDependencies ?? {});
-        const computedDevDeps = sortKeys(computed.devDependencies ?? {});
-        const hasDrift = JSON.stringify(currentDeps) !== JSON.stringify(computedDeps) || JSON.stringify(currentDevDeps) !== JSON.stringify(computedDevDeps);
-        if (!hasDrift) {
+        const lists = (pkg)=>{
+            const sortKeys = (obj)=>Object.fromEntries(Object.entries(obj ?? {}).sort());
+            return {
+                dependencies: sortKeys(pkg.dependencies),
+                devDependencies: sortKeys(pkg.devDependencies),
+                peerDependencies: sortKeys(pkg.peerDependencies)
+            };
+        };
+        const original = lists(current);
+        const updated = lists(computed);
+        if (JSON.stringify(original) === JSON.stringify(updated)) {
             return null;
         }
         return {
-            original: {
-                dependencies: currentDeps,
-                devDependencies: currentDevDeps
-            },
-            updated: {
-                dependencies: computedDeps,
-                devDependencies: computedDevDeps
-            }
+            original,
+            updated
         };
     }
     async getWorkspacePackages(workspace, projects) {
@@ -78,29 +76,77 @@ class DependencyResolver {
         ]);
     }
     async computeProjectDependencies(project, workspacePackages) {
-        const { dependencies, devDependencies, warnings } = await this.getDependencies(project, workspacePackages);
         const pkg = await project.getPackageJson();
-        const updatedPackage = pkg.withDependencies(dependencies).withDevDependencies(devDependencies);
+        const peerNames = Object.keys(pkg.peerDependencies ?? {});
+        const peerDependencies = this.getPeerDependencies(project, peerNames, workspacePackages);
+        const { dependencies, devDependencies, warnings } = await this.getDependencies(project, workspacePackages, new Set(peerNames));
+        let updatedPackage = pkg.withDependencies(dependencies).withDevDependencies(devDependencies);
+        if (peerNames.length > 0) {
+            updatedPackage = updatedPackage.withPeerDependencies(peerDependencies);
+        }
         return {
             project,
             updatedPackage,
             warnings
         };
     }
-    async getDependencies(project, workspacePackages) {
+    /**
+	 * A package declares its peers by name in its own `peerDependencies` (and marks optional ones in
+	 * `peerDependenciesMeta`, which sync leaves as written). The root owns every version, so each
+	 * peer gets the root's range; a peer the root doesn't list is an error. A declared peer stays
+	 * even when no code imports it: a pino transport, say, is loaded by name.
+	 */ getPeerDependencies(project, peerNames, workspacePackages) {
+        const peers = {};
+        for (const name of [
+            ...peerNames
+        ].sort()){
+            const version = workspacePackages.get(name)?.version;
+            if (version == null) {
+                throw new _errors.ForgeError(`"${name}" is declared a peer of ${project.name}, but the root package.json doesn't list it. ` + "Add it there: the root owns every version.");
+            }
+            peers[name] = version;
+        }
+        return peers;
+    }
+    async getDependencies(project, workspacePackages, peers) {
         const files = await project.getAllFiles();
-        const results = await Promise.all(files.map((file)=>this.getFileImports(file)));
-        const imports = results.flatMap((r)=>r.imports);
+        const results = await Promise.all(files.map(async (file)=>({
+                file,
+                ...await this.getFileImports(file)
+            })));
         const warnings = results.flatMap((r)=>r.warnings);
-        const allDependencies = [
-            ...new Set(imports)
-        ].map((fileImport)=>this.getDependencyFrom(fileImport, workspacePackages)).filter((dep)=>dep != null);
+        /** Which files import each package, for errors that point at the code. */ const importedBy = new Map();
+        const allDependencies = [];
+        for (const { file, imports } of results){
+            for (const fileImport of imports){
+                const dep = this.getDependencyFrom(fileImport, workspacePackages);
+                if (dep == null || peers.has(dep.name)) {
+                    continue;
+                }
+                if (!importedBy.has(dep.name)) {
+                    importedBy.set(dep.name, new Set());
+                    allDependencies.push(dep);
+                }
+                importedBy.get(dep.name)?.add(file.relativePath);
+            }
+        }
         const missing = allDependencies.filter((dep)=>dep.missing);
         if (missing.length > 0) {
             const names = missing.map((dep)=>dep.name).join(", ");
             throw new _errors.ForgeError(`Missing packages in project "${project.name}": ${names}`);
         }
         const resolved = allDependencies.filter((dep)=>!dep.missing);
+        // A configuration that packs is the published shape: its files ship, so a package they
+        // import that the root keeps for development would be missing for the consumer.
+        if (project.configuration.pack === true) {
+            const devOnly = resolved.filter((dep)=>dep.isDev && !dep.internal);
+            if (devOnly.length > 0) {
+                const lines = devOnly.map((dep)=>`  - ${dep.name}, imported by ${[
+                        ...importedBy.get(dep.name) ?? []
+                    ].sort().join(", ")}`);
+                throw new _errors.ForgeError(`${project.name} ships code that imports packages the root lists only as a devDependency:\n` + `${lines.join("\n")}\n` + "Move each to the root's dependencies, or, if the consumer provides it, " + `declare it in ${project.name}'s peerDependencies.`);
+            }
+        }
         const dependencies = Object.fromEntries(resolved.filter((dep)=>!dep.isDev).map((dep)=>[
                 dep.name,
                 dep.version

package/es6/src/actions/copy.action.js

@@ -36,11 +36,30 @@ export class Copy {
                 cwd
             });
             await Promise.all(rootFiles.map((file)=>this.copyFileToOut(file, root)));
+            await this.copyWorkspaceLicense(proj, rootFiles, root);
             // Configuration-only globs → each pack target outDir (next to emitted JS).
             await this.copyColocatedPackAssets(proj, cwd);
         }));
         return ActionResponse.Success(Copy.name);
     };
+    /**
+	 * A package without a LICENSE of its own ships the workspace's, so a monorepo
+	 * licensed once at the root still puts the license text in every tarball.
+	 */ async copyWorkspaceLicense(proj, rootFiles, outDir) {
+        if (!proj.configuration.pack) {
+            return;
+        }
+        if (rootFiles.some((file)=>/^LICEN[CS]E/i.test(file.relativePath))) {
+            return;
+        }
+        const licenses = await findFiles([
+            "LICENSE*",
+            "LICENCE*"
+        ], {
+            cwd: this.workspace.rootDir
+        });
+        await Promise.all(licenses.map((file)=>this.copyFileToOut(file, outDir)));
+    }
     /**
 	 * Packed builds emit JS under `<out>/<target>/` (e.g. `es6/`). Assets listed on
 	 * the *configuration* `copyFiles` (not the workspace defaults) are also copied

package/es6/src/services/dependency-resolver.service.js

@@ -11,24 +11,22 @@ import { BUILT_IN_MODULES } from "../const.js";
 import { ForgeError } from "../errors.js";
 export class DependencyResolver {
     computeDrift(current, computed) {
-        const sortKeys = (obj)=>Object.fromEntries(Object.entries(obj).sort());
-        const currentDeps = sortKeys(current.dependencies ?? {});
-        const computedDeps = sortKeys(computed.dependencies ?? {});
-        const currentDevDeps = sortKeys(current.devDependencies ?? {});
-        const computedDevDeps = sortKeys(computed.devDependencies ?? {});
-        const hasDrift = JSON.stringify(currentDeps) !== JSON.stringify(computedDeps) || JSON.stringify(currentDevDeps) !== JSON.stringify(computedDevDeps);
-        if (!hasDrift) {
+        const lists = (pkg)=>{
+            const sortKeys = (obj)=>Object.fromEntries(Object.entries(obj ?? {}).sort());
+            return {
+                dependencies: sortKeys(pkg.dependencies),
+                devDependencies: sortKeys(pkg.devDependencies),
+                peerDependencies: sortKeys(pkg.peerDependencies)
+            };
+        };
+        const original = lists(current);
+        const updated = lists(computed);
+        if (JSON.stringify(original) === JSON.stringify(updated)) {
             return null;
         }
         return {
-            original: {
-                dependencies: currentDeps,
-                devDependencies: currentDevDeps
-            },
-            updated: {
-                dependencies: computedDeps,
-                devDependencies: computedDevDeps
-            }
+            original,
+            updated
         };
     }
     async getWorkspacePackages(workspace, projects) {
@@ -68,29 +66,77 @@ export class DependencyResolver {
         ]);
     }
     async computeProjectDependencies(project, workspacePackages) {
-        const { dependencies, devDependencies, warnings } = await this.getDependencies(project, workspacePackages);
         const pkg = await project.getPackageJson();
-        const updatedPackage = pkg.withDependencies(dependencies).withDevDependencies(devDependencies);
+        const peerNames = Object.keys(pkg.peerDependencies ?? {});
+        const peerDependencies = this.getPeerDependencies(project, peerNames, workspacePackages);
+        const { dependencies, devDependencies, warnings } = await this.getDependencies(project, workspacePackages, new Set(peerNames));
+        let updatedPackage = pkg.withDependencies(dependencies).withDevDependencies(devDependencies);
+        if (peerNames.length > 0) {
+            updatedPackage = updatedPackage.withPeerDependencies(peerDependencies);
+        }
         return {
             project,
             updatedPackage,
             warnings
         };
     }
-    async getDependencies(project, workspacePackages) {
+    /**
+	 * A package declares its peers by name in its own `peerDependencies` (and marks optional ones in
+	 * `peerDependenciesMeta`, which sync leaves as written). The root owns every version, so each
+	 * peer gets the root's range; a peer the root doesn't list is an error. A declared peer stays
+	 * even when no code imports it: a pino transport, say, is loaded by name.
+	 */ getPeerDependencies(project, peerNames, workspacePackages) {
+        const peers = {};
+        for (const name of [
+            ...peerNames
+        ].sort()){
+            const version = workspacePackages.get(name)?.version;
+            if (version == null) {
+                throw new ForgeError(`"${name}" is declared a peer of ${project.name}, but the root package.json doesn't list it. ` + "Add it there: the root owns every version.");
+            }
+            peers[name] = version;
+        }
+        return peers;
+    }
+    async getDependencies(project, workspacePackages, peers) {
         const files = await project.getAllFiles();
-        const results = await Promise.all(files.map((file)=>this.getFileImports(file)));
-        const imports = results.flatMap((r)=>r.imports);
+        const results = await Promise.all(files.map(async (file)=>({
+                file,
+                ...await this.getFileImports(file)
+            })));
         const warnings = results.flatMap((r)=>r.warnings);
-        const allDependencies = [
-            ...new Set(imports)
-        ].map((fileImport)=>this.getDependencyFrom(fileImport, workspacePackages)).filter((dep)=>dep != null);
+        /** Which files import each package, for errors that point at the code. */ const importedBy = new Map();
+        const allDependencies = [];
+        for (const { file, imports } of results){
+            for (const fileImport of imports){
+                const dep = this.getDependencyFrom(fileImport, workspacePackages);
+                if (dep == null || peers.has(dep.name)) {
+                    continue;
+                }
+                if (!importedBy.has(dep.name)) {
+                    importedBy.set(dep.name, new Set());
+                    allDependencies.push(dep);
+                }
+                importedBy.get(dep.name)?.add(file.relativePath);
+            }
+        }
         const missing = allDependencies.filter((dep)=>dep.missing);
         if (missing.length > 0) {
             const names = missing.map((dep)=>dep.name).join(", ");
             throw new ForgeError(`Missing packages in project "${project.name}": ${names}`);
         }
         const resolved = allDependencies.filter((dep)=>!dep.missing);
+        // A configuration that packs is the published shape: its files ship, so a package they
+        // import that the root keeps for development would be missing for the consumer.
+        if (project.configuration.pack === true) {
+            const devOnly = resolved.filter((dep)=>dep.isDev && !dep.internal);
+            if (devOnly.length > 0) {
+                const lines = devOnly.map((dep)=>`  - ${dep.name}, imported by ${[
+                        ...importedBy.get(dep.name) ?? []
+                    ].sort().join(", ")}`);
+                throw new ForgeError(`${project.name} ships code that imports packages the root lists only as a devDependency:\n` + `${lines.join("\n")}\n` + "Move each to the root's dependencies, or, if the consumer provides it, " + `declare it in ${project.name}'s peerDependencies.`);
+            }
+        }
         const dependencies = Object.fromEntries(resolved.filter((dep)=>!dep.isDev).map((dep)=>[
                 dep.name,
                 dep.version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/forge",
-  "version": "0.0.1-dev.121",
+  "version": "0.0.1-dev.123",
   "description": "TypeScript monorepo build system — zero config, fast compilation, streamlined developer workflow",
   "keywords": [
     "typescript",
@@ -10,6 +10,15 @@
     "swc",
     "decohere"
   ],
+  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/forge#readme",
+  "bugs": {
+    "url": "https://github.com/typesmiths/decohere/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typesmiths/decohere.git",
+    "directory": "projects/forge"
+  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -29,11 +38,11 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/core": "0.0.1-dev.121",
-    "@decohere/crucible": "0.0.1-dev.121",
-    "@decohere/devkit": "0.0.1-dev.121",
-    "@decohere/scribe": "0.0.1-dev.121",
-    "@decohere/workspace": "0.0.1-dev.121",
+    "@decohere/core": "0.0.1-dev.123",
+    "@decohere/crucible": "0.0.1-dev.123",
+    "@decohere/devkit": "0.0.1-dev.123",
+    "@decohere/scribe": "0.0.1-dev.123",
+    "@decohere/workspace": "0.0.1-dev.123",
     "@swc/core": "^1.11.11",
     "async": "^3.2.6",
     "parse-imports": "^2.2.1",

package/types/src/actions/copy.action.d.ts

@@ -10,6 +10,11 @@ export declare class Copy implements Action<CopyOptions> {
     private readonly workspace;
     constructor(workspace: Workspace);
     run: (options: CopyOptions) => Promise<ActionResponse>;
+    /**
+     * A package without a LICENSE of its own ships the workspace's, so a monorepo
+     * licensed once at the root still puts the license text in every tarball.
+     */
+    private copyWorkspaceLicense;
     /**
      * Packed builds emit JS under `<out>/<target>/` (e.g. `es6/`). Assets listed on
      * the *configuration* `copyFiles` (not the workspace defaults) are also copied

package/types/src/services/dependency-resolver.service.d.ts

@@ -9,6 +9,13 @@ export declare class DependencyResolver {
     computeDrift(current: PackageJson, computed: PackageJson): DriftEntry | null;
     getWorkspacePackages(workspace: Workspace, projects: readonly Project[]): Promise<Map<string, Package>>;
     computeProjectDependencies(project: Project, workspacePackages: Map<string, Package>): Promise<ProjectDependencies>;
+    /**
+     * A package declares its peers by name in its own `peerDependencies` (and marks optional ones in
+     * `peerDependenciesMeta`, which sync leaves as written). The root owns every version, so each
+     * peer gets the root's range; a peer the root doesn't list is an error. A declared peer stays
+     * even when no code imports it: a pino transport, say, is loaded by name.
+     */
+    private getPeerDependencies;
     private getDependencies;
     private getDependencyFrom;
     private getFileImports;

package/types/src/types/dependency.types.d.ts

@@ -22,15 +22,14 @@ export type SyncprojectResult = ResultStatus & {
     projectName: string;
     drift?: DriftEntry | null;
 };
+export type DependencyLists = {
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    peerDependencies: Record<string, string>;
+};
 export type DriftEntry = {
-    original: {
-        dependencies: Record<string, string>;
-        devDependencies: Record<string, string>;
-    };
-    updated: {
-        dependencies: Record<string, string>;
-        devDependencies: Record<string, string>;
-    };
+    original: DependencyLists;
+    updated: DependencyLists;
 };
 export type DependencyWarning = {
     file: string;