@bobfrankston/npmglobalize 1.0.164 → 1.0.166

package/README.md

@@ -498,19 +498,34 @@ npmglobalize --dry-run     # See what would happen
 1. **Validates** package.json and git status
 2. **Checks** if current version is on npm (recovers from failed publishes)
 3. **Updates dependencies** (if `--update-deps`)
-4. **Publishes file: dependencies** (if needed)
-5. **Backs up** original file: references to `.dependencies`
-6. **Converts** `file:` → npm version references
-7. **Commits** changes
-8. **Bumps** version (using npm version) — skipped if recovering a failed publish
-9. **Publishes** to npm
-10. **Pushes** to git (with push-protection detection and auto-bypass)
-11. **Installs** globally (if `--install`)
-12. **Restores** file: references (if `--files`, default)
-13. **Runs audit** (shows security status)
+4. **Builds `file:` deps in topological order**, then the target itself, so consumers' `tsc` reads up-to-date `.d.ts` from sibling checkouts whose source has changed (see [Build Cascade](#build-cascade))
+5. **Publishes file: dependencies** (if needed)
+6. **Backs up** original file: references to `.dependencies`
+7. **Converts** `file:` → npm version references
+8. **Commits** changes
+9. **Bumps** version (using npm version) — skipped if recovering a failed publish
+10. **Publishes** to npm
+11. **Pushes** to git (with push-protection detection and auto-bypass)
+12. **Installs** globally (if `--install`)
+13. **Restores** file: references (if `--files`, default)
+14. **Runs audit** (shows security status)
 
 ## Operational Details
 
+### Build Cascade
+
+Before transforming or publishing anything, `npmglobalize` builds `file:` dependencies in topological order — deps before consumers — and then builds the target itself. This guarantees the target's `tsc` reads up-to-date `.d.ts` and `.js` from sibling checkouts even when a dep's source has changed since its last build.
+
+For each project visited (the target and every transitive `file:` dep):
+
+- If `tsconfig.json` is missing or has `"noEmit": true` → **skip** (not a TypeScript build).
+- If `tsconfig.json` exists but `package.json` has no `"build"` script → **prompt** to add `"build": "tsc"`. Decline and that project is skipped.
+- Otherwise → run `npm run build`. A failure halts the cascade unless `-force` is passed.
+
+Cycle-safe via a shared visited set; each project is built at most once per run.
+
+This complements the existing publish cascade (which ensures version refs are correct) by closing the build-freshness gap that `npm install` alone left open.
+
 ### The `.dependencies` Backup (Internal/Transient)
 
 **You should never see `.dependencies` in your `package.json` under normal operation.** It is a temporary internal backup that exists only during the brief publish cycle and is removed automatically when the cycle completes.

package/cli.js

@@ -2,11 +2,10 @@
 /**
  * npmglobalize CLI - Transform file: dependencies to npm versions for publishing
  */
-import { globalize, globalizeWorkspace, installCleanupHandlers, readConfig, readPackageJson, readUserNpmConfig, writeConfig, writePackageJson, confirm, getBuildIssues, clearBuildIssues, recordBuildIssue, extractFirstTscError, ensureFileDepModules, runCommand } from './lib.js';
+import { globalize, globalizeWorkspace, installCleanupHandlers, readConfig, readPackageJson, readUserNpmConfig, writeConfig, writePackageJson, getBuildIssues, clearBuildIssues, ensureFileDepModules, buildProject, buildFileDepsTopologically } from './lib.js';
 import fs from 'fs';
 import path from 'path';
 import { styleText } from 'util';
-import JSON5 from 'json5';
 // npmglobalize install directory (for --version)
 const __dirname = import.meta.dirname;
 function printHelp() {
@@ -429,53 +428,25 @@ export async function main() {
             process.exit(1);
         }
     }
-    // Build the target project if it has tsconfig (not noEmit)
+    // Build file: deps topologically, then the target itself.
+    // Ensures consumers' tsc sees up-to-date `.d.ts` from sibling checkouts
+    // whose source has changed since their last build.
     if (!cliOptions.cleanup) {
-        let shouldBuild = false;
-        try {
-            const tsconfigPath = path.join(cwd, 'tsconfig.json');
-            const content = fs.readFileSync(tsconfigPath, 'utf-8');
-            const tsconfig = JSON5.parse(content);
-            shouldBuild = tsconfig.compilerOptions?.noEmit !== true;
-        }
-        catch (error) {
-            // No tsconfig — skip build
+        ensureFileDepModules(cwd, !!cliOptions.verbose);
+        const depsOk = await buildFileDepsTopologically(cwd, { verbose: !!cliOptions.verbose, force: !!cliOptions.force });
+        if (!depsOk && !cliOptions.force) {
+            printBuildSummary();
+            process.exit(1);
         }
-        if (shouldBuild) {
-            const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
-            if (!pkg.scripts?.build) {
-                // TypeScript project without a build script — offer to add one
-                console.log(styleText('yellow', `TypeScript project has no "build" script in ${cwd}`));
-                const addIt = await confirm('Add "build": "tsc" to package.json?', true);
-                if (addIt) {
-                    if (!pkg.scripts)
-                        pkg.scripts = {};
-                    pkg.scripts.build = 'tsc';
-                    writePackageJson(cwd, pkg);
-                    console.log(styleText('green', '✓ Added "build": "tsc" to package.json'));
-                }
-            }
-            if (pkg.scripts?.build) {
-                ensureFileDepModules(cwd, !!cliOptions.verbose);
-                console.log(`Building ${cwd}...`);
-                const buildResult = runCommand('npm', ['run', 'build'], { cwd, silent: true });
-                if (buildResult.success) {
-                    console.log(styleText('green', '✓ Build succeeded'));
-                }
-                else {
-                    const buildOutput = (buildResult.stderr || '') + (buildResult.output || '');
-                    if (buildOutput)
-                        console.error(buildOutput);
-                    console.error(styleText('red', `Build failed in ${cwd}`));
-                    const firstErr = extractFirstTscError(buildOutput);
-                    recordBuildIssue(pkg.name || path.basename(cwd), 'error', firstErr || 'Build failed');
-                    if (!cliOptions.force) {
-                        printBuildSummary();
-                        process.exit(1);
-                    }
-                    console.log(styleText('yellow', 'Continuing with --force...'));
-                }
+        if (!depsOk)
+            console.log(styleText('yellow', 'Continuing with --force despite dep build failure...'));
+        const targetOk = await buildProject(cwd, { verbose: !!cliOptions.verbose, force: !!cliOptions.force });
+        if (!targetOk) {
+            if (!cliOptions.force) {
+                printBuildSummary();
+                process.exit(1);
             }
+            console.log(styleText('yellow', 'Continuing with --force...'));
         }
     }
     // Handle --package: update scripts in target package.json

package/lib.d.ts

@@ -270,6 +270,23 @@ export declare function missingDeps(pkgDir: string, pkg: any): string[];
  *  re-run" (partial-sync) cases. Also covers `cwd` itself on the first call.
  *  Cycle-safe via the shared `visited` set. */
 export declare function ensureFileDepModules(cwd: string, verbose?: boolean, visited?: Set<string>): void;
+/** Build a single project: detect tsconfig, prompt to add `build: tsc` if a
+ *  TypeScript project lacks a build script, run `npm run build`, record
+ *  failures. Returns true if build succeeded (or was skipped because no
+ *  tsconfig / noEmit / no build script after declining the prompt). */
+export declare function buildProject(cwd: string, opts?: {
+    verbose?: boolean;
+    force?: boolean;
+}): Promise<boolean>;
+/** Walk `file:` deps depth-first (deps before consumers) and build each one
+ *  that has a tsconfig. Mirrors `ensureFileDepModules`'s traversal but invokes
+ *  `buildProject` instead of `npm install`. Cycle-safe via shared `visited` set.
+ *  Does NOT build `cwd` itself — caller does that after this returns. Returns
+ *  true if every visited dep built successfully (or was skipped). */
+export declare function buildFileDepsTopologically(cwd: string, opts?: {
+    verbose?: boolean;
+    force?: boolean;
+}, visited?: Set<string>): Promise<boolean>;
 /** Ensure the workspace-root `node_modules/` is in sync with every member's
  *  declared deps. Workspaces hoist deps to the root, so a dep added to any
  *  member `package.json` without a follow-up `npm install` at the root leaves

package/lib.js

@@ -1563,6 +1563,98 @@ export function ensureFileDepModules(cwd, verbose = false, visited = new Set())
         }
     }
 }
+/** Build a single project: detect tsconfig, prompt to add `build: tsc` if a
+ *  TypeScript project lacks a build script, run `npm run build`, record
+ *  failures. Returns true if build succeeded (or was skipped because no
+ *  tsconfig / noEmit / no build script after declining the prompt). */
+export async function buildProject(cwd, opts = {}) {
+    let shouldBuild = false;
+    try {
+        const tsconfigPath = path.join(cwd, 'tsconfig.json');
+        const content = fs.readFileSync(tsconfigPath, 'utf-8');
+        const tsconfig = JSON5.parse(content);
+        shouldBuild = tsconfig.compilerOptions?.noEmit !== true;
+    }
+    catch {
+        // No tsconfig — skip
+    }
+    if (!shouldBuild)
+        return true;
+    const pkg = readPackageJson(cwd);
+    if (!pkg.scripts?.build) {
+        console.log(colors.yellow(`TypeScript project has no "build" script in ${pkg.name || cwd}`));
+        const addIt = await confirm(`Add "build": "tsc" to ${pkg.name || path.basename(cwd)}'s package.json?`, true);
+        if (addIt) {
+            if (!pkg.scripts)
+                pkg.scripts = {};
+            pkg.scripts.build = 'tsc';
+            writePackageJson(cwd, pkg);
+            console.log(colors.green(`✓ Added "build": "tsc" to ${pkg.name || path.basename(cwd)}`));
+        }
+        else {
+            return true;
+        }
+    }
+    console.log(`Building ${pkg.name || cwd}...`);
+    const buildResult = runCommand('npm', ['run', 'build'], { cwd, silent: true });
+    if (buildResult.success) {
+        console.log(colors.green(`✓ Build succeeded (${pkg.name || path.basename(cwd)})`));
+        return true;
+    }
+    const buildOutput = (buildResult.stderr || '') + (buildResult.output || '');
+    if (buildOutput)
+        console.error(buildOutput);
+    console.error(colors.red(`Build failed in ${pkg.name || cwd}`));
+    const firstErr = extractFirstTscError(buildOutput);
+    recordBuildIssue(pkg.name || path.basename(cwd), 'error', firstErr || 'Build failed');
+    return false;
+}
+/** Walk `file:` deps depth-first (deps before consumers) and build each one
+ *  that has a tsconfig. Mirrors `ensureFileDepModules`'s traversal but invokes
+ *  `buildProject` instead of `npm install`. Cycle-safe via shared `visited` set.
+ *  Does NOT build `cwd` itself — caller does that after this returns. Returns
+ *  true if every visited dep built successfully (or was skipped). */
+export async function buildFileDepsTopologically(cwd, opts = {}, visited = new Set()) {
+    const abs = path.resolve(cwd);
+    if (visited.has(abs))
+        return true;
+    visited.add(abs);
+    let pkg;
+    try {
+        pkg = readPackageJson(cwd);
+    }
+    catch {
+        return true;
+    }
+    let allOk = true;
+    for (const key of ['dependencies', 'devDependencies']) {
+        const deps = pkg?.[key];
+        if (!deps || typeof deps !== 'object')
+            continue;
+        for (const [, spec] of Object.entries(deps)) {
+            if (typeof spec !== 'string' || !spec.startsWith('file:'))
+                continue;
+            const target = path.resolve(cwd, spec.slice('file:'.length));
+            if (!fs.existsSync(path.join(target, 'package.json')))
+                continue;
+            const targetAbs = path.resolve(target);
+            if (visited.has(targetAbs))
+                continue;
+            // Recurse first (deps before consumer)
+            const childOk = await buildFileDepsTopologically(target, opts, visited);
+            if (!childOk)
+                allOk = false;
+            // Build this dep itself
+            const ok = await buildProject(target, opts);
+            if (!ok) {
+                allOk = false;
+                if (!opts.force)
+                    return false;
+            }
+        }
+    }
+    return allOk;
+}
 /** Ensure the workspace-root `node_modules/` is in sync with every member's
  *  declared deps. Workspaces hoist deps to the root, so a dep added to any
  *  member `package.json` without a follow-up `npm install` at the root leaves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.164",
+  "version": "1.0.166",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",