@diplodoc/lint 1.3.2 → 1.4.0

package/.editorconfig

@@ -0,0 +1,20 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[{*.json,*.yml,*.yaml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[GNUmakefile]
+indent_style = tab
+indent_size = 4

package/.eslintignore

@@ -0,0 +1,21 @@
+.idea
+.vscode
+.history
+.env
+.DS_Store
+node_modules
+/lib
+/dist
+/build
+/cache
+/coverage
+/external
+# Test files - they use Node.js globals
+test/
+# Scripts use Node.js globals
+scripts/
+
+.lintstagedrc.js
+.eslintrc.js
+.prettierrc.js
+.stylelintrc.js

package/.eslintrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+    root: true,
+    extends: require.resolve('@diplodoc/lint/eslint-config'),
+    parserOptions: {
+        tsconfigRootDir: __dirname,
+        project: true,
+    },
+};

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm run pre-commit

package/.lintstagedrc.js

@@ -0,0 +1,39 @@
+/* eslint-env node */
+module.exports = {
+    // Exclude config files and scripts from linting (they use CommonJS)
+    '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}': (filenames) => {
+        // Filter out config files and scripts
+        const configFiles = [
+            '.lintstagedrc.js',
+            '.eslintrc.js',
+            '.prettierrc.js',
+            '.stylelintrc.js',
+        ];
+        const filtered = filenames.filter(
+            (f) =>
+                !configFiles.some((config) => f.includes(config)) &&
+                !f.includes('scripts/') &&
+                !f.includes('test/'),
+        );
+        if (filtered.length === 0) {
+            return [];
+        }
+        return ['prettier --write', 'eslint --max-warnings=0 --fix --no-warn-ignored'];
+    },
+    '**/*.{css,scss}': ['prettier --write', 'stylelint --fix'],
+    '**/*.{json,yaml,yml,md}': ['prettier --write'],
+    '**/*.{svg,svgx}': ['svgo'],
+    // Run unit tests when test files or source files change
+    '**/*.{ts,tsx}': (filenames) => {
+        const testFiles = filenames.filter((f) => f.includes('.test.') || f.includes('.spec.'));
+        const sourceFiles = filenames.filter(
+            (f) => !f.includes('.test.') && !f.includes('.spec.') && f.includes('src/'),
+        );
+        const commands = [];
+        // Run tests if test files or source files changed
+        if (testFiles.length > 0 || sourceFiles.length > 0) {
+            commands.push('npm test');
+        }
+        return commands;
+    },
+};

package/.prettierignore

@@ -0,0 +1,14 @@
+.idea
+.vscode
+.history
+.env
+.DS_Store
+node_modules
+/lib
+/dist
+/build
+/cache
+/coverage
+/external
+# Test fixtures with invalid JSON
+test/fixtures/package-invalid.json

package/.prettierrc.js

@@ -0,0 +1 @@
+module.exports = require('@diplodoc/lint/prettier-config');

package/.stylelintignore

@@ -0,0 +1,12 @@
+.idea
+.vscode
+.history
+.env
+.DS_Store
+node_modules
+/lib
+/dist
+/build
+/cache
+/coverage
+/external

package/.stylelintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+    extends: require.resolve('@diplodoc/lint/stylelint-config'),
+};

package/AGENTS.md

@@ -0,0 +1,529 @@
+# AGENTS.md
+
+This file contains instructions for AI agents working with the `@diplodoc/lint` project.
+
+## Common Rules and Standards
+
+**Important**: This package follows common rules and standards defined in the Diplodoc metapackage. When working in metapackage mode, refer to:
+
+- **`.agents/style-and-testing.md`** in the metapackage root for:
+  - Code style guidelines
+  - Commit message format (Conventional Commits)
+  - Pre-commit hooks rules (**CRITICAL**: Never commit with `--no-verify`)
+  - Testing standards
+  - Documentation requirements
+- **`.agents/core.md`** for core concepts
+- **`.agents/monorepo.md`** for workspace and dependency management
+- **`.agents/dev-infrastructure.md`** for build and CI/CD
+
+**Note**: In standalone mode (when this package is used independently), these rules still apply. If you need to reference the full documentation, check the [Diplodoc metapackage repository](https://github.com/diplodoc-platform/diplodoc).
+
+## Project Description
+
+`@diplodoc/lint` is a DevOps infrastructure package that provides linting utilities for all Diplodoc platform packages. It consolidates ESLint, Prettier, Stylelint, Husky, and lint-staged configurations into a single package, replacing the deprecated `@diplodoc/eslint-config` and `@diplodoc/prettier-config` packages.
+
+**Key Features**:
+
+- Unified linting infrastructure for all platform packages
+- Automatic infrastructure updates on each run
+- Pre-commit hooks via Husky
+- Multiple ESLint configurations (common, client, node)
+- Prettier and Stylelint configurations
+- SVGO integration for SVG optimization
+
+## Project Structure
+
+### Main Directories
+
+- `bin/` — executable scripts (see detailed description below)
+- `scaffolding/` — template files copied during `init`/`update`
+  - `.eslintrc.js` — ESLint configuration template
+  - `.prettierrc.js` — Prettier configuration template
+  - `.stylelintrc.js` — Stylelint configuration template
+  - `.lintstagedrc.js` — lint-staged configuration template
+  - `.husky/pre-commit` — Husky pre-commit hook template
+- `scripts/` — helper scripts for package.json and .ignore file modification
+  - `modify-package.js` — adds lint scripts to package.json
+  - `modify-ignore.js` — updates .ignore files with standard patterns
+- `test/` — package tests
+
+### Configuration Files
+
+- `eslint-common-config.js` — common ESLint configuration
+- `eslint-client-config.js` — client-side ESLint configuration
+- `eslint-node-config.js` — Node.js ESLint configuration
+- `eslint-prettier-config.js` — ESLint config with Prettier integration
+- `prettier-common-config.js` — Prettier configuration
+- `stylelint-common-config.js` — Stylelint configuration
+
+## Tech Stack
+
+This package follows the standard Diplodoc platform tech stack. See `.agents/dev-infrastructure.md` and `.agents/style-and-testing.md` in the metapackage root for detailed information.
+
+**Package-specific details**:
+
+- **Language**: JavaScript (Node.js) - no TypeScript, pure JavaScript
+- **Runtime**: Node.js >=11.5.1 (npm requirement)
+- **Testing**: Custom test setup in `test/` directory (Node.js `assert` and `child_process`, no testing framework)
+- **Build**: No build step required (pure JavaScript package)
+
+## Usage Modes
+
+This package can be used in two different contexts:
+
+### 1. As Part of Metapackage (Workspace Mode)
+
+When `@diplodoc/lint` is part of the Diplodoc metapackage:
+
+- Located at `devops/lint/` in the metapackage
+- Linked via npm workspaces
+- Dependencies are shared from metapackage root `node_modules`
+- Can be developed alongside other packages
+- Changes are immediately available to other packages via workspace linking
+
+**Development in Metapackage**:
+
+```bash
+# From metapackage root
+cd devops/lint
+npm install  # Uses workspace dependencies
+
+# Or from metapackage root
+npx nx build @diplodoc/lint  # If configured in nx
+```
+
+**Using from Other Packages in Metapackage**:
+
+- Other packages can use `@diplodoc/lint` directly
+- Workspace linking ensures local version is used
+- No need to publish to npm for local development
+
+### 2. As Standalone Package (Independent Mode)
+
+When `@diplodoc/lint` is used as a standalone npm package:
+
+- Installed via `npm install --save-dev @diplodoc/lint`
+- Has its own `node_modules` with all dependencies
+- Can be cloned and developed independently
+- Must be published to npm for others to use
+
+**Development Standalone**:
+
+```bash
+# Clone the repository
+git clone git@github.com:diplodoc-platform/lint.git
+cd lint
+npm install  # Installs all dependencies locally
+
+# Run tests
+npm test
+```
+
+**Using in External Projects**:
+
+```bash
+# Install from npm
+npm install --save-dev @diplodoc/lint
+
+# Initialize
+npx @diplodoc/lint init
+
+# Use
+npm run lint
+```
+
+### Important Considerations
+
+**Path Resolution**:
+
+- In metapackage: Scripts resolve paths relative to metapackage structure
+- Standalone: Scripts resolve paths relative to package root
+- Proxy scripts (`bin/eslint`, etc.) use `require.resolve()` which works in both modes
+
+**Dependencies**:
+
+- In metapackage: May use dependencies from root `node_modules`
+- Standalone: Must have all dependencies in local `node_modules`
+- Both modes should work identically from user perspective
+
+**Package Lock Management**:
+
+- When adding/updating dependencies, use `npm i --no-workspaces --package-lock-only` to regenerate `package-lock.json` for standalone mode
+- This ensures `package-lock.json` is valid when package is used outside workspace
+- Always regenerate after dependency changes to maintain standalone compatibility
+
+**Testing**:
+
+- Test setup works in both modes
+- When testing, ensure dependencies are properly resolved
+- Consider testing both modes if making significant changes
+
+## Setup Commands
+
+**In Metapackage**:
+
+```bash
+# From devops/lint directory
+npm install  # Uses workspace dependencies
+
+# Or from metapackage root
+npm install  # Installs all workspace dependencies
+```
+
+**Standalone**:
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+```
+
+**Important: Package Lock Management**
+
+When working in metapackage mode but need to update `package-lock.json` for standalone mode:
+
+```bash
+# Regenerate package-lock.json for standalone mode
+npm i --no-workspaces --package-lock-only
+```
+
+This ensures `package-lock.json` is valid when the package is used as a standalone npm package (not in workspace). Always use this when adding/updating dependencies in standalone mode.
+
+## Development Commands
+
+**In Metapackage**:
+
+```bash
+# From devops/lint directory
+cd test && npm start
+
+# Or using nx from metapackage root
+npx nx test @diplodoc/lint  # If configured
+```
+
+**Standalone**:
+
+```bash
+# Test the package
+cd test && npm start
+```
+
+## Architecture
+
+### Bin Directory Structure
+
+The `bin/` directory contains executable scripts that are made available via npm bin:
+
+**Main Script: `lint`**
+
+- **Purpose**: Main entry point for all linting operations
+- **Commands**:
+  - `lint` (default) — runs all linters in check mode
+  - `lint fix` — runs all linters in fix mode (auto-fixes issues)
+  - `lint init` — initializes linting infrastructure in a package
+  - `lint update` — updates linting infrastructure (runs automatically on each `lint` call)
+
+**Proxy Scripts** (redirect to original binaries from node_modules):
+
+- `eslint` — proxies to `eslint/bin/eslint.js`
+- `prettier` — proxies to `prettier/bin/prettier.cjs`
+- `stylelint` — proxies to `stylelint/bin/stylelint.mjs`
+- `husky` — proxies to `husky/bin.js`
+- `lint-staged` — proxies to `lint-staged/bin/lint-staged.js`
+- `svgo` — proxies to `svgo/bin/svgo`
+
+**How Proxy Scripts Work**:
+
+1. Find the source directory of `@diplodoc/lint` package
+2. Use `require.resolve()` to locate the original package in node_modules
+3. Redirect execution to the original binary
+4. This allows using tools via `npx @diplodoc/lint eslint` instead of `npx eslint`
+
+**Lint Script Behavior**:
+
+**Default mode** (`lint`):
+
+- Runs ESLint on all JS/TS files (check only)
+- Runs Prettier in check mode on all JS/TS files
+- Runs Stylelint on CSS/SCSS files (if found and not ignored)
+
+**Fix mode** (`lint fix`):
+
+- Runs ESLint with `--fix` flag (auto-fixes issues)
+- Runs Prettier with `--write` flag (formats files)
+- Runs Stylelint with `--fix` flag (auto-fixes CSS issues)
+
+**Init/Update mode** (`lint init` or `lint update`):
+
+1. **Modify package.json**: Adds/updates lint scripts via `scripts/modify-package.js`
+2. **Initialize Husky**: Runs `husky init` (only on `init`)
+3. **Copy scaffolding**: Copies all files from `scaffolding/` directory to package root
+4. **Update ignore files**: Extends `.gitignore`, `.eslintignore`, `.prettierignore`, `.stylelintignore` via `scripts/modify-ignore.js`
+
+### Infrastructure Auto-Update
+
+**Key Design Principle**: The package automatically checks and updates infrastructure in consuming packages on each run.
+
+**How it works**:
+
+1. `@diplodoc/lint` is installed as a dev dependency in packages
+2. It's configured in `prepare` scripts: `"prepare": "husky || true"`
+3. On each `lint` command execution, it runs `lint update` first
+4. The `update` command checks if scaffolding files are up-to-date
+5. If outdated, it automatically copies/updates configuration files
+6. This prevents infrastructure drift across packages
+
+**Current Implementation**:
+
+- `lint update` always copies scaffolding files (overwrites existing)
+- `lint update` always updates ignore files (adds missing patterns)
+- No diff checking - always performs updates
+
+**Potential Improvements**:
+
+- Add hash-based change detection to skip unnecessary file operations
+- Cache scaffolding file hashes to avoid redundant copies
+- Only update ignore files if patterns are actually missing
+
+### Package Integration
+
+When a package uses `@diplodoc/lint`:
+
+1. **Installation**: `npm install --save-dev @diplodoc/lint`
+2. **Initialization**: `npx @diplodoc/lint init`
+   - **Step 1**: Modifies `package.json` via `scripts/modify-package.js`
+     - Adds `lint`, `lint:fix`, `pre-commit`, `prepare` scripts
+   - **Step 2**: Initializes Husky (`husky init`)
+     - Creates `.husky/` directory
+     - Sets up git hooks
+   - **Step 3**: Copies scaffolding files from `scaffolding/` to package root
+     - `.eslintrc.js`, `.prettierrc.js`, `.stylelintrc.js`
+     - `.lintstagedrc.js`, `.husky/pre-commit`
+   - **Step 4**: Updates ignore files via `scripts/modify-ignore.js`
+     - Extends `.gitignore`, `.eslintignore`, `.prettierignore`, `.stylelintignore`
+     - Adds standard patterns (system files, build artifacts, node_modules)
+3. **Usage**: `npm run lint` or `npm run lint:fix`
+   - **Automatic update**: Runs `lint update` first (ensures infrastructure is current)
+   - **Then**: Runs actual linting (check or fix mode)
+
+**Update Process** (`lint update`):
+
+- Runs automatically on every `lint` command
+- Copies scaffolding files (overwrites if changed)
+- Updates ignore files (adds missing patterns)
+- Does NOT re-initialize Husky (only `init` does that)
+- Does NOT modify package.json scripts (only `init` does that)
+
+### Exports
+
+The package exports configurations that can be imported by packages:
+
+- `@diplodoc/lint/eslint-config` — Common ESLint config
+- `@diplodoc/lint/eslint-config/client` — Client-side ESLint config
+- `@diplodoc/lint/eslint-config/node` — Node.js ESLint config
+- `@diplodoc/lint/prettier-config` — Prettier config
+- `@diplodoc/lint/stylelint-config` — Stylelint config
+
+Packages can extend these configs at the `src` level if needed.
+
+## Configuration
+
+### Linting Tools
+
+**ESLint**:
+
+- Uses `@gravity-ui/eslint-config` as base
+- TypeScript support via `@typescript-eslint/eslint-plugin`
+- Import resolution via `eslint-import-resolver-typescript`
+- Security checks via `eslint-plugin-security`
+- Prettier integration via `eslint-config-prettier`
+
+**Prettier**:
+
+- Uses `@gravity-ui/prettier-config` as base
+- Consistent formatting across all packages
+
+**Stylelint**:
+
+- Uses `@gravity-ui/stylelint-config` as base
+- CSS and SCSS support
+
+**Husky**:
+
+- Git hooks management
+- Pre-commit hook runs `lint-staged`
+
+**lint-staged**:
+
+- Runs linting only on staged files
+- Faster pre-commit checks
+
+### Scaffolding Files
+
+Files in `scaffolding/` are copied to packages during `init`/`update`:
+
+**`.eslintrc.js`**:
+
+- Extends `@diplodoc/lint/eslint-config`
+- Configures TypeScript parser with project-aware settings
+- Sets `root: true` to prevent config inheritance from parent directories
+
+**`.prettierrc.js`**:
+
+- Exports `@diplodoc/lint/prettier-config` directly
+
+**`.stylelintrc.js`**:
+
+- Extends `@diplodoc/lint/stylelint-config`
+
+**`.editorconfig`**:
+
+- EditorConfig settings for consistent code formatting
+- UTF-8 charset, LF line endings
+- 4-space indentation by default, 2-space for JS/TS/JSON/YAML
+- Trims trailing whitespace (except in Markdown files)
+
+**`.lintstagedrc.js`**:
+
+- Configures lint-staged to run on staged files:
+  - JS/TS files: Prettier + ESLint (with auto-fix, excludes config files and scripts)
+  - CSS/SCSS files: Prettier + Stylelint (with auto-fix)
+  - JSON/YAML/MD files: Prettier
+  - SVG files: SVGO optimization
+  - **Unit tests**: Automatically runs `npm test` when test files (`.test.ts`, `.spec.ts`) or source files (`src/`) are changed
+  - Config files (`.lintstagedrc.js`, `.eslintrc.js`, etc.) are excluded from ESLint checks (they use CommonJS)
+
+**`.husky/pre-commit`**:
+
+- Runs `npm run pre-commit` before each commit
+- Pre-commit script runs `lint update && lint-staged`
+- lint-staged automatically runs unit tests when relevant files are changed
+
+**Ignore Files** (updated via `modify-ignore.js`):
+
+- `.gitignore`, `.eslintignore`, `.prettierignore`, `.stylelintignore`
+- Adds standard patterns:
+  - System files: `.idea`, `.vscode`, `.history`, `.env`, `.DS_Store`
+  - Build artifacts: `/lib`, `/dist`, `/build`, `/cache`, `/coverage`, `/external`
+  - Dependencies: `node_modules`
+
+## Testing
+
+The package has a comprehensive test suite in the `test/` directory:
+
+### Test Structure
+
+- `test/unit/` — unit tests for JavaScript modules
+  - `modify-package.test.js` — tests for package.json modification (8 tests)
+  - `modify-ignore.test.js` — tests for ignore file updates (9 tests)
+- `test/integration/` — integration tests for bash scripts
+  - `init.test.js` — tests for `lint init` flow (4 tests)
+  - `update.test.js` — tests for `lint update` flow (6 tests)
+  - `lint.test.js` — tests for `lint` and `lint fix` flows (7 tests)
+- `test/helpers/` — test utilities
+  - `temp-dir.js` — temporary directory management
+  - `file-utils.js` — file operations helpers
+  - `exec.js` — command execution helpers
+- `test/fixtures/` — test data files
+- `test/runner.js` — simple test runner (no external dependencies)
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run only unit tests
+npm run test:unit
+
+# Run only integration tests
+npm run test:integration
+
+# Run old test script (legacy)
+npm run test:old
+```
+
+**Test Results**: All 34 tests should pass. The test runner uses Node.js built-in `assert` module and `child_process` for integration tests.
+
+## Code Conventions
+
+1. **File naming**:
+
+   - Config files: `*-config.js` (e.g., `eslint-common-config.js`)
+   - Scripts: `modify-*.js` in `scripts/` directory
+   - Binaries: executable scripts in `bin/` directory
+
+2. **Comments and documentation**:
+
+   - **All code comments must be in English**
+   - **All documentation files (ADR, AGENTS.md, README, etc.) must be in English**
+
+3. **Code style**:
+   - Follow standard JavaScript/Node.js conventions
+   - Use consistent formatting (enforced by Prettier)
+
+## Common Tasks
+
+### Adding a New Linting Rule
+
+1. Update the appropriate config file (e.g., `eslint-common-config.js`)
+2. Test the change in the `test/` directory
+3. Update version in `package.json`
+4. Packages will pick up the change on next `lint update`
+
+### Modifying Scaffolding Files
+
+1. Update files in `scaffolding/` directory
+2. Test with `npx @diplodoc/lint init` in a test package
+3. Verify that files are copied correctly
+4. Update version in `package.json`
+
+### Adding a New Configuration Export
+
+1. Create the config file (e.g., `new-config.js`)
+2. Add export to `package.json`:
+   ```json
+   {
+     "exports": {
+       "./new-config": "./new-config.js"
+     }
+   }
+   ```
+3. Document the export in README.md
+4. Update version in `package.json`
+
+### Updating Dependencies
+
+1. Update dependency versions in `package.json`
+2. Test that linting still works with new versions
+3. Run `npm test` to verify
+4. Update version in `package.json`
+
+## Important Notes
+
+1. **Auto-update mechanism**: The `lint update` command runs automatically on each `lint` execution. This ensures infrastructure stays in sync across packages.
+
+2. **Backward compatibility**: When updating configs, consider backward compatibility. Breaking changes may require major version bumps.
+
+3. **Package independence**: This package should not depend on other Diplodoc packages (except devops infrastructure like `@diplodoc/tsconfig` if needed).
+
+4. **Scaffolding updates**: When scaffolding files change, packages will automatically get updates on next `lint update` run.
+
+5. **Extensibility**: Packages can extend ESLint configs at the `src` level, but should not override base configs.
+
+6. **Replaces deprecated packages**: This package replaces `@diplodoc/eslint-config` and `@diplodoc/prettier-config`. Do not use those packages.
+
+7. **Used by all packages**: This is a critical infrastructure package used by all Diplodoc packages. Changes should be carefully tested.
+
+8. **Performance consideration**: Running `lint update` on every `lint` call can be slow. Consider implementing smart update detection in the future.
+
+9. **Dual usage mode**: This package works both as part of the metapackage (workspace mode) and as a standalone npm package. All scripts and commands must work correctly in both contexts. When making changes, test both modes to ensure compatibility.
+
+## Additional Resources
+
+- `README.md` — main documentation
+- `CONTRIBUTING.md` — contributor guide
+- `CHANGELOG.md` — change history
+- Metapackage `.agents/` — platform-wide agent documentation

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [1.4.0](https://github.com/diplodoc-platform/lint/compare/v1.3.3...v1.4.0) (2025-12-26)
+
+
+### Features
+
+* add .editorconfig to scaffolding ([876ac1d](https://github.com/diplodoc-platform/lint/commit/876ac1de0e48f99b607608c87a63a2dd25ff0f5e))
+* add unit tests to pre-commit hook and fix ESLint config ([3b063db](https://github.com/diplodoc-platform/lint/commit/3b063dbfd6feb382fcab2990cd6cea04b9f0d113))
+
+
+### Bug Fixes
+
+* add --no-warn-ignored flag to ESLint to suppress ignored file warnings ([06685b6](https://github.com/diplodoc-platform/lint/commit/06685b6d037d03607138836c110d7995b82a34f2))
+* add eslint-env node comment to lint-staged config files ([c7516d9](https://github.com/diplodoc-platform/lint/commit/c7516d99f90b39b02ae7c788a4224da21a844fe6))
+* add ignorePatterns to scaffolding/.eslintrc.js ([3a12425](https://github.com/diplodoc-platform/lint/commit/3a124252b3e41fcd4e1da337fe65305b2d252d19))
+* add override for .mjs/.cjs files in ESLint config ([f494b66](https://github.com/diplodoc-platform/lint/commit/f494b661e377c0e21be86aab1f26c0d9e550fb6e))
+* handle .lintstagedrc.js separately in lint-staged config ([fee8678](https://github.com/diplodoc-platform/lint/commit/fee8678ae67784c2372f21f470d4aeeaa195f7f4))
+* improve cross-platform compatibility for integration tests ([d00f796](https://github.com/diplodoc-platform/lint/commit/d00f7964d4f284f727aa9ca78c0acbb9138d2a63))
+* install @diplodoc/lint in test directory for npm script test ([d0bd5f1](https://github.com/diplodoc-platform/lint/commit/d0bd5f1e3c68a918b4d828309d2c14a0401592ef))
+* make integration tests cross-platform compatible ([cc59464](https://github.com/diplodoc-platform/lint/commit/cc59464eb65e3cfc0589fff68a972df45cbd2305))
+* update scaffolding/.lintstagedrc.js with test execution and ESLint fixes ([b065de0](https://github.com/diplodoc-platform/lint/commit/b065de0b39daa27fc1aa7bd8e2396571e887310e))
+* update workflow and package-lock for standalone mode ([7fe3390](https://github.com/diplodoc-platform/lint/commit/7fe33909a55bc77ff0ba4abbae77bb936a4a2ca4))
+* use find + grep to filter files before ESLint to respect .eslintignore ([edc7d90](https://github.com/diplodoc-platform/lint/commit/edc7d9047f2f902b05e708af7d1fa474b6418c0d))
+
+## [1.3.3](https://github.com/diplodoc-platform/lint/compare/v1.3.2...v1.3.3) (2025-08-21)
+
+
+### Bug Fixes
+
+* Update @typescript-eslint/parser ([60cf215](https://github.com/diplodoc-platform/lint/commit/60cf215e7bea2fd50953ea1f8ce1fe234b5bc75a))
+
 ## [1.3.2](https://github.com/diplodoc-platform/lint/compare/v1.3.1...v1.3.2) (2025-08-20)
 
 

package/README.md

@@ -2,32 +2,286 @@
 
 # @diplodoc/lint
 
-Diplodoc platform internal utility set for linting
+Centralized linting and code formatting toolkit for Diplodoc projects. Combines ESLint, Prettier, and Stylelint configurations and automates their setup.
 
+## Features
 
-## Install
+- **Automatic setup** — one command to initialize all tools
+- **Automatic updates** — synchronizes configurations across packages
+- **Metapackage and standalone support** — works as part of the metapackage and as a standalone npm package
+- **Unified standards** — shared linting rules for all Diplodoc packages
+- **Git hooks** — automatic pre-commit hook setup via Husky
+- **TypeScript/JavaScript** — full support for both languages
+- **CSS/SCSS** — style support via Stylelint
 
-```
+## Installation
+
+```bash
 npm install --save-dev @diplodoc/lint
 ```
 
-## Usage
+## Quick Start
+
+### 1. Initialization
 
-Add initial configuration
+Run the initialization command in your package root:
 
-```sh
+```bash
 npx @diplodoc/lint init
+```
+
+This command will:
+
+- Add necessary scripts to `package.json`
+- Create configuration files (`.eslintrc.js`, `.prettierrc.js`, `.stylelintrc.js`)
+- Set up Git hooks via Husky
+- Update `.gitignore`, `.eslintignore`, `.prettierignore`, `.stylelintignore`
+
+After initialization, commit the changes:
+
+```bash
 git add --all && git commit -m 'chore: init lint'
 ```
 
-Run lint
+### 2. Usage
+
+**Code checking:**
 
-```sh
+```bash
 npm run lint
 ```
 
-Run lint in fix mode
+**Automatic fixing:**
 
-```sh
+```bash
 npm run lint:fix
 ```
+
+**Update configurations:**
+
+```bash
+npx @diplodoc/lint update
+```
+
+> **Note**: The `update` command runs automatically before each check (`npm run lint`), so configurations are always up-to-date.
+
+## Commands
+
+### `lint init`
+
+Initializes linting in a package:
+
+- Adds scripts to `package.json`:
+  - `lint` — code checking
+  - `lint:fix` — automatic fixing
+  - `pre-commit` — pre-commit checking
+  - `prepare` — Husky setup
+- Copies configuration files from `scaffolding/`
+- Sets up Husky for Git hooks
+- Updates ignore files
+
+### `lint update`
+
+Updates configuration files to the latest versions:
+
+- Updates `.eslintrc.js`, `.prettierrc.js`, `.stylelintrc.js`
+- Updates ignore files with new patterns
+- **Does not** re-initialize Husky
+- **Does not** modify existing scripts in `package.json`
+
+> **Important**: This command runs automatically before `lint` and `lint fix`, so configurations are always synchronized.
+
+### `lint`
+
+Checks code for rule compliance:
+
+1. Automatically runs `lint update`
+2. Runs ESLint for JavaScript/TypeScript files
+3. Runs Prettier for formatting checks
+4. Runs Stylelint for CSS/SCSS files (if present)
+
+### `lint fix`
+
+Automatically fixes found issues:
+
+1. Automatically runs `lint update`
+2. Runs ESLint with `--fix` flag
+3. Runs Prettier with `--write` flag
+4. Runs Stylelint with `--fix` flag (if CSS/SCSS files exist)
+
+## Configuration
+
+After initialization, the following files are created in the package root:
+
+### `.eslintrc.js`
+
+```javascript
+module.exports = {
+  root: true,
+  extends: require.resolve('@diplodoc/lint/eslint-config'),
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: true,
+  },
+};
+```
+
+Packages can extend the configuration at the `src/` level, but should not override base settings.
+
+### `.prettierrc.js`
+
+```javascript
+module.exports = require('@diplodoc/lint/prettier-config');
+```
+
+### `.stylelintrc.js`
+
+```javascript
+module.exports = {
+  extends: require.resolve('@diplodoc/lint/stylelint-config'),
+};
+```
+
+Created only if CSS/SCSS files exist in the project.
+
+## Supported Tools
+
+### ESLint
+
+- Configurations for TypeScript and JavaScript
+- React support (via `eslint-config/client`)
+- Node.js support (via `eslint-config/node`)
+- Project-aware TypeScript parsing
+
+### Prettier
+
+- Unified formatting style for all packages
+- Automatic formatting on save (via editor)
+
+### Stylelint
+
+- CSS and SCSS support
+- Uses `@gravity-ui/stylelint-config` as base
+
+### Husky
+
+- Git hooks management
+- Pre-commit hook runs `lint-staged`
+
+### lint-staged
+
+- Checks only changed files
+- Fast pre-commit checking
+
+## Metapackage vs Standalone Usage
+
+The package works in two modes:
+
+### In Metapackage (workspace mode)
+
+When the package is installed as part of the metapackage via npm workspaces:
+
+- Dependencies are resolved through shared `node_modules`
+- Commands work through workspace links
+- `package-lock.json` is managed at the metapackage level
+
+### Standalone Mode
+
+When the package is used as a standalone npm package:
+
+- All dependencies are installed locally
+- Commands work through `node_modules/.bin`
+- For `package-lock.json` management, use `npm i --no-workspaces --package-lock-only`
+
+Both modes are supported automatically — the package detects the context and works accordingly.
+
+## package.json Scripts
+
+After `lint init`, the following scripts are added to `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "lint update && lint",
+    "lint:fix": "lint update && lint fix",
+    "pre-commit": "lint update && lint-staged",
+    "prepare": "husky"
+  }
+}
+```
+
+- `lint` — code checking (with auto-update)
+- `lint:fix` — automatic fixing (with auto-update)
+- `pre-commit` — pre-commit checking (runs via Husky)
+- `prepare` — Husky setup when installing dependencies
+
+## Ignore Files
+
+The package automatically updates the following ignore files:
+
+- `.gitignore` — system files, dependencies, artifacts
+- `.eslintignore` — system files, dependencies, artifacts, `test/`, `scripts/`
+- `.prettierignore` — system files, dependencies, artifacts
+- `.stylelintignore` — system files, dependencies, artifacts
+
+Patterns are added automatically on `init` and `update`, duplicates are not created.
+
+## Testing
+
+The package includes a comprehensive test suite (34 tests):
+
+```bash
+# Run all tests
+npm test
+
+# Unit tests only
+npm run test:unit
+
+# Integration tests only
+npm run test:integration
+```
+
+Tests use Node.js built-in `assert` module and require no external dependencies.
+
+## Development
+
+### Package Structure
+
+```
+@diplodoc/lint/
+├── bin/              # Executable scripts
+│   ├── lint         # Main script
+│   ├── eslint       # ESLint proxy
+│   ├── prettier     # Prettier proxy
+│   └── ...
+├── scripts/         # Helper scripts
+│   ├── modify-package.js
+│   └── modify-ignore.js
+├── scaffolding/     # Configuration templates
+│   ├── .eslintrc.js
+│   ├── .prettierrc.js
+│   └── ...
+└── test/            # Tests
+    ├── unit/
+    ├── integration/
+    └── helpers/
+```
+
+### Making Changes
+
+1. Make code changes
+2. Run tests: `npm test`
+3. Check linting: `npm run lint`
+4. Test in a test package: `npx @diplodoc/lint init`
+
+## Important Notes
+
+- **Auto-update**: The `lint update` command runs automatically on each `lint` execution, ensuring configuration synchronization
+- **Backward compatibility**: When updating configs, backward compatibility is considered. Breaking changes require major version bumps
+- **Package independence**: This package does not depend on other Diplodoc packages (except devops infrastructure)
+- **Replaces deprecated packages**: This package replaces `@diplodoc/eslint-config` and `@diplodoc/prettier-config`. Do not use deprecated packages
+- **Critical package**: This is a critical infrastructure dependency used by all Diplodoc packages. Changes should be thoroughly tested
+
+## License
+
+MIT

package/bin/lint

@@ -40,7 +40,12 @@ fi
 if [[ -n $FIX ]]; then
   echo "Run linters in fix mode"
 
-  $BINDIR/eslint '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}' --fix
+  # Filter files using .eslintignore before passing to ESLint
+  if [[ -f .eslintignore ]]; then
+    find . -type f \( -name '*.js' -o -name '*.mjs' -o -name '*.cjs' -o -name '*.jsx' -o -name '*.ts' -o -name '*.mts' -o -name '*.cts' -o -name '*.tsx' \) ! -path '*/node_modules/*' | grep -vwFf .eslintignore | xargs $BINDIR/eslint --fix --no-warn-ignored || exit 1
+  else
+    $BINDIR/eslint '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}' --fix
+  fi
   $BINDIR/prettier --write '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'
   if [[ -n $(find . -type f -name '*.css' -name '*.scss' | grep -vwFf .stylelintignore) ]]; then
     $BINDIR/stylelint '**/*.{css,scss}' --fix
@@ -51,7 +56,13 @@ fi
 
 echo "Run linters"
 
-$BINDIR/eslint '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'
+# Filter files using .eslintignore before passing to ESLint
+# This ensures ignorePatterns and .eslintignore are respected
+if [[ -f .eslintignore ]]; then
+  find . -type f \( -name '*.js' -o -name '*.mjs' -o -name '*.cjs' -o -name '*.jsx' -o -name '*.ts' -o -name '*.mts' -o -name '*.cts' -o -name '*.tsx' \) ! -path '*/node_modules/*' | grep -vwFf .eslintignore | xargs $BINDIR/eslint --no-warn-ignored || exit 1
+else
+  $BINDIR/eslint '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'
+fi
 $BINDIR/prettier --check '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'
 if [[ -n $(find . -type f -name '*.css' -name '*.scss' | grep -vwFf .stylelintignore) ]]; then
   $BINDIR/stylelint '**/*.{css,scss}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diplodoc/lint",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Diplodoc platform internal utility set for linting",
   "bin": {
     "lint": "./bin/lint",
@@ -11,8 +11,22 @@
     "lint-staged": "./bin/lint-staged",
     "svgo": "./bin/svgo"
   },
+  "engines": {
+    "npm": ">=11.5.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:diplodoc-platform/lint.git"
+  },
   "scripts": {
-    "test": "cd test && npm start"
+    "test": "node test/runner.js",
+    "test:unit": "node test/runner.js unit",
+    "test:integration": "node test/runner.js integration",
+    "test:old": "cd test && npm start",
+    "lint": "lint update && lint",
+    "lint:fix": "lint update && lint fix",
+    "pre-commit": "lint update && lint-staged",
+    "prepare": "husky"
   },
   "exports": {
     "./eslint-config": "./eslint-common-config.js",
@@ -30,7 +44,8 @@
     "@gravity-ui/eslint-config": "^3.2.0",
     "@gravity-ui/prettier-config": "^1.1.0",
     "@gravity-ui/stylelint-config": "^4.0.1",
-    "@typescript-eslint/parser": "^6.21.0",
+    "@typescript-eslint/eslint-plugin": "^8.40.0",
+    "@typescript-eslint/parser": "^8.40.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-typescript": "^3.6.1",
@@ -41,5 +56,8 @@
     "prettier": "^3.3.3",
     "stylelint": "15",
     "svgo": "^3.3.2"
+  },
+  "devDependencies": {
+    "fs-extra": "^11.3.3"
   }
 }

package/scaffolding/.editorconfig

@@ -0,0 +1,20 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[{*.json,*.yml,*.yaml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[GNUmakefile]
+indent_style = tab
+indent_size = 4

package/scaffolding/.eslintrc.js

@@ -5,4 +5,12 @@ module.exports = {
         tsconfigRootDir: __dirname,
         project: true,
     },
+    overrides: [
+        {
+            files: ['*.mjs', '*.cjs'],
+            parserOptions: {
+                project: null,
+            },
+        },
+    ],
 };

package/scaffolding/.lintstagedrc.js

@@ -1,6 +1,41 @@
+/* eslint-env node */
 module.exports = {
-    '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}': ['prettier --write', 'eslint --max-warnings=0 --fix'],
+    // Exclude config files and scripts from linting (they use CommonJS)
+    '**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}': (filenames) => {
+        // Filter out config files and scripts
+        const configFiles = [
+            '.lintstagedrc.js',
+            '.eslintrc.js',
+            '.prettierrc.js',
+            '.stylelintrc.js',
+        ];
+        const filtered = filenames.filter(
+            (f) =>
+                !configFiles.some((config) => f.includes(config)) &&
+                !f.includes('scripts/') &&
+                !f.includes('test/'),
+        );
+        if (filtered.length === 0) {
+            return [];
+        }
+        return ['prettier --write', 'eslint --max-warnings=0 --fix --no-warn-ignored'];
+    },
+    // Handle .lintstagedrc.js separately (only prettier, no eslint)
+    '.lintstagedrc.js': ['prettier --write'],
     '**/*.{css,scss}': ['prettier --write', 'stylelint --fix'],
     '**/*.{json,yaml,yml,md}': ['prettier --write'],
     '**/*.{svg,svgx}': ['svgo'],
+    // Run unit tests when test files or source files change
+    '**/*.{ts,tsx}': (filenames) => {
+        const testFiles = filenames.filter((f) => f.includes('.test.') || f.includes('.spec.'));
+        const sourceFiles = filenames.filter(
+            (f) => !f.includes('.test.') && !f.includes('.spec.') && f.includes('src/'),
+        );
+        const commands = [];
+        // Run tests if test files or source files changed
+        if (testFiles.length > 0 || sourceFiles.length > 0) {
+            commands.push('npm test');
+        }
+        return commands;
+    },
 };

package/scripts/modify-ignore.js

@@ -30,6 +30,14 @@ const ignores = {
         ...SYSTEM,
         ...INSTALL,
         ...ARTIFACTS,
+        // Test files and scripts use Node.js globals
+        'test/',
+        'scripts/',
+        // Config files use CommonJS
+        '.lintstagedrc.js',
+        '.eslintrc.js',
+        '.prettierrc.js',
+        '.stylelintrc.js',
     ],
     '.prettierignore': [
         ...SYSTEM,

package/scripts/modify-package.js

@@ -11,6 +11,9 @@ try {
 }
 
 function configure(command, impl, force = false) {
+    if (!pkg.scripts) {
+        pkg.scripts = {};
+    }
     if (pkg.scripts[command] && !force) {
         if (pkg.scripts[command] !== impl) {
             throw `Lint command '${command}' already configured with different program`;