@stride.it/appoint-lint-governance 0.1.24 → 0.1.25

package/README.md

@@ -1,91 +1,162 @@
-# @stride-info-tech/appoint-lint-governance
+# @stride.it/appoint-lint-governance
 
-Shareable ESLint **flat-config** profiles for normalizing lint rules across repositories.
+Shareable ESLint v9 flat-config builders to normalize TypeScript linting across repositories.
 
-## TypeScript profiles
+This package focuses on framework-agnostic TypeScript quality gates (correctness, imports hygiene, security, maintainability, and optional type-aware checks). It is designed to be composed in consumer repos, not to enforce an all-or-nothing mega-config.
 
-Profiles are flat-config builders intended to be composed:
+## What you get
 
-- `typescriptBase()` — parser + baseline correctness/hygiene
-- `typescriptMinimal()` — MVP (currently the same as Base)
-- `typescriptQuality()` — unicorn + sonarjs maintainability rules
-- `typescriptImports()` — import correctness + deterministic sorting
-- `typescriptSecurity()` — rushstack security + regexp safety
-- `typescriptDocs()` — eslint-comments hygiene + jsdoc basics
-- `typescriptTypeAware()` — type-checked rules (opt-in via project/tsconfig)
-- `typescriptPrettierInterop()` — disable formatting conflicts when using Prettier
-- `typescriptRecommended()` — composes Base + Quality + Imports + Security + Docs; optionally type-aware via `typeChecked: true`
+- Composable flat-config builders (arrays of ESLint config objects).
+- A minimal baseline for fast adoption.
+- A recommended preset that composes the major rule groups.
+- Optional type-aware rules (requires a TSConfig project).
+- Optional Prettier interop preset to disable formatting-rule conflicts.
+
+Non-goals:
+
+- No framework/domain targeting (React/Next/Vue/a11y/test-runner plugins are out of scope).
+- No formatting (Prettier remains the formatter; ESLint formatting conflicts are disabled via the interop preset).
 
 ## Install
 
 In a consumer repo:
 
 ```bash
-pnpm add -D @stride-info-tech/appoint-lint-governance eslint
+pnpm add -D @stride.it/appoint-lint-governance eslint
 ```
 
-## Use in a consumer repo (ESLint v9 flat config)
+ESLint is a peer dependency; your repo owns the ESLint version.
+
+## Quick start (ESLint v9 flat config)
 
 Create (or edit) `eslint.config.mjs`:
 
 ```js
 import { typescriptMinimal } from "@stride.it/appoint-lint-governance";
 
-export default [
- ...typescriptMinimal(),
-];
+export default [...typescriptMinimal()];
 ```
 
-### Type-Aware Linting (Optional)
+Run ESLint in your repo as usual:
+
+```bash
+pnpm lint
+```
+
+## Public API
+
+These builders return arrays you spread into your `eslint.config.*`:
+
+- `typescriptBase(options?)`\
+  Baseline correctness + safe defaults (files globs, languageOptions).
+- `typescriptMinimal(options?)`\
+  Minimal preset (fast adoption baseline).
+- `typescriptRecommended(options?)`\
+  Recommended preset that composes core groups and can optionally enable type-aware rules.
+- `typescriptPrettierInterop(options?)`\
+  Disables formatting-rule conflicts when the consumer repo uses Prettier.
 
-To enable powerful Type-Aware rules (verifies promise handling, proper awaiting, etc.), provide `typeChecked: true` and project details:
+Additionally:
+
+- `plugin`\
+  Optional plugin export used by internal configs.
+
+## Recommended preset (most repos)
+
+```js
+import { typescriptRecommended } from "@stride.it/appoint-lint-governance";
+
+export default [...typescriptRecommended()];
+```
+
+### Type-aware linting (optional)
+
+Type-aware rules can catch issues ESLint cannot detect from syntax alone (for example: misused promises, unsafe operations). They require a TSConfig project.
 
 ```js
 import { typescriptRecommended } from "@stride.it/appoint-lint-governance";
 
 export default [
- ...typescriptRecommended({
-   typeChecked: true,
-   tsconfigPath: "./tsconfig.json",
-   tsconfigRootDir: import.meta.dirname, // Requires Node.js 20.11+ or 22+
- }),
+  ...typescriptRecommended({
+    typeChecked: true,
+    tsconfigPath: "./tsconfig.json",
+    tsconfigRootDir: import.meta.dirname,
+  }),
 ];
 ```
 
-### Prettier Interop (Optional)
+If your Node.js version does not support `import.meta.dirname`, use this portable alternative:
 
-If your project uses [Prettier](https://prettier.io/) for formatting, you must disable conflicting formatting rules. Include this **last** to ensure it overrides any other formatting rules:
+```js
+import { fileURLToPath } from "node:url";
+
+const tsconfigRootDir = fileURLToPath(new URL(".", import.meta.url));
+```
+
+Then pass `tsconfigRootDir` into `typescriptRecommended({ ... })`.
+
+## Prettier interop (optional)
+
+If your project uses Prettier, include the interop preset last so it can override earlier formatting rules:
 
 ```js
-import { typescriptRecommended, typescriptPrettierInterop } from "@stride.it/appoint-lint-governance";
+import {
+  typescriptPrettierInterop,
+  typescriptRecommended,
+} from "@stride.it/appoint-lint-governance";
 
 export default [
- ...typescriptRecommended(),
- // ... other configs
- ...typescriptPrettierInterop(), // Must be last
+  ...typescriptRecommended(),
+  ...typescriptPrettierInterop(),
 ];
 ```
 
-## Local testing (before publishing to npm)
+## Overriding rules in consumer repos
+
+Flat config is order-dependent: later entries win. Consumers can override by appending their own config object after spreading a preset.
+
+If your organization wants to prevent overrides, ESLint itself cannot lock consumer rules; enforce that with CI/policy checks on the consumer repo’s `eslint.config.*`.
+
+## Suggested companion quality gates (outside ESLint)
+
+This package intentionally focuses on ESLint rules. Many teams also enforce these CI gates:
+
+- Type checking: `tsc --noEmit`
+- Dependency audit: `pnpm audit` (or your org-approved alternative)
+- Secret scanning and SAST (org-dependent)
 
-From this repo:
+## Development (this repo)
 
 ```bash
 pnpm install
+pnpm test
 pnpm build
+```
+
+To validate the publish output locally:
+
+```bash
 npm pack
 ```
 
-Then in a different repo, install the generated `.tgz`:
+Then install the generated `.tgz` into a consumer repo.
+
+## Publishing
+
+1) Bump version:
 
 ```bash
-pnpm add -D ../appoint-lint-governance/<generated-file>.tgz
+pnpm version patch
 ```
 
-## Can consumer repos override rules?
+1) Dry run:
 
-Yes.
+```bash
+pnpm publish --dry-run
+```
 
-In flat config, **later config entries win**. So a consumer can override by adding their own config object after spreading the profile (as shown above).
+1) Publish (requires npm credentials with access to the `@stride.it` scope):
 
-If you want to prevent overrides for governance reasons, ESLint itself cannot “lock” consumer rules — you’d enforce that via policy/CI (for example: validate `eslint.config.*` in consumers and fail if it sets forbidden overrides).
+```bash
+pnpm publish --access public
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stride.it/appoint-lint-governance",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Shareable ESLint flat-config profiles (MVP: TypeScript) for normalizing lint across repos.",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,7 +11,6 @@
       "import": "./dist/index.js"
     }
   },
-  "packageManager": "pnpm@9.0.0",
   "files": [
     "dist",
     "README.md"
@@ -19,13 +18,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "lint": "eslint . --fix",
-    "lint:fix": "eslint . --fix",
-    "prepack": "pnpm build",
-    "test": "vitest run --passWithNoTests"
-  },
   "dependencies": {
     "@eslint-community/eslint-plugin-eslint-comments": "^4.6.0",
     "eslint-config-prettier": "^10.1.8",
@@ -51,5 +43,11 @@
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint . --fix",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run --passWithNoTests"
   }
 }