@vltpkg/query 1.0.0-rc.32 → 1.0.0-rc.33

package/src/pseudo/outdated.ts

@@ -0,0 +1,305 @@
+import pRetry, { AbortError } from 'p-retry'
+import { hydrate, splitDepID } from '@vltpkg/dep-id/browser'
+import { error } from '@vltpkg/error-cause'
+import { asError } from '@vltpkg/types'
+import {
+  compare,
+  gt,
+  major,
+  minor,
+  patch,
+  satisfies,
+} from '@vltpkg/semver'
+import {
+  asPostcssNodeWithChildren,
+  asStringNode,
+  asTagNode,
+  isStringNode,
+  isTagNode,
+} from '@vltpkg/dss-parser'
+import { removeNode, removeQuotes } from './helpers.ts'
+import type { NodeLike, Packument } from '@vltpkg/types'
+import type { ParserState } from '../types.ts'
+import type { PostcssNode } from '@vltpkg/dss-parser'
+
+/**
+ * The possible values accepted by the :outdated() pseudo selector.
+ */
+export type OutdatedKinds =
+  'any' | 'major' | 'minor' | 'patch' | 'in-range' | 'out-of-range'
+
+/**
+ * Result of the internal parsing of the :outdated() pseudo selector.
+ */
+export type OutdatedInternals = {
+  kind: OutdatedKinds
+}
+
+/**
+ * Extracts a semver type from a version string.
+ */
+export type SemverTypeExtraction = (
+  version: string,
+) => number | undefined
+
+const kinds = new Set<OutdatedKinds>([
+  'any',
+  'major',
+  'minor',
+  'patch',
+  'in-range',
+  'out-of-range',
+])
+
+/**
+ * Checks if a string is a valid {@link OutdatedKinds}.
+ */
+export const isOutdatedKind = (
+  value: string,
+): value is OutdatedKinds => kinds.has(value as OutdatedKinds)
+
+/**
+ * Asserts that a string is a valid {@link OutdatedKinds}.
+ */
+export const asOutdatedKind = (value: string): OutdatedKinds => {
+  if (!isOutdatedKind(value)) {
+    throw error('Expected a valid outdated kind', {
+      found: value,
+      validOptions: Array.from(kinds),
+    })
+  }
+  return value
+}
+
+/**
+ * Fetches the available versions of a package from the npm registry.
+ */
+export const retrieveRemoteVersions = async (
+  node: NodeLike,
+  signal?: AbortSignal,
+): Promise<string[]> => {
+  const spec = hydrate(node.id, String(node.name), node.options)
+  if (!spec.registry || !node.name) {
+    return []
+  }
+
+  const url = new URL(spec.registry)
+  url.pathname = `/${node.name}`
+
+  const response = await fetch(String(url), {
+    headers: {
+      Accept: 'application/vnd.npm.install-v1+json',
+    },
+    signal,
+  })
+  // on missing valid auth or API, it should abort the retry logic
+  if (response.status === 404) {
+    throw new AbortError('Missing API')
+  }
+  if (!response.ok) {
+    throw error('Failed to fetch packument', {
+      name: node.name,
+      spec,
+      response,
+    })
+  }
+  const packument = (await response.json()) as Packument
+  return Object.keys(packument.versions).sort(compare)
+}
+
+/**
+ * Retrieves what kind of check the :outdated selector should perform.
+ */
+export const parseInternals = (
+  nodes: PostcssNode[],
+): OutdatedInternals => {
+  let kind: OutdatedKinds = 'any'
+
+  if (isStringNode(asPostcssNodeWithChildren(nodes[0]).nodes[0])) {
+    kind = asOutdatedKind(
+      removeQuotes(
+        asStringNode(asPostcssNodeWithChildren(nodes[0]).nodes[0])
+          .value,
+      ),
+    )
+  } else if (
+    isTagNode(asPostcssNodeWithChildren(nodes[0]).nodes[0])
+  ) {
+    kind = asOutdatedKind(
+      asTagNode(asPostcssNodeWithChildren(nodes[0]).nodes[0]).value,
+    )
+  }
+
+  return { kind }
+}
+
+/**
+ * Filter nodes by queueing up for removal those that are not outdated.
+ */
+export const queueNode = async (
+  state: ParserState,
+  node: NodeLike,
+  kind: OutdatedKinds,
+): Promise<NodeLike | undefined> => {
+  if (!node.name || !node.version) {
+    return node
+  }
+
+  const nodeVersion: string = node.version
+  let versions: string[]
+  try {
+    versions = await pRetry(
+      () => retrieveRemoteVersions(node, state.signal),
+      {
+        retries: state.retries,
+        signal: state.signal,
+      },
+    )
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      error('Could not retrieve registry versions', {
+        name: node.name,
+        cause: err,
+      }),
+    )
+    versions = []
+  }
+
+  const greaterVersions = versions.filter((version: string) =>
+    gt(version, nodeVersion),
+  )
+
+  // if there are no greater versions, then the node is not outdated
+  if (!greaterVersions.length) {
+    return node
+  }
+
+  const checkKind = new Map<OutdatedKinds, SemverTypeExtraction>([
+    ['major', major],
+    ['minor', minor],
+    ['patch', patch],
+  ])
+
+  switch (kind) {
+    case 'any':
+      return
+    case 'major':
+    case 'minor':
+    case 'patch': {
+      return (
+          greaterVersions.some((version: string) => {
+            const va = checkKind.get(kind)?.(version)
+            const vb = checkKind.get(kind)?.(nodeVersion)
+            /* c8 ignore next - impossible but typescript doesn't know */
+            if (va === undefined || vb === undefined) return false
+            return va > vb
+          })
+        ) ?
+          undefined
+        : node
+    }
+    // the node should be part of the result as long as it has at least
+    // one parent node that has a spec definition that satisfies one
+    // of the available remove versions
+    case 'in-range': {
+      for (const edge of node.edgesIn) {
+        // if the edge is not part of the partial results, skip it
+        /* c8 ignore next */
+        if (!state.partial.edges.has(edge)) continue
+
+        if (
+          greaterVersions.some(
+            version =>
+              edge.spec.final.range &&
+              satisfies(version, edge.spec.final.range),
+          )
+        ) {
+          return
+        }
+      }
+      return node
+    }
+    // the node is part of the result as long as none of its parents has
+    // a spec definition that satisfies one of the available remote versions
+    case 'out-of-range': {
+      for (const edge of node.edgesIn) {
+        // if the edge is not part of the partial results, skip it
+        /* c8 ignore next */
+        if (!state.partial.edges.has(edge)) continue
+
+        if (
+          greaterVersions.some(
+            version =>
+              edge.spec.final.range &&
+              satisfies(version, edge.spec.final.range),
+          )
+        ) {
+          return node
+        }
+      }
+      return
+    }
+  }
+}
+
+/**
+ * Filters out nodes that are not outdated.
+ *
+ * The :outdated() pseudo selector supports one `type` argument,
+ * possible values are the following:
+ *
+ * - `any`: Selects all nodes that have a greater version available.
+ * - `major`: Selects all nodes that have a greater major version available.
+ * - `minor`: Selects all nodes that have a greater minor version available.
+ * - `patch`: Selects all nodes that have a greater patch version available.
+ * - `in-range`: Selects all nodes that have a parent node with a spec definition
+ *  that satisfies one of the available remote versions.
+ *  - `out-of-range`: Selects all nodes that have a parent node with a spec definition
+ *  that does not satisfy any of the available remote versions.
+ */
+export const outdated = async (state: ParserState) => {
+  let internals
+  try {
+    internals = parseInternals(
+      asPostcssNodeWithChildren(state.current).nodes,
+    )
+  } catch (err) {
+    if (asError(err).message === 'Expected a query node') {
+      internals = { kind: 'any' } satisfies OutdatedInternals
+    } else {
+      throw error('Failed to parse :outdated selector', {
+        cause: err,
+      })
+    }
+  }
+
+  const { kind } = internals
+  const queue = []
+
+  for (const node of state.partial.nodes) {
+    // filter out nodes that are always ignored by the outdated selector
+    if (
+      node.mainImporter ||
+      node.manifest?.private ||
+      splitDepID(node.id)[0] !== 'registry'
+    ) {
+      removeNode(state, node)
+      continue
+    }
+
+    // fetchs outdated info and performs checks to define
+    // whether or not a node should be filtered out
+    queue.push(queueNode(state, node, kind))
+  }
+
+  // nodes queued for removal are then finally removed
+  const removeNodeQueue = await Promise.all(queue)
+  for (const node of removeNodeQueue) {
+    if (node) {
+      removeNode(state, node)
+    }
+  }
+
+  return state
+}

package/src/pseudo/overridden.ts

@@ -0,0 +1,20 @@
+import type { ParserState } from '../types.ts'
+import { removeEdge, removeUnlinkedNodes } from './helpers.ts'
+
+/**
+ * :overridden Pseudo-Selector, matches only edges that have a truthy overridden property in their spec.
+ * It filters out any edges that don't have edge.spec.overridden set to a truthy value
+ * and removes any unlinked nodes from the result.
+ */
+export const overridden = async (state: ParserState) => {
+  // filter edges that don't have a truthy overridden property
+  for (const edge of state.partial.edges) {
+    if (!edge.spec.overridden) {
+      removeEdge(state, edge)
+    }
+  }
+
+  removeUnlinkedNodes(state)
+
+  return state
+}

package/src/pseudo/path.ts

@@ -0,0 +1,146 @@
+import { minimatch } from 'minimatch'
+import { error } from '@vltpkg/error-cause'
+import { splitDepID } from '@vltpkg/dep-id/browser'
+import { asError } from '@vltpkg/types'
+import {
+  asPostcssNodeWithChildren,
+  asStringNode,
+  isStringNode,
+} from '@vltpkg/dss-parser'
+import {
+  removeNode,
+  removeDanglingEdges,
+  removeQuotes,
+  clear,
+} from './helpers.ts'
+import type { ParserState } from '../types.ts'
+
+/**
+ * Normalizes a path by trimming whitespace and removing leading './' or '.' prefix.
+ * This ensures consistent path comparison regardless of how paths are specified.
+ */
+export function normalizePath(path: string): string {
+  const trimmed = path.trim().replaceAll('\\', '/')
+
+  if (trimmed === '.') {
+    return ''
+  }
+
+  if (trimmed.startsWith('./')) {
+    return trimmed.slice(2)
+  }
+
+  return trimmed
+}
+
+/**
+ * Creates a path matcher function that tests if
+ * a given path matches a glob pattern.
+ */
+export function createPathMatcher(pattern: string, loose = false) {
+  const normalizedPattern = normalizePath(pattern)
+  const isRoot = normalizedPattern === '' || pattern.trim() === '.'
+
+  return (path: string) => {
+    const normalizedPath = normalizePath(path)
+
+    if (isRoot) {
+      return normalizedPath === '' || normalizedPath === '.'
+    }
+    try {
+      return minimatch(normalizedPath, normalizedPattern, {
+        dot: true,
+        nocase: false,
+        matchBase: normalizedPattern === '*',
+      })
+    } catch (err) {
+      // In loose mode, return false for invalid patterns
+      if (loose) {
+        return false
+      }
+      // In strict mode, throw an error
+      throw error(
+        'Invalid glob pattern in :path selector',
+        asError(err),
+      )
+    }
+  }
+}
+
+/**
+ * :path("glob") Pseudo-Selector will match only workspace & file
+ * nodes whose file path matches the provided glob pattern relative
+ * to the project root. Path patterns must be quoted strings to avoid
+ * parser conflicts with special characters.
+ */
+export const path = async (state: ParserState) => {
+  // Extract path container and handle empty parameters
+  const pathContainer = asPostcssNodeWithChildren(state.current)
+  if (!pathContainer.nodes[0]) {
+    return clear(state)
+  }
+
+  // Extract the selector node and handle empty selectors
+  const selector = asPostcssNodeWithChildren(pathContainer.nodes[0])
+  if (!selector.nodes[0]) {
+    return clear(state)
+  }
+
+  // Extract and validate the path pattern
+  let pathPattern = ''
+  if (isStringNode(selector.nodes[0])) {
+    pathPattern = removeQuotes(asStringNode(selector.nodes[0]).value)
+  } else {
+    if (state.loose) {
+      return clear(state)
+    }
+    throw error(
+      'Failed to parse path pattern in :path selector',
+      new Error('Path pattern must be a quoted string'),
+    )
+  }
+
+  // If no pattern provided, match nothing
+  if (!pathPattern) {
+    return clear(state)
+  }
+
+  // Check for unmatched brackets
+  if (
+    pathPattern === '[' ||
+    (pathPattern.includes('[') && !pathPattern.includes(']'))
+  ) {
+    if (state.loose) {
+      return clear(state)
+    }
+    throw error(
+      'Invalid glob pattern in :path selector',
+      new Error(`Unmatched bracket in pattern: ${pathPattern}`),
+    )
+  }
+
+  // Create path matcher function
+  const matchPath = createPathMatcher(pathPattern, state.loose)
+
+  // Filter nodes by path
+  for (const node of state.partial.nodes) {
+    /* c8 ignore next */
+    const nodePath = node.location || ''
+    const [type] = splitDepID(node.id)
+
+    // Special case for main importer with root path pattern
+    if (pathPattern === '.' && node.mainImporter) {
+      continue // Keep main importer node for root path pattern
+    }
+
+    // Only match workspace or file nodes with matching paths
+    const pathBased = type === 'workspace' || type === 'file'
+    if (!pathBased || !matchPath(nodePath)) {
+      removeNode(state, node)
+    }
+  }
+
+  // Clean up any dangling edges
+  removeDanglingEdges(state)
+  return state
+}

package/src/pseudo/peer.ts

@@ -0,0 +1,18 @@
+import type { ParserState } from '../types.ts'
+import { removeEdge, removeUnlinkedNodes } from './helpers.ts'
+
+/**
+ * :peer Pseudo-Selector will only match peer dependencies.
+ */
+export const peer = async (state: ParserState) => {
+  // filter edges that aren't marked as peer
+  for (const edge of state.partial.edges) {
+    if (!edge.peer) {
+      removeEdge(state, edge)
+    }
+  }
+
+  removeUnlinkedNodes(state)
+
+  return state
+}

package/src/pseudo/prerelease.ts

@@ -0,0 +1,47 @@
+import { parse } from '@vltpkg/semver'
+import { removeNode, removeDanglingEdges } from './helpers.ts'
+import type { ParserState } from '../types.ts'
+
+/**
+ * :prerelease Pseudo-selector, matches only nodes that have prerelease
+ * elements in their parsed semver value.
+ *
+ * Examples of versions that should match:
+ * - 19.2.0-canary-fa3feba6-20250623
+ * - 1.0.0-beta.0
+ * - 0.0.0-16
+ * - 1.2.3-rc.1+rev.2
+ *
+ * Examples of versions that should NOT match:
+ * - 1.0.0
+ * - 99.9.9
+ * - 0.0.1
+ */
+export const prerelease = async (state: ParserState) => {
+  for (const node of state.partial.nodes) {
+    const version = node.manifest?.version
+
+    // Skip nodes without a version (like root/importer nodes)
+    if (!version) {
+      removeNode(state, node)
+      continue
+    }
+
+    const parsedVersion = parse(version)
+    if (!parsedVersion) {
+      // Remove nodes with invalid semver versions
+      removeNode(state, node)
+      continue
+    }
+
+    // Check if the version has prerelease identifiers
+    if (!parsedVersion.prerelease?.length) {
+      // Remove nodes that don't have prerelease identifiers
+      removeNode(state, node)
+    }
+  }
+
+  removeDanglingEdges(state)
+
+  return state
+}

package/src/pseudo/private.ts

@@ -0,0 +1,19 @@
+import { asManifest } from '@vltpkg/types'
+import type { ParserState } from '../types.ts'
+import { removeNode, removeDanglingEdges } from './helpers.ts'
+
+/**
+ * :private Pseudo-Selector will only match packages that have
+ * a `private: true` key set in their `package.json` metadata.
+ */
+export const privateParser = async (state: ParserState) => {
+  for (const node of state.partial.nodes) {
+    if (!node.manifest || !asManifest(node.manifest).private) {
+      removeNode(state, node)
+    }
+  }
+
+  removeDanglingEdges(state)
+
+  return state
+}

package/src/pseudo/prod.ts

@@ -0,0 +1,18 @@
+import type { ParserState } from '../types.ts'
+import { removeEdge, removeUnlinkedNodes } from './helpers.ts'
+
+/**
+ * :prod Pseudo-Selector will only match production dependencies.
+ */
+export const prod = async (state: ParserState) => {
+  // filter edges that don't have type 'prod'
+  for (const edge of state.partial.edges) {
+    if (edge.type !== 'prod') {
+      removeEdge(state, edge)
+    }
+  }
+
+  removeUnlinkedNodes(state)
+
+  return state
+}