@vltpkg/query 1.3.8 → 1.5.0

package/src/types.ts

@@ -4,7 +4,7 @@ import type {
   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[]
@@ -46,6 +46,24 @@ 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
@@ -53,6 +71,7 @@ export type ParserState = {
   current: PostcssNode
   diffFiles?: DiffFilesProvider
   getAuthHeader?: GetAuthHeader
+  hasSkills?: HasSkills
   hostContexts?: HostContextsMap
   importers: Set<NodeLike>
   initial: GraphSelectionState
@@ -63,6 +82,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[]
@@ -75,6 +100,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'> & {

package/tap-snapshots/test/pseudo/skills.ts.test.cjs

@@ -0,0 +1,19 @@
+/* IMPORTANT
+ * This snapshot file is auto-generated, but designed for humans.
+ * It should be checked into source control and tracked carefully.
+ * Re-generate by setting TAP_SNAPSHOT=1 and running tests.
+ * Make sure to inspect the output below.  Do not ignore changes!
+ */
+'use strict'
+exports[`test/pseudo/skills.ts > TAP > matches packages the provider says ship skills > must match snapshot 1`] = `
+Object {
+  "edges": Array [
+    "a",
+    "d",
+  ],
+  "nodes": Array [
+    "a",
+    "d",
+  ],
+}
+`

package/test/index.ts

@@ -289,6 +289,99 @@ t.test('insights', async t => {
   }
 })
 
+t.test('parts', async t => {
+  const graph = getSimpleGraph()
+  const opts = {
+    nodes: new Set(graph.nodes.values()),
+    edges: graph.edges,
+    importers: graph.importers,
+    securityArchive: undefined,
+  }
+  const query = new Query({ ...opts, partSelectors: ['skill'] })
+  const search = (q: string) => query.search(q, mockSearchOptions)
+  const parts = async (q: string) =>
+    (await search(q)).parts?.map(({ nodes, ...p }) => ({
+      ...p,
+      nodes: nodes.map(n => n.name).sort(),
+    }))
+
+  t.strictSame(await parts(':root > *, #b:skill(x)'), [
+    { nodes: ['@x/y', 'a', 'b', 'e'] },
+    { name: 'skill', patterns: ['x'], nodes: ['b'] },
+  ])
+  const res = await search(':root > *, #b:skill(x)')
+  const [plain, b] = res.parts ?? []
+  t.notOk(plain && 'name' in plain, 'plain part has no name')
+  t.notOk(plain && 'patterns' in plain, 'plain part has no patterns')
+  t.equal(
+    b?.nodes[0],
+    res.nodes.find(n => n.name === 'b'),
+    'part nodes are response nodes',
+  )
+  t.ok(b?.nodes[0]?.insights, 'part nodes are hydrated')
+  t.equal(
+    await search(':root > *, #b:skill(x)'),
+    res,
+    'cache hit keeps parts',
+  )
+
+  t.strictSame(await parts(':root > *:not(#b), #b:skill(x)'), [
+    { nodes: ['@x/y', 'a', 'e'] },
+    { name: 'skill', patterns: ['x'], nodes: ['b'] },
+  ])
+  t.strictSame(await parts('#a, #b:skill(x), #c:skill(y)'), [
+    { nodes: ['a'] },
+    { name: 'skill', patterns: ['x'], nodes: ['b'] },
+    { name: 'skill', patterns: ['y'], nodes: ['c'] },
+  ])
+  t.strictSame(await parts('#b:skill(x), #a'), [
+    { name: 'skill', patterns: ['x'], nodes: ['b'] },
+    { nodes: ['a'] },
+  ])
+  t.strictSame(await parts('#nope:skill(x)'), [
+    { name: 'skill', patterns: ['x'], nodes: [] },
+  ])
+  t.strictSame(await parts('#a, #b:skills(x)'), [
+    { nodes: ['a'] },
+    { nodes: [] },
+  ])
+  t.notOk('parts' in (await search('')), 'empty query')
+
+  const plainQuery = new Query(opts)
+  t.notOk(
+    'parts' in
+      (await plainQuery.search(':root > *', mockSearchOptions)),
+    'no parts without partSelectors',
+  )
+})
+
+t.test(':skills', async t => {
+  const graph = getSimpleGraph()
+  const query = new Query({
+    nodes: new Set(graph.nodes.values()),
+    edges: graph.edges,
+    importers: graph.importers,
+    securityArchive: undefined,
+    hasSkills: async node => node.name === 'c' || node.name === 'e',
+  })
+  const names = async (q: string) =>
+    (await query.search(q, mockSearchOptions)).nodes
+      .map(n => n.name)
+      .sort()
+  t.strictSame(await names(':skills'), ['c', 'e'])
+  t.strictSame(await names(':root > :skills'), ['e'])
+  t.strictSame(await names(':not(:skills)'), [
+    '@x/y',
+    'a',
+    'b',
+    'd',
+    'f',
+    'my-project',
+  ])
+  t.strictSame(await names(':is(:skills)'), ['c', 'e'])
+  t.strictSame(await names(':has(:skills)'), ['b', 'd', 'my-project'])
+})
+
 t.test('bad selector type', async t => {
   await t.rejects(
     walk(testBrokenState()),
@@ -333,6 +426,12 @@ t.test('trying to use tag selectors', async t => {
     'should suggest the pseudo-class of the same name',
   )
 
+  await t.rejects(
+    search('skill'),
+    { cause: { code: 'EQUERY', found: 'skill', wanted: '#skill' } },
+    'should not suggest a part selector',
+  )
+
   await t.rejects(
     search('.foo'),
     { cause: { code: 'EQUERY', found: '.foo', wanted: '#foo' } },

package/test/pseudo/skill.ts

@@ -0,0 +1,189 @@
+import t from 'tap'
+import { Query } from '../../src/index.ts'
+import { getSimpleGraph } from '../fixtures/graph.ts'
+import type { Test } from 'tap'
+import type { QueryOptions } from '../../src/index.ts'
+
+type Opts = Pick<QueryOptions, 'partSelectors'>
+
+const search = (
+  q: string,
+  opts: Opts = { partSelectors: ['skill'] },
+) => {
+  const graph = getSimpleGraph()
+  return new Query({
+    edges: graph.edges,
+    nodes: new Set(graph.nodes.values()),
+    importers: graph.importers,
+    securityArchive: undefined,
+    ...opts,
+  }).search(q, { signal: new AbortController().signal })
+}
+
+const parts = async (q: string) =>
+  (await search(q)).parts?.map(({ nodes, ...p }) => ({
+    ...p,
+    nodes: nodes.map(n => n.name).sort(),
+  }))
+
+type QueryErr = Error & {
+  cause: { code: string; found: string; wanted?: string }
+}
+const errorOf = async (q: string, opts?: Opts) =>
+  search(q, opts).then(
+    () => {
+      throw new Error(`expected ${q} to throw`)
+    },
+    (er: unknown) => er as QueryErr,
+  )
+
+const fails = async (
+  t: Test,
+  queries: string[],
+  message: string,
+  opts?: Opts,
+) => {
+  for (const q of queries) {
+    const er = await errorOf(q, opts)
+    t.equal(er.message, message, q)
+    t.equal(er.cause.code, 'EQUERY', q)
+  }
+}
+
+t.test('patterns', async t => {
+  const cases: [string, string[]][] = [
+    ['#a:skill(find-skills)', ['find-skills']],
+    ['#a:skill("my skill")', ['my skill']],
+    [
+      '#a:skill(vercel*, *-review, a*b*c, *, **)',
+      ['vercel*', '*-review', 'a*b*c', '*', '**'],
+    ],
+    [
+      '#a:skill(X, my.skill, a_b, 3d-print, -x)',
+      ['X', 'my.skill', 'a_b', '3d-print', '-x'],
+    ],
+    ['#a:skill("my "*)', ['my *']],
+    ['#a:skill(a\\ b)', ['a b']],
+    ['#a:skill(/* c */ a)', ['a']],
+    ['#a:skill("it\'s")', ["it's"]],
+    ['#a:skill(x)/* c */ /* d */', ['x']],
+  ]
+  for (const [q, patterns] of cases) {
+    t.strictSame(
+      await parts(q),
+      [{ name: 'skill', patterns, nodes: ['a'] }],
+      q,
+    )
+  }
+})
+
+t.test('never filters nodes', async t => {
+  const nodesOf = async (q: string) => (await parts(q))?.[0]?.nodes
+  t.strictSame(await nodesOf(':skill(x)'), [
+    '@x/y',
+    'a',
+    'b',
+    'c',
+    'd',
+    'e',
+    'f',
+    'my-project',
+  ])
+  t.strictSame(await nodesOf('#b :skill(x)'), ['c', 'd', 'e', 'f'])
+  t.strictSame(await nodesOf(':root > :skill(x)'), [
+    '@x/y',
+    'a',
+    'b',
+    'e',
+  ])
+})
+
+t.test('specificity', async t => {
+  t.strictSame((await search('#a:skill(x)')).specificity, {
+    idCounter: 1,
+    commonCounter: 1,
+  })
+})
+
+t.test('errors', async t => {
+  await fails(
+    t,
+    [
+      '#a:skill(x) > #b',
+      '#a:skill(x):prod',
+      '#a:skill(x):skill(y)',
+      ':not(#a:skill(x))',
+      ':is(#a:skill(x))',
+      ':has(#a:skill(x))',
+      '#b, #a:skill(x) > *',
+    ],
+    ':skill() must end a top-level selector',
+  )
+  await fails(
+    t,
+    [
+      '#a:skill',
+      '#a:skill()',
+      '#a:skill( )',
+      '#a:skill(a,)',
+      '#a:skill(/* c */)',
+      '#a:skill("")',
+    ],
+    'Missing skill name in :skill()',
+  )
+  await fails(
+    t,
+    ['#a:skill(a b)', '#a:skill(x > y)', '#b, #a:skill(a b)'],
+    'Invalid skill name in :skill(), quote names with spaces',
+  )
+  await fails(
+    t,
+    ["#a:skill('b c')", "#a:skill(x, 'y')", "#a:skill('y'*)"],
+    'Invalid skill name in :skill(), use double quotes',
+  )
+  await fails(
+    t,
+    [
+      '#a:skill(#x)',
+      '#a:skill(:prod)',
+      '#a:skill([x])',
+      '#a:skill(a|b)',
+      '#a:skill(|a)',
+      '#a:skill(a|*)',
+      '#a:skill(a&b)',
+    ],
+    'Invalid skill name in :skill()',
+  )
+  t.equal((await errorOf('#a:skill(a b)')).cause.found, ':skill(a b)')
+  t.equal(
+    (await errorOf('#a:skill(x) > #b')).cause.found,
+    ':skill(x)',
+  )
+})
+
+t.test('opt-in', async t => {
+  const queries = ['#a:skill(x)', '#a, #b:skill(x)', '#a:skill()']
+  const message =
+    ':skill() only applies to --allow-skills and vlt skills'
+  for (const opts of [{}, { partSelectors: [] }]) {
+    await fails(t, queries, message, opts)
+    // position is checked first
+    await fails(
+      t,
+      [':not(#a:skill(x))'],
+      ':skill() must end a top-level selector',
+      opts,
+    )
+  }
+})
+
+t.test('typo', async t => {
+  const er = await errorOf('#a:skills(x)')
+  t.equal(er.message, ':skills takes no arguments')
+  t.equal(er.cause.wanted, ':skill')
+  // loose in a comma list: silently empty
+  t.strictSame(await parts('#a, #b:skills(x)'), [
+    { nodes: ['a'] },
+    { nodes: [] },
+  ])
+})

package/test/pseudo/skills.ts

@@ -0,0 +1,90 @@
+import t from 'tap'
+import postcssSelectorParser from 'postcss-selector-parser'
+import type { EdgeLike, NodeLike } from '@vltpkg/types'
+import type { HasSkills, ParserState } from '../../src/types.ts'
+import { skills } from '../../src/pseudo/skills.ts'
+import { getSimpleGraph } from '../fixtures/graph.ts'
+
+const getState = (
+  query: string,
+  hasSkills?: HasSkills,
+  loose?: boolean,
+) => {
+  const graph = getSimpleGraph()
+  const current = postcssSelectorParser().astSync(query).first.first
+  const state: ParserState = {
+    comment: '',
+    current,
+    initial: {
+      edges: new Set(graph.edges.values()),
+      nodes: new Set(graph.nodes.values()),
+    },
+    partial: {
+      edges: new Set(graph.edges.values()),
+      nodes: new Set(graph.nodes.values()),
+    },
+    collect: { edges: new Set(), nodes: new Set() },
+    cancellable: async () => {},
+    walk: async i => i,
+    retries: 0,
+    securityArchive: undefined,
+    importers: new Set(graph.importers),
+    signal: new AbortController().signal,
+    specificity: { idCounter: 0, commonCounter: 0 },
+    hasSkills,
+    loose,
+  }
+  return state
+}
+
+const names = (state: ParserState) => ({
+  nodes: [...state.partial.nodes].map(n => n.name).sort(),
+  edges: [...state.partial.edges].map(e => e.name).sort(),
+})
+
+t.test('matches packages the provider says ship skills', async t => {
+  const asked: string[] = []
+  const hasSkills: HasSkills = async (node: NodeLike) => {
+    asked.push(String(node.name))
+    await new Promise(r => setTimeout(r, 0))
+    return node.name === 'a' || node.name === 'd'
+  }
+  const state = getState(':skills', hasSkills)
+  // edge with no node: dropped
+  state.partial.edges.add({ name: 'gone' } as EdgeLike)
+  const res = await skills(state)
+  t.strictSame(names(res), { nodes: ['a', 'd'], edges: ['a', 'd'] })
+  t.matchSnapshot(names(res))
+  t.strictSame(
+    asked.sort(),
+    ['@x/y', 'a', 'b', 'c', 'd', 'e', 'f', 'my-project'],
+    'asked once per node',
+  )
+})
+
+t.test('none', async t => {
+  const res = await skills(getState(':skills', async () => false))
+  t.strictSame(names(res), { nodes: [], edges: [] })
+})
+
+t.test('no provider', async t => {
+  await t.rejects(skills(getState(':skills')), {
+    message: 'The :skills selector is not supported here',
+    cause: { code: 'EQUERY', found: ':skills' },
+  })
+})
+
+t.test('arguments', async t => {
+  for (const q of [':skills(x)', ':skills()']) {
+    await t.rejects(
+      skills(getState(q, async () => true)),
+      {
+        message: ':skills takes no arguments',
+        cause: { code: 'EQUERY', found: q, wanted: ':skill' },
+      },
+      q,
+    )
+    const res = await skills(getState(q, async () => true, true))
+    t.strictSame(names(res), { nodes: [], edges: [] }, `${q} loose`)
+  }
+})