# Lint and Format Adoption Guide

> Status: design approved by the architecture blueprint; tooling not installed in this
> checkpoint.

## 1. Current state

- Node.js runtime: 18.17.1 minimum;
- module system: CommonJS with `module-alias`;
- tests: built-in `node:test` and `assert`;
- ESLint dependency/config: absent;
- Prettier dependency/config: absent;
- code style: mixed quotes, indentation, declaration styles, and semicolon usage;
- generated/vendor/minified/browser assets: large and must not be bulk-formatted.

`package.json` is frozen by project rules. No package is installed or script changed by
the blueprint wave. Installing lint dependencies requires explicit approval.

## 2. Adoption principle

Linting is a regression-prevention tool, not a pretext for a repository-wide formatting
diff. Adoption is changed-files-first and domain-by-domain.

Never run `eslint . --fix` or `prettier . --write` across the legacy repository as the
first step.

## 3. Proposed dependencies

After explicit package approval, use versions compatible with Node 18 and CommonJS:

```text
eslint
prettier
```

No TypeScript or module-system conversion is part of this work. Additional plugins are
added only when a concrete rule needs them.

## 4. Proposed scripts

The first implementation wave should target explicit paths rather than `.`:

```json
{
  "lint:changed": "eslint <changed-js-files>",
  "format:check:changed": "prettier --check <changed-files>"
}
```

Only after module waves are green may the project add:

```json
{
  "lint": "eslint .",
  "lint:fix": "eslint . --fix",
  "format": "prettier . --write",
  "format:check": "prettier . --check"
}
```

The exact changed-file command should be implemented as a small package-independent Node
script if cross-platform Git diff discovery is needed.

## 5. Initial lint policy

Phase 1 rules should detect correctness issues without forcing legacy style changes:

- syntax/parser errors;
- undefined variables;
- accidental globals;
- unreachable code;
- duplicate case labels/keys where supported;
- invalid regular expressions;
- unused disable directives;
- unsafe equality only when enabling it does not create a mass legacy failure;
- Node and CommonJS globals;
- `node:test` files with test globals imported explicitly.

Style-only rules remain off initially. `no-unused-vars`, complexity, max-lines,
`no-console`, and quote/semicolon rules begin as reports or scoped module rules because
the current code contains large legacy hotspots.

## 6. Ignore policy

Lint/format tools must ignore at least:

```text
node_modules/
public/admin/app-assets/
public/admin/assets/vendor/
public/admin/assets/libs/
public/admin/assets/fonts/
public/admin/ui-lab/screenshots/
public/assets/uploads/
public/api-docs/openapi.json
public/api-docs/exports/
postman/.export-meta.json
postman/*collection.json
postman/*environment.json
*.min.js
*.min.css
package-lock.json          # until lockfile formatting is intentionally reviewed
```

Generated permissions/locales are linted only by their generator contract tests, not
automatically rewritten by Prettier.

## 7. Staged rollout

### L0 — configuration proof

- explicit package approval;
- add config/ignore files;
- lint one new documentation/QA script and one low-risk module;
- no auto-fix outside the selected paths.

### L1 — changed files

- every architecture wave runs lint/format check on its changed JS/JSON/Markdown/EJS
  subset where supported;
- formatting changes stay in a separate commit/diff from behavior changes when possible.

### L2 — low-risk domains

- Reasons, Socials, Countries/Cities, Coupons, and package catalogue modules;
- fix warnings inside one module only;
- add a per-module zero-warning gate.

### L3 — adapters and shared infrastructure

- API/dashboard/socket adapters and shared utilities after their contract tests exist;
- progressively enable `no-console`, unused-variable, and complexity rules.

### L4 — high-risk domains

- identity, providers, products, orders, auctions, and payments;
- never combine broad formatting with state-machine or contract changes.

### L5 — whole-project check

- only after all active runtime families are migrated or have an explicit baseline;
- generated/vendor trees remain ignored permanently.

## 8. Prettier policy

- formatting must not change EJS output semantics;
- no automatic formatting of minified/vendor/generated files;
- no formatting of OpenAPI/Postman generated JSON unless the generator owns it;
- no repository-wide line-ending churn;
- review template literals, regex route definitions, and chained Express middleware
  manually after formatting.

## 9. Gate and rollback

Every lint/format wave must pass syntax, focused tests, full `npm test`, and
`git diff --check`. If a formatter creates a broad unrelated diff, revert that formatting
wave rather than accepting review noise.

Current status: **BLOCKED_BY_PACKAGE_APPROVAL**, with no runtime or package changes made.