{"id":18778452,"url":"https://github.com/csstree/validator","last_synced_at":"2025-04-12T22:35:38.892Z","repository":{"id":45437264,"uuid":"68395926","full_name":"csstree/validator","owner":"csstree","description":"CSS validator based on CSSTree","archived":false,"fork":false,"pushed_at":"2025-02-20T00:52:28.000Z","size":328,"stargazers_count":66,"open_issues_count":13,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-12T17:23:33.357Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csstree.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-16T16:24:38.000Z","updated_at":"2025-01-07T23:22:27.000Z","dependencies_parsed_at":"2024-06-18T15:26:12.305Z","dependency_job_id":"8f11b8f4-fd81-46a8-9051-763ac0c6ccb8","html_url":"https://github.com/csstree/validator","commit_stats":{"total_commits":114,"total_committers":4,"mean_commits":28.5,"dds":0.06140350877192979,"last_synced_commit":"f8d754fa8e7f30509bea47a883731fd4ad57c7fc"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstree%2Fvalidator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstree%2Fvalidator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstree%2Fvalidator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstree%2Fvalidator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csstree","download_url":"https://codeload.github.com/csstree/validator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248642488,"owners_count":21138351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T20:16:19.985Z","updated_at":"2025-04-12T22:35:38.870Z","avatar_url":"https://github.com/csstree.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM Version](https://img.shields.io/npm/v/csstree-validator.svg)](https://www.npmjs.com/package/csstree-validator)\n[![Build Status](https://github.com/csstree/validator/actions/workflows/build.yml/badge.svg)](https://github.com/csstree/validator/actions/workflows/build.yml)\n[![Coverage Status](https://coveralls.io/repos/github/csstree/validator/badge.svg?branch=master)](https://coveralls.io/github/csstree/validator?branch=master)\n\n# CSSTree Validator\n\nCSS Validator built on [CSSTree](https://github.com/csstree/csstree).\n\nTechnically, 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.\n\n\u003e **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).\n\n\u003e **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.\n\n## Installation\n\nInstall the package via npm:\n\n```bash\nnpm install csstree-validator\n```\n\n## Usage\n\nYou can validate a CSS string or a [CSSTree AST](https://github.com/csstree/csstree/blob/master/docs/ast.md):\n\n```js\nimport { validate } from 'csstree-validator';\n// For CommonJS:\n// const { validate } = require('csstree-validator');\n\nconst filename = 'demo/example.css';\nconst css = '.class { pading: 10px; border: 1px super red }';\n\nconsole.log(validate(css, filename));\n// Output:\n// [\n//   SyntaxError [SyntaxReferenceError]: Unknown property `pading` {\n//     reference: 'pading',\n//     property: 'pading',\n//     offset: 9,\n//     line: 1,\n//     column: 10\n//   },\n//   SyntaxError [SyntaxMatchError]: Mismatch {\n//     message: 'Invalid value for `border` property',\n//     rawMessage: 'Mismatch',\n//     syntax: '\u003cline-width\u003e || \u003cline-style\u003e || \u003ccolor\u003e',\n//     css: '1px super red',\n//     mismatchOffset: 4,\n//     mismatchLength: 5,\n//     offset: 35,\n//     line: 1,\n//     column: 36,\n//     loc: { source: 'demo/example.css', start: [Object], end: [Object] },\n//     property: 'border',\n//     details: 'Mismatch\\n' +\n//       '  syntax: \u003cline-width\u003e || \u003cline-style\u003e || \u003ccolor\u003e\\n' +\n//       '   value: 1px super red\\n' +\n//       '  ------------^'\n//   }\n// ]\n```\n\nAlternatively, you can use [helper functions](#helpers) to validate a file or directory and utilize one of the built-in [reporters](#reporters):\n\n```js\nimport { validateFile, reporters } from 'csstree-validator';\n\nconst result = validateFile('./path/to/style.css');\nconsole.log(reporters.checkstyle(result));\n```\n\n### Validation Methods\n\n- `validate(css, filename)`\n- `validateAtrule(node)`\n- `validateAtrulePrelude(atrule, prelude, preludeLoc)`\n- `validateAtruleDescriptor(atrule, descriptor, value, descriptorLoc)`\n- `validateDeclaration(property, value, valueLoc)`\n- `validateRule(node)`\n\n## Helpers\n\n\u003e **Note:** Helpers are not available in browser environments as they rely on Node.js APIs.\n\nAll 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.\n\nExample:\n\n```js\nconst result = validateFile('path/to/file.css');\n\nfor (const [filename, errors] of result) {\n  // Process errors\n}\n```\n\nAvailable helper functions:\n\n- `validateString(css, filename)`\n- `validateDictionary(dictionary)`\n- `validateFile(filename)`\n- `validatePath(searchPath, filter)`\n- `validatePathList(pathList, filter)`\n\n## Reporters\n\nCSSTree Validator provides several built-in reporters to convert validation results into different formats:\n\n- `console` – Human-readable text suitable for console output.\n- `json` – Converts errors into a unified JSON array of objects:\n\n  ```ts\n  type ErrorEntry = {\n    name: string; // Filename\n    line: number;\n    column: number;\n    atrule?: string;\n    descriptor?: string;\n    property?: string;\n    message: string;\n    details?: any;\n  }\n  ```\n\n- `checkstyle` – [Checkstyle](https://checkstyle.sourceforge.io/) XML report format:\n\n  ```xml\n  \u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n  \u003ccheckstyle version=\"4.3\"\u003e\n    \u003cfile name=\"{filename}\"\u003e\n      \u003cerror line=\"{line}\" column=\"{column}\" severity=\"error\" message=\"{message}\" source=\"csstree-validator\" /\u003e\n    \u003c/file\u003e\n  \u003c/checkstyle\u003e\n  ```\n\n- `gnu` – GNU error log format:\n\n  ```\n  \"FILENAME\":LINE.COLUMN: error: MESSAGE\n  \"FILENAME\":START_LINE.COLUMN-END_LINE.COLUMN: error: MESSAGE\n  ```\n\nExample usage:\n\n```js\nimport { validate, reporters } from 'csstree-validator';\n\nconst css = '.class { padding: 10px; color: red; }';\nconst result = validate(css, 'example.css');\n\nconsole.log(reporters.json(result));\n// Output:\n// [\n//   { \"name\": 'example.css', ... },\n//   { \"name\": 'example.css', ... },\n//   ...\n// ]\n```\n\n## Browser Usage\n\nCSSTree Validator can be used in browser environments using the available bundles:\n\n- **IIFE Bundle (`dist/csstree-validator.js`)** – Minified IIFE with `csstreeValidator` as a global variable.\n\n  ```html\n  \u003cscript src=\"node_modules/csstree-validator/dist/csstree-validator.js\"\u003e\u003c/script\u003e\n  \u003cscript\u003e\n    const errors = csstreeValidator.validate('.some { css: source }');\n  \u003c/script\u003e\n  ```\n\n- **ES Module (`dist/csstree-validator.esm.js`)** – Minified ES module.\n\n  ```html\n  \u003cscript type=\"module\"\u003e\n    import { validate } from 'csstree-validator/dist/csstree-validator.esm.js';\n\n    const errors = validate('.some { css: source }');\n  \u003c/script\u003e\n  ```\n\nYou 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:\n\n```html\n\u003c!-- ESM --\u003e\n\u003cscript type=\"module\"\u003e\n  import * as csstreeValidator from 'https://cdn.jsdelivr.net/npm/csstree-validator';\n  // or\n  import * as csstreeValidator from 'https://unpkg.com/csstree-validator';\n\u003c/script\u003e\n\n\u003c!-- IIFE with csstreeValidator as a global --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/csstree-validator/dist/csstree-validator.js\"\u003e\u003c/script\u003e\n\u003c!-- or --\u003e\n\u003cscript src=\"https://unpkg.com/csstree-validator/dist/csstree-validator.js\"\u003e\u003c/script\u003e\n```\n\n**Note:** Helpers are not available in the browser version.\n\n## Command-Line Interface (CLI)\n\nInstall globally via npm:\n\n```bash\nnpm install -g csstree-validator\n```\n\nRun the validator on a CSS file:\n\n```bash\ncsstree-validator /path/to/style.css\n```\n\nDisplay help:\n\n```bash\ncsstree-validator -h\n```\n\n```\nUsage:\n\n    csstree-validator [fileOrDir] [options]\n\nOptions:\n\n    -h, --help                     Output usage information\n    -r, --reporter \u003cnameOrFile\u003e    Output formatter: console (default), checkstyle, json, gnu\n                                   or \u003cpath to a module\u003e\n    -v, --version                  Output version\n```\n\n### Custom Reporters\n\nIn 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:\n\n```js\nexport default function(result) {\n  let output = '';\n\n  for (const [filename, errors] of result) {\n    // Generate custom output\n  }\n\n  return output;\n}\n\n// For CommonJS:\n// module.exports = function(result) { ... }\n```\n\nThe `reporter` option accepts:\n\n- **ESM Module** – Full path to a file with a `.js` extension.\n- **CommonJS Module** – Full path to a file with a `.cjs` extension.\n- **ESM Package** – Package name or full path to a module within the package.\n- **CommonJS Package** – Package name or path to a module within the package.\n- **Dual Package** – Package name or full path to a module within the package.\n\nThe resolution algorithm checks the `reporter` value in the following order:\n\n1. If it's a path to a file (relative to `process.cwd()`), use it as a module.\n2. If it's a path to a package module (relative to `process.cwd()`), use the package's module.\n3. Otherwise, the value should be the name of one of the predefined reporters, or an error will be raised.\n\n## Integrations\n\nPlugins that use `csstree-validator`:\n\n- [VS Code Plugin](https://github.com/csstree/vscode-plugin)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstree%2Fvalidator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsstree%2Fvalidator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstree%2Fvalidator/lists"}