@vltpkg/dss-parser 1.3.7 → 1.4.0

package/README.md

@@ -14,3 +14,29 @@ import { parse } from '@vltpkg/dss-parser'
 // Parse a selector string into an AST
 const ast = parse(':root > *')
 ```
+
+## Validation
+
+`parse()` throws a `SyntaxError` on invalid DSS, with `cause.code`
+`EQUERY` and the offending input in `cause.found`. Rejected:
+
+- malformed syntax, e.g. `:outdated(`, `[name=`
+- empty / whitespace-only queries and empty selectors (`#a,`,
+  `:not()`)
+- unknown pseudo-classes, combinators and attribute operators
+- dangling combinators, e.g. `:root >`, `> >`
+- bare words, strings, empty ids / attributes, e.g. `foo`, `.dev`,
+  `"foo"`, `#`, `[]`
+
+`:is()` arguments are a forgiving list: only the last group above is
+rejected there.
+
+Pass `{ loose: true }` to skip the DSS checks (malformed syntax still
+throws):
+
+```js
+parse('#a, :unknown', { loose: true }) // no throw
+```
+
+Supported names are exported as `pseudoClassNames`, `combinatorNames`
+and `attributeOperatorNames`.

package/dist/grammar.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pseudo-class names supported by DSS, without the leading `:`.
+ */
+export declare const pseudoClassNames: readonly ["abandoned", "attr", "built", "confused", "cve", "cwe", "debug", "deprecated", "dev", "diff", "dist", "dynamic", "empty", "entropic", "env", "eval", "fs", "has", "host", "hostname", "is", "license", "link", "malware", "minified", "missing", "native", "network", "not", "obfuscated", "optional", "outdated", "overridden", "path", "peer", "prerelease", "private", "prod", "project", "published", "registry", "root", "scanned", "scope", "score", "scripts", "semver", "sev", "severity", "shell", "shrinkwrap", "spec", "squat", "suspicious", "tracker", "trivial", "type", "undesirable", "unknown", "unmaintained", "unpopular", "unstable", "v", "vuln", "vulnerable", "workspace"];
+export type PseudoClassName = (typeof pseudoClassNames)[number];
+/**
+ * Combinators supported by DSS.
+ */
+export declare const combinatorNames: readonly [">", "~", " "];
+export type CombinatorName = (typeof combinatorNames)[number];
+/**
+ * Attribute selector operators supported by DSS.
+ */
+export declare const attributeOperatorNames: readonly ["=", "^=", "$=", "~=", "*=", "|="];
+export type AttributeOperatorName = (typeof attributeOperatorNames)[number];

package/dist/grammar.js

@@ -0,0 +1,86 @@
+/**
+ * Pseudo-class names supported by DSS, without the leading `:`.
+ */
+export const pseudoClassNames = [
+    'abandoned',
+    'attr',
+    'built',
+    'confused',
+    'cve',
+    'cwe',
+    'debug',
+    'deprecated',
+    'dev',
+    'diff',
+    'dist',
+    'dynamic',
+    'empty',
+    'entropic',
+    'env',
+    'eval',
+    'fs',
+    'has',
+    'host',
+    'hostname',
+    'is',
+    'license',
+    'link',
+    'malware',
+    'minified',
+    'missing',
+    'native',
+    'network',
+    'not',
+    'obfuscated',
+    'optional',
+    'outdated',
+    'overridden',
+    'path',
+    'peer',
+    'prerelease',
+    'private',
+    'prod',
+    'project',
+    'published',
+    'registry',
+    'root',
+    'scanned',
+    'scope',
+    'score',
+    'scripts',
+    'semver',
+    'sev',
+    'severity',
+    'shell',
+    'shrinkwrap',
+    'spec',
+    'squat',
+    'suspicious',
+    'tracker',
+    'trivial',
+    'type',
+    'undesirable',
+    'unknown',
+    'unmaintained',
+    'unpopular',
+    'unstable',
+    'v',
+    'vuln',
+    'vulnerable',
+    'workspace',
+];
+/**
+ * Combinators supported by DSS.
+ */
+export const combinatorNames = ['>', '~', ' '];
+/**
+ * Attribute selector operators supported by DSS.
+ */
+export const attributeOperatorNames = [
+    '=',
+    '^=',
+    '$=',
+    '~=',
+    '*=',
+    '|=',
+];

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import type { Root } from 'postcss-selector-parser';
 export * from './types.ts';
+export * from './grammar.ts';
 /**
  * Escapes forward slashes in specific patterns matching @scoped/name paths
  * This will allow usage of unescaped forward slashes necessary for scoped
@@ -8,8 +9,13 @@ export * from './types.ts';
 export declare const escapeScopedNamesSlashes: (query: string) => string;
 export declare const escapeDots: (query: string) => string;
 export declare const unescapeDots: (query: string) => string;
+export type ParseOptions = {
+    /** skip DSS grammar checks, malformed syntax still throws */
+    loose?: boolean;
+};
 /**
- * Parses a CSS selector string into an AST
+ * Parses a DSS query string into an AST
  * Handles escaping of forward slashes in specific patterns
+ * Throws an `EQUERY` SyntaxError on invalid DSS
  */
-export declare const parse: (query: string) => Root;
+export declare const parse: (query: string, { loose }?: ParseOptions) => Root;

package/dist/index.js

@@ -1,6 +1,9 @@
 import postcssSelectorParser from 'postcss-selector-parser';
-import { asSelectorNode, isCombinatorNode, isPseudoNode, isTagNode, } from "./types.js";
+import { syntaxError } from '@vltpkg/error-cause';
+import { attributeOperatorNames, combinatorNames, pseudoClassNames, } from "./grammar.js";
+import { asSelectorNode, isAttributeNode, isCombinatorNode, isPseudoNode, isStringNode, isTagNode, } from "./types.js";
 export * from "./types.js";
+export * from "./grammar.js";
 /**
  * Escapes forward slashes in specific patterns matching @scoped/name paths
  * This will allow usage of unescaped forward slashes necessary for scoped
@@ -21,11 +24,78 @@ const pseudoCleanUpNeeded = new Set([
     ':vulnerable',
 ]);
 const hasParamsToEscape = (node) => pseudoCleanUpNeeded.has(node.value);
+const pseudoClasses = new Set(pseudoClassNames);
+const combinators = new Set(combinatorNames);
+const attributeOperators = new Set(attributeOperatorNames);
+// pseudo-classes taking selector args, all others take strings
+const selectorPseudos = new Set(['has', 'is', 'not']);
+const invalid = (message, found) => syntaxError(message, { code: 'EQUERY', found });
 /**
- * Parses a CSS selector string into an AST
+ * Checks a parsed selector against the DSS grammar.
+ * `forgiving`: inside `:is()`, only bare words / strings / empty
+ * `#` `[]` are rejected.
+ */
+const validate = (selector, query, forgiving = false) => {
+    const nodes = selector.nodes.filter(n => n.type !== 'comment');
+    if (!nodes.length && !forgiving) {
+        throw invalid('Empty selector', query);
+    }
+    nodes.forEach((node, i) => {
+        // `#` / `[]`: nothing to match
+        if ((node.type === 'id' && !node.value) ||
+            (node.type === 'attribute' && !node.attribute)) {
+            throw invalid('Unsupported selector', node.type === 'id' ? '#' : '[]');
+        }
+        if (isCombinatorNode(node)) {
+            if (forgiving)
+                return;
+            if (!combinators.has(node.value)) {
+                throw syntaxError(`Unsupported combinator: ${node.value}`, {
+                    code: 'EQUERY',
+                    found: node.value,
+                    validOptions: combinatorNames,
+                });
+            }
+            const next = nodes[i + 1];
+            if (!next || isCombinatorNode(next)) {
+                throw invalid('Dangling combinator', query);
+            }
+        }
+        else if (isPseudoNode(node)) {
+            const name = node.value.slice(1);
+            if (!pseudoClasses.has(name)) {
+                if (forgiving)
+                    return;
+                throw invalid(`Unsupported pseudo-class: ${node.value}`, node.value);
+            }
+            if (selectorPseudos.has(name)) {
+                for (const n of node.nodes) {
+                    validate(asSelectorNode(n), query, forgiving || name === 'is');
+                }
+            }
+        }
+        else if (isAttributeNode(node)) {
+            if (!forgiving &&
+                node.operator &&
+                !attributeOperators.has(node.operator)) {
+                throw invalid(`Unsupported attribute operator: ${node.operator}`, node.operator);
+            }
+        }
+        else if ((isTagNode(node) && node.value !== '{' && node.value !== '}') ||
+            isStringNode(node)) {
+            // `{` / `}` tags are a noop in the query engine
+            throw invalid('Unsupported selector', node.value);
+        }
+    });
+};
+/**
+ * Parses a DSS query string into an AST
  * Handles escaping of forward slashes in specific patterns
+ * Throws an `EQUERY` SyntaxError on invalid DSS
  */
-export const parse = (query) => {
+export const parse = (query, { loose = false } = {}) => {
+    if (!loose && !query.trim())
+        throw invalid('Empty query', query);
     const escapedQuery = escapeDots(escapeScopedNamesSlashes(query));
     const transformAst = (root) => {
         root.walk((node) => {
@@ -41,6 +111,8 @@ export const parse = (query) => {
                 for (const n of node.nodes) {
                     // the parameters have a selector node that wraps them up
                     const selector = asSelectorNode(n);
+                    if (!selector.nodes.length)
+                        continue;
                     selector.nodes.forEach((currentNode, index, arr) => {
                         // get the next node, we'll update it later
                         const nextNode = arr[index + 1];
@@ -89,5 +161,28 @@ export const parse = (query) => {
             }
         });
     };
-    return postcssSelectorParser(transformAst).astSync(escapedQuery);
+    let ast;
+    try {
+        ast = postcssSelectorParser(transformAst).astSync(escapedQuery);
+    }
+    catch (err) {
+        // postcss crashes with a TypeError when input ends after `(`
+        const reason = err instanceof TypeError ?
+            'unexpected end of input'
+            : err.message;
+        throw syntaxError(`Invalid query syntax: ${reason}`, {
+            code: 'EQUERY',
+            found: query,
+            cause: err,
+        });
+    }
+    if (!loose) {
+        // postcss silently drops a trailing top-level comma
+        if (/(^|[^\\])(\\\\)*,\s*$/.test(query)) {
+            throw invalid('Empty selector', query);
+        }
+        for (const s of ast.nodes)
+            validate(s, query);
+    }
+    return ast;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/dss-parser",
   "description": "The Dependency Selector Syntax (DSS) parser",
-  "version": "1.3.7",
+  "version": "1.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,7 +13,7 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/error-cause": "1.3.7",
+    "@vltpkg/error-cause": "1.4.0",
     "postcss-selector-parser": "^7.1.1"
   },
   "devDependencies": {