@truenas/ui-components 0.8.9 → 0.8.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/scripts/icon-sprite/cli-main.ts

@@ -17,7 +17,12 @@
  *
  * Configuration File:
  *   Create truenas-icons.config.js in your project root, as ESM or as CommonJS —
- *   either is read. See `lib/load-config.ts` for which shapes are read and how.
+ *   either is read. A .cjs, .mjs, .cts, .mts or .json file is read too when named
+ *   with --config. For TypeScript prefer .mts or .cts: a bare .ts takes its module
+ *   kind from its package scope, so a scope declaring no "type" at all has it read
+ *   as CommonJS, leaving import.meta.dirname undefined — which is warned about
+ *   rather than loaded quietly. See `lib/load-config.ts` for which shapes are read
+ *   and how.
  *
  *   export default {
  *     srcDirs: ['./src/lib', './src/app'],
@@ -81,6 +86,15 @@ Configuration File:
 
   npx truenas-icons generate --config truenas-icons.config.cjs
 
+  For a TypeScript config, name it .mts if it is ESM or .cts if it is CommonJS.
+  Both are decided by their extension. A bare .ts takes its module kind from its
+  package scope instead — the nearest package.json above it, stopping at any
+  node_modules directory — and if that scope declares no "type" at all the file
+  is read as CommonJS whatever it contains, leaving import.meta.dirname
+  undefined. That case is warned about rather than loaded quietly.
+
+  npx truenas-icons generate --config truenas-icons.config.mts
+
 Examples:
   # Generate with defaults
   npx truenas-icons generate

package/scripts/icon-sprite/lib/load-config.spec.ts

@@ -31,13 +31,29 @@ import { resolveConfig } from '../sprite-config-interface';
 const repoRoot = path.resolve(__dirname, '..', '..', '..', '..', '..');
 const tsxCli = path.join(repoRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
 
+/**
+ * Whether this node strips TypeScript itself, which is what decides a `.ts` file's
+ * kind when its package scope declares an explicit `"type": "commonjs"`. Absent
+ * before 22.10, `false` when `--no-experimental-strip-types` turns it off, a string
+ * when on; widened because `@types/node` only grew the field in 22.x. The spawn
+ * below uses `process.execPath`, so this is the child's behaviour too.
+ */
+const nodeStripsTypeScript = Boolean((process.features as { typescript?: unknown }).typescript);
+
 interface CaseDefinition {
   /** What the consumer's own `package.json` says — `type` is what decides the config's kind. */
   packageJson: Record<string, unknown>;
+  /** Relative to the project root, so a `/` in it puts the config in a subdirectory. */
   configFile: string;
   contents: string;
   /** Set on the case that is about the file not being there. Defaults to writing it. */
   write?: false;
+  /**
+   * Extra files, by path relative to the project root. Only the walk cases need
+   * this: where a config's *package scope* is depends on what sits between it and
+   * the project root, which a single `packageJson` cannot express.
+   */
+  extraFiles?: Record<string, string>;
 }
 
 interface CaseResult {
@@ -184,6 +200,112 @@ const CASES = {
     contents: IMPORT_META_CONFIG,
   },
 
+  /**
+   * #369, the shape nothing can load correctly: a bare `.ts` whose project
+   * declares no type. Unlike the typeless `.js` above, tsx reads this one as
+   * CommonJS whatever its syntax and never reparses it as ESM, so
+   * `import.meta.dirname` is `undefined` and the value that reaches the sprite is
+   * wrong. The extension is what has to change, so what is asserted is that the
+   * loader says so instead of loading it quietly.
+   */
+  [`${IMPORT_META}-named-ts-in-a-plain-project`]: {
+    packageJson: {},
+    configFile: 'truenas-icons.config.ts',
+    contents: IMPORT_META_CONFIG,
+  },
+
+  /**
+   * The same file where its own project declares ESM, which is the half of `.ts`
+   * that works — and so the half a warning must stay out of.
+   */
+  [`${IMPORT_META}-named-ts-in-an-esm-project`]: {
+    packageJson: { type: 'module' },
+    configFile: 'truenas-icons.config.ts',
+    contents: IMPORT_META_CONFIG,
+  },
+
+  /**
+   * A `.ts` config that really is CommonJS, in a project declaring no type: read
+   * exactly right, and warned about regardless. Here so the false positive the
+   * warning accepts is on the record as a decision rather than found as a surprise.
+   */
+  'commonjs-config-named-ts': {
+    packageJson: {},
+    configFile: 'truenas-icons.config.ts',
+    contents: "module.exports = { srcDirs: ['./src/ts'] };",
+  },
+
+  /**
+   * Where the walk stops, half one: the closest manifest decides even when it
+   * declares nothing. The project root says `"type": "module"` and the config's own
+   * directory has a manifest that does not, so tsx reads the config as CommonJS —
+   * an implementation that skipped the typeless manifest to find a typed one would
+   * answer `"module"` and say nothing.
+   */
+  'ts-config-under-a-typeless-nested-manifest': {
+    packageJson: { type: 'module' },
+    configFile: 'tools/truenas-icons.config.ts',
+    contents: IMPORT_META_CONFIG,
+    extraFiles: { 'tools/package.json': '{ "name": "nested-tools", "version": "1.0.0" }' },
+  },
+
+  /**
+   * Where the walk stops, half two: a `node_modules` directory ends it. There is no
+   * manifest inside it, so a walk that merely looks for the nearest one keeps going
+   * and finds the project root's `"type": "module"` — which is not what tsx does,
+   * and the config loads as CommonJS with nothing said.
+   */
+  'ts-config-inside-node-modules': {
+    packageJson: { type: 'module' },
+    configFile: 'node_modules/truenas-icons.config.ts',
+    contents: IMPORT_META_CONFIG,
+  },
+
+  /**
+   * The rest of the family in `.ts`'s position. tsx recognises
+   * `/\.([cm]?ts|[tj]sx)($|\?)/` and settles only `.mts` and `.cts` by extension,
+   * so `.tsx` and `.jsx` take their kind from package scope exactly as `.ts` does
+   * — and were silently mis-read while the check was a literal `'.ts'`. `--config`
+   * takes any path, so these turn up whether or not anyone recommends them.
+   */
+  'tsx-config-in-a-plain-project': {
+    packageJson: {},
+    configFile: 'truenas-icons.config.tsx',
+    contents: IMPORT_META_CONFIG,
+  },
+
+  'jsx-config-in-a-plain-project': {
+    packageJson: {},
+    configFile: 'truenas-icons.config.jsx',
+    contents: IMPORT_META_CONFIG,
+  },
+
+  /**
+   * **The asymmetry between `.ts` and the other two, which one predicate gets
+   * wrong.** Node recognises `.ts` natively and supplies a format whenever the
+   * scope declares a `type` at all, so tsx's format override never runs and an
+   * explicit `"type": "commonjs"` still has the file read as ESM — correctly, with
+   * `import.meta.dirname` populated. A check for "scope is not module" warns here
+   * and every sentence it prints is false of this file.
+   */
+  [`${IMPORT_META}-named-ts-under-an-explicit-commonjs-type`]: {
+    packageJson: { type: 'commonjs' },
+    configFile: 'truenas-icons.config.ts',
+    contents: IMPORT_META_CONFIG,
+  },
+
+  /**
+   * The same scope with the extension node does *not* recognise, where the answer
+   * is the opposite: `getPackageType` decides, `"type": "commonjs"` is taken
+   * literally, and the file really is transformed. So this one must warn while the
+   * case above must not.
+   */
+  'tsx-config-under-an-explicit-commonjs-type': {
+    packageJson: { type: 'commonjs' },
+    configFile: 'truenas-icons.config.tsx',
+    contents: IMPORT_META_CONFIG,
+  },
+
   // The CommonJS half of that pair: an extension that rules ESM out, so the
   // CommonJS loader is the one that reads it.
   'commonjs-config-named-cts': {
@@ -313,8 +435,19 @@ beforeAll(() => {
       JSON.stringify({ name, version: '1.0.0', ...definition.packageJson })
     );
 
+    // Before the config, since a case may place one inside a directory that an
+    // extra file is what creates.
+    for (const [relativePath, contents] of Object.entries(definition.extraFiles ?? {})) {
+      const target = path.join(projectRoot, relativePath);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, contents);
+    }
+
     if (definition.write !== false) {
-      fs.writeFileSync(path.join(projectRoot, definition.configFile), definition.contents);
+      const configTarget = path.join(projectRoot, definition.configFile);
+      // `configFile` may name a subdirectory — that is what the walk cases vary.
+      fs.mkdirSync(path.dirname(configTarget), { recursive: true });
+      fs.writeFileSync(configTarget, definition.contents);
     }
   }
 
@@ -495,16 +628,19 @@ describe('an ESM config', () => {
    * no warning. So the assertion is on the value, and the count rules out it having
    * been reached by falling back after a failure.
    *
-   * Three projects, because what decides the kind differs in each and a rule can be
+   * Four projects, because what decides the kind differs in each and a rule can be
    * right about one and wrong about the others: `"type": "module"` says so; a
    * typeless project says nothing and is still ESM, since node reads a typeless
-   * `.js` as CommonJS and reparses it as ESM when that fails; and `.mts` says so in
-   * its own extension.
+   * `.js` as CommonJS and reparses it as ESM when that fails; `.mts` says so in its
+   * own extension; and a `.ts` under `"type": "module"` is ESM by its manifest,
+   * which is the one `.ts` shape that works — the typeless one cannot, and has its
+   * own describe below.
    */
   it.each([
     [`${IMPORT_META}-in-an-esm-project`],
     [`${IMPORT_META}-in-a-plain-project`],
     [`${IMPORT_META}-named-mts`],
+    [`${IMPORT_META}-named-ts-in-an-esm-project`],
   ])('loads %s with import.meta actually populated', (name) => {
     const { config, warnings, evaluations } = resultFor(name as keyof typeof CASES);
 
@@ -515,6 +651,162 @@ describe('an ESM config', () => {
   });
 });
 
+/**
+ * #369. A `.ts`, `.tsx` or `.jsx` config takes its module kind from its package
+ * scope rather than from its own extension, and a scope that does not make it ESM
+ * has tsx read it as CommonJS with no reparse. The value cannot be fixed from here
+ * — nothing makes tsx reparse the file — so the criterion is that the loader
+ * reports the condition rather than loading quietly, and stays quiet when there is
+ * nothing to report. Both halves are below, and the last case states them as one
+ * invariant.
+ */
+describe('what decides a TypeScript config module kind', () => {
+  it('warns and names .mts rather than loading a wrong import.meta silently', () => {
+    const { config, warnings } = resultFor(`${IMPORT_META}-named-ts-in-a-plain-project`);
+
+    // Still the wrong value. What changed is that it is announced: this is the
+    // measurement in the report, now with something said about it.
+    expect(config.srcDirs).toEqual(['undefined']);
+
+    const said = warnings.join('\n');
+    expect(said).toContain('truenas-icons.config.ts');
+    expect(said).toContain('will be read as CommonJS');
+    expect(said).toContain('import.meta.dirname');
+    expect(said).toContain('.mts');
+  });
+
+  it('says nothing when the project declares "type": "module"', () => {
+    expect(resultFor(`${IMPORT_META}-named-ts-in-an-esm-project`).warnings).toEqual([]);
+  });
+
+  /**
+   * The accepted false positive, asserted so that narrowing it later is a decision
+   * made against a failing test rather than a quiet change. Which kind a `.ts` file
+   * means to be is not knowable without running it, so a correct CommonJS config
+   * gets the warning too — and still loads.
+   */
+  it('still loads a .ts config that really is CommonJS, warning about it anyway', () => {
+    const { config, warnings } = resultFor('commonjs-config-named-ts');
+
+    expect(config.srcDirs).toEqual(['./src/ts']);
+    expect(warnings.join('\n')).toContain('will be read as CommonJS');
+  });
+
+  // The pair that needs no manifest to be right, and so draws no warning. `.cts`
+  // and `.mts` are covered for loading above; this is about staying quiet.
+  it.each([[`${IMPORT_META}-named-mts`], ['commonjs-config-named-cts']])(
+    'leaves %s alone, since its extension settles its kind',
+    (name) => {
+      expect(resultFor(name as keyof typeof CASES).warnings).toEqual([]);
+    }
+  );
+
+  /**
+   * **Where the walk stops, which is the half that cannot be checked by varying the
+   * project root's own manifest.** Both cases sit under a project declaring
+   * `"type": "module"` and are still read as CommonJS, so each one fails if the
+   * scope is computed by looking for the nearest manifest that *has* a `type`, or
+   * by walking past `node_modules`. Read off tsx's own `findPackageJson`; the
+   * asserted `['undefined']` is that resolver's answer, measured here rather than
+   * predicted.
+   */
+  it.each([
+    ['ts-config-under-a-typeless-nested-manifest'],
+    ['ts-config-inside-node-modules'],
+  ] as const)('warns for %s, whose scope is not the project root', (name) => {
+    const { config, warnings } = resultFor(name);
+
+    expect(config.srcDirs).toEqual(['undefined']);
+    expect(warnings.join('\n')).toContain('will be read as CommonJS');
+  });
+
+  /**
+   * **The other two extensions in `.ts`'s position**, which a literal `'.ts'` check
+   * missed: tsx settles only `.mts` and `.cts` by extension, so everything else it
+   * recognises is decided by package scope. Each asserts the mis-read value as well
+   * as the warning, so the case cannot go green against a file that loaded as ESM.
+   */
+  it.each([['tsx-config-in-a-plain-project'], ['jsx-config-in-a-plain-project']] as const)(
+    'warns for %s, which package scope decides the same way',
+    (name) => {
+      const { config, warnings } = resultFor(name);
+
+      expect(config.srcDirs).toEqual(['undefined']);
+      expect(warnings.join('\n')).toContain('will be read as CommonJS');
+    }
+  );
+
+  /**
+   * **What an explicit `"type": "commonjs"` does, which is not the same for `.ts`
+   * as for the other two.** Node recognises `.ts` natively and supplies a format
+   * for any declared `type`, so tsx never transforms it and the config is read as
+   * ESM; node does not recognise `.tsx`, so there `getPackageType` takes
+   * `commonjs` literally and the transform runs. A single "scope is not module"
+   * predicate passes the second of these and fails the first — which is why both
+   * are here, asserting opposite outcomes against one shared manifest.
+   */
+  /**
+   * **This one is decided by the node running the suite, so it asks that node.**
+   * `.ts` escapes an explicit `"type": "commonjs"` only where node strips
+   * TypeScript itself; with stripping off — every node before 22.18, and the
+   * `--no-experimental-strip-types` flag — it is transformed like `.tsx`. Jest
+   * spawns tsx with `process.execPath`, so the flag read here is the one the child
+   * ran under. Asserting either outcome unconditionally would be asserting CI's
+   * node rather than the loader.
+   */
+  it('matches the node it runs on for a .ts config under "type": "commonjs"', () => {
+    const name = `${IMPORT_META}-named-ts-under-an-explicit-commonjs-type`;
+    const { config, warnings } = resultFor(name);
+
+    if (nodeStripsTypeScript) {
+      // Populated, so the config reports its own directory rather than 'undefined'.
+      expect(config.srcDirs).toEqual([name]);
+      expect(warnings).toEqual([]);
+    } else {
+      expect(config.srcDirs).toEqual(['undefined']);
+      expect(warnings.join('\n')).toContain('will be read as CommonJS');
+    }
+  });
+
+  it('warns for a .tsx config under the same "type": "commonjs"', () => {
+    const { config, warnings } = resultFor('tsx-config-under-an-explicit-commonjs-type');
+
+    expect(config.srcDirs).toEqual(['undefined']);
+    expect(warnings.join('\n')).toContain('will be read as CommonJS');
+  });
+
+  /**
+   * **The invariant the whole warning exists to hold, stated once over every case
+   * whose config reports its own `import.meta`: it is said exactly when the value
+   * is wrong.** Both directions can fail — a silent mis-read, which is #369, and a
+   * warning on a config that loaded correctly, which is noise that teaches a
+   * consumer to ignore it.
+   *
+   * Worth having alongside the cases above because it needs no table: it holds on
+   * any node and any tsx, and it is what a new case is checked against for free.
+   * Every defect three review rounds found here — a walk that stopped in the wrong
+   * place, an extension missed, a predicate that was right for one extension and
+   * wrong for another — breaks it.
+   *
+   * The set is derived from the shared config rather than listed, so a case added
+   * with `contents: IMPORT_META_CONFIG` joins it without anyone remembering to.
+   */
+  it.each(
+    Object.entries(CASES)
+      .filter(([, definition]) => definition.contents === IMPORT_META_CONFIG)
+      .map(([name]) => [name])
+  )('says something for %s exactly when import.meta was not populated', (name) => {
+    const { config, warnings } = resultFor(name as keyof typeof CASES);
+
+    // The config reports `path.basename(String(import.meta.dirname))`, so the
+    // literal string 'undefined' is what a mis-read looks like from out here.
+    const misread = (config.srcDirs as string[])[0] === 'undefined';
+    const warned = warnings.join('\n').includes('will be read as CommonJS');
+
+    expect(warned).toBe(misread);
+  });
+});
+
 describe('a JSON config', () => {
   it('loads when --config names one', () => {
     const { config, warnings } = resultFor('json-config');

package/scripts/icon-sprite/lib/load-config.ts

@@ -34,14 +34,225 @@ function reasonFor(error: unknown): string {
  * extension already names is the one that should answer, not because an outcome
  * depends on it — do not read the measured asymmetry below as applying to it.
  *
- * `.ts` is deliberately not here and is not safe either: tsx reads a typeless `.ts`
- * as CommonJS whatever its syntax, with no ESM reparse, so `--config` pointing at
- * one gets an undefined `import.meta.dirname` and no warning. Neither order changes
- * that, it predates this function, and a `.ts` config is not a documented shape —
- * so it is recorded here rather than worked around.
+ * `.ts` is deliberately not here and is not safe either: tsx reads one whose scope
+ * is not ESM as CommonJS whatever its syntax, with no ESM reparse, so `--config`
+ * pointing at it gets an undefined `import.meta.dirname`. Neither order changes
+ * that, which is why no ordering entry fixes it —
+ * `warnAboutTypeScriptConfigReadAsCommonJS` reports it instead, for `.ts` and for
+ * the two other extensions in the same position, and the reasoning for reporting
+ * rather than refusing lives there — see `willBeReadAsCommonJS` for the set and for
+ * what decides each member of it.
  */
 const NEVER_ESM = ['.cjs', '.cts', '.json'];
 
+/**
+ * Whether tsx will read `configPath` as CommonJS — meaning its `import.meta`
+ * accessors come back undefined — for an extension whose kind is not settled by
+ * the extension itself.
+ *
+ * **The three extensions do not answer to the same condition, and one of them
+ * depends on the node running the CLI.** Measured under tsx 4.19.4 on node 26.7.0
+ * with native TypeScript stripping both on and off — the latter via
+ * `--no-experimental-strip-types`, which is also how every node before 22.18
+ * behaves — over scopes declaring nothing, `commonjs`, `module`, and an invalid
+ * string:
+ *
+ * | extension | typeless | `commonjs` | `module` | invalid string |
+ * |---|---|---|---|---|
+ * | `.ts`, node strips TS | **CommonJS** | ESM | ESM | ESM |
+ * | `.ts`, node does not | **CommonJS** | **CommonJS** | ESM | ESM |
+ * | `.tsx`, `.jsx` | **CommonJS** | **CommonJS** | ESM | ESM |
+ * | `.mts`, `.cts` | ESM | ESM | ESM | ESM |
+ *
+ * `.ts` is the only row with two states, and `process.features.typescript` tells
+ * them apart. Where node recognises `.ts` natively it supplies a format for any
+ * declared `type`, so tsx's own `!resolved.format &&
+ * (resolved.format = getFormatFromFileUrl(url))` never runs and its `load` hook
+ * returns `{ format: 'module' }` for a TS extension it did not transform. Where it
+ * does not, `.ts` reaches tsx's `getPackageType` exactly as `.tsx` does and a
+ * literal `"type": "commonjs"` transforms. Node never recognises `.tsx` or `.jsx`,
+ * so those have one row.
+ *
+ * **The second row is a real environment, and CI never exercises it.** The
+ * published manifest declares no `engines`, `cli.cjs` runs `tsx` on whatever node
+ * the consumer has, and tsx supports node 18 — while CI pins 24.15.0, where native
+ * stripping is on. So this is detected rather than assumed: reading the row off the
+ * repo's own development range would be correct about CI and wrong about the
+ * consumer the bin actually runs for.
+ *
+ * `.mts` and `.cts` are absent because `getFormatFromExtension` answers for them
+ * outright, in every scope and on both node behaviours. The three covered here are
+ * tsx's pattern `/\.([cm]?ts|[tj]sx)($|\?)/` minus those two — tsx's own internal
+ * `['.ts', '.tsx', '.jsx']`.
+ *
+ * An invalid `type` loads as ESM only when it is a *string*. A non-string
+ * `"type": 123` throws out of the loader instead, and `packageScopeType` reports it
+ * as `undefined`, so a warning is printed just before the real failure is reported.
+ * Not worth a branch, and not an ESM load either.
+ *
+ * **Case-sensitive, because tsx's pattern is.** A `--config` naming `.TS` draws no
+ * warning and is right not to, though not by the route it looks like: tsx does not
+ * recognise the extension, `import()` fails on it as unknown, and `loadConfig`'s
+ * `createRequire` fallback is what loads it — with `import.meta.dirname` populated
+ * and `typeof require` still `undefined` inside it, so node's own `require()` of an
+ * ES module is doing the work rather than any CommonJS transform. The value that
+ * reaches the sprite is correct, on a node new enough for that (22.12); before it
+ * both loaders fail and the config falls back to `{}` with both reasons reported.
+ */
+function willBeReadAsCommonJS(configPath: string): boolean {
+  const extension = path.extname(configPath);
+
+  if (extension !== '.ts' && extension !== '.tsx' && extension !== '.jsx') {
+    return false;
+  }
+
+  const scope = packageScopeType(configPath);
+
+  // A scope declaring nothing is read as CommonJS for all three, on either node.
+  if (scope === undefined) {
+    return true;
+  }
+
+  // Read off `process.features` rather than a version comparison, and widened
+  // because `@types/node` only grew the field in 22.x: it is absent before 22.10,
+  // `false` when the flag turns stripping off, and a string when it is on.
+  const nodeStripsTypeScript = Boolean((process.features as { typescript?: unknown }).typescript);
+
+  // Past that, only `.ts` on a node that strips TypeScript escapes an explicit
+  // `"type": "commonjs"`, because that is what supplies a format and keeps tsx's
+  // own override from running. See the table above.
+  return scope === 'commonjs' && !(extension === '.ts' && nodeStripsTypeScript);
+}
+
+/**
+ * The `type` declared by the `package.json` that decides `configPath`'s module
+ * kind — its *package scope* — or `undefined` when nothing in that scope declares
+ * one.
+ *
+ * **Two things decide where the walk stops, and both have to be here**, because a
+ * walk that answers `"module"` where tsx computes `"commonjs"` suppresses the
+ * warning in exactly the silent case this file exists to end:
+ *
+ * - **The closest manifest decides**, whether or not it carries the field. A
+ *   manifest further up gets no say, so skipping a typeless one to find a typed
+ *   one answers a different question than the loader is going to.
+ * - **The walk stops at a `node_modules` directory**, and does not look past it.
+ *   So a config under `node_modules/` is CommonJS however the project above it is
+ *   declared.
+ *
+ * Both read off tsx's own resolver, not inferred from node's documentation:
+ * `findPackageJson` in `tsx/dist/esm/index.mjs` is
+ * `for (; !url.pathname.endsWith('/node_modules/package.json');)` returning the
+ * first manifest that parses, and `getPackageType` is that `?.type ?? 'commonjs'`.
+ * Node's two loaders agree — `readPackageScope` returns false on `node_modules`,
+ * and `getPackageScopeConfig` breaks on `node_modules/package.json`.
+ *
+ * The path is resolved through `fs.realpathSync` first, because node resolves a
+ * symlinked module to its real path before any loader hook sees it: a config
+ * symlinked into a project takes its scope from where the file really lives, not
+ * from where it is linked.
+ *
+ * Unreadable or malformed reads as `undefined` rather than throwing. tsx itself
+ * throws on a nearest manifest it cannot parse, so that config was not going to
+ * load either way — this only decides which message the consumer gets, and the
+ * warning is the less confusing of the two.
+ */
+function packageScopeType(configPath: string): string | undefined {
+  let directory: string;
+
+  try {
+    directory = path.dirname(fs.realpathSync(configPath));
+  } catch {
+    directory = path.dirname(configPath);
+  }
+
+  for (;;) {
+    // Checked before the manifest is read, which is where tsx checks it: the
+    // boundary is the candidate path, so a `node_modules` directory's own
+    // `package.json` is not consulted either.
+    if (path.basename(directory) === 'node_modules') {
+      return undefined;
+    }
+
+    const manifest = path.join(directory, 'package.json');
+
+    if (fs.existsSync(manifest)) {
+      try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+        const declared = (parsed as { type?: unknown }).type;
+
+        return typeof declared === 'string' ? declared : undefined;
+      } catch {
+        return undefined;
+      }
+    }
+
+    const parent = path.dirname(directory);
+
+    if (parent === directory) {
+      return undefined;
+    }
+
+    directory = parent;
+  }
+}
+
+/**
+ * Reports a `--config` naming a file tsx is about to read as CommonJS, which
+ * `willBeReadAsCommonJS` decides. Such a config loads, says nothing, and gets
+ * `undefined` for `import.meta.dirname` and `import.meta.filename` — so the sprite
+ * is generated from a path the consumer never wrote and no output mentions it.
+ * That is #369.
+ *
+ * **It warns rather than refusing, because the mis-read file and a perfectly
+ * correct one are the same file to everything that can be inspected.** A `.ts`
+ * config written as CommonJS is read exactly right, and refusing every `.ts`
+ * would break it; which kind a file *means* to be is not knowable without running
+ * it, which is the same reason `loadConfig` does not pick a loader by kind. So the
+ * accepted cost is a warning on a config that did not need one, and the message
+ * names the condition it fired on so that reads as what it is. The other way round
+ * is the silent wrong value this exists to end.
+ *
+ * **It covers the extension and not what the file imports.** A `.mts` config —
+ * correctly silent — importing a `.ts` helper in a typeless scope gets that helper
+ * read as CommonJS, with `import.meta.dirname` undefined inside it and nothing
+ * said. Naming the config's own extension cannot reach that; only the loader
+ * reading each file could, and `--config` is the only path this one is given.
+ *
+ * **Reading `type` here is not the rule the docblocks above rule out.** That one
+ * guesses which kind an unknowable `.js` file *is*, in order to choose a loader,
+ * and is wrong because node itself reparses. This computes what tsx *will do* with
+ * the file, which for these extensions is settled rather than guessed — there is no
+ * reparse to upset the answer, and the inputs that decide it are enumerated in
+ * `willBeReadAsCommonJS`, measured rather than reasoned from. **No loader choice
+ * turns on it** — both still run, in the same order, and the file loads either way.
+ */
+function warnAboutTypeScriptConfigReadAsCommonJS(configPath: string): void {
+  if (!willBeReadAsCommonJS(configPath)) {
+    return;
+  }
+
+  // "does not make it ESM" rather than naming a manifest condition. The condition
+  // differs by extension and there may be no manifest at all, so any sentence
+  // specific enough to name one is false for some input that reaches here — which
+  // is what the first version of this message got wrong. The scope is described
+  // below, the fixes are listed, and neither claim depends on which case fired.
+  console.warn(
+    `Warning: ${configPath} will be read as CommonJS, because its package scope ` +
+      'does not make it ESM.'
+  );
+  console.warn('  (That scope is the nearest package.json above the file, and stops at a');
+  console.warn('  node_modules directory — nothing past one is consulted.)');
+  console.warn('  tsx applies its CommonJS transform with no ESM reparse, which leaves');
+  console.warn('  import.meta.dirname and import.meta.filename undefined — so an ESM config');
+  console.warn('  reading either one loads with no error and a wrong value in it.');
+  // Both extension pairs, because this also fires for a `.jsx` config, whose
+  // equivalents are `.mjs` and `.cjs` rather than the TypeScript pair.
+  console.warn('  Name it .mts or .mjs to be read as ESM, or .cts or .cjs if it really is');
+  console.warn('  CommonJS — none of those depends on a manifest — or declare');
+  console.warn('  "type": "module" in the package.json above it.');
+}
+
 /**
  * Loads a consumer's icon configuration file, which may be ESM or CommonJS.
  *
@@ -92,6 +303,10 @@ export async function loadConfig(
     return {};
   }
 
+  // Before the loaders, so it is said even for a file that then fails to load for
+  // its own reasons — the extension is the consumer's problem either way.
+  warnAboutTypeScriptConfigReadAsCommonJS(configPath);
+
   const loaders = [
     { label: 'import()', load: async () => await import(pathToFileURL(configPath).href) },
     { label: 'require()', load: async () => createRequire(configPath)(configPath) },