@noctcore/eslint-plugin-architecture 0.1.0 → 0.3.0

package/docs/rules/barrel-purity.md

@@ -0,0 +1,57 @@
+# `noctcore-architecture/barrel-purity`
+
+> A barrel (`index.ts` / `index.tsx`) must contain only re-exports — never local declarations, side effects, or default-exported values.
+
+## Why
+
+A barrel exists to present a folder's public surface. The moment it also *declares* something — a
+const, a function, a type, a default-exported value — or *does* something — a side-effect import, a
+top-level call — the barrel becomes a real module with behavior. Every consumer that imports the
+folder now silently pulls that behavior in, and the folder no longer has a clean, movable boundary.
+
+## What it flags
+
+Only `index.ts` / `index.tsx` (and the other index extensions) are inspected. Each top-level
+statement that is not a pure re-export is reported.
+
+```ts
+// index.ts
+
+export { Card } from './Card';          // ✓ named re-export
+export * from './Card.types';           // ✓ star re-export
+export * as card from './Card';         // ✓ namespace re-export
+export { default as Card } from './Card'; // ✓ default re-export
+import { a } from './a';                // ✓ import that feeds a re-export
+export { a };                           //   …its matching specifier
+export type { Props } from './Card';    // ✓ type re-export
+export default Card;                    // ✓ re-export of a binding by name
+
+export const helper = 1;                // ✗ local declaration
+export function build() {}              // ✗ local declaration
+export type T = string;                 // ✗ local declaration
+export default () => 1;                 // ✗ a value, not a re-export
+import './styles.css';                  // ✗ side-effect import
+console.log('hi');                      // ✗ side-effect statement
+const cache = new Map();                // ✗ non-export code
+```
+
+An import that carries bindings is allowed because it feeds a re-export; a specifier-less
+`import './x'` is a side effect and is flagged.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `allow` | `string[]` | `[]` | Globs (supporting `**`, `*`, `?`) of barrel paths to exempt entirely. |
+
+```js
+'noctcore-architecture/barrel-purity': ['error', {
+  allow: ['**/legacy/**'],
+}]
+```
+
+## When not to use it
+
+If you deliberately keep small helpers or feature flags inside a package's `index.ts`, this rule will
+fight you. Prefer moving them into a sibling module and re-exporting — but if you cannot, disable the
+rule for those paths via `allow`.

package/docs/rules/colocated-test-required.md

@@ -0,0 +1,48 @@
+# `noctcore-architecture/colocated-test-required`
+
+> A source file matching an `include` glob must have a colocated `*.test.*` / `*.spec.*` sibling on disk. Off until `include` is configured.
+
+## Why
+
+Some files are risky enough that shipping them untested should be a lint error, not a code-review
+afterthought — hooks, services, reducers, money math. This rule lets you name those globs and then
+requires each matching file to carry its test right next to it, so the test travels with the code and
+is obvious when missing.
+
+## What it flags
+
+For a file matching `include`, the rule reads the file's directory and looks for a sibling whose name
+is `<stem>.test.<ext>` or `<stem>.spec.<ext>` (any extension). If none exists, it reports.
+
+```
+src/hooks/useCart.ts          ← include: ['**/use*.ts']
+src/hooks/useCart.test.ts      ✓ colocated test present
+src/hooks/useWishlist.ts       ✗ no useWishlist.test.* / .spec.* sibling
+```
+
+A test file that itself matches `include` is never asked to test itself. Directory listings are
+cached for the lint run, so a folder full of gated files is read once.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `include` | `string[]` | `[]` | Globs of source files that must have a colocated test. **Empty = the rule is off.** |
+| `ignore` | `string[]` | `[]` | Globs of files to exempt even when they match `include`. |
+
+```js
+'noctcore-architecture/colocated-test-required': ['error', {
+  include: ['**/use*.ts', '**/*.service.ts', '**/*.reducer.ts'],
+  ignore: ['**/*.d.ts'],
+}]
+```
+
+## In `recommended`
+
+Ships **`'off'`**. There is no universal "everything needs a colocated test" default, so the
+`recommended` preset cannot safely enable it — turn it on with your own `include` globs.
+
+## When not to use it
+
+If your tests live in a separate `__tests__` tree or a top-level `test/` directory rather than beside
+the source, this colocation check does not model your layout. Leave it off.

package/docs/rules/filename-matches-export.md

@@ -0,0 +1,56 @@
+# `noctcore-architecture/filename-matches-export`
+
+> A file's basename must match its primary export (a default export, or the sole named export).
+
+## Why
+
+When a module has one clear public export, the filename should announce it. A `helpers.ts` that
+exports a single `formatDate` hides its contents from anyone scanning the file tree, and a rename of
+one without the other leaves the two permanently out of sync. Keeping them aligned makes the tree
+self-describing.
+
+## What it flags
+
+The rule first resolves the file's **primary export**:
+
+1. If the file has a default export with a name (`export default function Foo`, `export default
+   class Foo`, `export default Foo`), that name is the primary export. An anonymous default
+   (`export default () => …`) has no identifier to compare, so the file is skipped.
+2. Otherwise, if the file has exactly one local named export, that is the primary export.
+3. Otherwise (no primary, or several named exports) the file is skipped.
+
+The basename and the identifier are compared **case- and separator-insensitively**, so naming
+conventions never collide:
+
+```ts
+// TaskCard.tsx  → export default function TaskCard() {}   ✓
+// use-thing.ts  → export const useThing = () => {}        ✓ (kebab ↔ camel)
+// helpers.ts    → export const formatDate = () => {}      ✗ (genuine mismatch)
+```
+
+`index` files and files matching an `ignore` glob are always skipped.
+
+## Suggestion, not autofix
+
+A mismatch offers a **suggestion** to rename the export to the filename (the code-side resolution —
+the other is renaming the file). It is never an autofix: renaming a public identifier is a decision a
+human should confirm. When the basename is not a valid identifier (e.g. `2fa.ts`), the mismatch is
+reported without a suggestion.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `ignore` | `string[]` | `[]` | Globs (supporting `**`, `*`, `?`) of files to skip. |
+
+```js
+'noctcore-architecture/filename-matches-export': ['error', {
+  ignore: ['**/*.stories.tsx', '**/route.ts'],
+}]
+```
+
+## When not to use it
+
+If your files routinely export several unrelated symbols, or you use fixed conventional filenames
+(`route.ts`, `handler.ts`) that will never match their export, add them to `ignore` or leave the rule
+off.

package/docs/rules/max-import-depth.md

@@ -0,0 +1,52 @@
+# `noctcore-architecture/max-import-depth`
+
+> A relative import may not climb more than `max` parent levels (default 3). Autofixed to a path alias when one is configured.
+
+## Why
+
+A relative import that climbs several directories (`../../../../shared/log`) is brittle and hard to
+read: it couples the file to its exact position in the tree, so moving either end breaks the path. A
+path alias (`@/shared/log`) is stable and self-locating. This rule caps how far a relative import may
+reach before it must become an alias.
+
+## What it flags
+
+Any relative specifier whose leading `..` run exceeds `max` is reported, on every source-carrying
+construct: `import`, `import()`, `export … from`, and `export * from`.
+
+```ts
+// max: 3 (default)
+import a from '../../../shared';        // ✓ exactly at the limit
+import b from '../../../../shared/log'; // ✗ climbs 4 levels
+```
+
+## Autofix
+
+When `alias` maps a directory-anchor segment to an alias prefix, a too-deep import that resolves
+*through* that anchor is autofixed:
+
+```js
+'noctcore-architecture/max-import-depth': ['error', {
+  alias: { src: '@' },
+}]
+```
+
+```ts
+// from src/a/b/c/d/deep.ts
+import x from '../../../../shared/log'; // → import x from '@/shared/log';
+```
+
+With no matching alias anchor on the resolved path, the violation is **reported without a fix** —
+there is nothing safe to rewrite it to.
+
+## Options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `max` | `integer` | `3` | Maximum number of `..` parent hops a relative import may take. |
+| `alias` | `Record<string, string>` | `{}` | Map of directory-anchor segment → alias prefix used to autofix, e.g. `{ src: '@' }`. |
+
+## When not to use it
+
+If you do not use path aliases and genuinely prefer deep relative imports, raise `max` or leave the
+rule off.

package/docs/rules/single-semantic-module.md

@@ -0,0 +1,180 @@
+# `noctcore-architecture/single-semantic-module`
+
+> Each module exports one semantic concern: types, constants, functions, classes, React components,
+> hooks, schemas or enums. **Ships `off` in `recommended`**: choose the files and the allowed mixes
+> for your codebase, then enable it.
+
+Ported from
+[`@boring-stack-pkg/eslint-plugin-module-boundaries`](https://github.com/boringstack-xyz/eslint-plugins/tree/main/eslint-plugin-module-boundaries)
+0.2.0 (MIT). Upstream peers ESLint `8.57.0 || ^9.0.0`; this port runs on ESLint 9 and 10.
+
+## Why
+
+A file that exports a component, the hook it uses, the constant that configures it and the type of its
+props has four reasons to change and four kinds of consumer. Splitting by concern keeps imports
+honest: a type-only consumer never pulls in runtime code, and a constant never drags a component into
+a server bundle.
+
+The rule classifies by **AST shape**, never by filename or suffix:
+
+| Category | Shape |
+| --- | --- |
+| `type` | `interface`, `type`, `namespace`, `declare ...` |
+| `enum` | `enum` (or `type`, with `enumCategory: 'type'`) |
+| `constant` | any other top-level value |
+| `function` | function declaration or function-valued `const` |
+| `class` | class declaration or class expression |
+| `react-component` | PascalCase function returning JSX (or typed `FC` / `JSX.Element`) |
+| `hook` | a function named like a hook (`^use[A-Z0-9]`) |
+| `schema` | a call on an identifier imported from `zod`, `yup` or `valibot` |
+
+## Examples
+
+```ts
+// ✗ a type and a runtime constant
+export interface User {
+  id: string;
+}
+export const DEFAULT_USER: User = { id: 'anonymous' };
+```
+
+```ts
+// ✗ a component and a hook
+export function UserCard() {
+  return <div />;
+}
+export function useUserCard() {
+  return useQuery(userCardQuery);
+}
+```
+
+```ts
+// ✓ one concern: types only
+export interface User {
+  id: string;
+}
+export type UserId = User['id'];
+```
+
+### Private helpers do not count
+
+Only the **exported** surface defines a module (`ignorePrivateDeclarations`, default `true`). A
+non-exported render helper beside a component, or a filter constant inside a hook file, serves that
+surface and is not a second concern:
+
+```tsx
+// ✓ the helper is private
+function renderBadge(count: number) {
+  return <span className="badge">{count}</span>;
+}
+export function Inbox({ unread }: { unread: number }) {
+  return <div>{renderBadge(unread)}</div>;
+}
+```
+
+```ts
+// ✓ the filter object is private
+const ACTIVE_FILTER = { status: 'active', archived: false } as const;
+export function useActiveProjects() {
+  return useQuery({ queryKey: ['projects', ACTIVE_FILTER] });
+}
+```
+
+A declaration exported further down by name (`export { DEFAULT_USER }`, `export default UserCard`)
+is surface all the same.
+
+## Options
+
+```ts
+type SemanticCategory =
+  | 'type' | 'constant' | 'function' | 'class'
+  | 'react-component' | 'hook' | 'schema' | 'enum';
+
+type Options = {
+  /** Category sets a module may mix. Default []. */
+  allow?: SemanticCategory[][];
+  /** Whether an enum is its own category or a type. Default 'enum'. */
+  enumCategory?: 'enum' | 'type';
+  /** List every classified declaration and the reason in the report. Default false. */
+  debug?: boolean;
+  /** Skip `declare ...` and `declare global` entirely. Default false. */
+  ignoreAmbientDeclarations?: boolean;
+  /** Classify exported declarations only. Default true. */
+  ignorePrivateDeclarations?: boolean;
+  /** Libraries whose builders count as `schema`. Default ['zod', 'yup', 'valibot']. */
+  schemaLibraries?: Array<'zod' | 'yup' | 'valibot'>;
+  /** Default { enabled: true }. */
+  reactComponentDetection?: { enabled?: boolean };
+  /** Default { enabled: true, namePattern: '^use[A-Z0-9].*' }. */
+  hookDetection?: { enabled?: boolean; namePattern?: string };
+};
+```
+
+### `allow`: a NestJS `.constants.ts`
+
+In a NestJS module, `<name>.constants.ts` holds one module's enums, unions and DI tokens. That mixes
+categories **by design**, so allow the mix for those files only:
+
+```js
+// eslint.config.js
+export default [
+  {
+    files: ['apps/api/src/**/*.ts'],
+    rules: { 'noctcore-architecture/single-semantic-module': 'error' },
+  },
+  {
+    files: ['apps/api/src/**/*.constants.ts'],
+    rules: {
+      'noctcore-architecture/single-semantic-module': [
+        'error',
+        { allow: [['constant', 'type', 'enum']] },
+      ],
+    },
+  },
+];
+```
+
+```ts
+// ✓ billing.constants.ts with the config above
+export const BILLING_QUEUE = Symbol('BILLING_QUEUE');
+export const INVOICE_STATUSES = ['draft', 'sent', 'paid'] as const;
+export type InvoiceStatus = (typeof INVOICE_STATUSES)[number];
+export enum BillingEvent {
+  Paid = 'billing.paid',
+}
+
+// ✗ still reported: a function is outside the allowed group
+export function isPaid(status: InvoiceStatus) {
+  return status === 'paid';
+}
+```
+
+An `allow` group must cover **every** detected category; a module whose categories fit inside any one
+group passes.
+
+### `enumCategory`
+
+```js
+{ enumCategory: 'type' } // `export enum Role {}` beside `export type User = {}` is one concern
+```
+
+### `ignorePrivateDeclarations: false`
+
+Restores upstream's original behaviour, where every top-level declaration counts. Expect it to fight
+every non-trivial file.
+
+### `debug`
+
+Adds each classified declaration and the reason to the report, which is the quickest way to see why a
+file was flagged:
+
+```
+- type: User (TypeScript type-space declaration)
+- constant: DEFAULT_USER (object literal runtime value)
+```
+
+## When not to use it
+
+Barrels and generated files. Re-exports (`export * from`, `export { x } from`) are never classified, so
+a pure barrel passes anyway, but generated clients routinely mix every category; scope the rule away
+from them with `files` / `ignores`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-architecture",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic folder-per-component and feature-boundary architecture ESLint rules.",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,6 @@
     "@typescript-eslint/rule-tester": "^8.61.1",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0",
-    "vitest": "^3"
+    "vitest": "^4"
   }
 }