@bobfrankston/npmglobalize 1.0.204 → 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.
@@ -2383,23 +2474,43 @@ function migrateTsconfigDeprecations(cwd, snapshot) {
     };
     const note = (msg) => console.log(colors.cyan(`  ${msg}`));
     let changed = false;
-    // moduleResolution: node/node10/classic → nodenext (+ align module).
+    // moduleResolution: node/node10/classic → NodeNext (+ align module).
     const mr = effectiveCompilerOption(chain, 'moduleResolution');
     if (mr && typeof mr.value === 'string' && DEPRECATED_MODULE_RESOLUTION.has(mr.value.toLowerCase())) {
         const tgt = targetFor(mr.definedIn);
-        if (tgt && edit(tgt.path, t => upsertCompilerOption(t, 'moduleResolution', '"nodenext"'))) {
+        if (tgt && edit(tgt.path, t => upsertCompilerOption(t, 'moduleResolution', `"${CANONICAL_NODENEXT}"`))) {
             changed = true;
-            note(`Migrated moduleResolution "${mr.value}" → "nodenext" in ${path.relative(cwd, tgt.path) || 'tsconfig.json'}`);
+            note(`Migrated moduleResolution "${mr.value}" → "${CANONICAL_NODENEXT}" in ${path.relative(cwd, tgt.path) || 'tsconfig.json'}`);
             // nodenext resolution requires a matching module setting.
             const mod = effectiveCompilerOption(chain, 'module');
             const modOk = mod && typeof mod.value === 'string' && /^(node16|nodenext|preserve)$/i.test(mod.value);
             if (!modOk) {
                 const modTgt = mod ? targetFor(mod.definedIn) : mostLeafWritable;
-                if (modTgt && edit(modTgt.path, t => upsertCompilerOption(t, 'module', '"nodenext"'))) {
-                    note(`Aligned module → "nodenext" (required by moduleResolution "nodenext")`);
+                if (modTgt && edit(modTgt.path, t => upsertCompilerOption(t, 'module', `"${CANONICAL_NODENEXT}"`))) {
+                    note(`Aligned module → "${CANONICAL_NODENEXT}" (required by moduleResolution "${CANONICAL_NODENEXT}")`);
                 }
             }
-            recordBuildIssue(name, 'warning', `Migrated moduleResolution "${mr.value}" → "nodenext". Verify relative imports resolve (NodeNext requires explicit file extensions on relative specifiers).`);
+            recordBuildIssue(name, 'warning', `Migrated moduleResolution "${mr.value}" → "${CANONICAL_NODENEXT}". Verify relative imports resolve (NodeNext requires explicit file extensions on relative specifiers).`);
+        }
+    }
+    // Canonical casing for values we write ourselves. TypeScript reads these
+    // case-insensitively, but the JSON schema behind editor linting (webhint,
+    // "Microsoft Edge Tools") only accepts the documented spelling, so an
+    // all-lowercase "nodenext" we wrote earlier shows up as an error in the
+    // editor even though the build is fine.
+    for (const key of ['module', 'moduleResolution']) {
+        const opt = effectiveCompilerOption(chain, key);
+        if (!opt || typeof opt.value !== 'string')
+            continue;
+        const canonical = CANONICAL_CASING[opt.value.toLowerCase()];
+        if (!canonical || canonical === opt.value)
+            continue;
+        const def = chain.find(c => c.path === opt.definedIn);
+        if (!def?.writable)
+            continue; // an override would be noise, not a fix
+        if (edit(def.path, t => upsertCompilerOption(t, key, `"${canonical}"`))) {
+            changed = true;
+            note(`Normalized ${key} "${opt.value}" → "${canonical}" in ${path.relative(cwd, def.path) || 'tsconfig.json'}`);
         }
     }
     // target: es3 → es2022 (es3 is removed in TS7).
@@ -2440,9 +2551,10 @@ const esLevelRank = (value) => ES_LEVEL_RANK[value.toLowerCase().replace(/\.full
 /** tsc says "Try changing the 'lib' compiler option to 'es2023' or later"
  *  (TS2550/TS2583/TS2584) when the code uses a standard-library API newer than
  *  the configured level. That isn't a deprecation — it's a tsconfig the language
- *  moved past — so raise the level to whatever the build asked for and let it
- *  try again, rather than leaving the user to decode `replaceAll` and `toSorted`
- *  errors by hand.
+ *  moved past — so raise the level and let the build try again, rather than
+ *  leaving the user to decode `replaceAll` and `toSorted` errors by hand. The
+ *  level asked for only decides *whether* to raise; what we write is
+ *  `RAISED_ES_LEVEL`, so the next new method used doesn't start this over.
  *
  *  We raise `target`: its implied `lib` keeps the DOM declarations a bare
  *  `lib: ["es2023"]` would silently drop. An explicit `lib` overrides `target`
@@ -2506,12 +2618,12 @@ function raiseTsconfigLibLevel(cwd, buildOutput, snapshot) {
         const entries = lib.value.filter((e) => typeof e === 'string');
         if (entries.some(e => esLevelRank(e) >= esLevelRank(required)))
             return false;
-        const raised = [required, ...entries.filter(e => esLevelRank(e) === 0)];
+        const raised = [RAISED_ES_LEVEL, ...entries.filter(e => esLevelRank(e) === 0)];
         const tgt = targetFor(lib.definedIn);
         if (!edit(tgt.path, t => upsertCompilerOption(t, 'lib', JSON.stringify(raised).replace(/","/g, '", "'))))
             return false;
         console.log(colors.cyan(`  Raised lib [${entries.join(', ')}] → [${raised.join(', ')}] in ${path.relative(cwd, tgt.path) || 'tsconfig.json'} (build needs ${required})`));
-        recordBuildIssue(name, 'warning', `Raised "lib" to ${required} — the code uses standard-library APIs newer than the tsconfig allowed.`);
+        recordBuildIssue(name, 'warning', `Raised "lib" to ${RAISED_ES_LEVEL} — the code uses standard-library APIs newer than the tsconfig allowed (needs ${required}).`);
         return true;
     }
     const tg = effectiveCompilerOption(chain, 'target');
@@ -2519,10 +2631,10 @@ function raiseTsconfigLibLevel(cwd, buildOutput, snapshot) {
     if (esLevelRank(current) >= esLevelRank(required))
         return false;
     const tgt = targetFor(tg?.definedIn);
-    if (!edit(tgt.path, t => upsertCompilerOption(t, 'target', `"${required}"`)))
+    if (!edit(tgt.path, t => upsertCompilerOption(t, 'target', `"${RAISED_ES_LEVEL}"`)))
         return false;
-    console.log(colors.cyan(`  Raised target "${current}" → "${required}" in ${path.relative(cwd, tgt.path) || 'tsconfig.json'} (build needs it)`));
-    recordBuildIssue(name, 'warning', `Raised "target" ${current} → ${required} — the code uses standard-library APIs newer than the tsconfig allowed.`);
+    console.log(colors.cyan(`  Raised target "${current}" → "${RAISED_ES_LEVEL}" in ${path.relative(cwd, tgt.path) || 'tsconfig.json'} (build needs ${required})`));
+    recordBuildIssue(name, 'warning', `Raised "target" ${current} → ${RAISED_ES_LEVEL} — the code uses standard-library APIs newer than the tsconfig allowed (needs ${required}).`);
     return true;
 }
 /** Write back the texts captured in a `migrateTsconfigDeprecations` snapshot
@@ -3197,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
@@ -3249,6 +3374,18 @@ export async function buildFileDepsTopologically(cwd, opts = {}, visited = new S
 }
 /** `moduleResolution` values TypeScript 6 deprecated and TypeScript 7 removes. */
 const DEPRECATED_MODULE_RESOLUTION = new Set(['node', 'node10', 'classic']);
+/** Spelling the tsconfig JSON schema — and so the editor linting built on it,
+ *  e.g. webhint via "Microsoft Edge Tools" — expects for the values we write.
+ *  TypeScript reads them case-insensitively; the schema does not. Deliberately
+ *  limited to the values npmglobalize writes itself: re-casing whatever the user
+ *  hand-typed would be churn, not a fix. */
+const CANONICAL_NODENEXT = 'NodeNext';
+const CANONICAL_CASING = { nodenext: CANONICAL_NODENEXT, node16: 'Node16' };
+/** Level we raise a too-old `target`/`lib` to. These are Node packages built and
+ *  run on the current Node, so tracking the newest language level costs nothing
+ *  and saves a re-raise every time the code picks up a newer standard-library
+ *  method. */
+const RAISED_ES_LEVEL = 'ESNext';
 /** Compiler flags TypeScript deprecated (TS5101) and will remove in TS7. Their
  *  mere presence — at any value — is a migration item. */
 const DEPRECATED_TS7_FLAGS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.204",
+  "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",