csstree-validator - npm Package Compare versions

Comparing version 3.0.0 to 4.0.0

dist/version.js

@@ -1,1 +0,1 @@
-export const version = "3.0.0";
+export const version = "4.0.0";

lib/bundle.js

@@ -0,2 +1,5 @@
+import * as reporters from './reporter/index.js';
+
 export * from './version.js';
 export * from './validate.js';
+export { reporters };

lib/cli.js

 import path from 'path';
 import fs from 'fs';
-import resolve from 'resolve';
+import resolve from 'enhanced-resolve';
 import { command as createCommand, Error as CliError } from 'clap';
@@ -32,2 +32,6 @@ import * as reporters from './reporter/index.js';
 
+const nodeResolver = resolve.create.sync({
+    conditionNames: ['node', 'import']
+});
+
 const command = createCommand('csstree-validate [fileOrDir]')
@@ -47,3 +51,3 @@ .version(version)
                 try {
-                    const resolvedPath = resolve.sync(nameOrFile, { basedir: process.cwd() });
+                    const resolvedPath = nodeResolver(process.cwd(), nameOrFile);
                     return import(resolvedPath);
@@ -50,0 +54,0 @@ } catch (e) {}

lib/reporter/json.js

@@ -1,2 +0,2 @@
-// [{ "name": {file}, "line": {line},"column": {column},"message": {error} }]
+// [{ "name": {file}, "line": {line}, "column": {column}, "property": {property}, "message": {error}, "details": {details} }]
 export default function(result) {
@@ -13,2 +13,4 @@ const output = [];
                 column: entry.column || 1,
+                atrule: entry.atrule,
+                descriptor: entry.descriptor,
                 property: entry.property,
@@ -15,0 +17,0 @@ message: entry.message,

package.json

 {
   "name": "csstree-validator",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "CSS validator built on csstree",
@@ -19,4 +19,9 @@ "author": "Roman Dvornov <[e-mail]>",
   "main": "./cjs/index.cjs",
+  "module": "./lib/index.js",
   "exports": {
     ".": {
+      "browser": {
+        "import": "./lib/bundle.js",
+        "require": "./cjs/bundle.cjs"
+      },
       "import": "./lib/index.js",
@@ -30,2 +35,4 @@ "require": "./cjs/index.cjs"
   "browser": {
+    "./cjs/index.cjs": "./cjs/bundle.cjs",
+    "./lib/index.js": "./lib/bundle.js",
     "./cjs/version.cjs": "./dist/version.cjs",
@@ -51,11 +58,11 @@ "./lib/version.js": "./dist/version.js"
     "clap": "^3.0.0",
-    "css-tree": "^2.0.2",
-    "resolve": "^1.20.0"
+    "css-tree": "^3.0.0",
+    "enhanced-resolve": "^5.16.0"
   },
   "devDependencies": {
     "c8": "^7.10.0",
-    "esbuild": "^0.14.2",
+    "esbuild": "^0.21.0",
     "eslint": "^8.4.1",
     "mocha": "^9.1.3",
-    "rollup": "^2.60.2"
+    "rollup": "^2.79.2"
   },
@@ -62,0 +69,0 @@ "engines": {

README.md

@@ -1,2 +0,2 @@
-[![NPM version](https://img.shields.io/npm/v/csstree-validator.svg)](https://www.npmjs.com/package/csstree-validator)
+[![NPM Version](https://img.shields.io/npm/v/csstree-validator.svg)](https://www.npmjs.com/package/csstree-validator)
 [![Build Status](https://github.com/csstree/validator/actions/workflows/build.yml/badge.svg)](https://github.com/csstree/validator/actions/workflows/build.yml)
@@ -7,15 +7,25 @@ [![Coverage Status](https://coveralls.io/repos/github/csstree/validator/badge.svg?branch=master)](https://coveralls.io/github/csstree/validator?branch=master)
 
-CSS validator built on [CSSTree](https://github.com/csstree/csstree)
+CSS Validator built on [CSSTree](https://github.com/csstree/csstree).
 
-## Usage
+Technically, the package utilizes the capabilities of CSSTree to match CSS syntaxes to various parts of your code and generates a list of errors, if any.
 
+> **Note:** If `csstree-validator` produces false positives or false negatives, such as unknown properties or invalid values for a property, please report the issue to the [CSSTree issue tracker](https://github.com/csstree/csstree/issues).
+
+> **Note:** CSSTree currently doesn't support selector syntax matching; therefore, `csstree-validator` doesn't support it either. Support for selector validation will be added once it is available in CSSTree.
+
+## Installation
+
+Install the package via npm:
+
 ```bash
-> npm install csstree-validator
+npm install csstree-validator
 ```
 
-Validate CSS string or [CSSTree's AST](https://github.com/csstree/csstree/blob/master/docs/ast.md):
+## Usage
 
+You can validate a CSS string or a [CSSTree AST](https://github.com/csstree/csstree/blob/master/docs/ast.md):
+
 ```js
 import { validate } from 'csstree-validator';
-// Commonjs:
+// For CommonJS:
 // const { validate } = require('csstree-validator');
@@ -27,2 +37,3 @@
 console.log(validate(css, filename));
+// Output:
 // [
@@ -56,3 +67,3 @@ //   SyntaxError [SyntaxReferenceError]: Unknown property `pading` {
 
-Another option is to use helpers to validate a file or a directory and one of buildin reporters:
+Alternatively, you can use [helper functions](#helpers) to validate a file or directory and utilize one of the built-in [reporters](#reporters):
 
@@ -62,18 +73,23 @@ ```js
 
-console.log(reporters.checkstyle(validateFile('./path/to/style.css')));
+const result = validateFile('./path/to/style.css');
+console.log(reporters.checkstyle(result));
 ```
 
-### Validate methods
+### Validation Methods
 
-* validate(css, filename)
-* validateAtrule(node)
-* validateAtrulePrelude(atrule, prelude, preludeLoc)
-* validateAtruleDescriptor(atrule, descriptor, value, descriptorLoc)
-* validateDeclaration(property, value, valueLoc)
-* validateRule(node)
+- `validate(css, filename)`
+- `validateAtrule(node)`
+- `validateAtrulePrelude(atrule, prelude, preludeLoc)`
+- `validateAtruleDescriptor(atrule, descriptor, value, descriptorLoc)`
+- `validateDeclaration(property, value, valueLoc)`
+- `validateRule(node)`
 
 ## Helpers
 
-All helper function return an object where key is a path to a file and value is an array of errors. The result object is iterable (has `Symbol.iterator`) and can be used with `for ... of` or `...` operator.
+> **Note:** Helpers are not available in browser environments as they rely on Node.js APIs.
 
+All helper functions return an object where the key is the path to a file and the value is an array of errors. The result object is iterable (has `Symbol.iterator`) and can be used with `for...of` loops or the spread operator.
+
+Example:
+
 ```js
@@ -83,42 +99,94 @@ const result = validateFile('path/to/file.css');
 for (const [filename, errors] of result) {
-  // ...
+  // Process errors
 }
 ```
 
-* validateString(css, filename)
-* validateDictionary(dictionary)
-* validateFile(filename)
-* validatePath(searchPath, filter)
-* validatePathList(pathList, filter)
+Available helper functions:
 
-Reporters:
+- `validateString(css, filename)`
+- `validateDictionary(dictionary)`
+- `validateFile(filename)`
+- `validatePath(searchPath, filter)`
+- `validatePathList(pathList, filter)`
 
-* `json`
-* `console`
-* `checkstyle`
-* `gnu`
+## Reporters
 
-## Using in a browser
+CSSTree Validator provides several built-in reporters to convert validation results into different formats:
 
-Available bundles to use in a browser:
+- `console` – Human-readable text suitable for console output.
+- `json` – Converts errors into a unified JSON array of objects:
 
-- `dist/csstree-validator.js` – minified IIFE with `csstreeValidator` as a global
-```html
-<script src="node_modules/csstree-validator/dist/csstree-validator.js"></script>
-<script>
-  const errors = csstreeValidator.validate('.some { css: source }');
-</script>
-```
+  ```ts
+  type ErrorEntry = {
+    name: string; // Filename
+    line: number;
+    column: number;
+    atrule?: string;
+    descriptor?: string;
+    property?: string;
+    message: string;
+    details?: any;
+  }
+  ```
 
-- `dist/csstree-validator.esm.js` – minified ES module
-```html
-<script type="module">
-  import { validate } from "csstree-validator/dist/csstree-validator.esm.js";
+- `checkstyle` – [Checkstyle](https://checkstyle.sourceforge.io/) XML report format:
 
-  const errors = validate('.some { css: source }');
-</script>
+  ```xml
+  <?xml version="1.0" encoding="utf-8"?>
+  <checkstyle version="4.3">
+    <file name="{filename}">
+      <error line="{line}" column="{column}" severity="error" message="{message}" source="csstree-validator" />
+    </file>
+  </checkstyle>
+  ```
+
+- `gnu` – GNU error log format:
+
+  ```
+  "FILENAME":LINE.COLUMN: error: MESSAGE
+  "FILENAME":START_LINE.COLUMN-END_LINE.COLUMN: error: MESSAGE
+  ```
+
+Example usage:
+
+```js
+import { validate, reporters } from 'csstree-validator';
+
+const css = '.class { padding: 10px; color: red; }';
+const result = validate(css, 'example.css');
+
+console.log(reporters.json(result));
+// Output:
+// [
+//   { "name": 'example.css', ... },
+//   { "name": 'example.css', ... },
+//   ...
+// ]
 ```
 
-One of CDN services like `unpkg` or `jsDelivr` can be used. By default (for short path) a ESM version is exposing. For IIFE version a full path to a bundle should be specified:
+## Browser Usage
 
+CSSTree Validator can be used in browser environments using the available bundles:
+
+- **IIFE Bundle (`dist/csstree-validator.js`)** – Minified IIFE with `csstreeValidator` as a global variable.
+
+  ```html
+  <script src="node_modules/csstree-validator/dist/csstree-validator.js"></script>
+  <script>
+    const errors = csstreeValidator.validate('.some { css: source }');
+  </script>
+  ```
+
+- **ES Module (`dist/csstree-validator.esm.js`)** – Minified ES module.
+
+  ```html
+  <script type="module">
+    import { validate } from 'csstree-validator/dist/csstree-validator.esm.js';
+
+    const errors = validate('.some { css: source }');
+  </script>
+  ```
+
+You can also use a CDN service like `unpkg` or `jsDelivr`. By default, the ESM version is exposed for short paths. For the IIFE version, specify the full path to the bundle:
+
 ```html
@@ -128,2 +196,3 @@ <!-- ESM -->
   import * as csstreeValidator from 'https://cdn.jsdelivr.net/npm/csstree-validator';
+  // or
   import * as csstreeValidator from 'https://unpkg.com/csstree-validator';
@@ -134,19 +203,32 @@ </script>
 <script src="https://cdn.jsdelivr.net/npm/csstree-validator/dist/csstree-validator.js"></script>
+<!-- or -->
 <script src="https://unpkg.com/csstree-validator/dist/csstree-validator.js"></script>
 ```
 
-NOTE: Helpers and reporters are not available for browser's version.
+**Note:** Helpers are not available in the browser version.
 
-## CLI (terminal command)
+## Command-Line Interface (CLI)
 
+Install globally via npm:
+
 ```bash
-> npm install -g csstree-validator
-> csstree-validator /path/to/style.css
+npm install -g csstree-validator
 ```
 
+Run the validator on a CSS file:
+
+```bash
+csstree-validator /path/to/style.css
 ```
-> csstree-validator -h
+
+Display help:
+
+```bash
+csstree-validator -h
+```
+
+```
 Usage:
 
-    csstree-validate [fileOrDir] [options]
+    csstree-validator [fileOrDir] [options]
 
@@ -161,12 +243,12 @@ Options:
 
-### Custom reporters
+### Custom Reporters
 
-In addition to predefined (buildin) reporters, you can specify the path to a module or a package with a custom reporter. Such module should export a single function which takes the validation result object and returns a string:
+In addition to the built-in reporters, you can specify a custom reporter by providing the path to a module or package. The module should export a single function that takes the validation result object and returns a string:
 
 ```js
 export default function(result) {
-  const output = '';
+  let output = '';
 
   for (const [filename, errors] of result) {
-    // ...
+    // Generate custom output
   }
@@ -181,26 +263,24 @@
 
-The specifier for a custom reporter might be:
-- ESM module – a full path to a file with `.js` extension
-- CommonJS module – a full path to a file with `.cjs` extension
-- ESM package – a package name or a full path to package's module (i.e. `package/lib/index.js`)
-- CommonJS package – a package name or a path to package's module (i.e. `package/lib/index.js`, `package/lib/index` or `package/lib`)
-- Dual package – a package name or a full path to package's module
+The `reporter` option accepts:
 
-The resolution algorithm is testing `reporter` option value in the following order:
-- If a value is a path to a file (a base dir for relative paths is `process.cwd()`), then use it a module
-- If a value is a path to a package module (a base dir for `node_modules` is `process.cwd()`), then use package's module
-- Otherwise the value should be a name of one of predifined reporter, or an error will be raised
+- **ESM Module** – Full path to a file with a `.js` extension.
+- **CommonJS Module** – Full path to a file with a `.cjs` extension.
+- **ESM Package** – Package name or full path to a module within the package.
+- **CommonJS Package** – Package name or path to a module within the package.
+- **Dual Package** – Package name or full path to a module within the package.
 
-## Ready to use
+The resolution algorithm checks the `reporter` value in the following order:
 
-Plugins that are using `csstree-validator`:
+1. If it's a path to a file (relative to `process.cwd()`), use it as a module.
+2. If it's a path to a package module (relative to `process.cwd()`), use the package's module.
+3. Otherwise, the value should be the name of one of the predefined reporters, or an error will be raised.
 
-* [Sublime plugin](https://github.com/csstree/SublimeLinter-contrib-csstree)
-* [VS Code plugin](https://github.com/csstree/vscode-plugin)
-* [Atom plugin](https://github.com/csstree/atom-plugin)
-* [Grunt plugin](https://github.com/sergejmueller/grunt-csstree-validator)
-* [Gulp plugin](https://github.com/csstree/gulp-csstree)
+## Integrations
 
+Plugins that use `csstree-validator`:
+
+- [VS Code Plugin](https://github.com/csstree/vscode-plugin)
+
 ## License
 
 MIT

No alert changes

Improved metrics

Total package byte prevSize

424188

increased by14.87%

Lines of code

2368

increased by10.6%

Number of lines in readme file

278

increased by40.4%

Dependency changes

• + Addedenhanced-resolve@^5.16.0

• + Addedcss-tree@3.1.0(transitive)

• + Addedenhanced-resolve@5.18.1(transitive)

• + Addedgraceful-fs@4.2.11(transitive)

• + Addedmdn-data@2.12.2(transitive)

• + Addedtapable@2.2.1(transitive)

• - Removedresolve@^1.20.0

• - Removedcss-tree@2.3.1(transitive)

• - Removedfunction-bind@1.1.2(transitive)

• - Removedhasown@2.0.2(transitive)

• - Removedis-core-module@2.16.1(transitive)

• - Removedmdn-data@2.0.30(transitive)

• - Removedpath-parse@1.0.7(transitive)

• - Removedresolve@1.22.10(transitive)

• - Removedsupports-preserve-symlinks-flag@1.0.0(transitive)

• Updatedcss-tree@^3.0.0