@bobfrankston/npmglobalize 1.0.205 → 1.0.206

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 {

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.
@@ -3218,8 +3309,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

package/package.json

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