@noctcore/eslint-plugin-architecture 0.1.0 → 0.2.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-architecture",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-agnostic folder-per-component and feature-boundary architecture ESLint rules.",
   "license": "MIT",
   "type": "module",