@crutchcrew/oxlint-plugin-import-access 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 uhyo
+Copyright (c) 2026 crutchcrew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# oxlint-plugin-import-access 📦🔒
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@crutchcrew/oxlint-plugin-import-access)](https://www.npmjs.com/package/@crutchcrew/oxlint-plugin-import-access)
+[![coverage](https://img.shields.io/endpoint?url=https://crutchcrew.github.io/oxlint-plugin-import-access/badges/coverage.json)](https://github.com/crutchcrew/oxlint-plugin-import-access/actions)
+[![provenance](https://img.shields.io/badge/provenance-verified-brightgreen)](https://www.npmjs.com/package/@crutchcrew/oxlint-plugin-import-access)
+[![license](https://img.shields.io/npm/l/@crutchcrew/oxlint-plugin-import-access)](./LICENSE)
+
+JSDoc import access for TypeScript, enforced by [oxlint](https://oxc.rs/docs/guide/usage/linter). Only `@public` exports can be imported from anywhere, and an export without an access tag is `@package`: only files in its own directory can import it. Tag an export `@public` to share it with the whole project, or `@private` so no other file can import it. To make untagged exports `@public` or `@private` instead, set [`defaultImportability`](#options).
+
+A native oxlint JS plugin port of [eslint-plugin-import-access](https://github.com/uhyo/eslint-plugin-import-access) that needs **no type checker**: no `typescript` dependency, no `tsconfig.json` project loading, no typed linting setup.
+
+## Access tags
+
+![sub/foo.ts exports api tagged @public, helper without a tag and secret tagged @private. sub/bar.ts, in the same package, can import api and helper but not secret. src/main.ts, outside the package, can import only api.](./docs/images/access.svg)
+
+Each export's JSDoc access tag decides which files can import it. A package is a directory with its subdirectories, and by default every directory is one (see [`packageDirectory`](./docs/rule-jsdoc.md#packagedirectory)). In the picture, `sub/foo.ts` has three exports:
+
+- `api` is **`@public`**: any file can import it, `sub/bar.ts` as well as `src/main.ts`.
+- `helper` has **no tag**, so it is `@package`: files in `sub/` and its subdirectories can import it, so `sub/bar.ts` can and `src/main.ts` can't.
+- `secret` is **`@private`**: no file can import it, not even `sub/bar.ts` next to it.
+
+Imports from Node.js builtins and from anything in `node_modules` are never checked.
+
+## Why?
+
+The largest encapsulation unit TypeScript gives you is a file. Once something is exported, the whole project can import it. Keeping things private means keeping them in one file, and files grow large.
+
+This plugin adds a directory-level layer between a file and the whole project: an export stays inside its directory (`@package`) until you tag it `@public`. Tag what the rest of the project may use `@public`, and what no other file may use `@private`.
+
+## Why this package
+
+|                                        | This package | [eslint-plugin-import-access](https://github.com/uhyo/eslint-plugin-import-access) | [oxlint-plugin-import-access](https://github.com/bitkey-oss/oxlint-plugin-import-access) |
+| -------------------------------------- | ------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Linter**                             | oxlint       | ESLint                                                                             | oxlint                                                                                   |
+| **Needs type information**             | ❌           | ✅ typed linting                                                                   | ✅ TypeScript 7 unstable API                                                             |
+| **`typescript` dependency**            | ❌           | ✅                                                                                 | ✅ `^7`                                                                                  |
+| **Works without `tsconfig.json`**      | ✅           | ❌                                                                                 | ❌                                                                                       |
+| **Checks unsaved edits in the editor** | ✅           | ✅                                                                                 | ❌ skipped until saved                                                                   |
+| **Same results as the original rule**  | ✅ verified¹ | –                                                                                  | ✅                                                                                       |
+
+¹ With `defaultImportability: "public"`, which makes exports without an access tag `@public` like in the original. This plugin's default is `"package"`.
+
+## Install
+
+Choose your fighter 🥊
+
+```sh
+pnpm add -D oxlint @crutchcrew/oxlint-plugin-import-access
+```
+
+```sh
+bun add -D oxlint @crutchcrew/oxlint-plugin-import-access
+```
+
+```sh
+yarn add -D oxlint @crutchcrew/oxlint-plugin-import-access
+```
+
+```sh
+npm add -D oxlint @crutchcrew/oxlint-plugin-import-access
+```
+
+Requires Node.js `^20.19.0 || >=22.12.0` (the same as oxlint) and oxlint `>=1.40.0`.
+
+## Configure
+
+In **`.oxlintrc.json`**:
+
+```json
+{
+	"jsPlugins": ["@crutchcrew/oxlint-plugin-import-access"],
+	"rules": {
+		"import-access/jsdoc": "error"
+	}
+}
+```
+
+Or in **`oxlint.config.ts`**:
+
+```ts
+import { defineConfig } from "oxlint"
+
+export default defineConfig({
+	jsPlugins: ["@crutchcrew/oxlint-plugin-import-access"],
+	rules: {
+		// Untagged exports are @package; tag an export @public to import it from anywhere
+		"import-access/jsdoc": "error",
+	},
+})
+```
+
+That's all: there is no parser or project to configure. Diagnostics also show up in your editor through the [oxc extension](https://oxc.rs/docs/guide/usage/linter/editors) (oxlint's language server).
+
+## Options
+
+| Option                  | Default      | Description                                                                                |
+| ----------------------- | ------------ | ------------------------------------------------------------------------------------------ |
+| `indexLoophole`         | `true`       | `sub/index.ts` counts as `sub.ts`, so its package-private exports are visible one level up |
+| `filenameLoophole`      | `false`      | `foo.ts` may import package-private exports from `foo/`                                    |
+| `defaultImportability`  | `"package"`  | Access of exports without a tag: `"package"` (`@package`), `"public"` or `"private"`       |
+| `treatSelfReferenceAs`  | `"external"` | Whether imports through your own package name are checked (`"internal"`) or not            |
+| `excludeSourcePatterns` | `[]`         | Globs (relative to the working directory) of exporter files to skip, e.g. generated code   |
+| `packageDirectory`      | every dir    | Globs of directories that are package boundaries, e.g. `["**", "!**/_internal"]`           |
+
+All options and access tags (`@public`, `@package`, `@private`, `@access <level>`) behave as in the original plugin, except that `defaultImportability` defaults to `"package"` instead of `"public"`. See the **[rule documentation](./docs/rule-jsdoc.md)** for details and examples.
+
+## How it works
+
+The original rule asks the TypeScript type checker which declaration an import refers to. This plugin answers the same question from syntax alone:
+
+1. resolve the import like TypeScript (`tsconfig` `paths`, `package.json` `exports`, `.js` → `.ts`) with [oxc-resolver](https://github.com/oxc-project/oxc-resolver),
+2. skip builtins and anything reached through `node_modules`,
+3. read the target file's exports and JSDoc with [oxc-parser](https://github.com/oxc-project/oxc/tree/main/napi/parser) — module record and comments only, no syntax tree — and cache them,
+4. follow `export *`, stop at direct re-exports like upstream, and read JSDoc with TypeScript's attachment and tag rules,
+5. check ambient `declare module "…"` and wildcard `declare module "*.svg"` declarations too.
+
+**Verified against the original:** the upstream test suite passes unchanged (same lines, columns, messages), and a differential test compares this plugin with upstream's TypeScript-based rule on every fixture file and option combination, including new fixtures for re-export chains, overloads, enums, `export =`, wildcard modules and JSDoc placement. The [known differences](./docs/rule-jsdoc.md#differences-from-upstream) are edge cases such as module augmentation across files.
+
+## Performance
+
+Generated project with nested feature directories, `export *` barrels and 6 imports per module (`bun run bench`), on an Apple M1 (8 cores, Asahi Linux), Node.js 26, oxlint 1.89:
+
+| Modules (imports) | ESLint + eslint-plugin-import-access | oxlint + this plugin | Speedup |
+| ----------------- | ------------------------------------ | -------------------- | ------- |
+| 1,000 (6,000)     | 1.90 s                               | **0.31 s**           | 6.1×    |
+| 2,500 (15,000)    | 4.89 s ¹                             | **0.55 s**           | 8.9×    |
+| 5,000 (30,000)    | fails after 524 s ²                  | **0.95 s**           | –       |
+
+ESLint 10 with typescript-eslint 8 typed linting (`projectService`), single run; oxlint best of 3. Both report identical diagnostics on every file the TypeScript-based rule can analyze. Of the 0.95 s, about 0.33 s is oxlint's own cost of running any JS plugin over 5,000 files.
+
+¹ TypeScript fails on 16 of the 2,600 files ("Maximum call stack size exceeded"), so those files went unchecked.
+² TypeScript fails on every file of this heavily cyclic project.
+
+In a long-running editor session, files are re-checked as they change: exporter files are re-validated by size and modification time, and only re-parsed when they changed.
+
+## Coming from eslint-plugin-import-access
+
+1. Install oxlint and this package, and remove `eslint-plugin-import-access` from your ESLint config.
+2. Move your rule options unchanged to `"import-access/jsdoc"` in the oxlint config. If you didn't set `defaultImportability`, set it to `"public"` to keep the original's behavior: here, untagged exports are `@package` by default.
+3. For IDE auto-import filtering you can keep using the original package's [TypeScript language service plugin](https://github.com/uhyo/eslint-plugin-import-access/blob/master/docs/ts-server.md) (it only needs TypeScript, not ESLint); this package has no language service plugin of its own.
+
+## Contributing
+
+```sh
+bun install
+bun run test          # rule and unit tests (Node.js >= 22)
+bun run build && bun run test:e2e
+bun run check         # format, lint + typecheck (oxlint, with this plugin on its own sources), lockfile
+```
+
+## Credits
+
+Based on [eslint-plugin-import-access](https://github.com/uhyo/eslint-plugin-import-access) by [uhyo](https://github.com/uhyo), whose rule design, options, documentation and test fixtures this port keeps.
+
+## License
+
+[MIT](./LICENSE)

package/dist/core/ambientModules.d.ts

@@ -0,0 +1,22 @@
+import type { ModuleExports } from "./exportTable.js";
+/**
+ * Collect `declare module "name" { … }` blocks of a declaration file that is a script
+ * (in a module file the same syntax is a module augmentation, not an ambient module).
+ */
+export declare function parseAmbientModules(fileName: string, text: string): Map<string, ModuleExports>;
+/**
+ * Index of ambient modules declared in the project's declaration files, built lazily on first use.
+ */
+export declare class AmbientModuleIndex {
+    #private;
+    /**
+     * The ambient module named exactly `specifier`. TypeScript prefers these over resolved files.
+     */
+    exact(rootDir: string, specifier: string): ModuleExports | undefined;
+    /**
+     * The wildcard ambient module (`declare module "*.svg"`) matching `specifier`;
+     * like TypeScript, the pattern with the longest prefix wins.
+     */
+    pattern(rootDir: string, specifier: string): ModuleExports | undefined;
+    clear(): void;
+}

package/dist/core/checkImportability.d.ts

@@ -0,0 +1,60 @@
+import type { PackageOptions } from "../utils/options.js";
+import { AmbientModuleIndex } from "./ambientModules.js";
+import { type ExportEntry, ExportTableCache, type ModuleExports } from "./exportTable.js";
+import { ModuleResolver } from "./resolveModule.js";
+/**
+ * A violation: the access level of the export, and its name as TypeScript reports it
+ * (`default` for default exports, `export=` for `export =`).
+ */
+export type Violation = {
+    readonly access: "package" | "private";
+    readonly identifier: string;
+};
+type FoundExport = {
+    readonly module: ModuleExports;
+    readonly name: string;
+    readonly entries: readonly ExportEntry[];
+};
+/**
+ * Shared state for checking imports: resolver, parsed modules and ambient modules.
+ * One instance lives for the whole process; its caches are keyed by file path.
+ * @public
+ */
+export declare class ImportabilityChecker {
+    #private;
+    readonly resolver: ModuleResolver;
+    readonly exportTables: ExportTableCache;
+    readonly ambientModules: AmbientModuleIndex;
+    /**
+     * Find the module entry TypeScript's `getImmediateAliasedSymbol` would return:
+     * a direct export of `name` stops the search (even when it re-exports something else),
+     * `export * from` edges are followed.
+     */
+    findExport(module: ModuleExports, name: string): FoundExport | undefined;
+    /**
+     * Module that `specifier` leads to from `importerFileName`, if the rule should check it.
+     * Mirrors TypeScript's order: exact ambient module, resolved file, wildcard ambient module.
+     */
+    targetModule(importerFileName: string, specifier: string, projectDirectory: string, assumeAllPublic: boolean): ModuleExports | undefined;
+    constructor(watching?: boolean);
+    /**
+     * Start checking `fileName`. In a long-running host, everything read for earlier files is
+     * re-validated: exporter files are stat-ed again and specifiers resolved again.
+     */
+    nextFile(fileName: string): void;
+    clear(): void;
+}
+/**
+ * Per-options part of the check: compiled globs and package boundaries.
+ * @public
+ */
+export declare class ImportabilityPolicy {
+    #private;
+    readonly options: PackageOptions;
+    constructor(options: PackageOptions);
+    /**
+     * Check importing `name` (the export name, `default` for default imports) via `specifier`.
+     */
+    check(checker: ImportabilityChecker, importerFileName: string, specifier: string, name: string): Violation | undefined;
+}
+export {};

package/dist/core/exportTable.d.ts

@@ -0,0 +1,102 @@
+import { type Comment, type Tag } from "../utils/jsdoc.js";
+/**
+ * Where the declaration of an export keeps the JSDoc that TypeScript's
+ * `symbol.getJsDocTags()` reads.
+ */
+export type OwnJsDoc = 
+/** Declarations that are statements: functions, classes, `export default …`, `export =`. */
+{
+    readonly kind: "statement";
+}
+/** `export { a }`: the specifier, including comments on the same line before it. */
+ | {
+    readonly kind: "specifier";
+    readonly start: number;
+}
+/** `export const a = 1, b = 2`: the declarator, and the statement when it is the only one. */
+ | {
+    readonly kind: "variable";
+    readonly nameStart: number;
+    readonly statementEnd: number;
+}
+/** `export * as ns from "…"`: the namespace export has no JSDoc of its own. */
+ | {
+    readonly kind: "none";
+};
+/**
+ * One export of a name by a module, in the shape the importability check needs.
+ */
+export type ExportEntry = {
+    /**
+     * `false` for exports upstream never checks (enums, namespaces, `export import x = …`):
+     * TypeScript's `findExportableDeclaration` finds no exportable statement for them.
+     */
+    readonly checked: boolean;
+    /** Start of the whole export statement. */
+    readonly statementStart: number;
+    readonly own: OwnJsDoc;
+};
+/**
+ * Exports of one module file.
+ */
+export type ModuleExports = {
+    readonly fileName: string;
+    /** `undefined` when the fast path proved every export public. */
+    readonly names: ReadonlyMap<string, readonly ExportEntry[]> | undefined;
+    /** Module requests of `export * from "…"` statements. */
+    readonly stars: readonly string[];
+    /**
+     * JSDoc tags of a name's entries, in the order upstream reads them:
+     * the own tags of every declaration, then all tags of the first declaration's statement.
+     */
+    tagsOf(entries: readonly ExportEntry[]): Tag[];
+};
+/** Name under which a module's `export = value` is stored, as TypeScript names the symbol. */
+export declare const EXPORT_EQUALS = "export=";
+export declare function skipTrivia(text: string, pos: number): number;
+type Declarator = {
+    readonly start: number;
+    readonly end: number;
+    /** Start of an initializer that carries JSDoc for the variable. */
+    readonly initializer: number | undefined;
+};
+/**
+ * What only the syntax tree can tell. Built lazily, for the few files that need it.
+ */
+type SyntaxDetails = {
+    /** Start of the first decorator of decorated `export class` statements, by statement start. */
+    readonly decoratorStarts: ReadonlyMap<number, number>;
+    /** Spans of `export { … }` statements without a source. */
+    readonly exportLists: readonly (readonly [number, number])[];
+    /** Starts of `export = value` statements. */
+    readonly exportEquals: readonly number[];
+    /** Declarators of exported variable statements, by statement start. */
+    readonly variables: ReadonlyMap<number, readonly Declarator[]>;
+};
+export declare function createModuleExports(fileName: string, text: string, comments: readonly Comment[], names: ReadonlyMap<string, readonly ExportEntry[]> | undefined, stars: readonly string[], details?: () => SyntaxDetails): ModuleExports;
+/**
+ * Build the export table of a module from its source text.
+ *
+ * Mostly oxc-parser's module record and comments are read. The syntax tree, several times
+ * slower to get, is only used for files with decorators, `export =`, re-exported imports
+ * or JSDoc inside variable statements.
+ */
+export declare function parseModuleExports(fileName: string, text: string, assumeAllPublic: boolean): ModuleExports;
+/**
+ * Process-wide cache of module export tables.
+ *
+ * Files are re-validated (stat-ed, re-parsed when changed) at most once per generation.
+ * In long-running hosts such as the oxlint language server, every linted file starts a new
+ * generation; a CLI run stays in one generation and reads each file once.
+ */
+export declare class ExportTableCache {
+    #private;
+    /** Start a new generation: files will be re-validated on their next lookup. */
+    nextGeneration(): void;
+    /**
+     * Export table of `fileName`, or `undefined` when the file can't be read.
+     */
+    get(fileName: string, assumeAllPublic: boolean): ModuleExports | undefined;
+    clear(): void;
+}
+export {};

package/dist/core/lookupPackageJson.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Name of the closest `package.json` above `file`, or `null`.
+ */
+export declare function lookupPackageName(file: string): string | null;
+/**
+ * Forget cached package.json lookups (for long-running processes and tests).
+ */
+export declare function clearPackageNameCache(): void;

package/dist/core/resolveModule.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where an import specifier leads.
+ *
+ * - `internal`: a source file of the project, which the rule checks.
+ * - `external`: a builtin module or a file reached through `node_modules`
+ *   (TypeScript's "external library import", which includes symlinked workspace packages).
+ * - `unresolved`: nothing found, or a file that is no module to TypeScript (`.svg`, `.css`…);
+ *   a wildcard ambient module (`declare module "*.svg"`) may still declare it.
+ */
+export type Resolution = {
+    readonly kind: "internal";
+    readonly fileName: string;
+} | {
+    readonly kind: "external";
+} | {
+    readonly kind: "unresolved";
+};
+/**
+ * Resolves import specifiers like TypeScript would.
+ *
+ * Results are memoized per importing directory, and relative specifiers also by the absolute
+ * path they point at, so every importer of a module shares one resolution.
+ */
+export declare class ModuleResolver {
+    #private;
+    resolve(importerFileName: string, specifier: string): Resolution;
+    clear(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/** @public */
+export type { Importability, JSDocRuleOptions } from "./utils/options.js";
+/**
+ * Shape of the plugin object. Declared here so the published types don't depend on
+ * `@oxlint/plugins`; it is checked against oxlint's `Plugin` type below.
+ * @public
+ */
+export type ImportAccessPlugin = {
+    readonly meta: {
+        readonly name: "import-access";
+    };
+    readonly rules: {
+        readonly jsdoc: object;
+    };
+};
+/**
+ * Oxlint JS plugin restricting imports of `@package` and `@private` exports.
+ *
+ * @example
+ * ```json
+ * {
+ *   "jsPlugins": ["@crutchcrew/oxlint-plugin-import-access"],
+ *   "rules": { "import-access/jsdoc": "error" }
+ * }
+ * ```
+ */
+declare const plugin: ImportAccessPlugin;
+/** @public */
+export default plugin;