@sister.software/oxlint-config 9.0.0

package/package.json

@@ -0,0 +1,44 @@
+{
+ "name": "@sister.software/oxlint-config",
+ "version": "9.0.0",
+ "description": "Sister Software's oxlint config",
+ "license": "AGPL-3.0",
+ "author": "teffen@sister.software",
+ "files": [
+  "out/**/*.js",
+  "out/**/*.d.ts",
+  "out/**/*.map",
+  "src"
+ ],
+ "type": "module",
+ "types": "./out/index.d.ts",
+ "exports": {
+  "./package.json": "./package.json",
+  ".": {
+   "import": "./out/index.js",
+   "types": "./out/index.d.ts"
+  },
+  "./headers-plugin": {
+   "import": "./out/headers-plugin.js",
+   "types": "./out/headers-plugin.d.ts"
+  }
+ },
+ "publishConfig": {
+  "access": "public"
+ },
+ "scripts": {
+  "build": "tsc -p .",
+  "verify": "node scripts/verify-fixtures.mjs"
+ },
+ "devDependencies": {
+  "@sister.software/tsconfig": "workspace:*",
+  "@types/node": "^25.6.0",
+  "typescript": "^6.0.3"
+ },
+ "peerDependencies": {
+  "oxlint": "^1.71.0"
+ },
+ "engines": {
+  "node": ">=24.0"
+ }
+}

package/src/headers-plugin.ts

@@ -0,0 +1,140 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file A JSDoc-aware license-header rule, authored as an oxlint JS plugin (ESLint v9-compatible
+ *   API). It reports files missing the `@copyright`/`@license`/`@author` header and autofixes them
+ *   while preserving any other JSDoc tags already present in the leading comment block.
+ */
+
+//#region Minimal ESLint-compatible plugin types (kept local to avoid coupling to oxlint's alpha
+// internal type surface, which is not subject to semver).
+
+interface Comment {
+	type: string
+	value: string
+	range: [number, number]
+}
+
+interface SourceCode {
+	getText(): string
+	getAllComments(): Comment[]
+}
+
+interface Fixer {
+	insertTextBeforeRange(range: [number, number], text: string): unknown
+	replaceTextRange(range: [number, number], text: string): unknown
+}
+
+interface RuleContext {
+	options: unknown[]
+	sourceCode?: SourceCode
+	getSourceCode?(): SourceCode
+	report(descriptor: { node: unknown; message: string; fix?(fixer: Fixer): unknown }): void
+}
+
+interface Rule {
+	meta: { name: string; type: string; fixable: "code"; schema: unknown[] }
+	create(context: RuleContext): Record<string, (node: unknown) => void>
+}
+
+interface Plugin {
+	meta: { name: string }
+	rules: Record<string, Rule>
+}
+
+//#endregion
+
+/** Options accepted by the header rule. */
+export interface HeaderRuleOptions {
+	copyrightHolder?: string
+	spdxLicenseIdentifier?: string
+	author?: string
+}
+
+const HEADER_TAG_PATTERN = /^@(copyright|license|author)\b/
+
+/**
+ * Splits a block comment's inner text into trimmed, non-empty content lines (one per JSDoc line), stripping the leading
+ * ` * ` decoration.
+ */
+function parseInnerLines(comment: Comment): string[] {
+	return comment.value
+		.split("\n")
+		.map((line) => line.replace(/^\s*\*?\s?/, "").replace(/\s+$/, ""))
+		.filter((line) => line.length > 0)
+}
+
+const rule: Rule = {
+	meta: {
+		name: "require-file-header",
+		type: "layout",
+		fixable: "code",
+		// Permissive schema: oxlint's alpha JS-plugin layer mangles complex option schemas, so we
+		// accept any object and read options defensively below.
+		schema: [{ type: "object", additionalProperties: true }],
+	},
+	create(context) {
+		const options = (context.options[0] ?? {}) as HeaderRuleOptions
+		const copyrightHolder = options.copyrightHolder ?? "Sister Software"
+		const spdxLicenseIdentifier = options.spdxLicenseIdentifier ?? "UNLICENSED"
+		const author = options.author ?? "Teffen Ellis, et al."
+		const headerLines = [`@copyright ${copyrightHolder}`, `@license ${spdxLicenseIdentifier}`, `@author ${author}`]
+
+		const sourceCode = context.sourceCode ?? context.getSourceCode!()
+
+		function buildBlock(preservedLines: string[]): string {
+			return "/**\n" + [...headerLines, ...preservedLines].map((line) => ` * ${line}`).join("\n") + "\n */"
+		}
+
+		return {
+			Program(node) {
+				const text = sourceCode.getText()
+				// A leading shebang (`#!...`) must stay on line 1, so the header goes *after* it.
+				const shebang = /^#![^\n]*\n?/.exec(text)?.[0] ?? ""
+
+				const comments = sourceCode.getAllComments()
+				// The first *block* comment, skipping any shebang (which some ASTs surface as a leading
+				// comment). It counts as the header block only if nothing but the shebang precedes it.
+				const firstBlock = comments.find((comment) => comment.type === "Block")
+				const leading = firstBlock && text.slice(shebang.length, firstBlock.range[0]).trim() === "" ? firstBlock : null
+
+				if (leading) {
+					const existing = parseInnerLines(leading)
+					const missing = headerLines.filter((line) => !existing.includes(line))
+					if (missing.length === 0) return
+
+					const preserved = existing.filter((line) => !HEADER_TAG_PATTERN.test(line))
+					const block = buildBlock(preserved)
+
+					context.report({
+						node,
+						message: `File header missing or incorrect: ${missing.join(", ")}`,
+						fix(fixer) {
+							return fixer.replaceTextRange(leading.range, block)
+						},
+					})
+				} else {
+					const block = buildBlock([])
+					const insertAt = shebang.length
+
+					context.report({
+						node,
+						message: "File header missing (@copyright/@license/@author).",
+						fix(fixer) {
+							return fixer.insertTextBeforeRange([insertAt, insertAt], block + "\n\n")
+						},
+					})
+				}
+			},
+		}
+	},
+}
+
+/** The Sister Software oxlint header plugin. Registers the `sister-software/require-file-header` rule. */
+const headerPlugin: Plugin = {
+	meta: { name: "sister-software" },
+	rules: { "require-file-header": rule },
+}
+
+export default headerPlugin

package/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file oxlint configuration factory for Sister Software projects.
+ */
+
+import { createRuntimeOverrides } from "./restrictions.js"
+
+export * from "./restrictions.js"
+
+/** An oxlint configuration object, as consumed by `oxlint.config.ts` / `.oxlintrc.json`. */
+export type OxlintConfig = Record<string, unknown>
+
+/** Options for {@link createOxlintConfig}. */
+export interface OxlintConfigOptions {
+	/** The package namespace whose runtime boundaries are enforced, e.g. `@sister.software`. */
+	packageNamespace?: string
+	/** The copyright holder stamped into file headers. */
+	copyrightHolder?: string
+	/** The SPDX license identifier stamped into file headers. */
+	spdxLicenseIdentifier?: string
+	/** The author stamped into file headers. */
+	author?: string
+	/** Enable oxlint's React plugin (off by default). */
+	react?: boolean
+	/** Enforce file headers via the bundled JS plugin (on by default). */
+	headers?: boolean
+	/** Override the default ignore patterns. */
+	ignorePatterns?: string[]
+	/** Extra config deep-merged last; an escape hatch for per-repo tweaks. */
+	overrides?: OxlintConfig
+}
+
+/** Default ignore patterns for generated/build output. */
+export const DefaultIgnorePatterns = [
+	"**/out",
+	"**/dist",
+	"**/.docusaurus/**",
+	"**/node_modules",
+	"**/coverage",
+	"**/storybook-static",
+]
+
+/**
+ * Builds the complete oxlint configuration for a Sister Software package.
+ *
+ * Consumers use it directly from an `oxlint.config.ts`:
+ *
+ * ```ts
+ * import { createOxlintConfig } from "@sister.software/oxlint-config"
+ * export default createOxlintConfig({ spdxLicenseIdentifier: "AGPL-3.0" })
+ * ```
+ *
+ * @param options Configuration options.
+ * @returns A complete oxlint config object (no `extends` required).
+ */
+export function createOxlintConfig(options: OxlintConfigOptions = {}): OxlintConfig {
+	const {
+		packageNamespace = "@sister.software",
+		copyrightHolder = "Sister Software",
+		spdxLicenseIdentifier = "UNLICENSED",
+		author = "Teffen Ellis, et al.",
+		react = false,
+		headers = true,
+		ignorePatterns = DefaultIgnorePatterns,
+		overrides = {},
+	} = options
+
+	const plugins = ["typescript", "unicorn", "oxc", ...(react ? ["react"] : [])]
+
+	const rules: Record<string, unknown> = {
+		// JavaScript
+		eqeqeq: ["error", "always", { null: "ignore" }],
+		"prefer-const": "warn",
+		"object-shorthand": ["warn", "always"],
+		"no-shadow": "off",
+		"no-undef": "off",
+		"no-unused-vars": [
+			"warn",
+			{
+				args: "all",
+				argsIgnorePattern: "^_",
+				caughtErrors: "all",
+				caughtErrorsIgnorePattern: "^_",
+				destructuredArrayIgnorePattern: "^_",
+				// Matches the prior ESLint config: unused vars are not reported (Prettier/oxfmt and TS
+				// already cover most cases); only unused args without a `_` prefix are flagged.
+				varsIgnorePattern: "^\\w",
+				ignoreRestSiblings: true,
+			},
+		],
+
+		// TypeScript — intentionally permissive (matches the prior ESLint config).
+		"typescript/ban-ts-comment": ["warn", { "ts-ignore": "allow-with-description" }],
+		"typescript/ban-types": "off",
+		"typescript/no-empty-interface": "off",
+		"typescript/no-explicit-any": "off",
+		"typescript/no-misused-new": "off",
+		"typescript/no-non-null-assertion": "off",
+		"typescript/no-var-requires": "off",
+		"typescript/no-require-imports": "off",
+	}
+
+	if (headers) {
+		// Error severity: missing headers should fail `oxlint` (a real CI gate) and surface as an
+		// editor error. The rule is auto-fixable, so `oxlint --fix` keeps the friction low.
+		rules["sister-software/require-file-header"] = ["error", { copyrightHolder, spdxLicenseIdentifier, author }]
+	}
+
+	return {
+		plugins,
+		...(headers ? { jsPlugins: ["@sister.software/oxlint-config/headers-plugin"] } : {}),
+		categories: { correctness: "error" },
+		ignorePatterns,
+		rules,
+		overrides: createRuntimeOverrides(packageNamespace),
+		...overrides,
+	}
+}
+
+export default createOxlintConfig

package/src/restrictions.ts

@@ -0,0 +1,253 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Platform-layering import restrictions, ported to oxlint's `no-restricted-imports`.
+ */
+
+import { builtinModules } from "node:module"
+
+//#region Runtime data
+
+/**
+ * Reserved package-name suffixes mapped to their target runtime.
+ *
+ * A package whose final name segment matches one of these signals that runtime, and imports across incompatible runtime
+ * boundaries become lint errors.
+ */
+export const RuntimePackageNamesRecord = {
+	browser: ["client", "browser"],
+	node: ["server", "node", "sdk"],
+	agnostic: ["shared", "common"],
+	worker: ["worker"],
+} as const
+
+export type RuntimePackageNamesRecord = typeof RuntimePackageNamesRecord
+
+/** Valid runtime names. */
+export type RuntimeName = keyof RuntimePackageNamesRecord
+
+/**
+ * Given a package name, produces the glob matcher for files belonging to that package.
+ *
+ * @param packageName The final package-name segment, e.g. `client`.
+ * @returns A single-element glob array, e.g. `["**\/client.{js,...}"]`.
+ */
+export function createPackageFileMatcher(packageName: string): string[] {
+	return [`**/${packageName}.{js,mjs,cjs,ts,d.ts,mts,tsx}`]
+}
+
+/** Joins a namespace and package name into a specifier, e.g. `@sister.software/client`. */
+function namespaced(packageNamespace: string, packageName: string): string {
+	return [packageNamespace, packageName].filter(Boolean).join("/")
+}
+
+//#endregion
+
+//#region Node built-in helpers
+
+const NODE_BUILTINS_NO_PREFIX = builtinModules.filter(
+	(moduleName) => !moduleName.startsWith("_") && !moduleName.startsWith("node:")
+)
+
+const NODE_BUILTINS_PREFIXED = NODE_BUILTINS_NO_PREFIX.map((moduleName) => `node:${moduleName}`)
+
+/** A restricted-import entry: an exact module name plus the message shown when it is imported. */
+export interface RestrictedPath {
+	name: string
+	message: string
+}
+
+/**
+ * Unprefixed Node built-ins (e.g. `fs`), each nudging toward the `node:` prefix. Used by browser- and node-runtime
+ * files where the bare form is ambiguous.
+ */
+export function ambiguousNodeBuiltinPaths(): RestrictedPath[] {
+	return NODE_BUILTINS_NO_PREFIX.map((name) => ({
+		name,
+		message: `Ambiguous module: did you mean \`node:${name}\`?`,
+	}))
+}
+
+/**
+ * Every Node built-in (prefixed and unprefixed), each carrying the given message. Used by agnostic-runtime files, which
+ * must not assume a Node runtime at all.
+ */
+export function allNodeBuiltinPaths(message: string): RestrictedPath[] {
+	return [...NODE_BUILTINS_NO_PREFIX, ...NODE_BUILTINS_PREFIXED].map((name) => ({ name, message }))
+}
+
+//#endregion
+
+//#region Browser globals
+
+/**
+ * Browser globals whose bare use is ambiguous (they collide with common identifiers). Browser- and node-runtime files
+ * warn on these, nudging toward an explicit `window.` access.
+ */
+const BROWSER_GLOBALS = [
+	"addEventListener",
+	"blur",
+	"close",
+	"closed",
+	"confirm",
+	"defaultStatus",
+	"defaultstatus",
+	"event",
+	"external",
+	"find",
+	"focus",
+	"frameElement",
+	"frames",
+	"history",
+	"innerHeight",
+	"innerWidth",
+	"length",
+	"location",
+	"locationbar",
+	"menubar",
+	"moveBy",
+	"moveTo",
+	"name",
+	"onblur",
+	"onerror",
+	"onfocus",
+	"onload",
+	"onresize",
+	"onunload",
+	"open",
+	"opener",
+	"opera",
+	"outerHeight",
+	"outerWidth",
+	"pageXOffset",
+	"pageYOffset",
+	"parent",
+	"print",
+	"removeEventListener",
+	"resizeBy",
+	"resizeTo",
+	"screen",
+	"screenLeft",
+	"screenTop",
+	"screenX",
+	"screenY",
+	"scroll",
+	"scrollbars",
+	"scrollBy",
+	"scrollTo",
+	"scrollX",
+	"scrollY",
+	"self",
+	"status",
+	"statusbar",
+	"stop",
+	"toolbar",
+	"top",
+] as const
+
+function restrictedBrowserGlobalsRule(): unknown {
+	return ["warn", ...BROWSER_GLOBALS.map((name) => ({ name, message: `Ambiguous: did you mean \`window.${name}\`?` }))]
+}
+
+//#endregion
+
+//#region Override generation
+
+/** A per-file-glob oxlint override: applies `rules` only to files matching `files`. */
+export interface OxlintOverride {
+	files: string[]
+	rules: Record<string, unknown>
+}
+
+/** A restricted-import pattern: a set of gitignore-style globs plus a message. */
+interface RestrictedPattern {
+	group: string[]
+	message: string
+}
+
+/**
+ * Builds the `patterns` entries forbidding a runtime from importing packages of incompatible runtimes, each with a
+ * tailored message.
+ */
+function crossRuntimePatterns(
+	packageNamespace: string,
+	self: RuntimeName,
+	incompatible: readonly RuntimeName[]
+): RestrictedPattern[] {
+	return incompatible.flatMap((targetRuntime) =>
+		RuntimePackageNamesRecord[targetRuntime].map((packageName) => {
+			const specifier = namespaced(packageNamespace, packageName)
+
+			return {
+				group: [specifier, `${specifier}/**`],
+				message: `A "${self}"-runtime module must not import "${specifier}", which targets the "${targetRuntime}" runtime. Move shared code into a "shared"/"common" package and import that from both.`,
+			}
+		})
+	)
+}
+
+/**
+ * Generates the per-runtime overrides enforcing platform layering. One override is emitted for each browser-, node-,
+ * and agnostic-runtime package name (matching the original ESLint config — worker files are a restricted _target_ but
+ * have no override of their own).
+ *
+ * @param packageNamespace The namespace whose packages are subject to the rules, e.g. `@sister.software`.
+ * @returns An array of oxlint `overrides` entries.
+ */
+export function createRuntimeOverrides(packageNamespace: string): OxlintOverride[] {
+	const overrides: OxlintOverride[] = []
+
+	for (const packageName of RuntimePackageNamesRecord.browser) {
+		overrides.push({
+			files: createPackageFileMatcher(packageName),
+			rules: {
+				"no-restricted-imports": [
+					"warn",
+					{
+						paths: ambiguousNodeBuiltinPaths(),
+						patterns: crossRuntimePatterns(packageNamespace, "browser", ["node", "worker"]),
+					},
+				],
+				"no-restricted-globals": restrictedBrowserGlobalsRule(),
+			},
+		})
+	}
+
+	for (const packageName of RuntimePackageNamesRecord.node) {
+		overrides.push({
+			files: createPackageFileMatcher(packageName),
+			rules: {
+				"no-restricted-imports": [
+					"warn",
+					{
+						paths: ambiguousNodeBuiltinPaths(),
+						patterns: crossRuntimePatterns(packageNamespace, "node", ["browser", "worker"]),
+					},
+				],
+				"no-restricted-globals": restrictedBrowserGlobalsRule(),
+			},
+		})
+	}
+
+	for (const packageName of RuntimePackageNamesRecord.agnostic) {
+		overrides.push({
+			files: createPackageFileMatcher(packageName),
+			rules: {
+				"no-restricted-imports": [
+					"warn",
+					{
+						paths: allNodeBuiltinPaths(
+							`A "shared"/"common" module assumes no runtime and must not import Node built-ins.`
+						),
+						patterns: crossRuntimePatterns(packageNamespace, "agnostic", ["browser", "node", "worker"]),
+					},
+				],
+			},
+		})
+	}
+
+	return overrides
+}
+
+//#endregion