@shivaedev/quality 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.6.0 - 2026-10-04
+
+### Added
+
+- Add `imports/aliased`. A relative import may name only a file in its own folder; one that goes up (`../format.ts`) or down into a subfolder (`./parts/deeper.ts`) is reported, in static imports, re-exports, side-effect imports, `import()`, `require()`, `import()` types, JSDoc `@import` tags and the paths of `vi.mock` and its kin. The message names the fix for where the import lands: a `#` alias from the `imports` of its own package's `package.json`, declared if none fits; the name of another workspace package, through a path its `exports` lists; or the name of an installed package. The rule only reports: the author picks the alias. Like every rule it is an error by default, so a repository that upgrades adopts it into its baseline.
+
+### Changed
+
+- The Biome preset organizes imports in five groups: Node and Bun builtins, packages, `@shivaedev/*` packages, aliases (`#…`, `@/…`, `~…`) and relative paths. `quality fix` regroups the imports of every file once; until then each file out of order is a `biome/assist/source/organizeImports` finding.
+
 ## 0.5.1 - 2026-10-04
 
 ### Changed

package/README.md

@@ -197,13 +197,14 @@ A weakening the preset makes without such a declaration is reported at the line
 
 ### Imports
 
-Three rules read the import graph of the TypeScript and JavaScript modules among the sources. They build it once per run with the TypeScript compiler, without a bundler or another dependency.
+Four rules read the imports of the TypeScript and JavaScript modules among the sources. They build it once per run with the TypeScript compiler, without a bundler or another dependency.
 
 | Rule | Reports | Options |
 | --- | --- | --- |
 | `imports/cycles` | Modules that import each other at run time | none |
 | `imports/resolvable` | An import that resolves to nothing | `generated` |
 | `imports/fences` | An import that crosses a fence the config declares | `fences` |
+| `imports/aliased` | A relative import that leaves its own folder | none |
 
 Each import resolves the way the compiler resolves it, with the options of the nearest `tsconfig.json` and the projects it references, under bundler resolution: `paths`, `package.json` `imports` and `exports` and the `source` condition hold, so a workspace package resolves to its source. The graph reads static and dynamic imports, `export ... from`, `require()`, `require.resolve()`, `import.meta.resolve()` of a bare specifier (a relative one is URL arithmetic that never checks the path), `import()` types, `/// <reference types>`, `/// <reference path>` and JSDoc `@import` tags.
 
@@ -221,6 +222,23 @@ Each import resolves the way the compiler resolves it, with the options of the n
 
 The gate fails closed: when the sources hold no module at all, the imports rules stop the run instead of passing on an empty graph. Point `sources` at the code, or turn the rules off.
 
+#### Aliases
+
+A relative import names only a file in its own folder, such as `./format.ts`: the folder is one module. Every other import goes through an alias, so moving a file never rewrites a chain of `../`:
+
+- the `imports` of the importer's nearest `package.json`, such as `"#lib/*": "./src/lib/*"`, or `"#shared/*": "@demo/shared/*"`, which names another workspace package;
+- the name of another workspace package, as far as its `exports` reach.
+
+An import that already goes through a tsconfig `paths` alias is not relative, so the rule leaves it alone.
+
+`imports/aliased` reports a relative import that goes up (`../format.ts`) or down into a subfolder (`./parts/deeper.ts`, or `./widgets` for `widgets/index.ts`). It reads static imports, `export ... from`, side-effect imports, `import()`, `require()`, `import()` types, JSDoc `@import` tags and the paths of `vi.mock`, `vi.doMock`, `vi.unmock`, `vi.doUnmock`, `vi.importActual` and `vi.importMock`, so a mock keeps pointing at the module it replaces. An escaped path, such as `"\x2e\x2e/format.ts"`, counts as the path it spells. Each finding has the import as its subject. Its message names the fix for where the import lands:
+
+- inside its own package: import through a `#` alias from the `imports` of the package's `package.json`, and declare one if none fits;
+- inside another workspace package: import it by that package's name, through a path its `exports` lists;
+- inside an installed package under `node_modules`: import that package by its name.
+
+The rule only reports; nothing rewrites the import. Whoever writes the import picks the alias, because only they know which conditions their runtimes, bundler and tests use.
+
 #### Fences
 
 A fence is one prohibition, stated in the config without patterns:
@@ -389,6 +407,7 @@ The preset sets:
 
 - **Formatting:** tabs, a line width of 150, double quotes, semicolons, trailing commas and operators at the start of a wrapped line.
 - **Lint:** every rule Biome recommends, at `error`, and a list of stricter rules on top, among them `noUnsafeTypeAssertion`, `useBlockStatements`, `noEqualsToNull`, `useNumericSeparators`, `useUnicodeRegex`, `useLiteralKeys`, `readonly T[]` arrays, `noFloatingPromises`, `noMisusedPromises`, `useExhaustiveSwitchCases`, `useExhaustiveDependencies`, `it` for every test, function declarations over function expressions, interfaces for object types, a cognitive complexity limit of 15, no nested ternaries, no barrel files and no `export *`.
+- **Imports:** organized in five groups: Node and Bun builtins, packages, `@shivaedev/*` packages, aliases and relative paths. Biome counts as an alias a specifier that starts with `#`, `@/`, `~`, `$` or `%`; a tsconfig path such as `@app/*` sorts with the packages, and Biome's `noUndeclaredDependencies` takes it for one, so name aliases in a form Biome recognizes.
 - **Assist:** organized imports and sorted keys, attributes, enum members, interface members and properties. Keys are sorted in JSON and in object literals alike; `package.json` is left out, because `manifests/sorted` gives it the order npm users expect.
 - **Plugins:** GritQL rules that ban ambient time, randomness, `console` and `process.env` for Effect's services, and that ask `Effect.fn` for a literal span name shaped `Owner.operation`. They load from `./node_modules/@shivaedev/quality/biome/plugins`, so the package must be installed at the repository root.
 - Files ignored by git are skipped.

package/biome/preset.json

@@ -3,7 +3,18 @@
 		"actions": {
 			"source": {
 				"noDuplicateClasses": "on",
-				"organizeImports": "on",
+				"organizeImports": {
+					"level": "on",
+					"options": {
+						"groups": [
+							[":NODE:", ":BUN:"],
+							[":PACKAGE:", ":PACKAGE_WITH_PROTOCOL:", ":URL:", "!@shivaedev/**"],
+							["@shivaedev/**"],
+							[":ALIAS:"],
+							[":PATH:"]
+						]
+					}
+				},
 				"useSortedAttributes": "on",
 				"useSortedEnumMembers": "on",
 				"useSortedInterfaceMembers": "on",

package/dist/imports/departures.d.ts

@@ -0,0 +1,9 @@
+import type { RuleInputs } from "../rule.ts";
+import { type SpecifierSite } from "./specifiers.ts";
+export interface Departure extends SpecifierSite {
+    readonly file: string;
+    readonly installed: string | undefined;
+    readonly workspace: string | undefined;
+}
+export declare function departures(inputs: RuleInputs): Promise<readonly Departure[]>;
+//# sourceMappingURL=departures.d.ts.map

package/dist/imports/departures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"departures.d.ts","sourceRoot":"","sources":["../../src/imports/departures.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,iBAAiB,CAAC;AAGrE,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AA4CD,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAalF"}

package/dist/imports/departures.js

@@ -0,0 +1,49 @@
+import { realpathSync } from "node:fs";
+import { posix } from "node:path";
+import { parse } from "../rules/syntax.js";
+import { projectsFor } from "./projects.js";
+import { resolveImport } from "./resolve.js";
+import { specifierSites } from "./specifiers.js";
+import { packageOf, workspacePackages } from "./workspace.js";
+const QUERY = /\?.*$/u;
+const RELATIVE = /^\.\.?(?:\/|$)/u;
+const MAY_BE_RELATIVE = /["'`]\.\.?[/"'`]|\\/u;
+const TRAILING_SLASHES = /\/+$/u;
+function noAmbient() {
+    return false;
+}
+function leavesLexically(path) {
+    const normal = posix.normalize(path).replace(TRAILING_SLASHES, "");
+    return normal === ".." || normal.startsWith("../") || normal.includes("/");
+}
+// A relative import leaves its folder when its path climbs or descends, or when it names a folder whose index file lies below.
+function departureAt(context, site) {
+    const path = site.specifier.replace(QUERY, "");
+    if (!RELATIVE.test(path)) {
+        return undefined;
+    }
+    const request = { kind: "import", line: site.line, specifier: site.specifier, type: site.type };
+    const target = resolveImport(context.root, noAmbient, request, context.from, context.project);
+    const local = target?.kind === "file" ? target.path : undefined;
+    if (!(leavesLexically(path) || (local !== undefined && posix.dirname(local) !== posix.dirname(context.path)))) {
+        return undefined;
+    }
+    const owner = local === undefined ? undefined : packageOf(context.packages, local);
+    const workspace = owner !== undefined && owner !== packageOf(context.packages, context.path) ? owner.name : undefined;
+    return { ...site, file: context.path, installed: target?.kind === "external" ? target.package : undefined, workspace };
+}
+export async function departures(inputs) {
+    const root = realpathSync(inputs.root);
+    const projectOf = projectsFor(root);
+    const packages = await workspacePackages(inputs);
+    return inputs.sources.flatMap((file) => {
+        const syntax = MAY_BE_RELATIVE.test(file.text) ? parse(file) : undefined;
+        if (syntax === undefined) {
+            return [];
+        }
+        const from = posix.join(root, file.path);
+        const context = { from, packages, path: file.path, project: projectOf(from), root };
+        return specifierSites(syntax).flatMap((site) => departureAt(context, site) ?? []);
+    });
+}
+//# sourceMappingURL=departures.js.map

package/dist/imports/departures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"departures.js","sourceRoot":"","sources":["../../src/imports/departures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,OAAO,EAAgB,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAsB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,SAAS,EAAyB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAQrF,MAAM,KAAK,GAAG,QAAQ,CAAC;AAEvB,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AAEnC,MAAM,eAAe,GAAG,sBAAsB,CAAC;AAE/C,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAEjC,SAAS,SAAS;IACjB,OAAO,KAAK,CAAC;AACd,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACpC,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IACnE,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC5E,CAAC;AAUD,+HAA+H;AAC/H,SAAS,WAAW,CAAC,OAAoB,EAAE,IAAmB;IAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,OAAO,GAAkB,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/G,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9F,MAAM,KAAK,GAAG,MAAM,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,IAAI,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/G,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACnF,MAAM,SAAS,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACtH,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;AACxH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAkB;IAClD,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACzE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAC;QACX,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;QACpF,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/imports/specifiers.d.ts

@@ -0,0 +1,9 @@
+import ts from "typescript";
+export interface SpecifierSite {
+    readonly line: number;
+    readonly specifier: string;
+    readonly start: number;
+    readonly type: boolean;
+}
+export declare function specifierSites(source: ts.SourceFile): readonly SpecifierSite[];
+//# sourceMappingURL=specifiers.d.ts.map

package/dist/imports/specifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specifiers.d.ts","sourceRoot":"","sources":["../../src/imports/specifiers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACvB;AAwED,wBAAgB,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,aAAa,EAAE,CAc9E"}

package/dist/imports/specifiers.js

@@ -0,0 +1,71 @@
+import ts from "typescript";
+const MOCKS = new Set(["doMock", "doUnmock", "importActual", "importMock", "mock", "unmock"]);
+const MAY_CALL = /\b(?:import|require)\s*\(|\bvi\s*\.\s*(?:doMock|doUnmock|importActual|importMock|mock|unmock)\b/u;
+function declared(node) {
+    if (ts.isImportDeclaration(node)) {
+        return { node: node.moduleSpecifier, type: node.importClause?.isTypeOnly === true };
+    }
+    if (ts.isExportDeclaration(node)) {
+        return { node: node.moduleSpecifier, type: node.isTypeOnly };
+    }
+    if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+        return { node: node.moduleReference.expression, type: node.isTypeOnly };
+    }
+    return undefined;
+}
+function isMock(callee) {
+    return (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "vi" && MOCKS.has(callee.name.text));
+}
+function called(node) {
+    if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+        return { node: node.argument.literal, type: true };
+    }
+    if (!ts.isCallExpression(node)) {
+        return undefined;
+    }
+    const callee = node.expression;
+    const loads = callee.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(callee) && callee.text === "require") || isMock(callee);
+    return loads ? { node: node.arguments[0], type: false } : undefined;
+}
+function siteOf(source, found) {
+    const literal = found?.node;
+    if (found === undefined || literal === undefined || !ts.isStringLiteralLike(literal)) {
+        return [];
+    }
+    const start = literal.getStart(source);
+    return [{ line: source.getLineAndCharacterOfPosition(start).line + 1, specifier: literal.text, start, type: found.type }];
+}
+const JSDOC_IMPORT = /^[ \t]*(?:\/\*\*|\*)?[ \t]*@import\b[^"'`]*?\bfrom\s*(?<quote>["'])(?<path>[^"'\r\n]*)\k<quote>/gmu;
+function siteAt(source, start, specifier) {
+    return { line: source.getLineAndCharacterOfPosition(start).line + 1, specifier, start, type: true };
+}
+// A node keeps only its last JSDoc block, so @import tags are read from every comment before it.
+function jsDocImports(source, node, seen) {
+    return (ts.getLeadingCommentRanges(source.text, node.pos) ?? []).flatMap((range) => {
+        const comment = source.text.slice(range.pos, range.end);
+        if (seen.has(range.pos) || !comment.startsWith("/**")) {
+            return [];
+        }
+        seen.add(range.pos);
+        return [...comment.matchAll(JSDOC_IMPORT)].map((match) => {
+            const path = match.groups?.path ?? "";
+            return siteAt(source, range.pos + match.index + match[0].length - path.length - 1, path);
+        });
+    });
+}
+export function specifierSites(source) {
+    const sites = [];
+    const nested = MAY_CALL.test(source.text);
+    const documented = source.text.includes("@import");
+    const comments = new Set();
+    function visit(node) {
+        sites.push(...siteOf(source, declared(node) ?? (nested ? called(node) : undefined)));
+        if (documented) {
+            sites.push(...jsDocImports(source, node, comments));
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return [...new Map(sites.map((site) => [site.start, site])).values()].sort((left, right) => left.start - right.start);
+}
+//# sourceMappingURL=specifiers.js.map

package/dist/imports/specifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specifiers.js","sourceRoot":"","sources":["../../src/imports/specifiers.ts"],"names":[],"mappings":"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"}

package/dist/rules/built-in.d.ts

@@ -17,5 +17,5 @@ export declare const builtInRules: readonly [import("../rule.ts").Rule<"structur
     readonly fences?: readonly import("../index.ts").Fence[];
 }>, import("../rule.ts").Rule<"imports/resolvable", {
     readonly generated?: readonly string[];
-}>, import("../rule.ts").Rule<"manifests/sorted", undefined>];
+}>, import("../rule.ts").Rule<"imports/aliased", undefined>, import("../rule.ts").Rule<"manifests/sorted", undefined>];
 //# sourceMappingURL=built-in.d.ts.map

package/dist/rules/built-in.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"built-in.d.ts","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;6DAiBf,CAAC"}
+{"version":3,"file":"built-in.d.ts","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;sHAkBf,CAAC"}

package/dist/rules/built-in.js

@@ -6,6 +6,7 @@ import { noJsdoc } from "./comments/no-jsdoc.js";
 import { noLineReference } from "./comments/no-line-reference.js";
 import { noPrReference } from "./comments/no-pr-reference.js";
 import { noTodo } from "./comments/no-todo.js";
+import { importsAliased } from "./imports/aliased.js";
 import { importCycles } from "./imports/cycles.js";
 import { importFences } from "./imports/fences.js";
 import { importsResolvable } from "./imports/resolvable.js";
@@ -30,6 +31,7 @@ export const builtInRules = [
     importCycles,
     importFences,
     importsResolvable,
+    importsAliased,
     manifestsSorted,
 ];
 //# sourceMappingURL=built-in.js.map

package/dist/rules/built-in.js.map

@@ -1 +1 @@
-{"version":3,"file":"built-in.js","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAEvD,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,QAAQ;IACR,OAAO;IACP,eAAe;IACf,aAAa;IACb,QAAQ;IACR,MAAM;IACN,mBAAmB;IACnB,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,cAAc;IACd,KAAK;IACL,YAAY;IACZ,YAAY;IACZ,iBAAiB;IACjB,eAAe;CACN,CAAC"}
+{"version":3,"file":"built-in.js","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAEvD,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,QAAQ;IACR,OAAO;IACP,eAAe;IACf,aAAa;IACb,QAAQ;IACR,MAAM;IACN,mBAAmB;IACnB,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,cAAc;IACd,KAAK;IACL,YAAY;IACZ,YAAY;IACZ,iBAAiB;IACjB,cAAc;IACd,eAAe;CACN,CAAC"}

package/dist/rules/imports/aliased.d.ts

@@ -0,0 +1,2 @@
+export declare const importsAliased: import("../../rule.ts").Rule<"imports/aliased", undefined>;
+//# sourceMappingURL=aliased.d.ts.map

package/dist/rules/imports/aliased.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliased.d.ts","sourceRoot":"","sources":["../../../src/rules/imports/aliased.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,cAAc,4DAWzB,CAAC"}

package/dist/rules/imports/aliased.js

@@ -0,0 +1,23 @@
+import { departures } from "../../imports/departures.js";
+import { defineRule } from "../../rule.js";
+function messageOf({ installed, specifier, workspace }) {
+    const leaves = `"${specifier}" leaves its folder.`;
+    if (installed !== undefined) {
+        return `${leaves} It reaches into the installed package ${installed}; import that package by its name.`;
+    }
+    if (workspace !== undefined) {
+        return `${leaves} It reaches into the workspace package ${workspace}; import it by that name, through a path its package.json "exports" lists.`;
+    }
+    return `${leaves} Import it through a "#…" alias from the "imports" of its package.json, and declare one there if none fits.`;
+}
+export const importsAliased = defineRule({
+    check: async (inputs) => (await departures(inputs)).map((departure) => ({
+        file: departure.file,
+        line: departure.line,
+        message: messageOf(departure),
+        subject: departure.specifier,
+    })),
+    description: "A relative import names only a file in its own folder. Every other import goes through an alias: the package.json `imports` of its package or another workspace package's name.",
+    id: "imports/aliased",
+});
+//# sourceMappingURL=aliased.js.map

package/dist/rules/imports/aliased.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliased.js","sourceRoot":"","sources":["../../../src/rules/imports/aliased.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,SAAS,SAAS,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAa;IAChE,MAAM,MAAM,GAAG,IAAI,SAAS,sBAAsB,CAAC;IACnD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,GAAG,MAAM,0CAA0C,SAAS,oCAAoC,CAAC;IACzG,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,GAAG,MAAM,0CAA0C,SAAS,4EAA4E,CAAC;IACjJ,CAAC;IACD,OAAO,GAAG,MAAM,6GAA6G,CAAC;AAC/H,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;IACxC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CACvB,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC9C,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC;QAC7B,OAAO,EAAE,SAAS,CAAC,SAAS;KAC5B,CAAC,CAAC;IACJ,WAAW,EACV,iLAAiL;IAClL,EAAE,EAAE,iBAAiB;CACrB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/quality",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Repository quality gate with typed rules, a shrink-only baseline and a registry of reasoned exceptions",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/quality#readme",
   "bugs": {

package/src/imports/departures.ts

@@ -0,0 +1,72 @@
+import { realpathSync } from "node:fs";
+import { posix } from "node:path";
+import type { RuleInputs } from "../rule.ts";
+import { parse } from "../rules/syntax.ts";
+import type { ImportRequest } from "./extract.ts";
+import { type Project, projectsFor } from "./projects.ts";
+import { resolveImport } from "./resolve.ts";
+import { type SpecifierSite, specifierSites } from "./specifiers.ts";
+import { packageOf, type WorkspacePackage, workspacePackages } from "./workspace.ts";
+
+export interface Departure extends SpecifierSite {
+	readonly file: string;
+	readonly installed: string | undefined;
+	readonly workspace: string | undefined;
+}
+
+const QUERY = /\?.*$/u;
+
+const RELATIVE = /^\.\.?(?:\/|$)/u;
+
+const MAY_BE_RELATIVE = /["'`]\.\.?[/"'`]|\\/u;
+
+const TRAILING_SLASHES = /\/+$/u;
+
+function noAmbient(): boolean {
+	return false;
+}
+
+function leavesLexically(path: string): boolean {
+	const normal = posix.normalize(path).replace(TRAILING_SLASHES, "");
+	return normal === ".." || normal.startsWith("../") || normal.includes("/");
+}
+
+interface FileContext {
+	readonly from: string;
+	readonly packages: readonly WorkspacePackage[];
+	readonly path: string;
+	readonly project: Project;
+	readonly root: string;
+}
+
+// A relative import leaves its folder when its path climbs or descends, or when it names a folder whose index file lies below.
+function departureAt(context: FileContext, site: SpecifierSite): Departure | undefined {
+	const path = site.specifier.replace(QUERY, "");
+	if (!RELATIVE.test(path)) {
+		return undefined;
+	}
+	const request: ImportRequest = { kind: "import", line: site.line, specifier: site.specifier, type: site.type };
+	const target = resolveImport(context.root, noAmbient, request, context.from, context.project);
+	const local = target?.kind === "file" ? target.path : undefined;
+	if (!(leavesLexically(path) || (local !== undefined && posix.dirname(local) !== posix.dirname(context.path)))) {
+		return undefined;
+	}
+	const owner = local === undefined ? undefined : packageOf(context.packages, local);
+	const workspace = owner !== undefined && owner !== packageOf(context.packages, context.path) ? owner.name : undefined;
+	return { ...site, file: context.path, installed: target?.kind === "external" ? target.package : undefined, workspace };
+}
+
+export async function departures(inputs: RuleInputs): Promise<readonly Departure[]> {
+	const root = realpathSync(inputs.root);
+	const projectOf = projectsFor(root);
+	const packages = await workspacePackages(inputs);
+	return inputs.sources.flatMap((file) => {
+		const syntax = MAY_BE_RELATIVE.test(file.text) ? parse(file) : undefined;
+		if (syntax === undefined) {
+			return [];
+		}
+		const from = posix.join(root, file.path);
+		const context = { from, packages, path: file.path, project: projectOf(from), root };
+		return specifierSites(syntax).flatMap((site) => departureAt(context, site) ?? []);
+	});
+}

package/src/imports/specifiers.ts

@@ -0,0 +1,94 @@
+import ts from "typescript";
+
+export interface SpecifierSite {
+	readonly line: number;
+	readonly specifier: string;
+	readonly start: number;
+	readonly type: boolean;
+}
+
+interface Found {
+	readonly node: ts.Node | undefined;
+	readonly type: boolean;
+}
+
+const MOCKS = new Set(["doMock", "doUnmock", "importActual", "importMock", "mock", "unmock"]);
+
+const MAY_CALL = /\b(?:import|require)\s*\(|\bvi\s*\.\s*(?:doMock|doUnmock|importActual|importMock|mock|unmock)\b/u;
+
+function declared(node: ts.Node): Found | undefined {
+	if (ts.isImportDeclaration(node)) {
+		return { node: node.moduleSpecifier, type: node.importClause?.isTypeOnly === true };
+	}
+	if (ts.isExportDeclaration(node)) {
+		return { node: node.moduleSpecifier, type: node.isTypeOnly };
+	}
+	if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+		return { node: node.moduleReference.expression, type: node.isTypeOnly };
+	}
+	return undefined;
+}
+
+function isMock(callee: ts.Expression): boolean {
+	return (
+		ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "vi" && MOCKS.has(callee.name.text)
+	);
+}
+
+function called(node: ts.Node): Found | undefined {
+	if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+		return { node: node.argument.literal, type: true };
+	}
+	if (!ts.isCallExpression(node)) {
+		return undefined;
+	}
+	const callee = node.expression;
+	const loads = callee.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(callee) && callee.text === "require") || isMock(callee);
+	return loads ? { node: node.arguments[0], type: false } : undefined;
+}
+
+function siteOf(source: ts.SourceFile, found: Found | undefined): readonly SpecifierSite[] {
+	const literal = found?.node;
+	if (found === undefined || literal === undefined || !ts.isStringLiteralLike(literal)) {
+		return [];
+	}
+	const start = literal.getStart(source);
+	return [{ line: source.getLineAndCharacterOfPosition(start).line + 1, specifier: literal.text, start, type: found.type }];
+}
+
+const JSDOC_IMPORT = /^[ \t]*(?:\/\*\*|\*)?[ \t]*@import\b[^"'`]*?\bfrom\s*(?<quote>["'])(?<path>[^"'\r\n]*)\k<quote>/gmu;
+
+function siteAt(source: ts.SourceFile, start: number, specifier: string): SpecifierSite {
+	return { line: source.getLineAndCharacterOfPosition(start).line + 1, specifier, start, type: true };
+}
+
+// A node keeps only its last JSDoc block, so @import tags are read from every comment before it.
+function jsDocImports(source: ts.SourceFile, node: ts.Node, seen: Set<number>): readonly SpecifierSite[] {
+	return (ts.getLeadingCommentRanges(source.text, node.pos) ?? []).flatMap((range) => {
+		const comment = source.text.slice(range.pos, range.end);
+		if (seen.has(range.pos) || !comment.startsWith("/**")) {
+			return [];
+		}
+		seen.add(range.pos);
+		return [...comment.matchAll(JSDOC_IMPORT)].map((match) => {
+			const path = match.groups?.path ?? "";
+			return siteAt(source, range.pos + match.index + match[0].length - path.length - 1, path);
+		});
+	});
+}
+
+export function specifierSites(source: ts.SourceFile): readonly SpecifierSite[] {
+	const sites: SpecifierSite[] = [];
+	const nested = MAY_CALL.test(source.text);
+	const documented = source.text.includes("@import");
+	const comments = new Set<number>();
+	function visit(node: ts.Node): void {
+		sites.push(...siteOf(source, declared(node) ?? (nested ? called(node) : undefined)));
+		if (documented) {
+			sites.push(...jsDocImports(source, node, comments));
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(source);
+	return [...new Map(sites.map((site) => [site.start, site])).values()].sort((left, right) => left.start - right.start);
+}

package/src/rules/built-in.ts

@@ -6,6 +6,7 @@ import { noJsdoc } from "./comments/no-jsdoc.ts";
 import { noLineReference } from "./comments/no-line-reference.ts";
 import { noPrReference } from "./comments/no-pr-reference.ts";
 import { noTodo } from "./comments/no-todo.ts";
+import { importsAliased } from "./imports/aliased.ts";
 import { importCycles } from "./imports/cycles.ts";
 import { importFences } from "./imports/fences.ts";
 import { importsResolvable } from "./imports/resolvable.ts";
@@ -31,5 +32,6 @@ export const builtInRules = [
 	importCycles,
 	importFences,
 	importsResolvable,
+	importsAliased,
 	manifestsSorted,
 ] as const;

package/src/rules/imports/aliased.ts

@@ -0,0 +1,26 @@
+import { type Departure, departures } from "../../imports/departures.ts";
+import { defineRule } from "../../rule.ts";
+
+function messageOf({ installed, specifier, workspace }: Departure): string {
+	const leaves = `"${specifier}" leaves its folder.`;
+	if (installed !== undefined) {
+		return `${leaves} It reaches into the installed package ${installed}; import that package by its name.`;
+	}
+	if (workspace !== undefined) {
+		return `${leaves} It reaches into the workspace package ${workspace}; import it by that name, through a path its package.json "exports" lists.`;
+	}
+	return `${leaves} Import it through a "#…" alias from the "imports" of its package.json, and declare one there if none fits.`;
+}
+
+export const importsAliased = defineRule({
+	check: async (inputs) =>
+		(await departures(inputs)).map((departure) => ({
+			file: departure.file,
+			line: departure.line,
+			message: messageOf(departure),
+			subject: departure.specifier,
+		})),
+	description:
+		"A relative import names only a file in its own folder. Every other import goes through an alias: the package.json `imports` of its package or another workspace package's name.",
+	id: "imports/aliased",
+});