pasika 0.2.0 → 0.3.1

package/dist/eslint/pasika/project/ccf.js

@@ -0,0 +1,119 @@
+import path from "node:path";
+export const SUPPORT_FOLDERS = new Set(["hooks", "types", "schemas", "constants", "utils"]);
+/** Path of a file relative to the source root, as segments. */
+export function segmentsOf(file, sourceRoot) {
+    const relative = path.relative(sourceRoot, file);
+    return relative.startsWith("..") ? [] : relative.split(path.sep);
+}
+/** Folder of a file relative to the source root, as segments. */
+export function folderSegmentsOf(file, sourceRoot) {
+    return segmentsOf(file, sourceRoot).slice(0, -1);
+}
+export const isUnderApp = (segments) => segments[0] === "app";
+export const isConfigModule = (segments) => segments[0] === "config";
+export const isUnderCompositions = (segments) => segments[0] === "compositions";
+/** The longest folder prefix every path shares. */
+function commonPrefix(folders) {
+    if (folders.length === 0)
+        return [];
+    const [first = []] = folders;
+    const shared = [];
+    for (const [depth, segment] of first.entries()) {
+        if (!folders.every((folder) => folder[depth] === segment))
+            break;
+        shared.push(segment);
+    }
+    return shared;
+}
+/** Walks out of any trailing support folders, since a component never lives in one. */
+function outOfSupportFolders(folder) {
+    const result = [...folder];
+    while (result.length > 0 && SUPPORT_FOLDERS.has(result[result.length - 1] ?? ""))
+        result.pop();
+    return result;
+}
+/**
+ * Resolves where a component belongs from the files that import it.
+ *
+ * Imports from `src/app/` and from configuration modules drop out, consumers
+ * under `src/compositions/` count only when every consumer is there, and a
+ * result of `src/features/` becomes `src/shared/` because no feature may import
+ * from another. Returns undefined when no consumer counts, which is the case the
+ * "lives in the feature it represents" requirement covers instead.
+ */
+export function resolveComponentPlacement(componentFile, index) {
+    const consumers = [...(index.consumers.get(componentFile) ?? [])];
+    const relevant = consumers.filter((consumer) => {
+        const segments = segmentsOf(consumer, index.sourceRoot);
+        return segments.length > 0 && !isUnderApp(segments) && !isConfigModule(segments);
+    });
+    if (relevant.length === 0)
+        return undefined;
+    const outsideCompositions = relevant.filter((consumer) => !isUnderCompositions(segmentsOf(consumer, index.sourceRoot)));
+    const counted = outsideCompositions.length > 0 ? outsideCompositions : relevant;
+    const shared = outOfSupportFolders(commonPrefix(counted.map((consumer) => folderSegmentsOf(consumer, index.sourceRoot))));
+    // A shared folder of `features` or of the source root itself means no single
+    // feature owns the component, so it belongs to the shared layer.
+    if (shared.length === 1 && shared[0] === "features") {
+        return { countedConsumers: counted, expectedFolder: ["shared"], reason: "across-features" };
+    }
+    if (shared.length === 0) {
+        return { countedConsumers: counted, expectedFolder: ["shared"], reason: "across-layers" };
+    }
+    return { countedConsumers: counted, expectedFolder: shared, reason: "ccf" };
+}
+export const formatFolder = (folder) => `src/${folder.join("/")}/`;
+/** The folder that owns a consumer: its own folder, stepped out of any support folder. */
+function owningFolderOf(consumer, sourceRoot) {
+    return outOfSupportFolders(folderSegmentsOf(consumer, sourceRoot));
+}
+/** The configuration module a file belongs to. `config/<name>/...` only: `config/<file>.ts` is not a module. */
+const configModuleOf = (segments) => isConfigModule(segments) && segments.length >= 3 ? segments[1] : undefined;
+/**
+ * Resolves where a support file belongs from the files that import it.
+ *
+ * A consumer inside a support folder is owned by that folder's parent, so the
+ * calculation lands on the scope that uses the file rather than on a sibling
+ * support folder. A consumer under `src/app/` forces the root support folder, a
+ * set of consumers inside one configuration module keeps the file in that module,
+ * and consumers spanning features land in the root support folder.
+ */
+export function resolveSupportPlacement(supportFile, supportFolder, index) {
+    const consumers = [...(index.consumers.get(supportFile) ?? [])].filter((consumer) => segmentsOf(consumer, index.sourceRoot).length > 0);
+    if (consumers.length === 0)
+        return undefined;
+    const consumerSegments = consumers.map((consumer) => segmentsOf(consumer, index.sourceRoot));
+    if (consumerSegments.some((segments) => isUnderApp(segments))) {
+        return { countedConsumers: consumers, expectedFolder: [supportFolder], reason: "app-consumer" };
+    }
+    const configModules = new Set(consumerSegments.map((segments) => configModuleOf(segments)));
+    const [onlyConfigModule] = [...configModules];
+    if (configModules.size === 1 && onlyConfigModule !== undefined) {
+        return {
+            countedConsumers: consumers,
+            expectedFolder: ["config", onlyConfigModule, supportFolder],
+            reason: "config-module",
+        };
+    }
+    const shared = commonPrefix(consumers.map((consumer) => owningFolderOf(consumer, index.sourceRoot)));
+    if (shared.length === 1 && shared[0] === "features") {
+        return { countedConsumers: consumers, expectedFolder: [supportFolder], reason: "across-features" };
+    }
+    if (shared.length === 0) {
+        return { countedConsumers: consumers, expectedFolder: [supportFolder], reason: "across-layers" };
+    }
+    return { countedConsumers: consumers, expectedFolder: [...shared, supportFolder], reason: "ccf" };
+}
+/**
+ * Consumers for a message. A widely used file can have dozens, so the list is
+ * capped: the point is to show where the requirement comes from, not to enumerate.
+ */
+export function describeConsumers(consumers, sourceRoot) {
+    const shown = 3;
+    const names = consumers
+        .map((consumer) => path.relative(path.dirname(sourceRoot), consumer).split(path.sep).join("/"))
+        .sort((left, right) => left.localeCompare(right));
+    if (names.length <= shown)
+        return names.join(", ");
+    return `${names.slice(0, shown).join(", ")} and ${String(names.length - shown)} more`;
+}

package/dist/eslint/pasika/project/index.d.ts

@@ -0,0 +1,21 @@
+import { type ParsedModule } from "./parse-module.js";
+export interface ProjectIndex {
+    sourceRoot: string;
+    /** Absolute file path to its parsed module. */
+    modules: Map<string, ParsedModule>;
+    /** Absolute file path to the files that import it. */
+    consumers: Map<string, Set<string>>;
+    /** `file` and name joined by a NUL, to the files that import that name from it. */
+    symbolConsumers: Map<string, Set<string>>;
+}
+export declare const symbolKey: (file: string, name: string) => string;
+/** Resolves an import specifier to a file inside the source tree, if it points at one. */
+export declare function resolveSpecifier(fromFile: string, specifier: string, sourceRoot: string): string | undefined;
+/**
+ * The project index for a source tree, rebuilt only when the tree changed.
+ * Returns undefined when the tree does not exist, which is how a repository
+ * without a `src/` folder opts out of every cross-file rule.
+ */
+export declare function getProjectIndex(sourceRoot: string): ProjectIndex | undefined;
+/** Drops the memoized index. Used by tests that write a fresh tree per case. */
+export declare function clearProjectIndex(): void;

package/dist/eslint/pasika/project/index.js

@@ -0,0 +1,139 @@
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { parseModule } from "./parse-module.js";
+const MODULE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+const INDEX_BASENAMES = ["index.ts", "index.tsx", "index.mts", "index.cts", "index.js", "index.jsx"];
+/**
+ * How long a built index is trusted before its inputs are re-checked. A long
+ * lived ESLint server keeps this module in memory across edits, so the index has
+ * to notice a changed tree without re-reading it on every single file.
+ */
+const REVALIDATE_AFTER_MS = 2000;
+export const symbolKey = (file, name) => `${file}\u0000${name}`;
+function listSourceFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries.flatMap((entry) => {
+        if (entry.startsWith(".") || entry === "node_modules")
+            return [];
+        const entryPath = path.join(dir, entry);
+        let stats;
+        try {
+            stats = statSync(entryPath);
+        }
+        catch {
+            return [];
+        }
+        if (stats.isDirectory())
+            return listSourceFiles(entryPath);
+        return MODULE_EXTENSIONS.includes(path.extname(entry)) ? [entryPath] : [];
+    });
+}
+/** Cheap fingerprint of the tree, so an unchanged tree is never re-parsed. */
+function fingerprint(files) {
+    let total = 0;
+    for (const file of files) {
+        try {
+            total += statSync(file).mtimeMs;
+        }
+        catch {
+            /* A file removed between listing and stat just drops out of the fingerprint. */
+        }
+    }
+    return `${String(files.length)}:${String(total)}`;
+}
+/** Resolves an import specifier to a file inside the source tree, if it points at one. */
+export function resolveSpecifier(fromFile, specifier, sourceRoot) {
+    let base;
+    if (specifier.startsWith("@/")) {
+        base = path.resolve(sourceRoot, specifier.slice(2));
+    }
+    else if (specifier.startsWith(".")) {
+        base = path.resolve(path.dirname(fromFile), specifier);
+    }
+    else {
+        return undefined;
+    }
+    const candidates = [
+        base,
+        ...MODULE_EXTENSIONS.map((extension) => `${base}${extension}`),
+        ...INDEX_BASENAMES.map((name) => path.join(base, name)),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            /* Try the next candidate. */
+        }
+    }
+    return undefined;
+}
+function build(sourceRoot, files) {
+    const modules = new Map();
+    const consumers = new Map();
+    const symbolConsumers = new Map();
+    for (const file of files) {
+        try {
+            modules.set(file, parseModule(file));
+        }
+        catch {
+            /* A file that cannot be read or parsed contributes nothing to the graph. */
+        }
+    }
+    for (const [file, module] of modules) {
+        for (const moduleImport of module.imports) {
+            const target = resolveSpecifier(file, moduleImport.specifier, sourceRoot);
+            if (!target || !modules.has(target))
+                continue;
+            const fileConsumers = consumers.get(target) ?? new Set();
+            fileConsumers.add(file);
+            consumers.set(target, fileConsumers);
+            for (const name of moduleImport.names) {
+                const key = symbolKey(target, name);
+                const nameConsumers = symbolConsumers.get(key) ?? new Set();
+                nameConsumers.add(file);
+                symbolConsumers.set(key, nameConsumers);
+            }
+        }
+    }
+    return { sourceRoot, modules, consumers, symbolConsumers };
+}
+let cache;
+/**
+ * The project index for a source tree, rebuilt only when the tree changed.
+ * Returns undefined when the tree does not exist, which is how a repository
+ * without a `src/` folder opts out of every cross-file rule.
+ */
+export function getProjectIndex(sourceRoot) {
+    const now = Date.now();
+    if (cache?.index.sourceRoot === sourceRoot && now - cache.checkedAt < REVALIDATE_AFTER_MS) {
+        return cache.index;
+    }
+    try {
+        if (!statSync(sourceRoot).isDirectory())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const files = listSourceFiles(sourceRoot).sort((left, right) => left.localeCompare(right));
+    const currentFingerprint = fingerprint(files);
+    if (cache?.index.sourceRoot === sourceRoot && cache.fingerprint === currentFingerprint) {
+        cache.checkedAt = now;
+        return cache.index;
+    }
+    const index = build(sourceRoot, files);
+    cache = { index, checkedAt: now, fingerprint: currentFingerprint };
+    return index;
+}
+/** Drops the memoized index. Used by tests that write a fresh tree per case. */
+export function clearProjectIndex() {
+    cache = undefined;
+}

package/dist/eslint/pasika/project/parse-module.d.ts

@@ -0,0 +1,27 @@
+/** What an exported name is, as far as the placement rules need to care. */
+export type ExportKind = "component" | "hook" | "type" | "schema" | "constant" | "function" | "other";
+export interface ModuleExport {
+    name: string;
+    kind: ExportKind;
+    line: number;
+}
+export interface ModuleImport {
+    /** The specifier exactly as written. */
+    specifier: string;
+    /** Names taken from the module; empty for a side-effect or namespace import. */
+    names: string[];
+    line: number;
+}
+export interface ParsedModule {
+    file: string;
+    imports: ModuleImport[];
+    exports: ModuleExport[];
+}
+/**
+ * Parses one module for the names it exports and the modules it imports.
+ *
+ * Uses the TypeScript parser without a program or typechecker: the placement
+ * rules only need the shape of the import and export statements, and parsing a
+ * file in isolation keeps this fast enough to run over a whole tree.
+ */
+export declare function parseModule(file: string): ParsedModule;

package/dist/eslint/pasika/project/parse-module.js

@@ -0,0 +1,128 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+const isPascalCase = (name) => /^[A-Z][A-Za-z0-9]*$/.test(name);
+const isHookName = (name) => /^use[A-Z]/.test(name);
+const isSchemaName = (name) => /[Ss]chema$/.test(name);
+function lineOf(sourceFile, node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}
+function returnsJsx(node) {
+    let found = false;
+    const visit = (child) => {
+        if (found)
+            return;
+        if (ts.isJsxElement(child) ||
+            ts.isJsxSelfClosingElement(child) ||
+            ts.isJsxFragment(child) ||
+            ts.isJsxOpeningFragment(child)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(child, visit);
+    };
+    ts.forEachChild(node, visit);
+    return found;
+}
+function classifyFunction(name, isTsx, hasJsx) {
+    if (isHookName(name))
+        return "hook";
+    if (isTsx && isPascalCase(name) && hasJsx)
+        return "component";
+    return "function";
+}
+function classifyValue(name, initializer, isTsx) {
+    const isFunctionLike = initializer !== undefined &&
+        (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer) || ts.isFunctionDeclaration(initializer));
+    if (isHookName(name))
+        return "hook";
+    if (isSchemaName(name))
+        return "schema";
+    if (isTsx && isPascalCase(name) && (initializer === undefined || returnsJsx(initializer) || isFunctionLike)) {
+        return "component";
+    }
+    if (isFunctionLike)
+        return "function";
+    return "constant";
+}
+/**
+ * Parses one module for the names it exports and the modules it imports.
+ *
+ * Uses the TypeScript parser without a program or typechecker: the placement
+ * rules only need the shape of the import and export statements, and parsing a
+ * file in isolation keeps this fast enough to run over a whole tree.
+ */
+export function parseModule(file) {
+    const text = readFileSync(file, "utf8");
+    const isTsx = file.endsWith(".tsx") || file.endsWith(".jsx");
+    const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const imports = [];
+    const exports = [];
+    const addImport = (specifierNode, names, node) => {
+        if (!ts.isStringLiteral(specifierNode))
+            return;
+        imports.push({ specifier: specifierNode.text, names, line: lineOf(sourceFile, node) });
+    };
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            const names = [];
+            const bindings = statement.importClause?.namedBindings;
+            if (statement.importClause?.name)
+                names.push(statement.importClause.name.text);
+            if (bindings && ts.isNamedImports(bindings)) {
+                for (const element of bindings.elements)
+                    names.push(element.propertyName?.text ?? element.name.text);
+            }
+            addImport(statement.moduleSpecifier, names, statement);
+            continue;
+        }
+        if (ts.isExportDeclaration(statement)) {
+            // `export { x } from "./y"` both imports and re-exports.
+            if (statement.moduleSpecifier) {
+                const names = [];
+                if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+                    for (const element of statement.exportClause.elements) {
+                        names.push(element.propertyName?.text ?? element.name.text);
+                    }
+                }
+                addImport(statement.moduleSpecifier, names, statement);
+            }
+            if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+                for (const element of statement.exportClause.elements) {
+                    exports.push({ name: element.name.text, kind: "other", line: lineOf(sourceFile, element) });
+                }
+            }
+            continue;
+        }
+        const isExported = ts.canHaveModifiers(statement)
+            ? (ts.getModifiers(statement) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+            : false;
+        if (!isExported)
+            continue;
+        if (ts.isFunctionDeclaration(statement) && statement.name) {
+            const name = statement.name.text;
+            exports.push({
+                name,
+                kind: classifyFunction(name, isTsx, returnsJsx(statement)),
+                line: lineOf(sourceFile, statement),
+            });
+            continue;
+        }
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (!ts.isIdentifier(declaration.name))
+                    continue;
+                exports.push({
+                    name: declaration.name.text,
+                    kind: classifyValue(declaration.name.text, declaration.initializer, isTsx),
+                    line: lineOf(sourceFile, declaration),
+                });
+            }
+            continue;
+        }
+        if (ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) {
+            exports.push({ name: statement.name.text, kind: "type", line: lineOf(sourceFile, statement) });
+        }
+    }
+    return { file: path.resolve(file), imports, exports };
+}

package/dist/eslint/pasika/rules/component-placement.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ESLint rule: pasika/component-placement
+ *
+ * Enforces the placement requirements from the "Component Placement Rule" by
+ * reading the whole source tree, because where a component belongs depends on
+ * which files import it — something a single-file pass cannot see.
+ *
+ * @see docs/code-organization-guide/rules/component-placement-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const componentPlacementRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/component-placement.js

@@ -0,0 +1,75 @@
+/**
+ * ESLint rule: pasika/component-placement
+ *
+ * Enforces the placement requirements from the "Component Placement Rule" by
+ * reading the whole source tree, because where a component belongs depends on
+ * which files import it — something a single-file pass cannot see.
+ *
+ * @see docs/code-organization-guide/rules/component-placement-rule.md
+ */
+import path from "node:path";
+import { getProjectIndex } from "../project/index.js";
+import { describeConsumers, folderSegmentsOf, formatFolder, isConfigModule, isUnderApp, resolveComponentPlacement, segmentsOf, } from "../project/ccf.js";
+const REASON_TEXT = {
+    ccf: "that is the closest folder its consumers share",
+    "across-features": "its consumers span more than one feature, and no feature may import from another",
+    "across-layers": "its consumers span more than one layer, so no feature can own it",
+};
+const sameFolder = (left, right) => left.length === right.length && left.every((segment, depth) => segment === right[depth]);
+export const componentPlacementRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Enforce that a component lives in the folder its consumers imply.",
+        },
+    },
+    create(context) {
+        const filename = context.filename;
+        if (!filename.endsWith(".tsx") && !filename.endsWith(".jsx"))
+            return {};
+        const sourceRoot = path.resolve("src");
+        const index = getProjectIndex(sourceRoot);
+        if (!index)
+            return {};
+        const componentFile = path.resolve(filename);
+        const segments = segmentsOf(componentFile, sourceRoot);
+        if (segments.length === 0)
+            return {};
+        // Routing files and configuration modules are not placed by their consumers.
+        if (isUnderApp(segments) || isConfigModule(segments))
+            return {};
+        const module = index.modules.get(componentFile);
+        if (!module?.exports.some((moduleExport) => moduleExport.kind === "component"))
+            return {};
+        const currentFolder = folderSegmentsOf(componentFile, sourceRoot);
+        const placement = resolveComponentPlacement(componentFile, index);
+        return {
+            Program(node) {
+                if (!placement) {
+                    // No consumer counts, so the component belongs to the feature it represents.
+                    if (segments[0] !== "features" || segments.length < 3) {
+                        context.report({
+                            node,
+                            loc: { line: 1, column: 0 },
+                            message: `This component has no consumer outside src/app/ or a configuration module, ` +
+                                `so it belongs in the feature folder it represents, not in ${formatFolder(currentFolder)}. ` +
+                                "See docs/code-organization-guide/rules/component-placement-rule.md",
+                        });
+                    }
+                    return;
+                }
+                if (sameFolder(currentFolder, placement.expectedFolder))
+                    return;
+                const explanation = REASON_TEXT[placement.reason] ?? "that is where its consumers place it";
+                context.report({
+                    node,
+                    loc: { line: 1, column: 0 },
+                    message: `Move this component to ${formatFolder(placement.expectedFolder)} — ${explanation}. ` +
+                        `Imported by ${describeConsumers(placement.countedConsumers, sourceRoot)}. ` +
+                        "See docs/code-organization-guide/rules/component-placement-rule.md",
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/enforce-cva-variant-props.js

@@ -53,7 +53,12 @@ export const enforceCvaVariantPropsRule = {
                         member.typeAnnotation?.typeAnnotation?.type === "TSUnionType") {
                         const keyName = String(member.key.name);
                         const typeAnn = member.typeAnnotation.typeAnnotation;
-                        const allStringLiterals = typeAnn.types.every((t) => t.type === "TSLiteralType" && t.literal.type === "StringLiteral");
+                        // typescript-eslint emits ESTree `Literal` nodes; other TypeScript
+                        // parsers emit `StringLiteral`. Accept both so the rule works
+                        // whichever parser the consuming config installs.
+                        const allStringLiterals = typeAnn.types.every((t) => t.type === "TSLiteralType" &&
+                            (t.literal?.type === "StringLiteral" ||
+                                (t.literal?.type === "Literal" && typeof t.literal.value === "string")));
                         if (allStringLiterals && typeAnn.types.length >= 2) {
                             for (const [, variantNames] of cvaDefinitions) {
                                 if (variantNames.includes(keyName)) {

package/dist/eslint/pasika/rules/import-boundaries.js

@@ -2,8 +2,8 @@
  * ESLint rule: pasika/import-boundaries
  *
  * Enforces the import conventions from the "Exports and Imports Rule":
- *  - Relative imports for nearby files (same folder, subfolder, one level up).
- *  - @/* alias for imports beyond one folder up.
+ *  - Whichever of the relative path and the @/* alias has fewer segments, with
+ *    a tie going to the relative path.
  *  - Layer boundary enforcement (app → compositions → features → shared → root).
  *
  * @see docs/code-organization-guide/rules/exports-and-imports-rule.md
@@ -29,12 +29,33 @@ function sourceSegments(absolutePath) {
     }
     return relativePath.split(path.sep);
 }
-function isNearbyImport(filename, resolvedPath) {
-    const relativePath = path.relative(path.dirname(filename), resolvedPath);
-    const segments = relativePath.split(path.sep).filter((segment) => segment !== ".");
-    const parentTraversals = segments.filter((segment) => segment === "..").length;
-    const nonParentSegments = segments.length - parentTraversals;
-    return (parentTraversals === 0 && nonParentSegments <= 2) || (parentTraversals === 1 && nonParentSegments <= 1);
+/** The relative form of an import, always prefixed so it reads as a path. */
+function relativeSpecifier(filename, resolvedPath) {
+    const relativePath = path.relative(path.dirname(filename), resolvedPath).split(path.sep).join("/");
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+/** The `@/*` form of an import. */
+function aliasSpecifier(resolvedPath) {
+    return `@/${(sourceSegments(resolvedPath) ?? []).join("/")}`;
+}
+/** Segments in a specifier: one per `../` step and one per name, ignoring a leading `./`. */
+function segmentCount(specifier) {
+    return specifier
+        .replace(/^@\//, "")
+        .split("/")
+        .filter((segment) => segment !== "." && segment !== "").length;
+}
+function describeSegments(count) {
+    return `${String(count)} segment${count === 1 ? "" : "s"}`;
+}
+/**
+ * Whether the relative form is the one to use. Shorter wins, and a tie goes to
+ * the relative form. Because crossing a layer always costs at least one `../`
+ * while the alias spells the same tail, the alias always wins for a
+ * cross-layer import without this needing to know what a layer is.
+ */
+function prefersRelative(filename, resolvedPath) {
+    return segmentCount(relativeSpecifier(filename, resolvedPath)) <= segmentCount(aliasSpecifier(resolvedPath));
 }
 export const importBoundariesRule = {
     meta: {
@@ -60,18 +81,6 @@ export const importBoundariesRule = {
             if (!importer || !imported || importer.length === 0 || imported.length === 0) {
                 return;
             }
-            if (isNearbyImport(filename, resolvedPath) && importPath.startsWith("@/")) {
-                context.report({
-                    node: source,
-                    message: "Use a relative path for imports in the same folder, a descendant, or one folder up.",
-                });
-            }
-            if (!isNearbyImport(filename, resolvedPath) && importPath.startsWith(".")) {
-                context.report({
-                    node: source,
-                    message: "Use the @/* alias for imports beyond one folder up.",
-                });
-            }
             const [importerLayer = "", importerFeature] = importer;
             const [importedLayer = "", importedFeature] = imported;
             const extension = path.extname(importPath);
@@ -107,6 +116,30 @@ export const importBoundariesRule = {
                     node: source,
                     message: "This import violates the src layer boundary.",
                 });
+                // The fix is to move the file, so how the specifier is spelled does not matter yet.
+                return;
+            }
+            const relativeForm = relativeSpecifier(filename, resolvedPath);
+            const aliasForm = aliasSpecifier(resolvedPath);
+            const relativeSegments = segmentCount(relativeForm);
+            const aliasSegments = segmentCount(aliasForm);
+            function describeChoice(preferred, preferredSegments, other, otherSegments) {
+                const tie = preferredSegments === otherSegments ? ", and a tie goes to the relative path" : "";
+                return (`Use "${preferred}" (${describeSegments(preferredSegments)}) ` +
+                    `instead of "${other}" (${describeSegments(otherSegments)})${tie}.`);
+            }
+            if (prefersRelative(filename, resolvedPath) && importPath.startsWith("@/")) {
+                context.report({
+                    node: source,
+                    message: describeChoice(relativeForm, relativeSegments, aliasForm, aliasSegments),
+                });
+                return;
+            }
+            if (!prefersRelative(filename, resolvedPath) && importPath.startsWith(".")) {
+                context.report({
+                    node: source,
+                    message: describeChoice(aliasForm, aliasSegments, relativeForm, relativeSegments),
+                });
             }
         }
         return {