npm package: @locins/codequality
Description: Shared code quality config for the Locins ecosystem — ESLint, Prettier, Commitlint
Latest version: 1.0.0

# @locins/codequality

Shared code quality config for the Locins ecosystem. ESLint, Prettier, Commitlint, Husky, and lint-staged — one package, one command.

## Quick Start

```bash
npx @locins/codequality init
```

This will:

1. Detect your project type (NestJS, Next.js, Expo, React, or base TypeScript)
2. Ask for confirmation
3. Generate all config files
4. Update your `package.json` with scripts, prettier, lint-staged, and devDependencies
5. Set up Husky git hooks

After running, install dependencies:

```bash
pnpm install
```

## What Gets Generated

### Config Files

| File                    | Purpose                               |
| ----------------------- | ------------------------------------- |
| `eslint.config.mjs`     | ESLint config (project-type-specific) |
| `commitlint.config.mjs` | Conventional Commits enforcement      |
| `.prettierignore`       | Files excluded from formatting        |
| `.husky/pre-commit`     | Runs lint-staged on staged files      |
| `.husky/commit-msg`     | Validates commit message format       |
| `.husky/pre-push`       | Runs type-check before push           |

### package.json Changes

```json
{
  "scripts": {
    "lint": "eslint .",
    "type-check": "tsc --noEmit",
    "prepare": "husky"
  },
  "prettier": "@locins/codequality/prettier",
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix --max-warnings 0"],
    "*.{ts,tsx,json,md,mjs}": ["prettier --write"]
  }
}
```

For Turborepo monorepos, `lint` and `type-check` scripts use `turbo` instead.

## ESLint Configs

### Base (`@locins/codequality/eslint/base`)

For any TypeScript project. Includes:

- TypeScript strict rules (no `any`, no unused vars)
- SonarJS (cognitive complexity max 15, duplicate detection)
- Security plugin (unsafe patterns)
- Import sorting and unused import removal
- Prettier integration
- Size limits: 300 lines/file, 50 lines/function, max depth 4, max params 5
- No `console.log`, no magic numbers

```js
import { baseConfig } from '@locins/codequality/eslint/base'
export default [...baseConfig]
```

### NestJS (`@locins/codequality/eslint/nest`)

Extends base with strict type-checked rules for NestJS APIs:

- Floating promise detection
- Relaxed rules for NestJS patterns (decorators, DI tokens)
- Test file overrides (relaxed complexity, magic numbers, etc.)

```js
import { nestConfig } from '@locins/codequality/eslint/nest'

export default [
  ...nestConfig,
  {
    files: ['src/**/*.ts'],
    languageOptions: {
      parserOptions: {
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
]
```

### React (`@locins/codequality/eslint/react`)

Extends base with relaxed rules for React:

- Magic numbers allowed (component props, styles)
- Duplicate strings allowed (JSX text)
- Function size limit raised to 80 lines

```js
import { reactConfig } from '@locins/codequality/eslint/react'
export default [...reactConfig]
```

### Next.js (`@locins/codequality/eslint/next`)

Extends React config, adds `.next/` to ignores.

```js
import { nextConfig } from '@locins/codequality/eslint/next'
export default [...nextConfig]
```

### Expo (`@locins/codequality/eslint/expo`)

Extends React config, adds `.expo/`, `android/`, `ios/` to ignores.

```js
import { expoConfig } from '@locins/codequality/eslint/expo'
export default [...expoConfig]
```

## Other Configs

### Prettier (`@locins/codequality/prettier`)

```
No semicolons | Single quotes | Trailing commas | 100 char lines | 2 space indent | LF endings
```

Usage in `package.json`:

```json
{ "prettier": "@locins/codequality/prettier" }
```

### Commitlint (`@locins/codequality/commitlint`)

Enforces [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(scope): add new feature
fix(scope): fix a bug
refactor(scope): refactor code
docs | style | test | chore | ci | perf | revert
```

- Header max 100 characters
- Body max 200 characters per line
- Scopes are optional but encouraged

### Lint-Staged (`@locins/codequality/lint-staged`)

Exported config object for programmatic use:

```js
import lintStagedConfig from '@locins/codequality/lint-staged'
```

## Git Hooks

| Hook         | Action              | Purpose                    |
| ------------ | ------------------- | -------------------------- |
| `pre-commit` | `pnpm lint-staged`  | Lint + format staged files |
| `commit-msg` | `commitlint --edit` | Validate commit message    |
| `pre-push`   | `pnpm type-check`   | Full type safety check     |

## Security Features

### Secret Scanning (Pre-commit)

Automatically scans staged files for leaked secrets before every commit:

- AWS Access Keys
- Private Keys (PEM)
- Stripe API Keys
- GitHub/GitLab Tokens
- Database Connection Strings
- JWT Tokens
- Generic secrets in variable assignments

Test files and `.example` files are excluded. To suppress a false positive, add a comment:

```js
// codequality-ignore-secret
const exampleKey = 'not-a-real-secret'
```

### Dependency Audit (Pre-push)

Runs `pnpm audit --prod --audit-level=high` before every push. Blocks on `high` or `critical` vulnerabilities. Non-blocking if the registry is unreachable (offline development).

### Branch Naming Convention (Pre-push)

Enforces branch names to follow the pattern:

- `main`, `master`, `develop`, `staging`
- `feature/*`, `fix/*`, `bugfix/*`, `hotfix/*`
- `chore/*`, `docs/*`, `refactor/*`, `test/*`, `release/*`
- `ci/*`, `perf/*`, `revert/*`

### ESLint Security Rules

All `eslint-plugin-security` rules run as **errors** (not warnings), blocking commits. Additional regex security via `eslint-plugin-regexp` catches ReDoS vulnerabilities.

### Import Restrictions

Frontend configs (React, Next.js, Expo) block imports of Node.js-only modules (`fs`, `child_process`, `net`, etc.) to prevent accidental server-side code in client bundles.

### .gitignore Template

The `init` command generates (or extends) a `.gitignore` that excludes:

- Source maps (`*.map`)
- Secrets (`*.pem`, `*.key`, `.env.*`, `credentials.json`)
- Cloud credentials (`.aws/`, `.gcloud/`, `.kube/`)
- IDE files, OS files, logs

### Test Coverage (Pre-push)

Runs tests before push. Configure coverage thresholds in your test config (Jest/Vitest):

```json
"coverageThreshold": {
  "global": { "branches": 80, "functions": 80, "lines": 80, "statements": 80 }
}
```

### License Compliance (Pre-push)

Scans production dependencies for copyleft/disallowed licenses (GPL, AGPL, SSPL, etc.). Only permits permissive licenses (MIT, ISC, BSD, Apache-2.0, etc.).

### Bundle Size Guard (Pre-push)

Checks build output for oversized bundles:

- Total bundle: max 10 MB
- Single file: max 2 MB

Skipped if no build output exists.

### Accessibility Linting (React/Next.js/Expo)

Frontend configs include `eslint-plugin-jsx-a11y` for accessibility best practices. Catches missing alt text, invalid ARIA attributes, and other a11y issues.

### Copy-Paste Detection (Pre-push)

Detects duplicated code blocks using `jscpd`. Blocks push if code duplication exceeds 5%. Requires `jscpd` to be installed (`pnpm add -D jscpd`).

### Dead Code Detection (Pre-push)

Detects unused exports, files, and dependencies using `knip`. Requires `knip` to be installed (`pnpm add -D knip`).

### Circular Dependency Detection (Pre-push)

Detects circular imports using `madge`. Blocks push if any circular dependencies are found. Requires `madge` to be installed (`pnpm add -D madge`).

## Project Type Detection

The `init` command detects your project type from `package.json` dependencies:

| Dependency     | Detected Type |
| -------------- | ------------- |
| `@nestjs/core` | nest          |
| `next`         | next          |
| `expo`         | expo          |
| `react`        | react         |
| None           | base          |

If multiple types are detected, you'll be prompted to choose.

## Requirements

- Node.js >= 18
- pnpm (recommended), npm, or yarn