eslint-plugin-import-structure 0.10.5 → 0.11.1

package/README.md

@@ -85,9 +85,9 @@ An alias owns its target, and code outside the owned area reaches it only throug
 The rules never depend on folder or file names; an alias may point anywhere.
 
 - An alias to a folder's `index` file (`index.ts`, or any other extension) owns that folder and everything below it. An alias to any other file owns only that file.
-- No file may be owned by 2 aliases: no alias inside another alias's area, and no 2 aliases with the same target.
-  `enforce-layer-order` reports an overlap once at the top of every file 2 aliases claim, since lint cannot report on `package.json`.
-- Outside an area, any other route to an owned file is a bypass: a deeper alias specifier such as `#a/one.ts` (`no-barrel-bypass`), or a relative path (`no-relative-bypass`, and `prefer-alias-import`, which rewrites a path to the alias's exact target).
+- An alias may sit inside another alias's area. The deeper alias owns its part, carved out of the outer area, and the outer alias owns the rest; the two are ordered like any other pair of aliases.
+- No 2 aliases may have the same area, such as the same target or 2 `index` files in one folder. `enforce-layer-order` reports an overlap once at the top of every file both own, since lint cannot report on `package.json`.
+- Outside an area, any other route to an owned file is a bypass: a deeper alias specifier such as `#a/one.ts` (`no-barrel-bypass`), or a relative path (`no-relative-bypass`, and `prefer-alias-import`, which rewrites a path to the alias's target, in any spelling TypeScript resolves to it).
 - Inside an area, relative imports of siblings and subfolders are free.
 - `../` is banned in every file, owned or not (`no-parent-import`). Anything above a file needs an alias.
 - Files no alias owns need no `index.ts` and no alias, and import `./` siblings and subfolders freely.
@@ -95,7 +95,8 @@ The rules never depend on folder or file names; an alias may point anywhere.
 
 ```jsonc
 "imports": {
-  "#a": "./a/index.ts", // owns a/ and everything below it
+  "#a": "./a/index.ts", // owns a/ and everything below it but a/sub/
+  "#a-sub": "./a/sub/index.ts", // owns a/sub/, carved out of #a
   "#f": "./b/f.ts", // owns only b/f.ts; b/g.ts stays unowned
 }
 ```
@@ -108,7 +109,9 @@ import { f } from "./b/f.ts"; // ❌ relative path to a file alias; use "#f"
 import { g } from "./b/g.ts"; // ✅ unowned
 // in a/one.ts, owned by #a
 import { two } from "./two.ts"; // ✅ sibling
-import { deep } from "./sub/deep.ts"; // ✅ subfolder of the same area
+import { deep } from "./other/deep.ts"; // ✅ subfolder of the same area
+import { sub } from "./sub/x.ts"; // ❌ relative path into #a-sub
+import { sub } from "#a/sub/x.ts"; // ❌ deeper alias specifier; use "#a-sub"
 ```
 
 The other rules (import order, duplicate sources, wildcards, absolute paths, self-imports) are not about aliases and apply to every file.

package/dist/index.js

@@ -161,6 +161,63 @@ function resolveFrom(baseDir, relative) {
 function isInsideDir(path, dir) {
 	return path.startsWith(dir.endsWith("/") ? dir : `${dir}/`);
 }
+/**
+* The `./` specifier from a directory to a path inside it, such as
+* `./sub/x.ts`. Returns `null` for a path outside the directory, which only
+* a banned `../` specifier could reach.
+*/
+function childSpecifier(fromDir, path) {
+	return isInsideDir(path, fromDir) ? `./${path.slice(fromDir.replace(/\/$/u, "").length + 1)}` : null;
+}
+/** The extensions a specifier without one may resolve to, in TypeScript's order. */
+const BARE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx"
+];
+/**
+* The source extensions a specifier's extension stands for, in the order
+* TypeScript tries them: `./x.js` names `x.ts`, then `x.tsx`, and so on.
+*/
+const SOURCE_EXTENSIONS = /* @__PURE__ */ new Map([
+	[".js", [".ts", ".tsx"]],
+	[".jsx", [".tsx"]],
+	[".mjs", [".mts"]],
+	[".cjs", [".cts"]],
+	[".ts", []],
+	[".tsx", []],
+	[".mts", []],
+	[".cts", []]
+]);
+/** The last extension of a path's last segment, or `""` when it has none. */
+function extensionOf(path) {
+	const dot = path.lastIndexOf(".");
+	return dot > path.lastIndexOf("/") + 1 ? path.slice(dot) : "";
+}
+/**
+* The files a resolved specifier path may name, in the order TypeScript
+* tries them: the path itself, then the source files of a script extension
+* (`./x.js` gives `x.ts` and `x.tsx`, `./x.mjs` gives `x.mts`), or, for a
+* path without a script extension, the path with `.ts`, `.tsx`, `.js`, or
+* `.jsx` added.
+*/
+function moduleCandidates(path) {
+	const extension = extensionOf(path);
+	const sources = SOURCE_EXTENSIONS.get(extension);
+	if (sources === void 0) return [path, ...BARE_EXTENSIONS.map((added) => path + added)];
+	const stem = path.slice(0, path.length - extension.length);
+	return [path, ...sources.map((source) => stem + source)];
+}
+/**
+* Whether a resolved specifier path names the module file `file`, the way
+* TypeScript resolves it (`moduleCandidates`). One-directional: `./x.mts`
+* never names `x.ts`, and another extension, such as `index.css`, names
+* another file.
+*/
+function namesSameModule(path, file) {
+	return moduleCandidates(path).includes(file);
+}
 //#endregion
 //#region src/helpers/imports.ts
 /**
@@ -180,6 +237,21 @@ const REJECTED_STEMS = ["mod"];
 const CONFIG_NAME = "package.json";
 /** A query or fragment suffix, which never names part of a path. */
 const QUERY_PATTERN = /[?#].*$/u;
+/**
+* A specifier without its query or fragment, such as `#a/x.js` for
+* `#a/x.js?raw`. The `#` that starts an alias is kept.
+*/
+function stripQuery(specifier) {
+	const alias = specifier.startsWith("#") ? "#" : "";
+	return alias + specifier.slice(alias.length).replace(QUERY_PATTERN, "");
+}
+/**
+* Whether a relative specifier climbs with a `..` segment anywhere, such as
+* `../x.ts` or `./sub/../../x.ts`.
+*/
+function isParentSpecifier(specifier) {
+	return specifier.startsWith(".") && stripQuery(specifier).split("/").includes("..");
+}
 /** A path written with a Windows drive after a leading slash, as in `/C:/dir`. */
 const SLASHED_DRIVE_PATTERN = /^\/[a-zA-Z]:/u;
 /**
@@ -247,7 +319,7 @@ function readImportsField(configPath) {
 /**
 * Whether an `imports` entry is a `#` alias with a relative string target.
 * Only those point at local files. A "#" alias for a package, or a condition
-* object, is legitimate but irrelevant here.
+* object, names no file here but still takes part in Node.js precedence.
 */
 function isLocalEntry(specifier, value) {
 	return specifier.startsWith("#") && typeof value === "string" && (value.startsWith("./") || value.startsWith("../"));
@@ -274,37 +346,51 @@ function moduleEntry(configDir, specifier, value, index) {
 	};
 }
 /**
-* Reads and parses one config file. Returns `null` when the file
-* is unreadable, is not JSON, or has no local `#` entries.
+* The order Node.js tries subpath patterns in: longest prefix first, then
+* longest key.
+*/
+function comparePatterns(left, right) {
+	return right.prefix.length - left.prefix.length || right.specifier.length - left.specifier.length;
+}
+/**
+* Adds one `imports` key to a config being built: a pattern, local or not, a
+* foreign exact key, or a local exact entry.
+*/
+function addImport(config, specifier, value) {
+	const local = isLocalEntry(specifier, value) ? value : null;
+	const star = specifier.indexOf("*");
+	if (star !== -1) {
+		config.patterns.push(patternEntry(specifier, star, local));
+		return;
+	}
+	if (local === null) {
+		config.foreignSpecifiers.add(specifier);
+		return;
+	}
+	const entry = moduleEntry(config.configDir, specifier, local, config.entries.length);
+	config.entries.push(entry);
+	config.bySpecifier.set(specifier, entry);
+	if (!config.byTarget.has(entry.target)) config.byTarget.set(entry.target, entry);
+}
+/**
+* Reads and parses one config file. Returns `null` when the file is
+* unreadable, is not JSON, or has no local `#` entries.
 */
 function readConfig(configPath, configDir) {
 	const imports = readImportsField(configPath);
 	if (imports === null) return null;
-	const entries = [];
-	const byTarget = /* @__PURE__ */ new Map();
-	const bySpecifier = /* @__PURE__ */ new Map();
-	const patterns = [];
-	for (const [specifier, value] of Object.entries(imports)) {
-		if (!isLocalEntry(specifier, value)) continue;
-		const star = specifier.indexOf("*");
-		if (star !== -1) {
-			patterns.push(patternEntry(specifier, star, value));
-			continue;
-		}
-		const entry = moduleEntry(configDir, specifier, value, entries.length);
-		entries.push(entry);
-		bySpecifier.set(specifier, entry);
-		if (!byTarget.has(entry.target)) byTarget.set(entry.target, entry);
-	}
-	if (entries.length === 0 && patterns.length === 0) return null;
-	patterns.sort((left, right) => right.prefix.length - left.prefix.length);
-	return {
+	const config = {
 		configDir,
-		entries,
-		byTarget,
-		bySpecifier,
-		patterns
+		entries: [],
+		byTarget: /* @__PURE__ */ new Map(),
+		bySpecifier: /* @__PURE__ */ new Map(),
+		foreignSpecifiers: /* @__PURE__ */ new Set(),
+		patterns: []
 	};
+	for (const [specifier, value] of Object.entries(imports)) if (specifier.startsWith("#")) addImport(config, specifier, value);
+	if (config.entries.length === 0 && config.patterns.every((pattern) => pattern.target === null)) return null;
+	config.patterns.sort(comparePatterns);
+	return config;
 }
 //#endregion
 //#region src/helpers/modules.ts
@@ -313,9 +399,13 @@ function readConfig(configPath, configDir) {
 * own: which alias owns a file, which one a specifier names, and whether an
 * import touches an owned area at all.
 *
-* An alias owns its target. An alias to a folder's `index.ts` owns that
-* folder and everything below it; an alias to any other file owns only that
-* file. Nothing here depends on folder or file names.
+* An alias owns its target minus the area of any deeper alias inside it. An
+* alias to a folder's `index.ts` owns that folder and everything below it;
+* an alias to any other file owns only that file. Where one area lies inside
+* another, the deeper alias owns its part and the outer one owns the rest, so
+* every file has a single owner: the alias with the deepest area holding it.
+* Two aliases on the same area tie, which `enforce-layer-order` reports.
+* Nothing here depends on folder or file names.
 */
 /**
 * Whether a normalized path lies in the area an alias owns. A folder alias's
@@ -326,46 +416,104 @@ function ownsPath(entry, path) {
 	return entry.target === path || entry.isBarrel && (path === entry.dir || isInsideDir(path, entry.dir));
 }
 /**
-* Every alias whose area holds a file, in declaration order. More than one
-* means two aliases overlap, which `enforce-layer-order` reports.
+* The aliases that own a file: those whose area holds it and lies deepest,
+* in declaration order. An outer alias gives way to any alias inside its
+* area, so this is one alias unless two share the same area, which
+* `enforce-layer-order` reports as an overlap.
 */
-function claimingEntries(config, filePath) {
+function owningEntries(config, filePath) {
 	const path = normalizePath(filePath);
-	return config.entries.filter((entry) => ownsPath(entry, path));
+	let owners = [];
+	for (const entry of config.entries) {
+		const deepest = owners[0];
+		if (!ownsPath(entry, path)) continue;
+		if (deepest === void 0 || entry.dir.length > deepest.dir.length) owners = [entry];
+		else if (entry.dir.length === deepest.dir.length) owners.push(entry);
+	}
+	return owners;
 }
 /**
-* Whether `entry` is among the aliases that claim a file. A file two aliases
-* overlap on counts as inside both areas, so the overlap is reported once by
-* `enforce-layer-order` rather than again as a bypass.
+* Whether `entry` owns a file. A file two aliases share an area on counts as
+* inside both, so the overlap is reported once by `enforce-layer-order`
+* rather than again as a bypass.
 */
-function isClaimedBy(config, filePath, entry) {
-	return claimingEntries(config, filePath).some((claimant) => claimant.index === entry.index);
+function isOwnedBy(config, filePath, entry) {
+	return owningEntries(config, filePath).some((owner) => owner.index === entry.index);
 }
 /**
-* Finds the alias that owns a file, which is the one with the most specific
-* area containing it. Returns `null` for a file no alias owns.
+* Finds the alias that owns a file, the one with the deepest area holding
+* it; the first declared when two share that area. Returns `null` for a file
+* no alias owns.
 */
 function findOwningEntry(config, filePath) {
-	let best = null;
-	for (const entry of claimingEntries(config, filePath)) if (best === null || entry.dir.length > best.dir.length) best = entry;
-	return best;
+	return owningEntries(config, filePath)[0] ?? null;
 }
 /**
-* The exact alias a deeper `#` specifier reaches past, such as `#utils` for
-* `#utils/internal.ts`, whether or not a subpath pattern makes it resolve.
-* The longest alias wins. Returns `null` when no alias is a prefix.
+* The alias a deeper `#` specifier reaches past, such as `#utils` for
+* `#utils/internal.ts`: the alias whose target the named file is, in any
+* spelling, else the owner of its area. A matching subpath pattern alone
+* names the file, whatever its name; one into unowned files or out of the
+* project gives `null`. With no pattern, the rest is read as a path in the
+* folder of the longest alias prefix (`#a/sub/x.ts` reaches past `#a-sub`
+* when it owns `a/sub/`), falling back to that prefix. A query or fragment
+* is ignored.
 */
 function deeperAliasOwner(config, specifier) {
+	const bare = stripQuery(specifier);
+	if (config.foreignSpecifiers.has(bare)) return null;
+	const pattern = findPatternEntry(config, bare);
+	if (pattern !== null) return ownerOfNamed(config, patternPath(config, pattern, bare));
+	const prefix = longestAliasPrefix(config, bare);
+	return ownerOfNamed(config, namedPath(config, bare, prefix)) ?? prefix;
+}
+/**
+* The file a deeper `#` specifier names, as `deeperAliasOwner` reads it, or
+* `null` when no subpath pattern matches and no folder alias is a prefix.
+*/
+function deeperAliasPath(config, specifier) {
+	const bare = stripQuery(specifier);
+	if (config.foreignSpecifiers.has(bare)) return null;
+	return namedPath(config, bare, longestAliasPrefix(config, bare));
+}
+/** The alias with the longest specifier that is a `/` prefix of `bare`. */
+function longestAliasPrefix(config, bare) {
 	let best = null;
-	for (const entry of config.entries) if (specifier.startsWith(`${entry.specifier}/`) && (best === null || entry.specifier.length > best.specifier.length)) best = entry;
+	for (const entry of config.entries) if (bare.startsWith(`${entry.specifier}/`) && (best === null || entry.specifier.length > best.specifier.length)) best = entry;
 	return best;
 }
 /**
+* The file a deeper `#` specifier, without its query, names: where a
+* subpath pattern sends it, or else, under a folder alias prefix `prefix`,
+* the rest of the specifier read as a path in that folder. Returns `null`
+* when neither applies.
+*/
+function namedPath(config, bare, prefix) {
+	const pattern = findPatternEntry(config, bare);
+	if (pattern !== null) return patternPath(config, pattern, bare);
+	if (prefix === null || !prefix.isBarrel) return null;
+	return resolveFrom(prefix.dir, `./${bare.slice(prefix.specifier.length + 1)}`);
+}
+/**
+* The file a subpath pattern resolves a matching `#` specifier to, or `null`
+* for a pattern that leads out of the project.
+*/
+function patternPath(config, pattern, specifier) {
+	if (pattern.target === null) return null;
+	const bare = stripQuery(specifier);
+	const matched = bare.slice(pattern.prefix.length, bare.length - pattern.suffix.length);
+	return resolveFrom(config.configDir, pattern.target.replaceAll("*", matched));
+}
+/**
 * Finds the subpath pattern a deep `#` specifier reaches through, such as
-* `#utils/*` for `#utils/internal.ts`. Returns `null` when none match.
+* `#utils/*` for `#utils/internal.ts`. A query or fragment is ignored, so
+* `#utils/x.js?raw` still matches `#utils/*.js`. Returns `null` when none
+* match or an exact key, which Node.js tries first, names the specifier.
+* The pattern found may lead out of the project, with a `null` target.
 */
 function findPatternEntry(config, specifier) {
-	for (const pattern of config.patterns) if (specifier.length >= pattern.prefix.length + pattern.suffix.length && specifier.startsWith(pattern.prefix) && specifier.endsWith(pattern.suffix)) return pattern;
+	const bare = stripQuery(specifier);
+	if (config.bySpecifier.has(bare) || config.foreignSpecifiers.has(bare)) return null;
+	for (const pattern of config.patterns) if (bare.length >= pattern.prefix.length + pattern.suffix.length && bare.startsWith(pattern.prefix) && bare.endsWith(pattern.suffix)) return pattern;
 	return null;
 }
 /**
@@ -373,7 +521,7 @@ function findPatternEntry(config, specifier) {
 * entry such as `#utils` or a deep one such as `#utils/internal.ts`.
 */
 function targetModule(config, specifier) {
-	const exact = config.bySpecifier.get(specifier);
+	const exact = config.bySpecifier.get(stripQuery(specifier));
 	if (exact !== void 0) return exact;
 	return deeperAliasOwner(config, specifier);
 }
@@ -392,12 +540,10 @@ function resolveLocalSpecifier(filename, specifier) {
 	if (!specifier.startsWith("#")) return null;
 	const config = findImportsConfig(filename);
 	if (config === null) return null;
-	const exact = config.bySpecifier.get(specifier);
+	const exact = config.bySpecifier.get(stripQuery(specifier));
 	if (exact !== void 0) return exact.target;
 	const pattern = findPatternEntry(config, specifier);
-	if (pattern === null) return null;
-	const matched = specifier.slice(pattern.prefix.length, specifier.length - pattern.suffix.length).replace(QUERY_PATTERN, "");
-	return resolveFrom(config.configDir, pattern.target.replaceAll("*", matched));
+	return pattern === null ? null : patternPath(config, pattern, specifier);
 }
 /**
 * The module a specifier points at, whether it was written as a `#` alias or
@@ -408,13 +554,28 @@ function resolveLocalSpecifier(filename, specifier) {
 function resolveTarget(config, filename, specifier) {
 	if (specifier.startsWith("#")) return targetModule(config, specifier);
 	if (!specifier.startsWith(".")) return null;
-	const resolved = resolveFrom(parentDir(normalizePath(filename)), specifier);
-	return config.byTarget.get(resolved) ?? null;
+	return entryAt(config, resolveFrom(parentDir(normalizePath(filename)), stripQuery(specifier)));
+}
+/**
+* The alias whose target a resolved path names, trying the files it may name
+* in TypeScript's order (`moduleCandidates`), so `./x.js` names `x.ts` before
+* `x.tsx`; the first declared when two aliases share a target. Returns
+* `null` when the path names no target.
+*/
+function entryAt(config, path) {
+	for (const candidate of moduleCandidates(path)) {
+		const entry = config.byTarget.get(candidate);
+		if (entry !== void 0) return entry;
+	}
+	return null;
+}
+/** The alias whose target a specifier path names, else its area's owner. */
+function ownerOfNamed(config, path) {
+	return path === null ? null : entryAt(config, path) ?? findOwningEntry(config, path);
 }
 /** Whether a path lies in the area some alias owns. */
 function isModulePath(config, path) {
-	const normalized = normalizePath(path);
-	return config.entries.some((entry) => ownsPath(entry, normalized));
+	return findOwningEntry(config, path) !== null;
 }
 /**
 * Whether an import touches an owned area: the importing file or the file it
@@ -641,10 +802,24 @@ const enforceImportOrderRule = {
 //#endregion
 //#region src/rules/enforce-layer-order.ts
 /**
+* Whether a specifier resolved to its importer's own area names that area's
+* entry point. A deeper `#` specifier to any other file of the area is no
+* cycle; `no-barrel-bypass` reports it and suggests a relative path.
+*/
+function namesOwnEntry(config, specifier, owner) {
+	if (!specifier.startsWith("#") || config.bySpecifier.has(stripQuery(specifier))) return true;
+	const path = deeperAliasPath(config, specifier);
+	return path !== null && namesSameModule(path, owner.target);
+}
+/**
 * `enforce-layer-order` - treats the order of `#` aliases in `package.json`
 * `imports` as the layer order, top layer first: an area may only import
 * aliases declared below its own. Also rejects a file that imports its own
-* area's alias, by alias or by path, and a file that two aliases claim.
+* area's alias, by alias or by path, and a file that two aliases with the
+* same area both own.
+*
+* An alias inside another alias's area owns its part, carved out of the
+* outer area, and the two are ordered like any other pair of aliases.
 *
 * This makes cycles between areas structurally impossible rather than
 * merely detectable. Lint cannot report on `package.json` itself, so an
@@ -661,7 +836,7 @@ const enforceLayerOrderRule = {
 		messages: {
 			ownEntry: "'{{owner}}' must not import its own entry point through '{{specifier}}'.",
 			upward: "'{{owner}}' must not import '{{target}}', which is declared above it in package.json.",
-			overlap: "This file is owned by more than one alias in package.json: {{aliases}}."
+			overlap: "This file is owned by more than one alias with the same area in package.json: {{aliases}}."
 		}
 	},
 	create(context) {
@@ -673,6 +848,7 @@ const enforceLayerOrderRule = {
 				const target = resolveTarget(config, context.filename, specifier);
 				if (owner === null || target === null) return;
 				if (target.index === owner.index) {
+					if (!namesOwnEntry(config, specifier, owner)) return;
 					context.report({
 						node,
 						messageId: "ownEntry",
@@ -694,8 +870,8 @@ const enforceLayerOrderRule = {
 			}),
 			Program(node) {
 				const config = findImportsConfig(context.filename);
-				const claiming = config === null ? [] : claimingEntries(config, context.filename);
-				if (claiming.length < 2) return;
+				const owners = config === null ? [] : owningEntries(config, context.filename);
+				if (owners.length < 2) return;
 				context.report({
 					node,
 					loc: {
@@ -703,7 +879,7 @@ const enforceLayerOrderRule = {
 						column: 0
 					},
 					messageId: "overlap",
-					data: { aliases: claiming.map((entry) => entry.specifier).join(", ") }
+					data: { aliases: owners.map((entry) => entry.specifier).join(", ") }
 				});
 			}
 		};
@@ -788,6 +964,57 @@ const noAbsoluteImportRule = {
 //#endregion
 //#region src/rules/no-barrel-bypass.ts
 /**
+* The `./` specifier a file inside `owner`'s area can use instead of a deeper
+* `#` specifier into that same area, keeping any query. `null` when the named
+* file is not in the importer's folder or below, since `../` is banned, or
+* when it is the area's entry point or the importer itself, which
+* `enforce-layer-order` and `no-self-import` reject by any spelling.
+*/
+function relativeSpecifier(config, filename, specifier, owner) {
+	const path = deeperAliasPath(config, specifier);
+	const importer = normalizePath(filename);
+	if (path === null || namesSameModule(path, owner.target) || namesSameModule(path, importer)) return null;
+	const relative = childSpecifier(parentDir(importer), path);
+	return relative === null ? null : relative + specifier.slice(stripQuery(specifier).length);
+}
+/**
+* Reports a deeper `#` specifier into the importing file's own area. The
+* alias itself is never suggested there, since importing it is a cycle;
+* a relative path is, when one without `../` exists.
+*/
+function reportOwnArea(context, node, data, relative) {
+	context.report({
+		node,
+		messageId: "ownArea",
+		data,
+		suggest: relative === null ? [] : [{
+			messageId: "useRelative",
+			data: { path: relative },
+			fix: (fixer) => fixer.replaceText(node, quoteLike(node, relative))
+		}]
+	});
+}
+/**
+* Reports a deeper `#` specifier from outside the area of its owner,
+* suggesting the alias unless a query or fragment, which the alias cannot
+* carry, would be lost.
+*/
+function reportBypass(context, node, specifier, owner) {
+	context.report({
+		node,
+		messageId: "bypass",
+		data: {
+			specifier,
+			owner: owner.specifier
+		},
+		suggest: stripQuery(specifier) === specifier ? [{
+			messageId: "useEntry",
+			data: { owner: owner.specifier },
+			fix: (fixer) => fixer.replaceText(node, quoteLike(node, owner.specifier))
+		}] : []
+	});
+}
+/**
 * `no-barrel-bypass` - rejects a `#` specifier deeper than an alias, such as
 * `#components/internal.ts` beside `#components`, whether or not a subpath
 * pattern makes it resolve, and any use of a subpath pattern that reaches
@@ -795,7 +1022,8 @@ const noAbsoluteImportRule = {
 *
 * Code outside an alias's area reaches it only through the exact alias, so
 * the area keeps one public surface. Switching to the alias is a suggestion,
-* since its target may not export the name yet.
+* since its target may not export the name yet. Inside the area, the alias
+* is a cycle, so a relative path is suggested instead.
 */
 const noBarrelBypassRule = {
 	meta: {
@@ -808,37 +1036,37 @@ const noBarrelBypassRule = {
 		schema: [],
 		messages: {
 			bypass: "'{{specifier}}' reaches past the entry point '{{owner}}'.",
+			ownArea: "'{{specifier}}' reaches into this file's own area '{{owner}}' through an alias.",
 			internals: "'{{specifier}}' reaches into module internals.",
-			useEntry: "Import from '{{owner}}' instead."
+			useEntry: "Import from '{{owner}}' instead.",
+			useRelative: "Import from '{{path}}' instead."
 		}
 	},
 	create(context) {
 		return visitSpecifiers((node, specifier) => {
 			if (!specifier.startsWith("#")) return;
 			const config = findImportsConfig(context.filename);
-			if (config === null || config.bySpecifier.has(specifier)) return;
+			const bare = stripQuery(specifier);
+			if (config === null || config.bySpecifier.has(bare) || config.foreignSpecifiers.has(bare)) return;
 			const owner = deeperAliasOwner(config, specifier);
 			if (owner === null) {
-				if (findPatternEntry(config, specifier) !== null && isInModuleScope(context.filename, specifier)) context.report({
+				const pattern = findPatternEntry(config, specifier);
+				if (pattern !== null && pattern.target !== null && isInModuleScope(context.filename, specifier)) context.report({
 					node,
 					messageId: "internals",
 					data: { specifier }
 				});
 				return;
 			}
-			context.report({
-				node,
-				messageId: "bypass",
-				data: {
+			if (isOwnedBy(config, context.filename, owner)) {
+				const relative = relativeSpecifier(config, context.filename, specifier, owner);
+				reportOwnArea(context, node, {
 					specifier,
 					owner: owner.specifier
-				},
-				suggest: [{
-					messageId: "useEntry",
-					data: { owner: owner.specifier },
-					fix: (fixer) => fixer.replaceText(node, quoteLike(node, owner.specifier))
-				}]
-			});
+				}, relative);
+				return;
+			}
+			reportBypass(context, node, specifier, owner);
 		});
 	}
 };
@@ -899,9 +1127,10 @@ const noDuplicateImportSourceRule = {
 //#endregion
 //#region src/rules/no-parent-import.ts
 /**
-* `no-parent-import` - rejects `../` specifiers in every file, owned by an
-* alias or not, rewriting one to its `#` alias where `package.json` declares
-* an alias for exactly that file.
+* `no-parent-import` - rejects `../` specifiers, and any relative specifier
+* with a `..` segment, in every file, owned by an alias or not, rewriting
+* one to its `#` alias where `package.json` declares an alias for that file,
+* in any spelling TypeScript resolves to it.
 *
 * Reaching up and back down couples two files through their layout instead
 * of a name. Anything above a file is reached through an alias.
@@ -922,11 +1151,11 @@ const noParentImportRule = {
 	},
 	create(context) {
 		return visitSpecifiers((node, specifier) => {
-			if (!specifier.startsWith("../")) return;
+			if (!isParentSpecifier(specifier)) return;
 			const config = findImportsConfig(context.filename);
 			const resolved = resolveLocalSpecifier(context.filename, specifier);
-			const entry = resolved === null ? void 0 : config?.byTarget.get(resolved);
-			if (config === null || entry === void 0 || isClaimedBy(config, context.filename, entry)) {
+			const entry = config === null || resolved === null ? null : entryAt(config, resolved);
+			if (config === null || entry === null || isOwnedBy(config, context.filename, entry)) {
 				context.report({
 					node,
 					messageId: "parentImport",
@@ -941,7 +1170,7 @@ const noParentImportRule = {
 					specifier,
 					alias: entry.specifier
 				},
-				fix: (fixer) => fixer.replaceText(node, quoteLike(node, entry.specifier))
+				fix: stripQuery(specifier) === specifier ? (fixer) => fixer.replaceText(node, quoteLike(node, entry.specifier)) : null
 			});
 		});
 	}
@@ -956,8 +1185,8 @@ const noParentImportRule = {
 * folder and everything below it, and an alias to any other file owns only
 * that file. Code outside an area reaches it only through the alias. Inside
 * an area, siblings and subfolders are free, and so are files no alias owns.
-* A path to an alias's exact target is left to `prefer-alias-import`, which
-* rewrites it to the alias.
+* A path to an alias's target, in any spelling TypeScript resolves to it, is
+* left to `prefer-alias-import`, which rewrites it to the alias.
 */
 const noRelativeBypassRule = {
 	meta: {
@@ -971,12 +1200,12 @@ const noRelativeBypassRule = {
 	},
 	create(context) {
 		return visitSpecifiers((node, specifier) => {
-			if (!specifier.startsWith("./")) return;
+			if (!specifier.startsWith("./") || isParentSpecifier(specifier)) return;
 			const config = findImportsConfig(context.filename);
 			const resolved = resolveLocalSpecifier(context.filename, specifier);
-			if (config === null || resolved === null || config.byTarget.has(resolved)) return;
+			if (config === null || resolved === null || entryAt(config, resolved) !== null) return;
 			const target = findOwningEntry(config, resolved);
-			if (target === null || isClaimedBy(config, context.filename, target)) return;
+			if (target === null || isOwnedBy(config, context.filename, target)) return;
 			context.report({
 				node,
 				messageId: "bypass",
@@ -993,7 +1222,8 @@ const noRelativeBypassRule = {
 /**
 * `no-self-import` - rejects any statically knowable specifier that resolves
 * to the importing file: a relative path, an absolute path or `file:` URL, an
-* exact `#` entry, or a `#` subpath pattern.
+* exact `#` entry, or a `#` subpath pattern, in any spelling TypeScript
+* resolves to the file (such as `.js` for `.ts`, or no extension).
 *
 * A self-import is an immediate circular dependency.
 */
@@ -1009,7 +1239,8 @@ const noSelfImportRule = {
 	},
 	create(context) {
 		return visitSpecifiers((node, specifier) => {
-			if (resolveLocalSpecifier(context.filename, specifier) !== normalizePath(context.filename)) return;
+			const target = resolveLocalSpecifier(context.filename, specifier);
+			if (target === null || !namesSameModule(target, normalizePath(context.filename))) return;
 			context.report({
 				node,
 				messageId: "selfImport",
@@ -1051,9 +1282,9 @@ const noWildcardImportRule = {
 //#region src/rules/prefer-alias-import.ts
 /**
 * `prefer-alias-import` - requires the `#` alias when a `./` specifier names
-* the exact target of an alias from outside that alias's area, a same-folder
-* sibling included. An alias owns its target, so its target has one spelling
-* everywhere outside it.
+* the target of an alias, in any spelling TypeScript resolves to it, from
+* outside that alias's area, a same-folder sibling included. An alias owns
+* its target, so its target has one spelling everywhere outside it.
 *
 * One spelling per module keeps `package.json` `imports` the single source of
 * truth, and keeps the layer rules from being sidestepped by a path.
@@ -1071,12 +1302,12 @@ const preferAliasImportRule = {
 	},
 	create(context) {
 		return visitSpecifiers((node, specifier) => {
-			if (!specifier.startsWith("./")) return;
+			if (!specifier.startsWith("./") || isParentSpecifier(specifier)) return;
 			const config = findImportsConfig(context.filename);
 			const resolved = resolveLocalSpecifier(context.filename, specifier);
-			const entry = resolved === null ? void 0 : config?.byTarget.get(resolved);
-			if (config === null || entry === void 0) return;
-			if (isClaimedBy(config, context.filename, entry)) return;
+			const entry = config === null || resolved === null ? null : entryAt(config, resolved);
+			if (config === null || entry === null) return;
+			if (isOwnedBy(config, context.filename, entry)) return;
 			context.report({
 				node,
 				messageId: "useAlias",
@@ -1084,7 +1315,7 @@ const preferAliasImportRule = {
 					specifier,
 					alias: entry.specifier
 				},
-				fix: (fixer) => fixer.replaceText(node, quoteLike(node, entry.specifier))
+				fix: stripQuery(specifier) === specifier ? (fixer) => fixer.replaceText(node, quoteLike(node, entry.specifier)) : null
 			});
 		});
 	}
@@ -1138,7 +1369,7 @@ const MODULES = [
 const basePlugin = {
 	meta: {
 		name: "eslint-plugin-import-structure",
-		version: "0.10.5",
+		version: "0.11.1",
 		namespace: NAMESPACE
 	},
 	rules: Object.fromEntries(rules)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-import-structure",
-  "version": "0.10.5",
+  "version": "0.11.1",
   "description": "ESLint and Oxlint rules that keep a module graph layered and free of cycles, with package.json \"#\" imports as the layer order.",
   "keywords": [
     "eslint",