@noctcore/eslint-plugin-architecture 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -1385,7 +1385,7 @@ var rules = {
 
 // src/index.ts
 var NAMESPACE = "noctcore-architecture";
-var VERSION = "0.3.0";
+var VERSION = "0.3.2";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-architecture", version: VERSION },
   rules,

package/dist/index.js

@@ -1347,7 +1347,7 @@ var rules = {
 
 // src/index.ts
 var NAMESPACE = "noctcore-architecture";
-var VERSION = "0.3.0";
+var VERSION = "0.3.2";
 var plugin = {
   meta: { name: "@noctcore/eslint-plugin-architecture", version: VERSION },
   rules,

package/docs/rules/barrel-purity.md

@@ -14,25 +14,26 @@ folder now silently pulls that behavior in, and the folder no longer has a clean
 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
+```ts good filename=src/components/Card/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 CardView } 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
+import Card from './Card';
+export default Card;                    // re-export of a binding by name
+```
+
+```ts bad reports=7 filename=src/components/Card/index.ts
+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

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

@@ -14,7 +14,7 @@ is obvious when missing.
 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.
 
-```
+```text prose reason="the rule checks for a sibling test file on disk"
 src/hooks/useCart.ts          ← include: ['**/use*.ts']
 src/hooks/useCart.test.ts      ✓ colocated test present
 src/hooks/useWishlist.ts       ✗ no useWishlist.test.* / .spec.* sibling

package/docs/rules/component-folder-structure.md

@@ -9,13 +9,19 @@ In a folder-per-component layout, a component is a folder — not a lone `.tsx`.
 `index.ts` barrel always travel with the component, refactors stay local and nothing is quietly
 untested or undocumented. This rule enforces that colocation by construction.
 
+A purely presentational component has no logic to extract, and its `.hooks.ts` ends up as an
+`export {};` with a comment. That is the cost of the convention, and it is deliberate: the file
+being present means there is one obvious place for logic to go the day the component grows some,
+and a reviewer never has to ask where it lives. A project that disagrees drops `.hooks.ts` from
+`requiredSiblings` rather than carrying stub files.
+
 ## What it flags
 
 For every **component entry file** — a PascalCase `.tsx` whose basename equals its parent folder
 (`TaskCard/TaskCard.tsx`) — that lives under the configured `componentRoot`, the rule reads the
 component's directory and reports any sibling from the required set that is missing on disk.
 
-```
+```text prose reason="the rule checks for sibling files on disk"
 components/board/TaskCard/
   TaskCard.tsx          ← entry file (checked)
   TaskCard.hooks.ts     ┐

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

@@ -22,10 +22,30 @@ The rule first resolves the file's **primary export**:
 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)
+```ts bad filename=src/utils/helpers.ts
+// genuine mismatch
+export const formatDate = () => {};
+```
+
+Renaming the file is one fix, renaming the export the other:
+
+```ts good filename=src/utils/format-date.ts relocation
+export const formatDate = () => {};
+```
+
+```ts good filename=src/utils/helpers.ts
+export const helpers = () => {};
+```
+
+The comparison ignores case and separators:
+
+```tsx good filename=src/components/TaskCard.tsx relocation
+export default function TaskCard() {}
+```
+
+```ts good filename=src/hooks/use-thing.ts relocation
+// kebab-case file, camelCase export
+export const useThing = () => {};
 ```
 
 `index` files and files matching an `ignore` glob are always skipped.

package/docs/rules/index-must-reexport-default.md

@@ -15,7 +15,7 @@ The rule only activates for an `index.ts` that sits next to a `<Folder>.tsx` of
 name on disk (`Card/Card.tsx` beside `Card/index.ts`). For those barrels, it reports when the file
 never re-exports the sibling's default export.
 
-```ts
+```ts prose reason="the rule only runs when a sibling Card.tsx exists on disk"
 // Card/index.ts
 
 export { default as Card } from './Card'; // ✓

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

@@ -14,10 +14,13 @@ reach before it must become an alias.
 Any relative specifier whose leading `..` run exceeds `max` is reported, on every source-carrying
 construct: `import`, `import()`, `export … from`, and `export * from`.
 
-```ts
+```ts bad
 // max: 3 (default)
-import a from '../../../shared';        // ✓ exactly at the limit
-import b from '../../../../shared/log'; // ✗ climbs 4 levels
+import b from '../../../../shared/log'; // climbs 4 levels
+```
+
+```ts good
+import a from '../../../shared';        // exactly at the limit
 ```
 
 ## Autofix
@@ -31,9 +34,13 @@ When `alias` maps a directory-anchor segment to an alias prefix, a too-deep impo
 }]
 ```
 
-```ts
-// from src/a/b/c/d/deep.ts
-import x from '../../../../shared/log'; // → import x from '@/shared/log';
+```ts bad filename=src/a/b/c/d/deep.ts options={"alias":{"src":"@"}}
+// autofixes to: import x from '@/shared/log';
+import x from '../../../../shared/log';
+```
+
+```ts good filename=src/a/b/c/d/deep.ts options={"alias":{"src":"@"}}
+import x from '@/shared/log';
 ```
 
 With no matching alias anchor on the resolved path, the violation is **reported without a fix** —

package/docs/rules/no-cross-feature-imports.md

@@ -24,13 +24,14 @@ Both the alias form (`<alias>/<feature>/…`) and relative paths that climb into
 to forbid them). Imports of the current feature, of a shared feature, or of non-feature modules are
 always fine.
 
-```tsx
-// in components/board/Board/Board.tsx
+```tsx good filename=src/components/board/Board/Board.tsx options={"featureRoot":"components","alias":"@/components","sharedFeatures":["ui"]}
+import { Button } from '@/components/ui/Button';         // shared feature
+import { cn } from '@/lib/utils';                        // non-feature module
+import { TaskCard } from '../TaskCard/TaskCard';         // same feature
+```
 
-import { Button } from '@/components/ui/Button';         // ✓ shared feature
-import { cn } from '@/lib/utils';                        // ✓ non-feature module
-import { TaskCard } from '../TaskCard/TaskCard';         // ✓ same feature
-import { ProjectCard } from '@/components/projects/…';   // ✗ cross-feature
+```tsx bad filename=src/components/board/Board/Board.tsx options={"featureRoot":"components","alias":"@/components","sharedFeatures":["ui"]}
+import { ProjectCard } from '@/components/projects/ProjectCard'; // cross-feature
 ```
 
 ## Options

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

@@ -30,16 +30,16 @@ The rule classifies by **AST shape**, never by filename or suffix:
 
 ## Examples
 
-```ts
-// ✗ a type and a runtime constant
+```ts bad
+// a type and a runtime constant
 export interface User {
   id: string;
 }
 export const DEFAULT_USER: User = { id: 'anonymous' };
 ```
 
-```ts
-// ✗ a component and a hook
+```tsx bad
+// a component and a hook
 export function UserCard() {
   return <div />;
 }
@@ -48,8 +48,8 @@ export function useUserCard() {
 }
 ```
 
-```ts
-// ✓ one concern: types only
+```ts good
+// one concern: types only
 export interface User {
   id: string;
 }
@@ -62,8 +62,8 @@ Only the **exported** surface defines a module (`ignorePrivateDeclarations`, def
 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
+```tsx good
+// the helper is private
 function renderBadge(count: number) {
   return <span className="badge">{count}</span>;
 }
@@ -72,8 +72,8 @@ export function Inbox({ unread }: { unread: number }) {
 }
 ```
 
-```ts
-// ✓ the filter object is private
+```ts good
+// the filter object is private
 const ACTIVE_FILTER = { status: 'active', archived: false } as const;
 export function useActiveProjects() {
   return useQuery({ queryKey: ['projects', ACTIVE_FILTER] });
@@ -85,7 +85,7 @@ is surface all the same.
 
 ## Options
 
-```ts
+```ts prose reason="the options type, not a lint example"
 type SemanticCategory =
   | 'type' | 'constant' | 'function' | 'class'
   | 'react-component' | 'hook' | 'schema' | 'enum';
@@ -134,16 +134,20 @@ export default [
 ];
 ```
 
-```ts
-// ✓ billing.constants.ts with the config above
+```ts good filename=apps/api/src/billing/billing.constants.ts options={"allow":[["constant","type","enum"]]}
+// 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
+```ts bad filename=apps/api/src/billing/billing.constants.ts options={"allow":[["constant","type","enum"]]}
+// still reported: a function is outside the allowed group
+export const INVOICE_STATUSES = ['draft', 'sent', 'paid'] as const;
+export type InvoiceStatus = (typeof INVOICE_STATUSES)[number];
 export function isPaid(status: InvoiceStatus) {
   return status === 'paid';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/eslint-plugin-architecture",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Framework-agnostic folder-per-component and feature-boundary architecture ESLint rules.",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@noctcore/eslint-utils": "^0.1.0",
+    "@noctcore/eslint-utils": "^0.1.1",
     "@typescript-eslint/utils": "^8.61.1"
   },
   "peerDependencies": {