eslint-plugin-unslop 0.2.1 → 0.2.2

package/README.md

@@ -12,7 +12,7 @@ npm install --save-dev eslint-plugin-unslop
 
 ## Quick Start
 
-The recommended config enables the three most universal rules out of the box:
+The recommended config enables the two most universal rules out of the box:
 
 ```js
 // eslint.config.mjs
@@ -27,7 +27,6 @@ This turns on:
 | --------------------------- | -------- | ------------------------------------------------------------------- |
 | `unslop/no-special-unicode` | error    | Catches smart quotes, invisible spaces, and other unicode impostors |
 | `unslop/no-unicode-escape`  | error    | Prefers `"©"` over `"\u00A9"`                                       |
-| `unslop/no-deep-imports`    | error    | Prevents importing too deep within the same top-level folder        |
 
 The remaining rules need explicit configuration:
 
@@ -86,37 +85,55 @@ const copyright = '© 2025'
 const arrow = '→'
 ```
 
-### `unslop/no-deep-imports`
+### `unslop/import-control`
 
-**Recommended**
+Think of this as customs control for your modules — you declare which modules are allowed to import from which, and anything undeclared gets turned away at the border.
 
-Forbids importing more than one level deeper than the current file within the same top-level folder. If `features/auth/login.ts` imports from `features/auth/validators/internal/format.ts`, that's reaching too deep into implementation details. This rule nudges you toward flatter structures and proper module boundaries.
+The rule reads from a shared policy in `settings.unslop.architecture`. It's deny-by-default for cross-module imports, which means forgetting to declare a dependency is a loud error rather than a silent free-for-all. It also enforces:
 
-Only triggers for imports within the same top-level folder. External packages and imports into other top-level folders are ignored.
+- cross-module imports must arrive through the public gate (`index.ts` or `types.ts`)
+- 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)
 
-#### Options
+#### Configuration
 
 ```js
-;['error', { sourceRoot: 'src' }]
-```
-
-| Option       | Type     | Default       | Description                               |
-| ------------ | -------- | ------------- | ----------------------------------------- |
-| `sourceRoot` | `string` | auto-detected | Source directory relative to project root |
-
-#### Examples
+// eslint.config.mjs
+import unslop from 'eslint-plugin-unslop'
 
-Given a project with `sourceRoot: 'src'`:
+export default [
+  {
+    settings: {
+      unslop: {
+        sourceRoot: 'src',
+        architecture: {
+          utils: { shared: true },
+          'repository/*': {
+            imports: ['utils', 'models/*'],
+            exports: ['^create\\w+Repo$', '^Repository[A-Z]\\w+$'],
+          },
+          'models/*': {
+            imports: ['utils'],
+          },
+          app: {
+            imports: ['*'],
+          },
+        },
+      },
+    },
+    rules: {
+      'unslop/import-control': 'error',
+      'unslop/export-control': 'error',
+    },
+  },
+]
+```
 
-```js
-// File: src/features/auth/login.ts
+### `unslop/export-control`
 
-// OK — one level deep, same folder
-import { validate } from './validators/email.js'
+The customs declaration form for the other direction: what are you actually exporting from your module's public entrypoints?
 
-// Bad — two levels deep into same top-level folder
-import { format } from './validators/internal/format.js'
-```
+When a module defines `exports` regex patterns in `settings.unslop.architecture`, every symbol exported from that module's `index.ts` or `types.ts` must match at least one pattern — otherwise it's stopped at the gate with an error at the export site. Modules without `exports` are waved through by default, so you can adopt this gradually.
 
 ### `unslop/no-false-sharing`
 
@@ -273,6 +290,58 @@ Yes, a fair amount of this was vibe-coded with LLM assistance — which is fitti
 
 The project also dogfoods itself: `eslint-plugin-unslop` is linted using `eslint-plugin-unslop`.
 
+## Maintainer: Main Branch Protection
+
+This repository treats `main` as a protected branch with pull-request-only merges.
+
+Baseline policy:
+
+- Require pull requests before merge
+- Require at least 1 approving review
+- Dismiss stale approvals when new commits are pushed
+- Require branch to be up to date before merge
+- Require status check: `PR Gate`
+- Apply restrictions to admins too (`enforce_admins`)
+
+The required check is produced by `.github/workflows/test.yml` (workflow/job name: `PR Gate`) and runs:
+
+1. `npm run verify`
+2. `npm run test`
+
+### Safe Workflow Renames
+
+If you rename the workflow or job that produces `PR Gate`, update branch protection required checks immediately to match the new check context.
+
+Recommended update command:
+
+```bash
+gh api -X PUT repos/skhoroshavin/eslint-plugin-unslop/branches/main/protection \
+  -H "Accept: application/vnd.github+json" \
+  -F 'required_status_checks[strict]=true' \
+  -F 'required_status_checks[contexts][]=PR Gate' \
+  -F 'enforce_admins=true' \
+  -F 'required_pull_request_reviews[dismiss_stale_reviews]=true' \
+  -F 'required_pull_request_reviews[require_code_owner_reviews]=false' \
+  -F 'required_pull_request_reviews[required_approving_review_count]=1' \
+  -F 'restrictions=null'
+```
+
+### Branch Protection Audit
+
+Run these checks periodically:
+
+```bash
+gh api repos/skhoroshavin/eslint-plugin-unslop/branches/main/protection
+gh run list --workflow "PR Gate" --limit 5
+```
+
+Expected audit outcomes:
+
+- `required_status_checks.contexts` includes `PR Gate`
+- `required_pull_request_reviews.required_approving_review_count` is `1` or greater
+- `required_pull_request_reviews.dismiss_stale_reviews` is `true`
+- `enforce_admins.enabled` is `true`
+
 ## Contributing
 
 See [AGENTS.md](./AGENTS.md) for development setup and guidelines.