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

package/dist/rules/jsdoc.d.ts

@@ -0,0 +1,9 @@
+import type { CreateOnceRule } from "@oxlint/plugins";
+import { ImportabilityChecker } from "../core/checkImportability.js";
+/**
+ * Process-wide caches shared by every file and every options object.
+ */
+export declare const checker: ImportabilityChecker;
+declare const rule: CreateOnceRule;
+/** @public */
+export default rule;

package/dist/utils/getAccessOfJsDocs.d.ts

@@ -0,0 +1,8 @@
+import type { Tag } from "./jsdoc.js";
+import type { Importability } from "./options.js";
+/**
+ * Access level declared by JSDoc tags: the first of `@package`, `@private`, `@public`
+ * or `@access <level>` wins, otherwise `defaultImportability`.
+ * @public
+ */
+export declare function getAccessOfJsDocs(tags: readonly Tag[], defaultImportability: Importability): Importability;

package/dist/utils/isInPackage.d.ts

@@ -0,0 +1,19 @@
+import type { PackageOptions } from "./options.js";
+/**
+ * Decides which directory is the "package" of a file and whether two files share a package.
+ * Create one per options object: it memoizes per-directory answers.
+ * @public
+ */
+export declare class PackageBoundaries {
+    #private;
+    constructor(options: PackageOptions);
+    /**
+     * The package directory of a file: its own directory, or with `packageDirectory` patterns,
+     * the closest ancestor directory that is a package boundary.
+     */
+    packageDirectoryOf(filePath: string): string;
+    /**
+     * Whether `importer` is in the same package as `exporter`, or in a descendant package.
+     */
+    isInPackage(importer: string, exporter: string): boolean;
+}

package/dist/utils/jsdoc.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A JSDoc tag such as `@package` or `@access package`.
+ * @public
+ */
+export type Tag = {
+    readonly name: string;
+    readonly text: string;
+};
+/**
+ * Minimal comment shape shared by oxc-parser and oxlint's `sourceCode`.
+ * `value` excludes the `/*` and `*\/` delimiters.
+ * @public
+ */
+export type Comment = {
+    readonly type: "Line" | "Block";
+    readonly value: string;
+    readonly start: number;
+    readonly end: number;
+};
+/**
+ * Find the JSDoc comments attached to a node starting at `nodeStart`, following TypeScript's rules:
+ *
+ * - only block comments starting with `/**` (but not the empty `/**\/`) count,
+ * - they must sit in the trivia between the previous token and the node,
+ * - for statements, comments on the same line as the previous token belong to that token
+ *   (`includeSameLine: false`); export specifiers and variable declarators take them too.
+ */
+export declare function findJsDocComments(sourceText: string, comments: readonly Comment[], nodeStart: number, includeSameLine?: boolean): Comment[];
+/**
+ * Parse the block tags of a JSDoc comment the way TypeScript does.
+ *
+ * A tag starts with `@` followed by its name, at the beginning of a line (after the optional `*`
+ * margin) or after a space or tab, but not inside backticks. Its text runs until the next tag.
+ */
+export declare function parseJsDocTags(comment: Comment): Tag[];
+/**
+ * Tags as TypeScript reports them for a node: `symbol.getJsDocTags()` only sees the last JSDoc block
+ * (`own`), while the declaration's `jsDoc` holds every block (`all`).
+ * @public
+ */
+export type NodeTags = {
+    readonly own: readonly Tag[];
+    readonly all: readonly Tag[];
+};
+/** @public */
+export declare function jsDocTagsAt(sourceText: string, comments: readonly Comment[], nodeStart: number, includeSameLine?: boolean): NodeTags;

package/dist/utils/options.d.ts

@@ -0,0 +1,55 @@
+/** @public */
+export type Importability = "public" | "package" | "private";
+/**
+ * Options of the `import-access/jsdoc` rule.
+ * @public
+ */
+export type JSDocRuleOptions = {
+    /**
+     * Allow importing package-private exports from `index.ts` in a subdirectory,
+     * as if `sub/index.ts` were `sub.ts`.
+     * @default true
+     */
+    indexLoophole: boolean;
+    /**
+     * Allow `foo.ts` to import package-private exports from files in `foo/`.
+     * @default false
+     */
+    filenameLoophole: boolean;
+    /**
+     * Importability of exports that have no access tag in their JSDoc.
+     * @default "package"
+     */
+    defaultImportability: Importability;
+    /**
+     * How to treat imports that use the package's own name (Node.js self-reference).
+     * `external` skips the check like for any other package; `internal` checks them.
+     * @default "external"
+     */
+    treatSelfReferenceAs: "internal" | "external";
+    /**
+     * Glob patterns, relative to the working directory, of exporter files to skip.
+     * Useful for generated code.
+     * @default []
+     */
+    excludeSourcePatterns: readonly string[];
+    /**
+     * Glob patterns of directories that are package boundaries. By default every directory is one.
+     * Negated patterns (`"!**\/_internal"`) exclude directories, which then belong to their parent package.
+     */
+    packageDirectory?: readonly string[] | undefined;
+};
+/**
+ * Resolved options used by the importability check.
+ * @public
+ */
+export type PackageOptions = Readonly<JSDocRuleOptions> & {
+    /** Base directory for relative glob patterns. */
+    readonly projectDirectory: string;
+};
+export declare const defaultOptions: JSDocRuleOptions;
+/**
+ * Fill in defaults for user-provided options.
+ * @public
+ */
+export declare function normalizeOptions(options: Partial<JSDocRuleOptions> | undefined, projectDirectory: string): PackageOptions;

package/package.json

@@ -1,6 +1,102 @@
 {
-  "name": "@crutchcrew/oxlint-plugin-import-access",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@crutchcrew/oxlint-plugin-import-access",
+	"version": "1.0.0",
+	"description": "Oxlint JS plugin for import access via JSDoc @public, @package and @private, without a type checker",
+	"keywords": [
+		"import-access",
+		"jsdoc",
+		"oxlint",
+		"oxlint-plugin",
+		"package-private",
+		"typescript"
+	],
+	"homepage": "https://github.com/crutchcrew/oxlint-plugin-import-access#readme",
+	"bugs": {
+		"url": "https://github.com/crutchcrew/oxlint-plugin-import-access/issues"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/crutchcrew/oxlint-plugin-import-access.git"
+	},
+	"workspaces": [
+		"src/__tests__/fixtures/packages/workspaces/*"
+	],
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"bench": "bun bench/run.ts",
+		"build": "bun run --parallel build:compile build:declaration",
+		"build:compile": "bun build src/index.ts --outdir dist --format esm --target node --packages external",
+		"build:declaration": "tsc -p tsconfig.build.json && bun scripts/fix-dts-extensions.ts",
+		"check": "bun run --parallel fmt:check lint lockfile:check",
+		"fmt": "oxfmt --write .",
+		"fmt:check": "oxfmt --check .",
+		"lint": "oxlint",
+		"lint:fix": "oxlint --fix",
+		"lockfile:check": "bun install --frozen-lockfile",
+		"prebuild": "rm -rf dist",
+		"prepare": "lefthook install",
+		"prepublishOnly": "bun run build",
+		"test": "vitest run --project unit",
+		"test:coverage": "vitest run --project unit --coverage",
+		"test:e2e": "vitest run --project e2e"
+	},
+	"dependencies": {
+		"minimatch": "^10.2.6",
+		"oxc-parser": "^0.155.0",
+		"oxc-resolver": "^11.24.2"
+	},
+	"devDependencies": {
+		"@fixture-package-third-party/has-sub-module": "file:src/__tests__/fixtures/packages/third-party/has-sub-module",
+		"@fixture-package-third-party/missing-entrypoint": "file:src/__tests__/fixtures/packages/third-party/missing-entrypoint",
+		"@fixture-package-third-party/with-exports-field": "file:src/__tests__/fixtures/packages/third-party/with-exports-field",
+		"@fixture-package-workspace/has-sub-module": "workspace:*",
+		"@fixture-package-workspace/missing-entrypoint": "workspace:*",
+		"@fixture-package-workspace/with-exports-field": "workspace:*",
+		"@oxlint/plugins": "^1.89.0",
+		"@types/node": "^24.13.3",
+		"@vitest/coverage-v8": "^5.0.5",
+		"lefthook": "^2.2.2",
+		"oxfmt": "^0.74.0",
+		"oxlint": "^1.89.0",
+		"oxlint-tsgolint": "^7.0.2005",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.5"
+	},
+	"peerDependencies": {
+		"oxlint": ">=1.40.0"
+	},
+	"devEngines": {
+		"packageManager": {
+			"name": "bun",
+			"onFail": "warn"
+		},
+		"runtime": [
+			{
+				"name": "bun",
+				"onFail": "warn"
+			},
+			{
+				"name": "node",
+				"version": ">=22.18.0",
+				"onFail": "warn"
+			}
+		]
+	},
+	"engines": {
+		"node": "^20.19.0 || >=22.12.0"
+	}
+}