@bobfrankston/npmglobalize 1.0.201 → 1.0.203

package/lib.js

@@ -42,6 +42,16 @@ const _buildIssues = [];
 export function recordBuildIssue(module, severity, message) {
     _buildIssues.push({ module, severity, message });
 }
+/** How many issues have been recorded so far — pair with `dropBuildIssuesFrom`
+ *  to un-record issues for an action that was subsequently undone. */
+function markBuildIssues() {
+    return _buildIssues.length;
+}
+/** Drop every issue recorded after `mark` (see `markBuildIssues`). */
+function dropBuildIssuesFrom(mark) {
+    if (mark >= 0 && mark < _buildIssues.length)
+        _buildIssues.length = mark;
+}
 /** Get all accumulated build issues */
 export function getBuildIssues() {
     return _buildIssues;
@@ -219,6 +229,33 @@ export function readConfig(dir) {
         return {};
     }
 }
+/** Inline comments for boolean settings in .globalize.json5. Value-aware: a
+ *  negated setting must not read as though it still does the thing (a
+ *  `"quiet": false` line saying "Suppress npm warnings" describes the
+ *  opposite of what it does). */
+const BOOL_COMMENTS = {
+    install: { on: 'Auto-install globally after publish (from registry)', off: 'Do NOT auto-install globally after publish' },
+    link: { on: 'Install globally via symlink (npm install -g .)', off: 'Do NOT install globally via symlink' },
+    wsl: { on: 'Also install in WSL', off: 'Do NOT install in WSL' },
+    files: { on: 'Restore file: paths after publish', off: 'Leave npm versions in package.json after publish' },
+    force: { on: 'Continue despite git errors', off: 'Stop on git errors' },
+    quiet: { on: 'Suppress npm warnings', off: 'Show npm warnings' },
+    verbose: { on: 'Show detailed output', off: 'Normal output detail' },
+    fix: { on: 'Auto-run npm audit fix', off: 'Do NOT run npm audit fix' },
+    local: { on: 'Local install only (skip transform/publish)', off: 'Normal transform/publish flow' },
+    noPublish: { on: 'Transform but don\'t publish', off: 'Publish normally' },
+    freeze: { on: 'Freeze node_modules (replace symlinks with real copies)', off: 'Leave node_modules symlinks as-is' },
+    usePaths: { on: 'Resolve file: deps from sibling checkouts', off: 'Resolve file: deps from npm, not siblings (standalone package)' },
+    allowTs: { on: 'Keep .ts source (and *.map, tsconfig.json) in the published npm tarball', off: 'Strip .ts source from the published npm tarball' },
+    importgen: { on: 'Regenerate browser import maps', off: 'Never ask about importgen here' }
+};
+/** Inline comments for settings whose value isn't a plain boolean. */
+const VALUE_COMMENTS = {
+    gitVisibility: 'private (default) or public',
+    npmVisibility: 'private (default) or public',
+    bump: 'patch (default), minor, or major',
+    subProjects: 'Sub-dirs with their own tsconfig that build must compile (false = never ask)'
+};
 /** Write .globalize.json5 config file */
 export function writeConfig(dir, config, explicitKeys) {
     const configPath = path.join(dir, '.globalize.json5');
@@ -284,68 +321,51 @@ export function writeConfig(dir, config, explicitKeys) {
             }
             const jsonValue = typeof value === 'string' ? `"${value}"` : JSON.stringify(value);
             const comma = ','; // JSON5 allows trailing commas
-            // Add inline comment for clarity
+            // Add inline comment for clarity, keyed off the actual value so a
+            // negated boolean doesn't describe the behaviour it turns off.
             let comment = '';
-            if (key === 'install')
-                comment = '  // Auto-install globally after publish (from registry)';
-            else if (key === 'link')
-                comment = '  // Install globally via symlink (npm install -g .)';
-            else if (key === 'wsl')
-                comment = '  // Also install in WSL';
-            else if (key === 'files')
-                comment = '  // Keep file: paths after publish';
-            else if (key === 'force')
-                comment = '  // Continue despite git errors';
-            else if (key === 'quiet')
-                comment = '  // Suppress npm warnings';
-            else if (key === 'verbose')
-                comment = '  // Show detailed output';
-            else if (key === 'gitVisibility')
-                comment = '  // private (default) or public';
-            else if (key === 'npmVisibility')
-                comment = '  // private (default) or public';
-            else if (key === 'bump')
-                comment = '  // patch (default), minor, or major';
-            else if (key === 'fix')
-                comment = '  // Auto-run npm audit fix';
-            else if (key === 'local')
-                comment = '  // Local install only (skip transform/publish)';
-            else if (key === 'noPublish')
-                comment = '  // Transform but don\'t publish';
-            else if (key === 'freeze')
-                comment = '  // Freeze node_modules (replace symlinks with real copies)';
-            else if (key === 'usePaths')
-                comment = '  // Resolve file: deps from sibling checkouts (set false for standalone packages)';
-            else if (key === 'allowTs')
-                comment = '  // Keep .ts source (and *.map, tsconfig.json) in the published npm tarball';
-            else if (key === 'importgen')
-                comment = '  // Regenerate browser import maps (false = never ask about importgen here)';
-            else if (key === 'subProjects')
-                comment = '  // Sub-dirs with their own tsconfig that build must compile (false = never ask)';
+            const boolComment = BOOL_COMMENTS[key];
+            if (boolComment && typeof value === 'boolean') {
+                comment = `  // ${value ? boolComment.on : boolComment.off}`;
+            }
+            else if (VALUE_COMMENTS[key]) {
+                comment = `  // ${VALUE_COMMENTS[key]}`;
+            }
+            else if (boolComment) {
+                // Non-boolean value for a normally-boolean key (e.g. subProjects: ["Sw"])
+                comment = `  // ${boolComment.on}`;
+            }
             lines.push(`  "${key}": ${jsonValue}${comma}${comment}`);
         });
         lines.push('');
     }
-    // Add commented reference for all options
+    // Add commented reference for all options. Booleans are phrased "true = ..."
+    // so the description reads correctly next to a default of false.
     lines.push('  // Defaults (omitted above):');
-    lines.push('  // "bump": "patch"              // Version bump: patch, minor, major');
-    lines.push('  // "install": false             // Auto-install globally after publish (from registry)');
-    lines.push('  // "link": false               // Install globally via symlink (npm install -g .)');
-    lines.push('  // "wsl": false                 // Also install in WSL');
-    lines.push('  // "files": true                // Keep file: paths after publish');
-    lines.push('  // "force": false               // Continue despite git errors');
-    lines.push('  // "quiet": true                // Suppress npm warnings');
-    lines.push('  // "verbose": false             // Show detailed output');
-    lines.push('  // "gitVisibility": "private"   // Git repo: private or public');
-    lines.push('  // "npmVisibility": "private"   // npm package: private or public');
-    lines.push('  // "fix": false                 // Auto-run npm audit fix');
-    lines.push('  // "local": false              // Local install only (skip transform/publish)');
-    lines.push('  // "noPublish": false          // Transform but don\'t publish');
-    lines.push('  // "freeze": false              // Freeze node_modules (replace symlinks with real copies)');
-    lines.push('  // "usePaths": true              // Resolve file: deps from siblings; false = use latest npm version (standalone)');
-    lines.push('  // "allowTs": false              // Include .ts source in npm tarball (auto-true for noEmit projects)');
-    lines.push('  // "importgen": auto             // Detected from .vscode/tasks.json / import map in HTML; false = never ask');
-    lines.push('  // "subProjects": auto           // Sub-dirs with their own tsconfig (e.g. ["Sw"]); detected from .vscode/tasks.json; false = never ask');
+    const reference = [
+        ['"bump": "patch"', 'Version bump: patch, minor, major'],
+        ['"install": false', 'true = auto-install globally after publish (from registry)'],
+        ['"link": false', 'true = install globally via symlink (npm install -g .)'],
+        ['"wsl": false', 'true = also install in WSL'],
+        ['"files": true', 'true = restore file: paths after publish; false = leave npm versions in package.json'],
+        ['"force": false', 'true = continue despite git errors'],
+        ['"quiet": true', 'true = suppress npm warnings'],
+        ['"verbose": false', 'true = show detailed output'],
+        ['"gitVisibility": "private"', 'Git repo: private or public'],
+        ['"npmVisibility": "private"', 'npm package: private or public'],
+        ['"fix": false', 'true = auto-run npm audit fix'],
+        ['"local": false', 'true = local install only (skip transform/publish)'],
+        ['"noPublish": false', 'true = transform but don\'t publish'],
+        ['"freeze": false', 'true = freeze node_modules (replace symlinks with real copies)'],
+        ['"usePaths": true', 'true = resolve file: deps from siblings; false = use latest npm version (standalone)'],
+        ['"allowTs": false', 'true = include .ts source in npm tarball (auto-true for noEmit projects)'],
+        ['"importgen": auto', 'Detected from .vscode/tasks.json / import map in HTML; false = never ask'],
+        ['"subProjects": auto', 'Sub-dirs with their own tsconfig (e.g. ["Sw"]); detected from .vscode/tasks.json; false = never ask']
+    ];
+    const refWidth = Math.max(...reference.map(([decl]) => decl.length));
+    for (const [decl, note] of reference) {
+        lines.push(`  // ${decl.padEnd(refWidth)}  // ${note}`);
+    }
     lines.push('}');
     fs.writeFileSync(configPath, lines.join('\n') + '\n');
 }
@@ -2313,8 +2333,12 @@ function ensureTsconfigNodeTypes(cwd) {
  *  most-leaf writable config so it wins. This is a *semantic* change: the rebuild
  *  may now surface genuine resolution errors — that is the point. Those are real
  *  bugs the `node10` resolver was hiding, not deprecations. Returns true if it
- *  changed any file. */
-function migrateTsconfigDeprecations(cwd) {
+ *  changed any file.
+ *
+ *  Pass `snapshot` to capture each touched file's original text (path → text)
+ *  before it is rewritten, so the caller can put the tsconfigs back if the
+ *  migrated build turns out to be worse than the un-migrated one. */
+function migrateTsconfigDeprecations(cwd, snapshot) {
     const tsconfigPath = path.join(cwd, 'tsconfig.json');
     if (!fs.existsSync(tsconfigPath))
         return false;
@@ -2348,6 +2372,8 @@ function migrateTsconfigDeprecations(cwd) {
             return false;
         try {
             fs.writeFileSync(filePath, patched);
+            if (snapshot && !snapshot.has(filePath))
+                snapshot.set(filePath, text);
             return true;
         }
         catch (error) {
@@ -2403,6 +2429,35 @@ function migrateTsconfigDeprecations(cwd) {
     }
     return changed;
 }
+/** Write back the texts captured in a `migrateTsconfigDeprecations` snapshot
+ *  (path → text). Used to undo a migration whose build turned out worse, and to
+ *  re-apply it afterwards. Returns false if any write failed — the tree is then
+ *  in a mixed state, which the caller reports rather than hides. */
+function restoreTsconfigTexts(texts) {
+    let ok = true;
+    for (const [filePath, text] of texts) {
+        try {
+            fs.writeFileSync(filePath, text);
+        }
+        catch (error) {
+            ok = false;
+            console.error(colors.yellow(`  Could not restore tsconfig (${filePath}): ${error.message}`));
+        }
+    }
+    return ok;
+}
+/** Current text of every file in a snapshot, so a migration can be re-applied
+ *  after being tried in reverse. */
+function readTsconfigTexts(paths) {
+    const out = new Map();
+    for (const p of paths) {
+        try {
+            out.set(p, fs.readFileSync(p, 'utf-8'));
+        }
+        catch { /* gone — nothing to re-apply */ }
+    }
+    return out;
+}
 /** Newest mtime of any regular file under `dir` (recursive). Symlinks/junctions
  *  are not followed — the file: dep webs here link back into sibling checkouts. */
 function newestMtimeUnder(dir) {
@@ -2903,15 +2958,29 @@ export async function buildProject(cwd, opts = {}) {
     // with no tsconfig at all, and still need its import map regenerated.
     await ensureImportgenInBuild(cwd);
     let shouldBuild = false;
+    let hasTsconfig = false;
     try {
         const tsconfigPath = path.join(cwd, 'tsconfig.json');
         const content = fs.readFileSync(tsconfigPath, 'utf-8');
         const tsconfig = JSON5.parse(content);
+        hasTsconfig = true;
         shouldBuild = tsconfig.compilerOptions?.noEmit !== true;
     }
     catch {
         // No tsconfig — skip
     }
+    // Fix removed-in-TS7 tsconfig settings up front rather than waiting for a
+    // build to fail on them. A deprecated `moduleResolution` is only a *hard*
+    // error under the tsc that flags it (TS6+, and the editor's bundled
+    // compiler), so a package pinned to an older tsc — or one that never gets
+    // to the build at all (noEmit, no build script, output already fresh) —
+    // would otherwise keep the deprecation until TS7 removes it outright.
+    // Deliberately ahead of every early return below: the tsconfig is worth
+    // fixing whether or not this package builds. Migrating also touches
+    // tsconfig.json, which makes the freshness check correctly read as stale.
+    const tsconfigSnapshot = new Map();
+    const issueMark = markBuildIssues();
+    const migratedUpFront = hasTsconfig && migrateTsconfigDeprecations(cwd, tsconfigSnapshot);
     let earlyPkg;
     try {
         earlyPkg = readPackageJson(cwd);
@@ -2964,7 +3033,9 @@ export async function buildProject(cwd, opts = {}) {
     // freshness — one the user declined to wire in isn't this build's business.
     const finalBuild = typeof pkg.scripts?.build === 'string' ? pkg.scripts.build : '';
     const wiredSubs = detectSubProjects(cwd).filter(s => scriptBuildsSubProject(finalBuild, s.dir));
-    if (!opts.forceBuild && isBuildUpToDate(cwd) && areSubProjectsUpToDate(cwd, wiredSubs)
+    // A migration just changed how modules resolve — never report that as fresh;
+    // the rebuild is what validates it (and what the revert path above needs).
+    if (!opts.forceBuild && !migratedUpFront && isBuildUpToDate(cwd) && areSubProjectsUpToDate(cwd, wiredSubs)
         && (!runsImportgen || isImportMapUpToDate(cwd))) {
         console.log(colors.dim(`– Build up to date (${pkg.name || path.basename(cwd)})`));
         return true;
@@ -2977,10 +3048,41 @@ export async function buildProject(cwd, opts = {}) {
         // We don't silence with ignoreDeprecations — the retry may now surface real
         // resolution errors, which are genuine bugs to fix, not deprecations.
         const out = (buildResult.stderr || '') + (buildResult.output || '');
-        if (/error TS510[17]\b/.test(out) && migrateTsconfigDeprecations(cwd)) {
+        if (/error TS510[17]\b/.test(out) && migrateTsconfigDeprecations(cwd, tsconfigSnapshot)) {
             buildResult = await runCommandAsync('npm', ['run', 'build'], { cwd, silent: true });
         }
     }
+    if (!buildResult.success && migratedUpFront && tsconfigSnapshot.size) {
+        // The up-front migration is a semantic change: `nodenext` resolution can
+        // surface real errors (missing file extensions on relative imports) that
+        // `node10` was hiding. Those are genuine bugs — but they are not this
+        // publish's business, and silently breaking a build that worked a moment
+        // ago is worse than leaving the deprecation in place. So put the
+        // tsconfigs back, and if that restores a working build, hand the user
+        // the errors plus the command that migrates for real.
+        const migratedOutput = (buildResult.stderr || '') + (buildResult.output || '');
+        const migratedTexts = readTsconfigTexts(tsconfigSnapshot.keys());
+        if (restoreTsconfigTexts(tsconfigSnapshot)) {
+            const retry = await runCommandAsync('npm', ['run', 'build'], { cwd, silent: true });
+            if (retry.success) {
+                dropBuildIssuesFrom(issueMark); // the migration was undone; its warnings no longer apply
+                const firstErr = extractFirstTscError(migratedOutput);
+                const label = pkg.name || path.basename(cwd);
+                console.log(colors.yellow(`  Reverted the tsconfig TS7 migration in ${label} — it broke the build:`));
+                if (firstErr)
+                    console.log(colors.yellow(`    ${firstErr}`));
+                console.log(colors.yellow(`    Deprecated settings left in place. Fix with: npmglobalize ${cwd} -tsfix`));
+                recordBuildIssue(label, 'warning', `tsconfig still uses settings TypeScript 7 removes: migrating to "nodenext" broke the build (${firstErr || 'see build output'}). Run \`npmglobalize ${cwd} -tsfix\` and fix the surfaced imports.`);
+                buildResult = retry;
+            }
+            else {
+                // The build was already failing for its own reasons — the migration
+                // isn't what broke it, so keep the migrated (TS7-ready) tsconfigs
+                // and report the migrated build's failure.
+                restoreTsconfigTexts(migratedTexts);
+            }
+        }
+    }
     if (buildResult.success) {
         console.log(colors.green(`✓ Build succeeded (${pkg.name || path.basename(cwd)})`));
         return true;

package/package.json

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