@bobfrankston/npmglobalize 1.0.205 → 1.0.207

package/lib.d.ts

@@ -25,6 +25,16 @@ export declare function clearBuildIssues(): void;
 /** Extract the first TypeScript error line from build output for the summary.
  *  Returns a short string like "file.ts(42,5): error TS2339: Property 'foo' ..." */
 export declare function extractFirstTscError(output: string): string | null;
+/** A TS7016 — "Could not find a declaration file for module 'X'" — that tsc blames
+ *  on the file being compiled is frequently not that file's fault: the copy of X in
+ *  node_modules carries no `.d.ts` whatsoever. That happens when X was published at
+ *  a moment its declaration output was not on disk, so the tarball ships JS only and
+ *  every consumer resolving X through the registry fails identically. tsc's stock
+ *  advice — `npm i --save-dev @types/bobfrankston__hlib` — then sends the user after
+ *  a types package that does not and will never exist, which is worse than no advice.
+ *  Recognize the shape and say what actually fixes it.
+ *  Returns one diagnosis line per untyped module; empty when TS7016 has another cause. */
+export declare function diagnoseUntypedDeps(cwd: string, buildOutput: string): string[];
 /** One package that depends on this one, recorded in this package's
  *  .globalize.json5 when that package publishes. */
 export interface UpstreamEntry {
@@ -277,6 +287,26 @@ export type UnpublishedDep = {
     path: string;
     reason: 'new' | 'update';
 };
+/** Vet the casing of every `file:` dependency path, in BOTH places it is recorded:
+ *  the spec in package.json and the junction npm created in node_modules.
+ *
+ *  npm resolves a `file:` spec by string concatenation against the cwd and writes
+ *  the result as the link target — it never canonicalizes case, and never checks
+ *  that the target exists. On Windows that rots invisibly: `projects/nodejs/x`
+ *  resolves fine when the directory is really `projects/NodeJS/x`, so nothing
+ *  complains until the path reaches somewhere case matters. Two places it does:
+ *  WSL and Linux deploys can't resolve it at all, and npm's own arborist keys
+ *  nodes by path string, so one directory reached under two spellings becomes two
+ *  nodes and tree loading dies with "Cannot read properties of null".
+ *
+ *  Both records must be repaired together. Fixing only the manifest leaves the
+ *  stale junction in place (npm will not recreate a link it thinks is satisfied);
+ *  fixing only the junction lets the next `npm install` write the bad case back. */
+export declare function verifyDepPathCase(cwd: string, pkg: any): {
+    specs: string[];
+    links: string[];
+    missing: string[];
+};
 export declare function transformDeps(pkg: any, baseDir: string, verbose?: boolean, forcePublish?: boolean): {
     transformed: boolean;
     unpublished: UnpublishedDep[];

package/lib.js

@@ -79,6 +79,97 @@ export function extractFirstTscError(output) {
     }
     return null;
 }
+/** Does `dir` contain any `.d.ts` at all? Bounded, and never descends into a
+ *  nested `node_modules` — we are asking about this package's own output. */
+function hasDeclarationFiles(dir, depth = 3) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const e of entries) {
+        if (e.isFile() && e.name.endsWith('.d.ts'))
+            return true;
+    }
+    if (depth <= 0)
+        return false;
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name === 'node_modules' || e.name.startsWith('.'))
+            continue;
+        if (hasDeclarationFiles(path.join(dir, e.name), depth - 1))
+            return true;
+    }
+    return false;
+}
+/** The spec a consumer declares for `name`. `.dependencies` is checked first
+ *  because during a publish the live `file:` paths live there while
+ *  `dependencies` temporarily holds the npm refs that were swapped in. */
+function declaredDepSpec(pkg, name) {
+    for (const bucket of ['.dependencies', 'dependencies', 'devDependencies']) {
+        const spec = pkg?.[bucket]?.[name];
+        if (typeof spec === 'string')
+            return spec;
+    }
+    return '';
+}
+/** A TS7016 — "Could not find a declaration file for module 'X'" — that tsc blames
+ *  on the file being compiled is frequently not that file's fault: the copy of X in
+ *  node_modules carries no `.d.ts` whatsoever. That happens when X was published at
+ *  a moment its declaration output was not on disk, so the tarball ships JS only and
+ *  every consumer resolving X through the registry fails identically. tsc's stock
+ *  advice — `npm i --save-dev @types/bobfrankston__hlib` — then sends the user after
+ *  a types package that does not and will never exist, which is worse than no advice.
+ *  Recognize the shape and say what actually fixes it.
+ *  Returns one diagnosis line per untyped module; empty when TS7016 has another cause. */
+export function diagnoseUntypedDeps(cwd, buildOutput) {
+    if (!buildOutput)
+        return [];
+    const named = new Set();
+    const re = /error TS7016: Could not find a declaration file for module '([^']+)'/g;
+    for (let m = re.exec(buildOutput); m; m = re.exec(buildOutput))
+        named.add(m[1]);
+    if (!named.size)
+        return [];
+    let consumer = {};
+    try {
+        consumer = readPackageJson(cwd);
+    }
+    catch { /* an unreadable consumer still leaves the dep diagnosable */ }
+    const scopeOf = (n) => n.startsWith('@') && n.includes('/') ? n.slice(0, n.indexOf('/')) : '';
+    const lines = [];
+    for (const name of named) {
+        if (name.startsWith('.'))
+            continue; // a relative import — a code bug, not a packaging one
+        const installed = path.join(cwd, 'node_modules', ...name.split('/'));
+        if (!fs.existsSync(path.join(installed, 'package.json')))
+            continue;
+        if (hasDeclarationFiles(installed))
+            continue; // declarations are present; TS7016 came from something else
+        let version = '';
+        try {
+            version = readPackageJson(installed).version || '';
+        }
+        catch { /* version is decoration here */ }
+        const at = version ? `@${version}` : '';
+        // A `file:` spec points at live source we can look at directly, which tells
+        // us whether the missing declarations are a build problem or a stale install.
+        const spec = declaredDepSpec(consumer, name);
+        const source = spec.startsWith('file:') ? path.resolve(cwd, spec.slice('file:'.length)) : '';
+        if (source && fs.existsSync(source)) {
+            lines.push(hasDeclarationFiles(source)
+                ? `${name} resolves to a copy in node_modules with no .d.ts, but its source at ${source} has them — the install is stale. Run \`npm install\` in ${cwd}.`
+                : `${name}'s source at ${source} emits no .d.ts — set "declaration": true in its tsconfig and rebuild it.`);
+            continue;
+        }
+        const ownScope = scopeOf(name) && scopeOf(name) === scopeOf(consumer?.name || '');
+        lines.push(ownScope
+            ? `${name}${at} was published with no .d.ts in the tarball, so every consumer that installs it from npm fails this way — it is not a problem in ${consumer?.name || 'this package'}. Rebuild and republish ${name} (\`npmglobalize\` in its source directory), or depend on its source with a file: path. Ignore tsc's @types/… suggestion; no such package exists.`
+            : `${name}${at} ships no type declarations. Install its @types package if one exists, or add a .d.ts declaring the module.`);
+    }
+    return lines;
+}
 /**
  * Remove 'nul' files from a directory tree (Windows reserved name issue).
  * These files break git and npm on Windows. Uses \\?\ prefix to bypass name validation.
@@ -1229,6 +1320,125 @@ function hasLocalChanges(packageName, version, targetPath, verbose) {
         return false;
     }
 }
+/** The canonical on-disk spelling of `target`, or null if it does not exist.
+ *  Windows answers path queries case-insensitively, so the only way to learn how
+ *  a directory is really spelled is to ask its parent to list it — a segment at a
+ *  time, from the root down. */
+function canonicalCase(target) {
+    const full = path.resolve(target);
+    if (!fs.existsSync(full))
+        return null;
+    const parsed = path.parse(full);
+    const parts = full.slice(parsed.root.length).split(/[\\/]/).filter(Boolean);
+    let cur = parsed.root.toUpperCase();
+    for (const part of parts) {
+        let entries;
+        try {
+            entries = fs.readdirSync(cur);
+        }
+        catch {
+            return null;
+        }
+        const real = entries.find(e => e.toLowerCase() === part.toLowerCase());
+        if (!real)
+            return null;
+        cur = path.join(cur, real);
+    }
+    return cur;
+}
+/** True when two paths name the same place but are spelled with different case
+ *  in a directory name. A bare drive-letter difference (`y:` vs `Y:`) doesn't
+ *  count — it resolves identically everywhere, including WSL's /mnt/y. */
+function caseDiffers(a, b) {
+    const strip = (p) => p.replace(/[\\/]+$/, '').slice(path.parse(p).root.length);
+    return strip(a) !== strip(b);
+}
+/** Vet the casing of every `file:` dependency path, in BOTH places it is recorded:
+ *  the spec in package.json and the junction npm created in node_modules.
+ *
+ *  npm resolves a `file:` spec by string concatenation against the cwd and writes
+ *  the result as the link target — it never canonicalizes case, and never checks
+ *  that the target exists. On Windows that rots invisibly: `projects/nodejs/x`
+ *  resolves fine when the directory is really `projects/NodeJS/x`, so nothing
+ *  complains until the path reaches somewhere case matters. Two places it does:
+ *  WSL and Linux deploys can't resolve it at all, and npm's own arborist keys
+ *  nodes by path string, so one directory reached under two spellings becomes two
+ *  nodes and tree loading dies with "Cannot read properties of null".
+ *
+ *  Both records must be repaired together. Fixing only the manifest leaves the
+ *  stale junction in place (npm will not recreate a link it thinks is satisfied);
+ *  fixing only the junction lets the next `npm install` write the bad case back. */
+export function verifyDepPathCase(cwd, pkg) {
+    const specs = [];
+    const links = [];
+    const missing = [];
+    for (const bucket of ['dependencies', 'devDependencies', '.dependencies']) {
+        const deps = pkg?.[bucket];
+        if (!deps || typeof deps !== 'object')
+            continue;
+        for (const [name, spec] of Object.entries(deps)) {
+            if (typeof spec !== 'string' || !spec.startsWith('file:'))
+                continue;
+            const abs = path.resolve(cwd, spec.slice('file:'.length));
+            const canonical = canonicalCase(abs);
+            if (!canonical) {
+                missing.push(`${name} -> ${spec} (no such directory)`);
+                continue;
+            }
+            if (!caseDiffers(abs, canonical))
+                continue;
+            // Keep the spec relative, the way it was written.
+            const rel = path.relative(cwd, canonical).split(path.sep).join('/');
+            deps[name] = `file:${rel}`;
+            specs.push(`${name}: ${spec} -> file:${rel}`);
+        }
+    }
+    // The junction npm already made from the old spelling.
+    for (const bucket of ['dependencies', 'devDependencies', '.dependencies']) {
+        const deps = pkg?.[bucket];
+        if (!deps || typeof deps !== 'object')
+            continue;
+        for (const [name, spec] of Object.entries(deps)) {
+            if (typeof spec !== 'string' || !spec.startsWith('file:'))
+                continue;
+            const linkPath = path.join(cwd, 'node_modules', ...name.split('/'));
+            let stat;
+            try {
+                stat = fs.lstatSync(linkPath);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isSymbolicLink())
+                continue;
+            let current;
+            try {
+                current = fs.readlinkSync(linkPath).replace(/[\\/]+$/, '');
+            }
+            catch {
+                continue;
+            }
+            const canonical = canonicalCase(current);
+            if (!canonical || !caseDiffers(current, canonical))
+                continue;
+            try {
+                // On Windows a directory junction is removed with rmdir, not unlink,
+                // and neither follows the link — which matters, because deleting
+                // through it would take the real package tree with it.
+                if (process.platform === 'win32')
+                    fs.rmdirSync(linkPath);
+                else
+                    fs.unlinkSync(linkPath);
+                fs.symlinkSync(canonical, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
+                links.push(`${name}: ${current} -> ${canonical}`);
+            }
+            catch (error) {
+                missing.push(`${name}: could not repair link (${error.message})`);
+            }
+        }
+    }
+    return { specs, links, missing };
+}
 export function transformDeps(pkg, baseDir, verbose = false, forcePublish = false) {
     let transformed = false;
     const unpublished = [];
@@ -3218,8 +3428,21 @@ export async function buildProject(cwd, opts = {}) {
     if (buildOutput)
         console.error(buildOutput);
     console.error(colors.red(`Build failed in ${pkg.name || cwd}`));
+    const label = pkg.name || path.basename(cwd);
+    // tsc reports a missing-declarations failure against the file that imports the
+    // dep, and suggests an @types package that does not exist for private scopes.
+    // When the real cause is a dep installed without any .d.ts, say so plainly and
+    // put THAT in the summary — the raw tsc line is already echoed above.
+    const untyped = diagnoseUntypedDeps(cwd, buildOutput);
+    if (untyped.length) {
+        for (const line of untyped) {
+            console.error(colors.yellow(`  ${line}`));
+            recordBuildIssue(label, 'error', line);
+        }
+        return false;
+    }
     const firstErr = extractFirstTscError(buildOutput);
-    recordBuildIssue(pkg.name || path.basename(cwd), 'error', firstErr || 'Build failed');
+    recordBuildIssue(label, 'error', firstErr || 'Build failed');
     return false;
 }
 /** Walk `file:` deps depth-first (deps before consumers) and build each one
@@ -6497,6 +6720,23 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
             }
         }
     }
+    // Vet file: path casing before transformDeps swaps the specs out — this is the
+    // last moment the real paths are still in hand. Repairs the manifest and the
+    // node_modules junction together; fixing either alone is undone by the other.
+    const caseCheck = verifyDepPathCase(cwd, pkg);
+    if (caseCheck.specs.length || caseCheck.links.length) {
+        for (const fix of caseCheck.specs)
+            console.log(colors.green(`  ✓ Corrected file: path case in package.json — ${fix}`));
+        for (const fix of caseCheck.links)
+            console.log(colors.green(`  ✓ Corrected node_modules link case — ${fix}`));
+        if (caseCheck.specs.length)
+            writePackageJson(cwd, pkg);
+        recordBuildIssue(pkg.name || path.basename(cwd), 'warning', `Corrected ${caseCheck.specs.length} file: path spec(s) and ${caseCheck.links.length} node_modules link(s) whose letter case did not match the directory on disk. npm does not canonicalize these, and the wrong case breaks WSL, Linux deploys, and npm's own tree loading.`);
+    }
+    for (const gone of caseCheck.missing) {
+        console.error(colors.red(`  ✗ file: dependency path does not exist — ${gone}`));
+        recordBuildIssue(pkg.name || path.basename(cwd), 'error', `file: dependency path does not exist — ${gone}`);
+    }
     // Transform dependencies
     if (verbose) {
         console.log('Transforming file: dependencies...');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.205",
+  "version": "1.0.207",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",
@@ -33,8 +33,8 @@
   "dependencies": {
     "@bobfrankston/freezepak": "^0.1.9",
     "@bobfrankston/importgen": "^0.1.40",
-    "@bobfrankston/themecolors": "^0.1.8",
-    "@bobfrankston/userconfig": "^1.0.10",
+    "@bobfrankston/themecolors": "^0.1.9",
+    "@bobfrankston/userconfig": "^1.0.11",
     "@npmcli/package-json": "^7.0.4",
     "json5": "^2.2.3",
     "libnpmversion": "^8.0.3",
@@ -61,8 +61,8 @@
     "dependencies": {
       "@bobfrankston/freezepak": "^0.1.9",
       "@bobfrankston/importgen": "^0.1.40",
-      "@bobfrankston/themecolors": "^0.1.8",
-      "@bobfrankston/userconfig": "^1.0.10",
+      "@bobfrankston/themecolors": "^0.1.9",
+      "@bobfrankston/userconfig": "^1.0.11",
       "@npmcli/package-json": "^7.0.4",
       "json5": "^2.2.3",
       "libnpmversion": "^8.0.3",