@zgeoff/oxlint-config 0.2.10 → 0.2.12

package/README.md

@@ -109,11 +109,19 @@ the paths that may name the words:
 
 ## `zgeoff/no-abbreviated-names`
 
-The `names` option maps each abbreviation to the text that replaces it, and the rule reports a
-variable, parameter, catch parameter, destructured name, import, property, getter or setter that has
-one of those names. A name matches whole, so `ms` reports `ms` but not `timeoutMs`. A destructured
-key that an alias renames belongs to the object being read, and the rule reports only the alias. The
-shipped config lists the abbreviations that the code-style skill bans and turns on `id-length`
+The `names` option maps each abbreviation to the text that replaces it, and the rule reports every
+value name that has one of those names. A value name is any name that a declaration, an import, an
+export alias, a key or a member write binds, so function, class and method names count beside
+variables and properties. A key counts in each of its spellings, so `src`, `'src'`, `['src']` and
+`#src` all report. A name matches whole, so `ms` reports `ms` but not `timeoutMs`.
+
+The rule leaves alone the names that hold no value of their own. A destructured key that an alias
+renames belongs to the object being read, so the rule reports only the alias. A computed key that
+reads a variable, such as `[src]`, names no property, and the rule checks the variable at its
+declaration. Type names, type-only imports and exports, labels and quoted module names hold no
+value, so the rule skips them.
+
+The shipped config lists the abbreviations that the code-style skill bans and turns on `id-length`
 beside the rule, so a one-letter name fails too, other than `x`, `y`, `z`, `$` and `_`.
 
 ## `zgeoff/no-file-snapshot`
@@ -134,19 +142,26 @@ Each entry has a `name`, which starts its report, an optional `reason`, which en
 
 - `edges` judge an import that resolves to a file: relative, with any bundler query such as `?url`
   dropped, or the package's own name resolved through its `exports` under `conditions` plus
-  `default`. A target in a `to` zone fails unless it is also in an `allow` zone; with `allow` alone,
-  a target in none of the `allow` zones fails, a target in no zone included. `allowTypeOnly` exempts
-  type-only imports (`true`, or globs the target must match), and `allowWithin: "src/*"` exempts an
-  import inside the importer's own `src/<name>/`.
+  `default`. They also judge the name of each package whose directory a `workspaces` glob matches,
+  such as `packages/*`, with one directory level per segment. That name maps to the package folder
+  joined with the subpath, never to an export's target: `@demo/store/testing` is judged as
+  `packages/store/testing`, so a zone names the folder path, such as `packages/store{,/**}`. A
+  target in a `to` zone fails unless it is also in an `allow` zone; with `allow` alone, a target in
+  none of the `allow` zones fails, a target in no zone included. `allowTypeOnly` exempts type-only
+  imports (`true`, or globs the target must match), and `allowWithin: "src/*"` exempts an import
+  inside the importer's own `src/<name>/`.
 - `modules` restrict a package or builtin (`node:` prefix optional, subpaths included) to the
   `allow` zones; `allowTypeOnly: true` exempts type-only imports. A name that ends in `*` restricts
   every specifier that starts with the text before it, such as `@scope/*`, and `node:*` restricts
   every builtin.
 - `globals` restrict a call to a global, bare or through `globalThis`, `self` or `window`.
 - `unzoned` reports a file in a `from` zone that belongs to none of `zones`.
-- `unresolved` reports a relative or self-referencing import that resolves to no file, and a dynamic
+- `unresolved` reports a relative or self-referencing import that resolves to no file, a workspace
+  import whose subpath no `exports` key lists, or one that a `null` key blocks, and a dynamic
   `import()`, `require()` or `import.meta.require()` whose specifier is computed. Bun's
   `import.meta.require` used as a value counts as computed too.
+- `selfImports` reports an import of the importer's own package by name, which a relative path
+  reaches without the `exports` map.
 
 ```jsonc
 {

package/import-zones-schema.js

@@ -26,6 +26,7 @@ const importZonesSchema = {
     zones: { type: 'object', additionalProperties: stringList },
     extensions: stringList,
     conditions: stringList,
+    workspaces: stringList,
     edges: buildEntrySchema(
       {
         to: stringList,
@@ -43,6 +44,7 @@ const importZonesSchema = {
     globals: buildEntrySchema({ globals: stringList, allow: stringList }, ['globals', 'allow']),
     unzoned: buildEntrySchema({ zones: stringList }, ['from', 'zones']),
     unresolved: buildEntrySchema({}, []),
+    selfImports: buildEntrySchema({}, []),
   },
   additionalProperties: false,
 };

package/import-zones.js

@@ -2,6 +2,7 @@ import { isBuiltin } from 'node:module';
 import { relative, sep } from 'node:path';
 import findRepoRoot from './find-repo-root.js';
 import importZonesSchema from './import-zones-schema.js';
+import loadWorkspaceManifests from './load-workspace-manifests.js';
 import loadZoneOptions from './load-zone-options.js';
 import resolveImportTarget from './resolve-import-target.js';
 
@@ -14,7 +15,17 @@ function buildFileState(context) {
   const root = findRepoRoot(filename) ?? context.cwd;
   const path = toRootPath(root, filename);
 
-  return { context, options, filename, root, path, zones: collectZones(options.zones, path) };
+  const workspaces = loadWorkspaceManifests(root, options.workspaces);
+
+  return {
+    context,
+    options,
+    filename,
+    root,
+    path,
+    workspaces,
+    zones: collectZones(options.zones, path),
+  };
 }
 
 function toRootPath(root, path) {
@@ -66,8 +77,13 @@ function checkImport(file, imported) {
     root: file.root,
     extensions: file.options.extensions,
     conditions: file.options.conditions,
+    workspaces: file.workspaces,
   });
 
+  if (target.self === true) {
+    emitSelfImport(file, imported.node, specifier);
+  }
+
   if (target.kind === 'module') {
     checkModule(file, imported, target.specifier);
   } else if (target.kind === 'missing') {
@@ -96,6 +112,12 @@ function emitUnresolved(file, node, report) {
   }
 }
 
+function emitSelfImport(file, node, specifier) {
+  for (const entry of collectEntries(file, file.options.selfImports)) {
+    emitReport(file, entry, { at: { node }, messageId: 'self', data: { specifier } });
+  }
+}
+
 function checkModule(file, imported, specifier) {
   for (const entry of collectEntries(file, file.options.modules)) {
     const isAllowed =
@@ -270,6 +292,7 @@ const importZones = {
       global: '{{rule}}: {{global}}() is allowed only in {{allow}}{{reason}}',
       unzoned: '{{rule}}: this file belongs to none of {{zones}}; add its path to one{{reason}}',
       unresolved: '{{rule}}: cannot resolve {{specifier}}{{reason}}',
+      self: '{{rule}}: {{specifier}} names the package this file belongs to; import it by a relative path{{reason}}',
       computed: '{{rule}}: cannot check a computed import specifier{{reason}}',
     },
     schema: [importZonesSchema],

package/load-workspace-manifests.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import makeGlobMatcher from './make-glob-matcher.js';
+
+// The manifest of every package directory the globs match, relative to the
+// root. Each glob segment matches one directory level, as a workspaces
+// field's globs do.
+export default function loadWorkspaceManifests(root, globs) {
+  return withManifestCache(JSON.stringify([root, globs]), () =>
+    globs
+      .flatMap((glob) => readGlobDirectories(root, splitGlob(glob), ''))
+      .map((directory) => loadManifest(join(root, directory)))
+      .filter((manifest) => typeof manifest?.name === 'string'),
+  );
+}
+
+const loadedManifests = new Map();
+
+// each linted file asks again, so the manifests load once per root and globs
+function withManifestCache(key, load) {
+  if (!loadedManifests.has(key)) {
+    loadedManifests.set(key, load());
+  }
+
+  return loadedManifests.get(key);
+}
+
+function splitGlob(glob) {
+  return glob.split('/').filter((segment) => segment !== '' && segment !== '.');
+}
+
+function readGlobDirectories(root, segments, prefix) {
+  const [segment, ...rest] = segments;
+
+  if (segment === undefined) {
+    return [prefix];
+  }
+
+  const isMatch = makeGlobMatcher([segment]);
+  const parent = join(root, prefix);
+  const names = existsSync(parent)
+    ? readdirSync(parent, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name !== 'node_modules')
+        .map((entry) => entry.name)
+        .filter((name) => isMatch(name))
+    : [];
+
+  return names.flatMap((name) => readGlobDirectories(root, rest, join(prefix, name)));
+}
+
+// `dir` is the field the resolver reads from every manifest it loads
+function loadManifest(directory) {
+  const path = join(directory, 'package.json');
+
+  if (!existsSync(path)) {
+    return null;
+  }
+
+  const manifest = JSON.parse(readFileSync(path, 'utf8'));
+
+  manifest.dir = directory;
+
+  return manifest;
+}

package/load-zone-options.js

@@ -30,11 +30,13 @@ function buildZoneOptions(options) {
     zones,
     extensions: options.extensions ?? defaultExtensions,
     conditions: new Set([...(options.conditions ?? []), 'default']),
+    workspaces: options.workspaces ?? [],
     edges: buildEntries(options.edges),
     modules: buildEntries(options.modules),
     globals: buildEntries(options.globals),
     unzoned: buildEntries(options.unzoned),
     unresolved: buildEntries(options.unresolved),
+    selfImports: buildEntries(options.selfImports),
   };
 }
 

package/no-abbreviated-names.js

@@ -25,9 +25,9 @@ const noAbbreviatedNames = {
     }
 
     const checkName = (node) => {
-      const isName = node?.type === 'Identifier' || node?.type === 'PrivateIdentifier';
+      const name = findStaticName(node);
 
-      if (!isName || !names.has(node.name)) {
+      if (name === null || !names.has(name)) {
         return;
       }
 
@@ -36,7 +36,7 @@ const noAbbreviatedNames = {
       context.report({
         node,
         messageId: 'abbreviated',
-        data: { name: `${prefix}${node.name}`, replacement: names.get(node.name) },
+        data: { name: `${prefix}${name}`, replacement: names.get(name) },
       });
     };
 
@@ -46,32 +46,63 @@ const noAbbreviatedNames = {
       }
     };
 
-    const checkKey = (node) => {
-      if (!node.computed) {
-        checkName(node.key);
+    // a computed key names its property as a plain key does when it is a
+    // string written in place, as in `{ ['src']: 1 }`; a computed identifier
+    // reads a variable, whose declaration is checked where it is made
+    const checkMemberName = (node, name) => {
+      if (!node.computed || name.type !== 'Identifier') {
+        checkName(name);
       }
     };
 
+    const checkKey = (node) => {
+      checkMemberName(node, node.key);
+    };
+
     const checkParams = (node) => {
       for (const param of node.params) {
         checkPattern(param);
       }
     };
 
+    // a write to a member names that property, whether the member stands
+    // alone or sits inside a destructuring target
+    const checkAssignmentTarget = (node) => {
+      for (const member of collectTargetMembers(node)) {
+        checkMemberName(member, member.property);
+      }
+    };
+
+    const checkLoopTarget = (node) => {
+      if (node.left.type !== 'VariableDeclaration') {
+        checkAssignmentTarget(node.left);
+      }
+    };
+
+    // function-verb checks only a plain function or method name, so a quoted
+    // method, a signature or a declared function would pass both rules
+    const checkFunction = (node) => {
+      checkName(node.id);
+      checkParams(node);
+    };
+
     return {
       VariableDeclarator(node) {
         checkPattern(node.id);
       },
-      FunctionDeclaration: checkParams,
-      FunctionExpression: checkParams,
+      FunctionDeclaration: checkFunction,
+      FunctionExpression: checkFunction,
       ArrowFunctionExpression: checkParams,
 
       // a signature without a body names its parameters as an implementation does
-      TSDeclareFunction: checkParams,
+      TSDeclareFunction: checkFunction,
       TSEmptyBodyFunctionExpression: checkParams,
       TSFunctionType: checkParams,
       TSConstructorType: checkParams,
-      TSMethodSignature: checkParams,
+      TSMethodSignature(node) {
+        checkKey(node);
+        checkParams(node);
+      },
       TSCallSignatureDeclaration: checkParams,
       TSConstructSignatureDeclaration: checkParams,
       CatchClause(node) {
@@ -83,15 +114,19 @@ const noAbbreviatedNames = {
       TSAbstractPropertyDefinition: checkKey,
       TSAbstractAccessorProperty: checkKey,
       TSPropertySignature: checkKey,
+      MethodDefinition: checkKey,
+      TSAbstractMethodDefinition: checkKey,
 
-      // a getter or setter is read and written as a property, so its key is a
-      // value name
-      "MethodDefinition[kind='get']": checkKey,
-      "MethodDefinition[kind='set']": checkKey,
-      "TSAbstractMethodDefinition[kind='get']": checkKey,
-      "TSAbstractMethodDefinition[kind='set']": checkKey,
-      "TSMethodSignature[kind='get']": checkKey,
-      "TSMethodSignature[kind='set']": checkKey,
+      // a class, an enum and a namespace are values at run time; a quoted
+      // module name is a path, not a value name
+      'ClassDeclaration, ClassExpression, TSEnumDeclaration'(node) {
+        checkName(node.id);
+      },
+      TSModuleDeclaration(node) {
+        if (node.id.type === 'Identifier') {
+          checkName(node.id);
+        }
+      },
 
       // an import's local binding is a value name in this module, whatever the
       // exporting module calls it; a type-only import names a type, not a value
@@ -105,19 +140,96 @@ const noAbbreviatedNames = {
           checkName(node.id);
         }
       },
-      'AssignmentExpression > MemberExpression.left'(node) {
-        if (!node.computed) {
-          checkName(node.property);
+      TSIndexSignature(node) {
+        for (const parameter of node.parameters) {
+          checkName(parameter);
+        }
+      },
+      TSEnumMember(node) {
+        checkName(node.id);
+      },
+
+      // an export alias is the name every importing module reads the value by
+      ExportSpecifier(node) {
+        if (!isTypeOnlyExport(node)) {
+          checkName(node.exported);
+        }
+      },
+      ExportAllDeclaration(node) {
+        if (node.exportKind !== 'type') {
+          checkName(node.exported);
         }
       },
+      AssignmentExpression(node) {
+        checkAssignmentTarget(node.left);
+      },
+      ForInStatement: checkLoopTarget,
+      ForOfStatement: checkLoopTarget,
     };
   },
 };
 
+// the name a key or binding spells out in the source: an identifier, a
+// string, or a template with no substitutions; a key built at run time has
+// no static name, so the result is null
+function findStaticName(node) {
+  if (node?.type === 'Identifier' || node?.type === 'PrivateIdentifier') {
+    return node.name;
+  }
+
+  if (node?.type === 'Literal' && typeof node.value === 'string') {
+    return node.value;
+  }
+
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0].value.cooked ?? null;
+  }
+
+  return null;
+}
+
 function isTypeOnlyImport(specifier) {
   return specifier.importKind === 'type' || specifier.parent.importKind === 'type';
 }
 
+function isTypeOnlyExport(specifier) {
+  return specifier.exportKind === 'type' || specifier.parent.exportKind === 'type';
+}
+
+// the members an assignment target writes; a bare identifier in the target
+// writes a variable declared elsewhere, and its declaration is checked there
+function collectTargetMembers(node) {
+  if (node === null || node === undefined) {
+    return [];
+  }
+
+  if (node.type === 'MemberExpression') {
+    return [node];
+  }
+
+  if (node.type === 'ObjectPattern') {
+    return node.properties.flatMap((property) => {
+      const target = property.type === 'RestElement' ? property : property.value;
+
+      return collectTargetMembers(target);
+    });
+  }
+
+  if (node.type === 'ArrayPattern') {
+    return node.elements.flatMap((element) => collectTargetMembers(element));
+  }
+
+  if (node.type === 'AssignmentPattern') {
+    return collectTargetMembers(node.left);
+  }
+
+  if (node.type === 'RestElement') {
+    return collectTargetMembers(node.argument);
+  }
+
+  return [];
+}
+
 // the names a binding pattern declares: a destructured key's alias, not the
 // key, since the key belongs to the object being read
 function collectPatternIdentifiers(node) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/oxlint-config",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Shareable oxlint config: strict categories, house-style rules, and a custom JS plugin",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,7 @@
     "import-zones.js",
     "import-zones-schema.js",
     "find-repo-root.js",
+    "load-workspace-manifests.js",
     "load-zone-options.js",
     "make-glob-matcher.js",
     "resolve-import-target.js",

package/resolve-import-target.js

@@ -1,12 +1,13 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isBuiltin } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 
 // a `.js` specifier in TypeScript source names the `.ts` file beside it
 const sourceExtensions = { '.js': ['.ts', '.tsx'], '.mjs': ['.mts'], '.cjs': ['.cts'] };
 
-// `module` with the specifier for a package or builtin, `file` with the
-// absolute path when the import resolves, `missing` otherwise. The package's
-// own name resolves through its `exports`, and `#` names through its `imports`.
+// `module` for a package or builtin, `file` with the absolute path, or
+// `missing`. The own name, which `self` marks, resolves through `exports`, `#`
+// names through `imports`, and a workspace name to a path in its folder.
 export default function resolveImportTarget(filename, specifier, settings) {
   if (isPathSpecifier(specifier)) {
     return toTarget(findImportedFile(filename, toFileSpecifier(specifier), settings.extensions));
@@ -14,30 +15,73 @@ export default function resolveImportTarget(filename, specifier, settings) {
 
   const manifest = findPackageManifest(dirname(filename), settings.root);
 
-  return resolveManifestTarget(manifest, specifier, settings.conditions);
+  return resolveManifestTarget(manifest, specifier, settings);
 }
 
-function resolveManifestTarget(manifest, specifier, conditions) {
-  const name = manifest?.name;
+function resolveManifestTarget(manifest, specifier, settings) {
+  if (!specifier.startsWith('#')) {
+    return resolveBareTarget(manifest, specifier, settings);
+  }
 
-  if (specifier.startsWith('#')) {
-    const mapped = findMappedTarget(manifest?.imports, specifier, conditions);
+  const mapped = findMappedTarget(manifest?.imports, specifier, settings.conditions);
+
+  return mapped !== null && !isPathSpecifier(mapped)
+    ? resolveBareTarget(manifest, mapped, settings)
+    : toMappedTarget(manifest, mapped);
+}
 
-    return mapped !== null && !isPathSpecifier(mapped)
-      ? { kind: 'module', specifier: mapped }
-      : toMappedTarget(manifest, mapped);
+// a builtin keeps its name even when a package shares it
+function resolveBareTarget(manifest, specifier, settings) {
+  const name = manifest?.name;
+
+  if (isBuiltin(specifier)) {
+    return { kind: 'module', specifier };
   }
 
-  if (typeof name === 'string' && (specifier === name || specifier.startsWith(`${name}/`))) {
+  if (isPackageSpecifier(name, specifier)) {
     const subpath = `.${specifier.slice(name.length)}`;
+    const mapped = findMappedTarget(toSubpathMap(manifest.exports), subpath, settings.conditions);
+
+    return { ...toMappedTarget(manifest, mapped), self: true };
+  }
+
+  return resolveWorkspaceTarget(settings.workspaces, specifier);
+}
 
-    return toMappedTarget(
-      manifest,
-      findMappedTarget(toSubpathMap(manifest.exports), subpath, conditions),
-    );
+function isPackageSpecifier(name, specifier) {
+  return typeof name === 'string' && (specifier === name || specifier.startsWith(`${name}/`));
+}
+
+// the edges judge the package folder joined with the subpath, such as
+// `packages/store/testing`, so the exports map's keys matter and not its targets
+function resolveWorkspaceTarget(workspaces, specifier) {
+  const workspace = workspaces.find((candidate) => isPackageSpecifier(candidate.name, specifier));
+
+  if (workspace === undefined) {
+    return { kind: 'module', specifier };
   }
 
-  return { kind: 'module', specifier };
+  const subpath = `.${specifier.slice(workspace.name.length)}`;
+
+  return isExportedSubpath(workspace.exports, subpath)
+    ? { kind: 'file', path: join(workspace.dir, subpath) }
+    : { kind: 'missing' };
+}
+
+// with no exports map, every subpath is public, and an empty one exports none
+function isExportedSubpath(exports, subpath) {
+  if (exports === undefined) {
+    return true;
+  }
+
+  if (typeof exports === 'object' && exports !== null && Object.keys(exports).length === 0) {
+    return false;
+  }
+
+  const map = toSubpathMap(exports);
+  const key = Object.hasOwn(map, subpath) ? subpath : findPatternKey(map, subpath);
+
+  return key !== undefined && map[key] !== null;
 }
 
 // a bundler query such as Vite's `./styles.css?url` names the file before it
@@ -105,6 +149,12 @@ function findMappedTarget(map, key, conditions) {
     return findConditionTarget(map[key], conditions);
   }
 
+  const pattern = findPatternKey(map, key);
+
+  return pattern === undefined ? null : findPatternTarget(map, pattern, { key, conditions });
+}
+
+function findPatternKey(map, key) {
   const [pattern] = Object.keys(map)
     .filter((candidate) => isPatternMatch(candidate, key))
     .toSorted((left, right) => {
@@ -113,7 +163,7 @@ function findMappedTarget(map, key, conditions) {
       return byPrefix === 0 ? right.length - left.length : byPrefix;
     });
 
-  return pattern === undefined ? null : findPatternTarget(map, pattern, { key, conditions });
+  return pattern;
 }
 
 function findPatternTarget(map, pattern, lookup) {