eslint-plugin-unslop 0.5.2 → 0.6.0

package/README.md

@@ -26,10 +26,10 @@ export default [
         architecture: {
           utils: { shared: true },
           'repository/*': {
-            imports: ['utils', 'models/*'],
+            imports: ['utils', 'models/+'],
             exports: ['^create\\w+Repo$', '^Repository[A-Z]\\w+$'],
           },
-          'models/*': {
+          models: {
             imports: ['utils'],
           },
           app: {
@@ -42,11 +42,12 @@ export default [
 ]
 ```
 
-Architecture rules (`import-control`, `export-control`, `no-false-sharing`, `no-single-use-constants`) require a reachable `tsconfig.json`. Set `compilerOptions.rootDir`, and if you use aliases, configure `compilerOptions.paths`.
+Architecture rules (`import-control`, `no-whitebox-testing`, `export-control`, `no-false-sharing`, `no-single-use-constants`) require a reachable `tsconfig.json`. Set `compilerOptions.rootDir`, and if you use aliases, configure `compilerOptions.paths`.
 
 | Rule                             | What it does                                                           |
 | -------------------------------- | ---------------------------------------------------------------------- |
 | `unslop/import-control`          | Enforces module boundaries and forbids local namespace imports         |
+| `unslop/no-whitebox-testing`     | Keeps tests on module entrypoints instead of same-folder internals     |
 | `unslop/export-control`          | Restricts export patterns and forbids `export *` in module entrypoints |
 | `unslop/no-false-sharing`        | Flags shared entrypoint symbols with fewer than two consumer groups    |
 | `unslop/no-single-use-constants` | Flags module-scope constants used once or never across the project     |
@@ -65,17 +66,42 @@ export default [unslop.configs.minimal]
 
 ## Architecture Settings
 
-All architecture rules read from `settings.unslop.architecture`. Each key is a module matcher (path segments, `*` per segment), and each value is a policy object:
+All architecture rules read from `settings.unslop.architecture`. Each file first resolves to a canonical module path equal to its containing directory relative to the source root from `tsconfig.json`.
+
+- `src/index.ts` -> `.`
+- `src/models/index.ts` -> `models`
+- `src/models/user/index.ts` -> `models/user`
+- `src/models/user/internal.ts` -> `models/user`
+
+Architecture keys are directory-shaped subtree selectors:
+
+- `.` matches the source-root module
+- `models` owns `models` and everything below it
+- `models/*` owns each direct child subtree under `models`, such as `models/user` and `models/user/internal`
+
+File-shaped keys like `index.ts` or `rules/public.ts` are not supported.
+
+Each value is a policy object:
 
 ```ts
 {
-  imports?: string[]  // module matchers this module may import from; '*' allows all
-  exports?: string[]  // regex patterns symbols exported from index.ts/types.ts must match
+  imports?: string[]  // exact module, direct child via /*, self-or-child via /+, or '*' for all
+  exports?: string[]  // regex patterns symbols exported from entrypoints must match
+  entrypoints?: string[] // public files allowed for external and test imports
   shared?: boolean    // marks module as shared; enables no-false-sharing
 }
 ```
 
-Best match wins by fewest wildcards, then longest matcher, then declaration order. All architecture rules take no options - policy comes entirely from this shared settings block.
+Architecture keys and import allowlists use different matching rules:
+
+- keys assign ownership to subtrees
+- `imports: ['models']` allows only the exact `models` module
+- `imports: ['models/*']` allows only direct children like `models/user`
+- `imports: ['models/+']` allows `models` and direct children like `models/user`
+
+When multiple keys cover the same canonical module path, the winner is chosen by nearest owner first, then exact named path over wildcard path at the same depth, then longer selector path, then declaration order. Unmatched canonical module paths become anonymous modules with empty `imports`, empty `exports`, `shared: false`, and default `entrypoints: ['index.ts']`.
+
+All architecture rules take no options. Policy comes entirely from this shared settings block.
 
 ## Rules
 
@@ -85,18 +111,24 @@ Customs control for your modules: you declare which modules are allowed to impor
 
 Deny-by-default for cross-module imports, so forgetting to declare a dependency is a loud error rather than a silent free-for-all. It also enforces:
 
-- cross-module imports must arrive through the public gate (`index.ts` or `types.ts`)
+- cross-module imports must arrive through the public gate (configured entrypoints)
 - local cross-module namespace imports are forbidden (`import * as X from '<local-module>'`)
 - same-module relative imports can only go one level deeper - no tunnelling into internals
-- files that don't match any declared module are denied (fail-closed, not fail-silently)
+- files that don't match any declared module become anonymous modules and are denied by default
 
 Alias imports are resolved via `compilerOptions.paths` from `tsconfig.json`.
 
+### `unslop/no-whitebox-testing`
+
+Keeps test files black-boxed. When a recognized test file lives beside a module's implementation, it must import that module through its public entrypoint (`.`, `./index`, or a configured `entrypoints` file) instead of reaching into sibling files like `./model.ts`.
+
+This rule only checks recognized test filenames (`*.test.*`, `*.spec.*`, `*.*-test.*`, `*.*-spec.*`). Child submodule imports and cross-module imports are left to `unslop/import-control`.
+
 ### `unslop/export-control`
 
 The customs declaration form for the other direction: what are you actually exporting from your module's public entrypoints?
 
-When a module defines `exports` regex patterns, every symbol exported from its `index.ts` or `types.ts` must match at least one pattern - otherwise it's stopped at the gate. Modules without `exports` are waved through by default, so you can adopt this gradually. Regardless of module policy, `export * from ...` is rejected in public entrypoints so symbol provenance stays explicit.
+When a module defines `exports` regex patterns, every symbol exported from its entrypoints must match at least one pattern - otherwise it's stopped at the gate. Modules without `exports` are waved through by default, so you can adopt this gradually. Regardless of module policy, `export * from ...` is rejected in public entrypoints so symbol provenance stays explicit.
 
 ### `unslop/no-false-sharing`
 
@@ -109,7 +141,7 @@ settings: {
   unslop: {
     architecture: {
       utils: { shared: true },
-      'shared/*': { shared: true },
+      shared: { shared: true },
     },
   },
 }
@@ -123,7 +155,7 @@ src/shared/index.ts
   -> imported only by src/features/calendar/view.ts
   -> error: symbol "formatDate" has 1 consumer group(s) (group: features/calendar)
 
-src/shared/types.ts
+src/shared/index.ts
   export type LegacyOptions = ...
   -> not imported by anyone
   -> error: symbol "LegacyOptions" has 0 consumer group(s) (no consumers found)