@vltpkg/query 1.4.0 → 1.6.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { EdgeLike, NodeLike } from '@vltpkg/types';
 import type { SecurityArchiveLike } from '@vltpkg/security-archive';
-import type { DiffFilesProvider, GetAuthHeader, HostContextsMap, ParsedSelectorToken, ParserState, QueryResponse } from './types.ts';
+import type { PartPseudoName } from '@vltpkg/dss-parser';
+import type { DiffFilesProvider, GetAuthHeader, HasSkills, HostContextsMap, ParsedSelectorToken, ParserState, QueryResponse } from './types.ts';
 import type { DepID } from '@vltpkg/dep-id';
 export * from './types.ts';
 export type SearchOptions = {
@@ -17,6 +18,10 @@ export type QueryOptions = {
     hostContexts?: HostContextsMap;
     diffFiles?: DiffFilesProvider;
     getAuthHeader?: GetAuthHeader;
+    /** for `:skills`; unset: `:skills` throws */
+    hasSkills?: HasSkills;
+    /** part selectors to allow, e.g. `['skill']`; others throw */
+    partSelectors?: readonly PartPseudoName[];
 };
 /**
  * The Query class is used to search the graph for nodes and edges
@@ -37,7 +42,7 @@ export declare class Query {
      * the original order is preserved.
      */
     static specificitySort(responses: QueryResponse[]): QueryResponse[];
-    constructor({ edges, nodes, importers, retries, securityArchive, hostContexts, diffFiles, getAuthHeader, }: QueryOptions);
+    constructor({ edges, nodes, importers, retries, securityArchive, hostContexts, diffFiles, getAuthHeader, hasSkills, partSelectors, }: QueryOptions);
     /**
      * Search the graph for nodes and edges that match the given query.
      */

package/dist/index.js

@@ -1,5 +1,5 @@
 import { joinDepIDTuple } from '@vltpkg/dep-id/browser';
-import { parse, isPostcssNodeWithChildren, asPostcssNodeWithChildren, isSelectorNode, isPseudoNode, isIdentifierNode, isAttributeNode, } from '@vltpkg/dss-parser';
+import { parse, partPseudoNames, isPostcssNodeWithChildren, asPostcssNodeWithChildren, isSelectorNode, isPseudoNode, isIdentifierNode, isAttributeNode, } from '@vltpkg/dss-parser';
 import { attribute } from "./attribute.js";
 import { combinator } from "./combinator.js";
 import { id } from "./id.js";
@@ -7,6 +7,7 @@ import { pseudo, pseudoSelectorNames } from "./pseudo.js";
 import { queryError, selectorText } from "./error.js";
 export * from "./types.js";
 const noopFn = async (state) => state;
+const partPseudos = new Set(partPseudoNames);
 /**
  * `.dev` and a bare `dev` are the two ways a css habit shows up in a
  * query. Neither is valid DSS, but the intent is usually a pseudo-class
@@ -16,7 +17,8 @@ const unsupportedName = (state) => {
     const text = selectorText(state.current);
     const name = text.replace(/^[.#]/, '');
     return queryError('Unsupported selector', state.current, {
-        wanted: pseudoSelectorNames.has(name) ? `:${name}`
+        wanted: pseudoSelectorNames.has(name) && !partPseudos.has(name) ?
+            `:${name}`
             : name ? `#${name}`
                 : undefined,
     });
@@ -97,6 +99,13 @@ export const walk = async (state) => {
             for (const node of state.partial.nodes) {
                 state.collect.nodes.add(node);
             }
+            if (state.parts && node.parent?.type === 'root') {
+                state.parts.push({
+                    ...state.part,
+                    nodes: [...state.partial.nodes],
+                });
+                delete state.part;
+            }
         }
     }
     return state;
@@ -155,12 +164,14 @@ export class Query {
     #cache;
     #diffFiles;
     #getAuthHeader;
+    #hasSkills;
     #edges;
     #nodes;
     #importers;
     #retries;
     #securityArchive;
     #hostContexts;
+    #partSelectors;
     /**
      * Helper method to determine if a given query string is using any of
      * the known security selectors. This is useful so that operations can
@@ -194,10 +205,12 @@ export class Query {
             return 0;
         });
     }
-    constructor({ edges, nodes, importers, retries, securityArchive, hostContexts, diffFiles, getAuthHeader, }) {
+    constructor({ edges, nodes, importers, retries, securityArchive, hostContexts, diffFiles, getAuthHeader, hasSkills, partSelectors, }) {
+        this.#partSelectors = new Set(partSelectors);
         this.#cache = new Map();
         this.#diffFiles = diffFiles;
         this.#getAuthHeader = getAuthHeader;
+        this.#hasSkills = hasSkills;
         this.#edges = edges;
         this.#nodes = nodes;
         this.#importers = importers;
@@ -325,7 +338,7 @@ export class Query {
         const loose = asPostcssNodeWithChildren(current).nodes.length > 1;
         // builds initial state and walks over it,
         // retrieving the collected result
-        const { collect, comment, importers: stateResultImporters, specificity, } = await walk({
+        const { collect, comment, importers: stateResultImporters, parts, specificity, } = await walk({
             cancellable: async () => {
                 await new Promise(resolve => {
                     setTimeout(resolve, 0);
@@ -344,9 +357,13 @@ export class Query {
             comment: '',
             diffFiles: this.#diffFiles,
             getAuthHeader: this.#getAuthHeader,
+            hasSkills: this.#hasSkills,
             loose,
             importers,
             partial: { nodes, edges },
+            ...(this.#partSelectors.size ?
+                { parts: [], partSelectors: this.#partSelectors }
+                : undefined),
             retries: this.#retries,
             signal,
             securityArchive: this.#securityArchive,
@@ -361,6 +378,8 @@ export class Query {
             importers: this.#getQueryResponseNodes(stateResultImporters),
             comment,
             specificity,
+            // part nodes are a subset of `nodes`, already hydrated above
+            ...(parts ? { parts: parts } : undefined),
         };
         this.#cache.set(query, res);
         return res;

package/dist/pseudo/skill.d.ts

@@ -0,0 +1,7 @@
+import type { ParserState } from '../types.ts';
+/**
+ * `:skill(<pattern>, ...)`: picks agent skills of the packages its
+ * selector matched. Never filters nodes: the walker stores the
+ * patterns in the selector's `parts` entry. Opt-in only.
+ */
+export declare const skill: (state: ParserState) => Promise<ParserState>;

package/dist/pseudo/skill.js

@@ -0,0 +1,52 @@
+import { asPseudoNode } from '@vltpkg/dss-parser';
+import { queryError } from "../error.js";
+import { removeQuotes } from "./helpers.js";
+/**
+ * `:skill(<pattern>, ...)`: picks agent skills of the packages its
+ * selector matched. Never filters nodes: the walker stores the
+ * patterns in the selector's `parts` entry. Opt-in only.
+ */
+export const skill = async (state) => {
+    const curr = asPseudoNode(state.current);
+    const sel = curr.parent;
+    const fail = (message) => queryError(message, state.current);
+    if (sel?.parent?.type !== 'root' ||
+        sel.nodes
+            .slice(sel.index(curr) + 1)
+            .some(n => n.type !== 'comment')) {
+        throw fail(':skill() must end a top-level selector');
+    }
+    if (!state.partSelectors?.has('skill')) {
+        throw fail(':skill() only applies to --allow-skills and vlt skills');
+    }
+    if (!curr.nodes.length)
+        throw fail('Missing skill name in :skill()');
+    const patterns = curr.nodes.map(arg => {
+        let pattern = '';
+        for (const n of arg.nodes) {
+            if (n.type === 'comment')
+                continue;
+            // `a|b` is tag `b` in namespace `a`: never drop the `a`
+            if ((n.type === 'tag' || n.type === 'universal') &&
+                !String(n).includes('|')) {
+                pattern += n.value;
+            }
+            else if (n.type === 'string') {
+                if (n.value.startsWith("'")) {
+                    throw fail('Invalid skill name in :skill(), use double quotes');
+                }
+                pattern += removeQuotes(n.value);
+            }
+            else {
+                throw fail(n.type === 'combinator' ?
+                    'Invalid skill name in :skill(), quote names with spaces'
+                    : 'Invalid skill name in :skill()');
+            }
+        }
+        if (!pattern)
+            throw fail('Missing skill name in :skill()');
+        return pattern;
+    });
+    state.part = { name: 'skill', patterns };
+    return state;
+};

package/dist/pseudo/skills.d.ts

@@ -0,0 +1,6 @@
+import type { ParserState } from '../types.ts';
+/**
+ * `:skills`: matches installed packages that ship agent skills, as
+ * told by the `hasSkills` provider.
+ */
+export declare const skills: (state: ParserState) => Promise<ParserState>;

package/dist/pseudo/skills.js

@@ -0,0 +1,26 @@
+import { asPseudoNode } from '@vltpkg/dss-parser';
+import { queryError } from "../error.js";
+import { clear, removeDanglingEdges, removeNode } from "./helpers.js";
+/**
+ * `:skills`: matches installed packages that ship agent skills, as
+ * told by the `hasSkills` provider.
+ */
+export const skills = async (state) => {
+    // `:skills(x)`: likely a `:skill(x)` typo
+    if (asPseudoNode(state.current).nodes.length) {
+        if (state.loose)
+            return clear(state);
+        throw queryError(':skills takes no arguments', state.current, {
+            wanted: ':skill',
+        });
+    }
+    if (!state.hasSkills) {
+        throw queryError('The :skills selector is not supported here', state.current);
+    }
+    for (const node of state.partial.nodes) {
+        if (!(await state.hasSkills(node)))
+            removeNode(state, node);
+    }
+    removeDanglingEdges(state);
+    return state;
+};

package/dist/pseudo.js

@@ -49,6 +49,8 @@ import { semverParser as semver } from "./pseudo/semver.js";
 import { severity } from "./pseudo/severity.js";
 import { spec } from "./pseudo/spec.js";
 import { shrinkwrap } from "./pseudo/shrinkwrap.js";
+import { skill } from "./pseudo/skill.js";
+import { skills } from "./pseudo/skills.js";
 import { squat } from "./pseudo/squat.js";
 import { suspicious } from "./pseudo/suspicious.js";
 import { tracker } from "./pseudo/tracker.js";
@@ -88,6 +90,7 @@ const has = async (state) => {
                     nodes: new Set(state.partial.nodes),
                 },
                 diffFiles: state.diffFiles,
+                hasSkills: state.hasSkills,
                 loose: state.loose,
                 hostContexts: state.hostContexts,
                 importers: state.importers,
@@ -164,6 +167,7 @@ const is = async (state) => {
                 },
                 current: node,
                 diffFiles: state.diffFiles,
+                hasSkills: state.hasSkills,
                 initial: state.initial,
                 loose: true,
                 partial: {
@@ -210,6 +214,7 @@ const not = async (state) => {
                 },
                 current: node,
                 diffFiles: state.diffFiles,
+                hasSkills: state.hasSkills,
                 initial: state.initial,
                 loose: state.loose,
                 partial: {
@@ -331,6 +336,8 @@ const pseudoSelectors = new Map(Object.entries({
     severity,
     shell,
     shrinkwrap,
+    skill,
+    skills,
     squat,
     suspicious,
     tracker,

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 import type { EdgeLike, NodeLike } from '@vltpkg/types';
 import type { SecurityArchiveLike, PackageScore } from '@vltpkg/security-archive';
 import type { DepID } from '@vltpkg/dep-id';
-import type { PostcssNode } from '@vltpkg/dss-parser';
+import type { PartPseudoName, PostcssNode } from '@vltpkg/dss-parser';
 export type HostContextsMapResult = {
     initialEdges: EdgeLike[];
     initialNodes: NodeLike[];
@@ -31,6 +31,22 @@ export type DiffFilesProvider = (commitish: string) => Set<string>;
  * keychain / registry-client dependency.
  */
 export type GetAuthHeader = (url: string) => Promise<string | undefined>;
+/**
+ * Whether an installed package ships agent skills; for `:skills`.
+ * Keeps fs out of this package.
+ */
+export type HasSkills = (node: NodeLike) => Promise<boolean>;
+/**
+ * One top-level selector of a query and the nodes it matched. `name`
+ * and `patterns` are set when it ends in a part selector, e.g.
+ * `#a:skill(x, y*)`.
+ */
+export type QueryPart<N = QueryResponseNode> = {
+    name?: PartPseudoName;
+    /** as typed, `*` = glob; for matching only, never paths */
+    patterns?: string[];
+    nodes: N[];
+};
 export type ParserState = {
     cancellable: () => Promise<void>;
     collect: GraphSelectionState;
@@ -38,6 +54,7 @@ export type ParserState = {
     current: PostcssNode;
     diffFiles?: DiffFilesProvider;
     getAuthHeader?: GetAuthHeader;
+    hasSkills?: HasSkills;
     hostContexts?: HostContextsMap;
     importers: Set<NodeLike>;
     initial: GraphSelectionState;
@@ -48,6 +65,12 @@ export type ParserState = {
     signal: AbortSignal;
     walk: ParserFn;
     partial: GraphSelectionState;
+    /** set by `:skill()`, read and cleared by `walk()` */
+    part?: Pick<QueryPart, 'name' | 'patterns'>;
+    /** one entry per top-level selector, only when opted in */
+    parts?: QueryPart<NodeLike>[];
+    /** part selectors this consumer allows */
+    partSelectors?: ReadonlySet<PartPseudoName>;
     retries: number;
     securityArchive: SecurityArchiveLike | undefined;
     scopeIDs?: DepID[];
@@ -59,6 +82,11 @@ export type QueryResponse = {
     importers: QueryResponseNode[];
     comment: string;
     specificity: Specificity;
+    /**
+     * one entry per top-level selector, only with `partSelectors` and
+     * a non-empty query
+     */
+    parts?: QueryPart[];
 };
 export type QueryResponseEdge = Omit<EdgeLike, 'from' | 'to'> & {
     from: QueryResponseNode;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/query",
   "description": "Query syntax parser that retrieves items from a graph",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,13 +13,13 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/dep-id": "1.4.0",
-    "@vltpkg/dss-parser": "1.4.0",
-    "@vltpkg/error-cause": "1.4.0",
-    "@vltpkg/security-archive": "1.4.0",
-    "@vltpkg/semver": "1.4.0",
-    "@vltpkg/types": "1.4.0",
-    "@vltpkg/user-agent": "1.4.0",
+    "@vltpkg/dep-id": "1.6.0",
+    "@vltpkg/dss-parser": "1.6.0",
+    "@vltpkg/error-cause": "1.6.0",
+    "@vltpkg/security-archive": "1.6.0",
+    "@vltpkg/semver": "1.6.0",
+    "@vltpkg/types": "1.6.0",
+    "@vltpkg/user-agent": "1.6.0",
     "minimatch": "^10.1.1",
     "p-retry": "^7.1.1",
     "postcss-selector-parser": "^7.1.1"
@@ -27,7 +27,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/node": "^22.19.2",
-    "@vltpkg/spec": "1.4.0",
+    "@vltpkg/spec": "1.6.0",
     "eslint": "^9.39.1",
     "prettier": "^3.7.4",
     "tap": "^21.8.0",
@@ -65,9 +65,7 @@
     }
   },
   "files": [
-    "dist",
-    "skills",
-    "!skills/dss-query/evals"
+    "dist"
   ],
   "bugs": [
     {

package/skills/dss-query/REFERENCE.md

@@ -1,123 +0,0 @@
-# DSS Reference
-
-Compiled from https://docs.vlt.io/cli/selectors/ (source:
-`www/docs/src/content/docs/cli/selectors/`). When in doubt, check
-those docs — they are canonical.
-
-## Attribute selectors
-
-Match against `package.json` fields.
-
-| Selector         | Meaning                                          |
-| ---------------- | ------------------------------------------------ |
-| `[attr]`         | has the property                                 |
-| `[attr=value]`   | equals                                           |
-| `[attr^=value]`  | starts with                                      |
-| `[attr$=value]`  | ends with                                        |
-| `[attr*=value]`  | contains                                         |
-| `[attr~=value]`  | whitespace-separated list contains               |
-| `[attr\|=value]` | equals value or starts with `value-`             |
-| `[attr=value i]` | case-insensitive (`s` = case-sensitive, default) |
-
-Nested fields (e.g. `engines.node`) need `:attr()`:
-`:attr(engines, [node])`,
-`:attr(peerDependenciesMeta, foo, [optional=true])`.
-
-`#foo` is shorthand for `[name=foo]`.
-
-## Combinators
-
-| Combinator | Meaning                                                              |
-| ---------- | -------------------------------------------------------------------- |
-| `A > B`    | B is a **direct** dependency of A (chain for depth: `:root > * > *`) |
-| `A B`      | B is a direct **or transitive** dependency of A                      |
-| `A ~ B`    | B shares a parent with A (sibling)                                   |
-
-## Pseudo-states (no arguments)
-
-Graph structure:
-
-| Selector     | Matches                                 |
-| ------------ | --------------------------------------- |
-| `:root`      | top-level package.json node             |
-| `:project`   | root + all workspaces ("your code")     |
-| `:workspace` | workspaces from vlt.json                |
-| `:scope`     | current selector scope (with `--scope`) |
-
-Dependency type:
-
-| Selector                                 | Matches                                                |
-| ---------------------------------------- | ------------------------------------------------------ |
-| `:prod` / `:dev` / `:optional` / `:peer` | by dependency type                                     |
-| `:missing`                               | declared but not installed (**edges only, not nodes**) |
-| `:overridden`                            | has an override applied                                |
-
-Package properties:
-
-| Selector      | Matches                                      |
-| ------------- | -------------------------------------------- |
-| `:private`    | `"private": true`                            |
-| `:empty`      | no dependencies                              |
-| `:link`       | linked packages                              |
-| `:prerelease` | version has prerelease part (`1.0.0-beta.1`) |
-| `:built`      | built during reify                           |
-| `:scanned`    | has Socket security metadata                 |
-
-## Pseudo-classes (take arguments)
-
-| Selector            | Meaning                                 | Example                                        |
-| ------------------- | --------------------------------------- | ---------------------------------------------- |
-| `:attr(...)`        | nested package.json property            | `:attr(engines, [node])`                       |
-| `:dist(tag)`        | registry dist-tag                       | `:dist(latest)`                                |
-| `:has(sel)`         | has matching descendant                 | `:has(:peer[name=react])`                      |
-| `:host(name)`       | switch graph context to another project | `:host(local) :malware`                        |
-| `:is(a, b)`         | any of (forgiving list)                 | `:is([name=a], [name=b])`                      |
-| `:not(sel)`         | negation                                | `:not([license=MIT])`                          |
-| `:outdated(kind?)`  | newer version exists                    | `:outdated(major)`                             |
-| `:published(range)` | by publish date                         | `:published(">2024")`                          |
-| `:semver(range)`    | semver comparison on installed version  | `:semver(^1.0.0)`                              |
-| `:spec(spec)`       | by declared specifier (edge)            | `:spec(^1.0.0)`                                |
-| `:path(glob)`       | workspace/file packages by path         | `:path("packages/**")`                         |
-| `:type(kind)`       | package type                            | `:type(git)`, `:type(registry)`, `:type(file)` |
-| `:diff(ref)`        | files changed vs git ref                | `:diff(main)`                                  |
-| `:hostname(host)`   | upstream hostname                       | `:hostname(github.com)`                        |
-| `:registry(name)`   | configured registry name                | `:registry(npm)`                               |
-
-## Security insights (Socket-powered, network call)
-
-Severity args accept names or numbers (`critical`/`0`, `high`/`1`,
-`medium`/`2`, `low`/`3`) and comparators: `:severity(">=medium")`.
-
-Threats: `:malware` (binary, no params), `:squat(sev?)`,
-`:suspicious`, `:confused`.
-
-Vulnerabilities: `:vuln(sev?)` (alias `:vulnerable`),
-`:cve(CVE-2023-1234)`, `:cve(*)`, `:cwe(CWE-79)`, `:severity(level)`.
-`:vuln` without params matches severity ≥ medium; `:vuln(critical)`
-exact-matches; `:vuln(">=high")` uses comparators. Also matches alerts
-carrying a `cveId` prop.
-
-Licensing: `:license(type)` — types: `unlicensed`, `misc`,
-`restricted`, `ambiguous`, `copyleft`, `unknown`, `none`, `exception`.
-
-Code behavior: `:eval`, `:network`, `:fs`, `:env`, `:shell`,
-`:scripts` (install scripts), `:debug`, `:dynamic`.
-
-Obfuscation: `:obfuscated`, `:minified`, `:entropic`, `:native`,
-`:shrinkwrap`.
-
-Health: `:deprecated`, `:unmaintained` (5+ years stale), `:unpopular`,
-`:trivial` (<10 LOC), `:abandoned`, `:unknown`, `:unstable`.
-
-Other: `:tracker` (telemetry), `:undesirable`, `:score(rate, kind?)` —
-kinds: `overall` (default), `license`, `maintenance`, `quality`,
-`supplyChain`, `vulnerability`; e.g. `:score("<=0.5", "maintenance")`.
-
-## Audit query starters
-
-```bash
-vlt query ':malware, :vuln(critical), :cve(*), :obfuscated'   # critical issues
-vlt query ':abandoned, :unmaintained, :unknown'        # supply chain risk
-vlt query ':license(copyleft), :license(unlicensed)'   # license compliance
-vlt query ':eval, :shell, :network, :fs'               # behavior audit
-```