@vltpkg/query 0.0.0-11 → 0.0.0-13

package/dist/esm/attribute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attribute.d.ts","sourceRoot":"","sources":["../../src/attribute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAG7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;AAOpE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,SAC9B,QAAQ,cACF,MAAM,EAAE,aACT,MAAM,KAChB,MAAM,EAAE,GAAG,SA+Db,CAAA;AAID,eAAO,MAAM,gBAAgB,UACpB,WAAW,cACN,YAAY,GAAG,SAAS,SAC7B,MAAM,gBACC,MAAM,eACP,OAAO,qBACF,MAAM,EAAE,KACzB,WAgDF,CAAA;AAcD,eAAO,MAAM,qBAAqB,2BAEjC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,UACb,WAAW,KACjB,OAAO,CAAC,WAAW,CAyBrB,CAAA"}
+{"version":3,"file":"attribute.d.ts","sourceRoot":"","sources":["../../src/attribute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAG7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG7C,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;AAOpE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,SAC9B,QAAQ,cACF,MAAM,EAAE,aACT,MAAM,KAChB,MAAM,EAAE,GAAG,SA+Db,CAAA;AAID,eAAO,MAAM,gBAAgB,UACpB,WAAW,cACN,YAAY,GAAG,SAAS,SAC7B,MAAM,gBACC,MAAM,eACP,OAAO,qBACF,MAAM,EAAE,KACzB,WAsCF,CAAA;AAcD,eAAO,MAAM,qBAAqB,2BAEjC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,UACb,WAAW,KACjB,OAAO,CAAC,WAAW,CA6BrB,CAAA"}

package/dist/esm/attribute.js

@@ -1,5 +1,6 @@
 import { error } from '@vltpkg/error-cause';
 import { asAttributeNode } from "./types.js";
+import { removeDanglingEdges } from "./pseudo/helpers.js";
 // JSONField has a mapped type constituent that would coerce to [object Object]
 // when stringified, which is what we want in this case.
 // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -93,17 +94,7 @@ export const filterAttributes = (state, comparator, value, propertyName, insensi
             deleteNode(node);
         }
     }
-    for (const edge of state.partial.edges) {
-        // edge.name is a special case in order
-        // to be able to match missing nodes by name
-        if (propertyName === 'name' && check(edge.name)) {
-            continue;
-        }
-        // remove any remaining dangling edge
-        if (!edge.to) {
-            state.partial.edges.delete(edge);
-        }
-    }
+    removeDanglingEdges(state);
     return state;
 };
 // ref: https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors
@@ -135,6 +126,8 @@ export const attribute = async (state) => {
     const value = curr.value || '';
     const propertyName = curr.attribute;
     const insensitive = !!curr.insensitive;
+    // Increment the commonCounter for specificity
+    state.specificity.commonCounter += 1;
     return filterAttributes(state, operatorFn, value, propertyName, insensitive);
 };
 //# sourceMappingURL=attribute.js.map

package/dist/esm/attribute.js.map

@@ -1 +1 @@
-{"version":3,"file":"attribute.js","sourceRoot":"","sources":["../../src/attribute.ts"],"names":[],"mappings":"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","sourcesContent":["import { error } from '@vltpkg/error-cause'\nimport type { NodeLike } from '@vltpkg/graph'\nimport type { JSONField, Manifest } from '@vltpkg/types'\nimport { asAttributeNode } from './types.ts'\nimport type { ParserState } from './types.ts'\n\nexport type ComparatorFn = (attr: string, value?: string) => boolean\n\n// JSONField has a mapped type constituent that would coerce to [object Object]\n// when stringified, which is what we want in this case.\n// eslint-disable-next-line @typescript-eslint/no-base-to-string\nconst jsonFieldToString = (v: JSONField) => String(v)\n\n/**\n * Retrieve the {@link Manifest} values found at the given `properties`\n * location for a given {@link Node}.\n */\nexport const getManifestPropertyValues = (\n  node: NodeLike,\n  properties: string[],\n  attribute: string,\n): string[] | undefined => {\n  if (!node.manifest) return\n\n  const traverse = new Set<JSONField>([node.manifest as JSONField])\n  const props = new Set<JSONField>()\n  for (const key of properties) {\n    for (const prop of traverse) {\n      /* c8 ignore start - should be impossible */\n      if (!prop) {\n        throw error('failed to find nested property in :attr', {\n          found: properties,\n        })\n      }\n      /* c8 ignore stop */\n\n      // expand the result list to include nested array values\n      if (Array.isArray(prop)) {\n        for (const p of prop) {\n          traverse.add(p)\n        }\n        continue\n      }\n\n      // guard for inspecting keys of objects next\n      if (\n        typeof prop === 'string' ||\n        typeof prop === 'number' ||\n        typeof prop === 'boolean'\n      ) {\n        continue\n      }\n\n      // assign next value when found\n      if (key in prop) {\n        const nextValue = prop[key]\n        if (nextValue) {\n          if (key === attribute) {\n            props.add(nextValue)\n          } else {\n            traverse.delete(prop)\n            traverse.add(nextValue)\n          }\n        }\n      }\n    }\n  }\n  // if no value was found after trying a given key\n  // then there's nothing to be collected\n  if (!props.size) return\n\n  // expand the result to include array values\n  const collect = new Set<string>()\n  for (const prop of props) {\n    if (Array.isArray(prop)) {\n      for (const p of prop) {\n        collect.add(p ? jsonFieldToString(p) : '')\n      }\n    } else {\n      collect.add(jsonFieldToString(prop))\n    }\n  }\n\n  return [...collect]\n}\n\n// decorator style of function that will filter `ParserState` results\n// based on a provided `comparator` function\nexport const filterAttributes = (\n  state: ParserState,\n  comparator: ComparatorFn | undefined,\n  value: string,\n  propertyName: string,\n  insensitive: boolean,\n  prefixProperties: string[] = [],\n): ParserState => {\n  const check = (attr: JSONField) =>\n    comparator?.(\n      insensitive ?\n        jsonFieldToString(attr).toLowerCase()\n      : jsonFieldToString(attr),\n      insensitive ? value.toLowerCase() : value,\n    )\n  const deleteNode = (node: NodeLike) => {\n    for (const edge of node.edgesIn) {\n      state.partial.edges.delete(edge)\n    }\n    state.partial.nodes.delete(node)\n  }\n\n  for (const node of state.partial.nodes) {\n    const prefixes =\n      prefixProperties.length ? prefixProperties : [propertyName]\n    const attrs = getManifestPropertyValues(\n      node,\n      prefixes,\n      propertyName,\n    )\n\n    // if no attribute value was found, that means the attribute won't match\n    if (!attrs?.length) {\n      deleteNode(node)\n      continue\n    }\n\n    // if the node attribute value won't match, then remove the node\n    if (comparator && !attrs.some(check)) {\n      deleteNode(node)\n    }\n  }\n\n  for (const edge of state.partial.edges) {\n    // edge.name is a special case in order\n    // to be able to match missing nodes by name\n    if (propertyName === 'name' && check(edge.name)) {\n      continue\n    }\n    // remove any remaining dangling edge\n    if (!edge.to) {\n      state.partial.edges.delete(edge)\n    }\n  }\n  return state\n}\n\n// ref: https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors\nconst attributeSelectors: Record<string, ComparatorFn> = {\n  '=': (attr: string, value = '') => attr === value,\n  '^=': (attr: string, value = '') => attr.startsWith(value),\n  '$=': (attr: string, value = '') => attr.endsWith(value),\n  '~=': (attr: string, value = '') =>\n    new Set<string>(attr.match(/\\w+/g)).has(value),\n  '*=': (attr: string, value = '') => attr.includes(value),\n  '|=': (attr: string, value = '') =>\n    attr === value || attr.startsWith(`${value}-`),\n  undefined: (attr: string) => !!attr,\n}\nexport const attributeSelectorsMap = new Map<string, ComparatorFn>(\n  Object.entries(attributeSelectors),\n)\n\n/**\n * Parse attributes selectors, e.g: `[name]`, `[name=value]`, etc\n */\nexport const attribute = async (\n  state: ParserState,\n): Promise<ParserState> => {\n  await state.cancellable()\n\n  const curr = asAttributeNode(state.current)\n  const operatorFn = attributeSelectorsMap.get(String(curr.operator))\n  if (!operatorFn) {\n    if (state.loose) {\n      return state\n    }\n\n    throw error(`Unsupported attribute operator: ${curr.operator}`, {\n      found: state.current,\n    })\n  }\n\n  const value = curr.value || ''\n  const propertyName = curr.attribute\n  const insensitive = !!curr.insensitive\n  return filterAttributes(\n    state,\n    operatorFn,\n    value,\n    propertyName,\n    insensitive,\n  )\n}\n"]}
+{"version":3,"file":"attribute.js","sourceRoot":"","sources":["../../src/attribute.ts"],"names":[],"mappings":"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","sourcesContent":["import { error } from '@vltpkg/error-cause'\nimport type { NodeLike } from '@vltpkg/graph'\nimport type { JSONField, Manifest } from '@vltpkg/types'\nimport { asAttributeNode } from './types.ts'\nimport type { ParserState } from './types.ts'\nimport { removeDanglingEdges } from './pseudo/helpers.ts'\n\nexport type ComparatorFn = (attr: string, value?: string) => boolean\n\n// JSONField has a mapped type constituent that would coerce to [object Object]\n// when stringified, which is what we want in this case.\n// eslint-disable-next-line @typescript-eslint/no-base-to-string\nconst jsonFieldToString = (v: JSONField) => String(v)\n\n/**\n * Retrieve the {@link Manifest} values found at the given `properties`\n * location for a given {@link Node}.\n */\nexport const getManifestPropertyValues = (\n  node: NodeLike,\n  properties: string[],\n  attribute: string,\n): string[] | undefined => {\n  if (!node.manifest) return\n\n  const traverse = new Set<JSONField>([node.manifest as JSONField])\n  const props = new Set<JSONField>()\n  for (const key of properties) {\n    for (const prop of traverse) {\n      /* c8 ignore start - should be impossible */\n      if (!prop) {\n        throw error('failed to find nested property in :attr', {\n          found: properties,\n        })\n      }\n      /* c8 ignore stop */\n\n      // expand the result list to include nested array values\n      if (Array.isArray(prop)) {\n        for (const p of prop) {\n          traverse.add(p)\n        }\n        continue\n      }\n\n      // guard for inspecting keys of objects next\n      if (\n        typeof prop === 'string' ||\n        typeof prop === 'number' ||\n        typeof prop === 'boolean'\n      ) {\n        continue\n      }\n\n      // assign next value when found\n      if (key in prop) {\n        const nextValue = prop[key]\n        if (nextValue) {\n          if (key === attribute) {\n            props.add(nextValue)\n          } else {\n            traverse.delete(prop)\n            traverse.add(nextValue)\n          }\n        }\n      }\n    }\n  }\n  // if no value was found after trying a given key\n  // then there's nothing to be collected\n  if (!props.size) return\n\n  // expand the result to include array values\n  const collect = new Set<string>()\n  for (const prop of props) {\n    if (Array.isArray(prop)) {\n      for (const p of prop) {\n        collect.add(p ? jsonFieldToString(p) : '')\n      }\n    } else {\n      collect.add(jsonFieldToString(prop))\n    }\n  }\n\n  return [...collect]\n}\n\n// decorator style of function that will filter `ParserState` results\n// based on a provided `comparator` function\nexport const filterAttributes = (\n  state: ParserState,\n  comparator: ComparatorFn | undefined,\n  value: string,\n  propertyName: string,\n  insensitive: boolean,\n  prefixProperties: string[] = [],\n): ParserState => {\n  const check = (attr: JSONField) =>\n    comparator?.(\n      insensitive ?\n        jsonFieldToString(attr).toLowerCase()\n      : jsonFieldToString(attr),\n      insensitive ? value.toLowerCase() : value,\n    )\n  const deleteNode = (node: NodeLike) => {\n    for (const edge of node.edgesIn) {\n      state.partial.edges.delete(edge)\n    }\n    state.partial.nodes.delete(node)\n  }\n\n  for (const node of state.partial.nodes) {\n    const prefixes =\n      prefixProperties.length ? prefixProperties : [propertyName]\n    const attrs = getManifestPropertyValues(\n      node,\n      prefixes,\n      propertyName,\n    )\n\n    // if no attribute value was found, that means the attribute won't match\n    if (!attrs?.length) {\n      deleteNode(node)\n      continue\n    }\n\n    // if the node attribute value won't match, then remove the node\n    if (comparator && !attrs.some(check)) {\n      deleteNode(node)\n    }\n  }\n\n  removeDanglingEdges(state)\n  return state\n}\n\n// ref: https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors\nconst attributeSelectors: Record<string, ComparatorFn> = {\n  '=': (attr: string, value = '') => attr === value,\n  '^=': (attr: string, value = '') => attr.startsWith(value),\n  '$=': (attr: string, value = '') => attr.endsWith(value),\n  '~=': (attr: string, value = '') =>\n    new Set<string>(attr.match(/\\w+/g)).has(value),\n  '*=': (attr: string, value = '') => attr.includes(value),\n  '|=': (attr: string, value = '') =>\n    attr === value || attr.startsWith(`${value}-`),\n  undefined: (attr: string) => !!attr,\n}\nexport const attributeSelectorsMap = new Map<string, ComparatorFn>(\n  Object.entries(attributeSelectors),\n)\n\n/**\n * Parse attributes selectors, e.g: `[name]`, `[name=value]`, etc\n */\nexport const attribute = async (\n  state: ParserState,\n): Promise<ParserState> => {\n  await state.cancellable()\n\n  const curr = asAttributeNode(state.current)\n  const operatorFn = attributeSelectorsMap.get(String(curr.operator))\n  if (!operatorFn) {\n    if (state.loose) {\n      return state\n    }\n\n    throw error(`Unsupported attribute operator: ${curr.operator}`, {\n      found: state.current,\n    })\n  }\n\n  const value = curr.value || ''\n  const propertyName = curr.attribute\n  const insensitive = !!curr.insensitive\n\n  // Increment the commonCounter for specificity\n  state.specificity.commonCounter += 1\n\n  return filterAttributes(\n    state,\n    operatorFn,\n    value,\n    propertyName,\n    insensitive,\n  )\n}\n"]}

package/dist/esm/id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/id.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;GAEG;AACH,eAAO,MAAM,EAAE,UACN,WAAW,KACjB,OAAO,CAAC,WAAW,CAiCrB,CAAA"}
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/id.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;GAEG;AACH,eAAO,MAAM,EAAE,UACN,WAAW,KACjB,OAAO,CAAC,WAAW,CAoCrB,CAAA"}

package/dist/esm/id.js

@@ -29,6 +29,8 @@ export const id = async (state) => {
             state.partial.nodes.delete(node);
         }
     }
+    // Increment the idCounter for specificity
+    state.specificity.idCounter += 1;
     return state;
 };
 //# sourceMappingURL=id.js.map

package/dist/esm/id.js.map

@@ -1 +1 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAG7C;;GAEG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,KAAK,EACrB,KAAkB,EACI,EAAE;IACxB,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAEjD,8CAA8C;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,KAAK,CAAC,yBAAyB,CAAC,CAAA;IACxC,CAAC;IACD,oBAAoB;IAEpB,wCAAwC;IACxC,yCAAyC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YACxB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAChC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;gBACZ,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,yDAAyD;IACzD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvC,IACE,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YACvB,IAAI,CAAC,IAAI,KAAK,KAAK;YACnB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAC7B,CAAC;YACD,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA","sourcesContent":["import { error } from '@vltpkg/error-cause'\nimport { asIdentifierNode } from './types.ts'\nimport type { ParserState } from './types.ts'\n\n/**\n * Parse ids, e.g: `#foo`\n */\nexport const id = async (\n  state: ParserState,\n): Promise<ParserState> => {\n  const { value } = asIdentifierNode(state.current)\n\n  /* c8 ignore start - should not be possible */\n  if (!value) {\n    throw error('Missing identifier name')\n  }\n  /* c8 ignore stop */\n\n  // Filter out any edges and their linked\n  // nodes if they don't match the id value\n  for (const edge of state.partial.edges) {\n    if (edge.name !== value) {\n      state.partial.edges.delete(edge)\n      if (edge.to) {\n        state.partial.nodes.delete(edge.to)\n      }\n    }\n  }\n\n  // Filter out importer nodes, this extra step is needed\n  // to filter out nodes that have no edges linking to them\n  for (const node of state.partial.nodes) {\n    if (\n      node.edgesIn.size === 0 &&\n      node.name !== value &&\n      state.partial.nodes.has(node)\n    ) {\n      state.partial.nodes.delete(node)\n    }\n  }\n\n  return state\n}\n"]}
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAG7C;;GAEG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,KAAK,EACrB,KAAkB,EACI,EAAE;IACxB,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAEjD,8CAA8C;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,KAAK,CAAC,yBAAyB,CAAC,CAAA;IACxC,CAAC;IACD,oBAAoB;IAEpB,wCAAwC;IACxC,yCAAyC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YACxB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAChC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;gBACZ,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,yDAAyD;IACzD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvC,IACE,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YACvB,IAAI,CAAC,IAAI,KAAK,KAAK;YACnB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAC7B,CAAC;YACD,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,WAAW,CAAC,SAAS,IAAI,CAAC,CAAA;IAEhC,OAAO,KAAK,CAAA;AACd,CAAC,CAAA","sourcesContent":["import { error } from '@vltpkg/error-cause'\nimport { asIdentifierNode } from './types.ts'\nimport type { ParserState } from './types.ts'\n\n/**\n * Parse ids, e.g: `#foo`\n */\nexport const id = async (\n  state: ParserState,\n): Promise<ParserState> => {\n  const { value } = asIdentifierNode(state.current)\n\n  /* c8 ignore start - should not be possible */\n  if (!value) {\n    throw error('Missing identifier name')\n  }\n  /* c8 ignore stop */\n\n  // Filter out any edges and their linked\n  // nodes if they don't match the id value\n  for (const edge of state.partial.edges) {\n    if (edge.name !== value) {\n      state.partial.edges.delete(edge)\n      if (edge.to) {\n        state.partial.nodes.delete(edge.to)\n      }\n    }\n  }\n\n  // Filter out importer nodes, this extra step is needed\n  // to filter out nodes that have no edges linking to them\n  for (const node of state.partial.nodes) {\n    if (\n      node.edgesIn.size === 0 &&\n      node.name !== value &&\n      state.partial.nodes.has(node)\n    ) {\n      state.partial.nodes.delete(node)\n    }\n  }\n\n  // Increment the idCounter for specificity\n  state.specificity.idCounter += 1\n\n  return state\n}\n"]}

package/dist/esm/index.d.ts

@@ -2,7 +2,12 @@ import type { GraphLike } from '@vltpkg/graph';
 import type { SpecOptions } from '@vltpkg/spec/browser';
 import type { SecurityArchiveLike } from '@vltpkg/security-archive';
 import type { ParsedSelectorToken, ParserState, QueryResponse } from './types.ts';
+import type { DepID } from '@vltpkg/dep-id';
 export * from './types.ts';
+export type SearchOptions = {
+    signal: AbortSignal;
+    scopeIDs?: DepID[];
+};
 export declare const walk: (state: ParserState) => Promise<ParserState>;
 export type QueryOptions = {
     graph: GraphLike;
@@ -10,6 +15,57 @@ export type QueryOptions = {
     specOptions: SpecOptions;
     securityArchive: SecurityArchiveLike | undefined;
 };
+/**
+ * A valid item of a given breadcrumb.
+ */
+export type InteractiveBreadcrumbItem = {
+    value: string;
+    type: string;
+    prev: InteractiveBreadcrumbItem | undefined;
+    next: InteractiveBreadcrumbItem | undefined;
+    importer: boolean;
+};
+/**
+ * The InteractiveBreadcrumb class is used to represent a valid breadcrumb.
+ *
+ * "Breadcrumb" is a term used to describe the subset of the query language
+ * that uses only root/workspace selectors, id selectors & combinators.
+ *
+ * It implements an iterable, doubly-linked list of items that can be used
+ * to navigate through the breadcrumb.
+ *
+ * It also validates that each element of the provided query string is
+ * valid according to the previous definition of a "breadcrumb".
+ */
+export declare class InteractiveBreadcrumb implements Iterable<InteractiveBreadcrumbItem> {
+    #private;
+    comment: string | undefined;
+    /**
+     * Initializes the interactive breadcrumb with a query string.
+     */
+    constructor(query: string);
+    /**
+     * The current breadcrumb item.
+     */
+    get current(): InteractiveBreadcrumbItem;
+    /**
+     * The next breadcrumb item.
+     */
+    next(): InteractiveBreadcrumbItem | undefined;
+    /**
+     * The previous breadcrumb item.
+     */
+    prev(): InteractiveBreadcrumbItem | undefined;
+    [Symbol.iterator](): ArrayIterator<InteractiveBreadcrumbItem>;
+    /**
+     * Empties the current breadcrumb list.
+     */
+    clear(): void;
+}
+/**
+ * The Query class is used to search the graph for nodes and edges
+ * using the Dependency Selector Syntax (DSS).
+ */
 export declare class Query {
     #private;
     /**
@@ -18,14 +74,26 @@ export declare class Query {
      * skip hydrating the security archive if it's not needed.
      */
     static hasSecuritySelectors(query: string): boolean;
+    /**
+     * Sorts an array of QueryResponse objects by specificity. Objects with
+     * higher idCounter values come first, if idCounter values are equal,
+     * then objects with higher commonCounter values come first. Otherwise,
+     * the original order is preserved.
+     */
+    static specificitySort(responses: QueryResponse[]): QueryResponse[];
     constructor({ graph, retries, specOptions, securityArchive, }: QueryOptions);
     /**
      * Search the graph for nodes and edges that match the given query.
      */
-    search(query: string, signal?: AbortSignal): Promise<QueryResponse>;
+    search(query: string, { signal, scopeIDs, }: SearchOptions): Promise<QueryResponse>;
     /**
      * Parses a query string in order to retrieve an array of tokens.
      */
     static getQueryTokens(query: string): ParsedSelectorToken[];
+    /**
+     * Returns an {@link InteractiveBreadcrumb} list of items
+     * for a given query string.
+     */
+    static getBreadcrumbItems(query: string): InteractiveBreadcrumb;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAY,SAAS,EAAY,MAAM,eAAe,CAAA;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAcnE,OAAO,KAAK,EAEV,mBAAmB,EAEnB,WAAW,EAEX,aAAa,EAGd,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAqC1B,eAAO,MAAM,IAAI,UACR,WAAW,KACjB,OAAO,CAAC,WAAW,CAsDrB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,SAAS,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,WAAW,CAAA;IACxB,eAAe,EAAE,mBAAmB,GAAG,SAAS,CAAA;CACjD,CAAA;AAiDD,qBAAa,KAAK;;IAOhB;;;;OAIG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;gBASvC,EACV,KAAK,EACL,OAAO,EACP,WAAW,EACX,eAAe,GAChB,EAAE,YAAY;IAyLf;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC;IAwDzB;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE;CAmE5D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAY,SAAS,EAAY,MAAM,eAAe,CAAA;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAgBnE,OAAO,KAAK,EAEV,mBAAmB,EAEnB,WAAW,EAEX,aAAa,EAGd,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C,cAAc,YAAY,CAAA;AAE1B,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAA;CACnB,CAAA;AA+CD,eAAO,MAAM,IAAI,UACR,WAAW,KACjB,OAAO,CAAC,WAAW,CAsDrB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,SAAS,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,WAAW,CAAA;IACxB,eAAe,EAAE,mBAAmB,GAAG,SAAS,CAAA;CACjD,CAAA;AAiDD;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,yBAAyB,GAAG,SAAS,CAAA;IAC3C,IAAI,EAAE,yBAAyB,GAAG,SAAS,CAAA;IAC3C,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,qBACX,YAAW,QAAQ,CAAC,yBAAyB,CAAC;;IAI9C,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAE3B;;OAEG;gBACS,KAAK,EAAE,MAAM;IA0GzB;;OAEG;IACH,IAAI,OAAO,IAAI,yBAAyB,CAEvC;IAED;;OAEG;IACH,IAAI,IAAI,yBAAyB,GAAG,SAAS;IAQ7C;;OAEG;IACH,IAAI,IAAI,yBAAyB,GAAG,SAAS;IAQ7C,CAAC,MAAM,CAAC,QAAQ,CAAC;IAIjB;;OAEG;IACH,KAAK;CAON;AAED;;;GAGG;AACH,qBAAa,KAAK;;IAOhB;;;;OAIG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IASnD;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CACpB,SAAS,EAAE,aAAa,EAAE,GACzB,aAAa,EAAE;gBAqBN,EACV,KAAK,EACL,OAAO,EACP,WAAW,EACX,eAAe,GAChB,EAAE,YAAY;IAuLf;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,EACE,MAAM,EACN,QAA0C,GAC3C,EAAE,aAAa,GACf,OAAO,CAAC,aAAa,CAAC;IAmEzB;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAoE3D;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB;CAGhE"}

package/dist/esm/index.js

@@ -4,7 +4,8 @@ import { attribute } from "./attribute.js";
 import { combinator } from "./combinator.js";
 import { id } from "./id.js";
 import { pseudo } from "./pseudo.js";
-import { isPostcssNodeWithChildren, asPostcssNodeWithChildren, isSelectorNode, isPseudoNode, isIdentifierNode, isAttributeNode, } from "./types.js";
+import { isPostcssNodeWithChildren, asPostcssNodeWithChildren, isSelectorNode, isPseudoNode, isIdentifierNode, isAttributeNode, isCombinatorNode, isCommentNode, } from "./types.js";
+import { joinDepIDTuple } from '@vltpkg/dep-id/browser';
 export * from "./types.js";
 const noopFn = async (state) => state;
 const selectors = {
@@ -15,7 +16,17 @@ const selectors = {
     },
     /* c8 ignore end */
     combinator,
-    comment: noopFn,
+    comment: async (state) => {
+        if (state.current.value && !state.comment) {
+            const commentValue = state.current.value;
+            const cleanComment = commentValue
+                .replace(/^\/\*/, '')
+                .replace(/\*\/$/, '')
+                .trim();
+            state.comment = cleanComment;
+        }
+        return state;
+    },
     id,
     nesting: noopFn,
     pseudo,
@@ -124,6 +135,159 @@ const setMethodToJSON = (node) => {
         insights,
     });
 };
+/**
+ * The InteractiveBreadcrumb class is used to represent a valid breadcrumb.
+ *
+ * "Breadcrumb" is a term used to describe the subset of the query language
+ * that uses only root/workspace selectors, id selectors & combinators.
+ *
+ * It implements an iterable, doubly-linked list of items that can be used
+ * to navigate through the breadcrumb.
+ *
+ * It also validates that each element of the provided query string is
+ * valid according to the previous definition of a "breadcrumb".
+ */
+export class InteractiveBreadcrumb {
+    #current;
+    #items;
+    comment;
+    /**
+     * Initializes the interactive breadcrumb with a query string.
+     */
+    constructor(query) {
+        this.#items = [];
+        const ast = parse(query);
+        // Keep track of the previous AST node for consolidation
+        let prevNode;
+        // iterates only at the first level of the AST since
+        // any nested nodes are invalid syntax
+        for (const item of ast.first.nodes) {
+            const isWorkspaceOrProject = isPseudoNode(item) &&
+                (item.value === ':workspace' || item.value === ':project');
+            const allowedPseudoNodes = isPseudoNode(item) &&
+                (item.value === ':root' ||
+                    item.value === ':workspace' ||
+                    item.value === ':project');
+            const allowedTypes = isIdentifierNode(item) ||
+                allowedPseudoNodes ||
+                (isCombinatorNode(item) && item.value === '>') ||
+                isCommentNode(item);
+            // Check if this is a nested selector that's not an allowed pseudo
+            const isNestedSelector = isPostcssNodeWithChildren(item) &&
+                !(allowedPseudoNodes && item.nodes.length === 0);
+            // validation, only the root/workspace selectors, id selectors
+            // and combinators are valid ast node items
+            if (isNestedSelector || !allowedTypes) {
+                throw error('Invalid query', { found: item });
+            }
+            // combinators and comments are skipped
+            if (isCombinatorNode(item)) {
+                prevNode = undefined;
+                continue;
+            }
+            else if (isCommentNode(item)) {
+                const cleanComment = item.value
+                    .replace(/^\/\*/, '')
+                    .replace(/\*\/$/, '')
+                    .trim();
+                this.comment = cleanComment;
+                prevNode = undefined;
+            }
+            else {
+                // check if we need to consolidate with previous item
+                const isPrevWorkspaceOrProject = prevNode &&
+                    isPseudoNode(prevNode) &&
+                    (prevNode.value === ':workspace' ||
+                        prevNode.value === ':project');
+                const isPrevId = prevNode && isIdentifierNode(prevNode);
+                const isCurrentId = isIdentifierNode(item);
+                const lastItem = this.#items.length > 0 ?
+                    this.#items[this.#items.length - 1]
+                    : null;
+                // current node is ID, previous was workspace/project
+                if (isCurrentId && isPrevWorkspaceOrProject && lastItem) {
+                    // Modify the last item to include the ID
+                    lastItem.value = `${lastItem.value}#${item.value}`;
+                    prevNode = undefined;
+                    continue;
+                }
+                // current node is workspace/project, previous was ID
+                if (isWorkspaceOrProject && isPrevId && lastItem) {
+                    // Modify the last item to include the pseudo
+                    lastItem.value = `${lastItem.value}${item.value}`;
+                    lastItem.importer = true;
+                    prevNode = undefined;
+                    continue;
+                }
+                // Default case: create a new item normally
+                const prev = this.#items[this.#items.length - 1];
+                const newItem = {
+                    value: item.value,
+                    type: item.type,
+                    prev,
+                    next: undefined,
+                    importer: allowedPseudoNodes,
+                };
+                if (prev) {
+                    prev.next = newItem;
+                }
+                this.#items.push(newItem);
+                prevNode = item;
+            }
+        }
+        // the parsed query should have at least one item
+        // that is then going to be set as the current item
+        if (!this.#items[0]) {
+            throw error('Failed to parse query', {
+                found: query,
+            });
+        }
+        this.#current = this.#items[0];
+    }
+    /**
+     * The current breadcrumb item.
+     */
+    get current() {
+        return this.#current;
+    }
+    /**
+     * The next breadcrumb item.
+     */
+    next() {
+        if (!this.#current.next) {
+            return;
+        }
+        this.#current = this.#current.next;
+        return this.#current;
+    }
+    /**
+     * The previous breadcrumb item.
+     */
+    prev() {
+        if (!this.#current.prev) {
+            return;
+        }
+        this.#current = this.#current.prev;
+        return this.#current;
+    }
+    [Symbol.iterator]() {
+        return this.#items.values();
+    }
+    /**
+     * Empties the current breadcrumb list.
+     */
+    clear() {
+        for (const item of this.#items) {
+            item.prev = undefined;
+            item.next = undefined;
+        }
+        this.#items.length = 0;
+    }
+}
+/**
+ * The Query class is used to search the graph for nodes and edges
+ * using the Dependency Selector Syntax (DSS).
+ */
 export class Query {
     #cache;
     #graph;
@@ -143,6 +307,26 @@ export class Query {
         }
         return false;
     }
+    /**
+     * Sorts an array of QueryResponse objects by specificity. Objects with
+     * higher idCounter values come first, if idCounter values are equal,
+     * then objects with higher commonCounter values come first. Otherwise,
+     * the original order is preserved.
+     */
+    static specificitySort(responses) {
+        return [...responses].sort((a, b) => {
+            // First compare by idCounter (higher comes first)
+            if (a.specificity.idCounter !== b.specificity.idCounter) {
+                return b.specificity.idCounter - a.specificity.idCounter;
+            }
+            // If idCounter values are equal, compare by commonCounter
+            if (a.specificity.commonCounter !== b.specificity.commonCounter) {
+                return (b.specificity.commonCounter - a.specificity.commonCounter);
+            }
+            // If both counters are equal, preserve original order
+            return 0;
+        });
+    }
     constructor({ graph, retries, specOptions, securityArchive, }) {
         this.#cache = new Map();
         this.#graph = graph;
@@ -173,10 +357,8 @@ export class Query {
                 abandoned: securityArchiveEntry.alerts.some(i => i.type === 'missingAuthor'),
                 confused: securityArchiveEntry.alerts.some(i => i.type === 'manifestConfusion'),
                 cve: securityArchiveEntry.alerts
-                    .filter(i => i.props?.cveId)
-                    // can not be undefined because of the filter above but TS doesn't know that
-                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion, @typescript-eslint/no-non-null-asserted-optional-chain
-                    .map(i => i.props?.cveId),
+                    .map(i => i.props?.cveId)
+                    .filter(i => i !== undefined),
                 cwe: Array.from(new Set(securityArchiveEntry.alerts
                     .filter(i => i.props?.cveId)
                     .flatMap(i => i.props?.cwes?.map(j => j.id)))),
@@ -236,9 +418,14 @@ export class Query {
     /**
      * Search the graph for nodes and edges that match the given query.
      */
-    async search(query, signal) {
+    async search(query, { signal, scopeIDs = [joinDepIDTuple(['file', '.'])], }) {
         if (!query)
-            return { edges: [], nodes: [] };
+            return {
+                edges: [],
+                nodes: [],
+                comment: '',
+                specificity: { idCounter: 0, commonCounter: 0 },
+            };
         const cachedResult = this.#cache.get(query);
         if (cachedResult) {
             return cachedResult;
@@ -255,12 +442,12 @@ export class Query {
         const loose = asPostcssNodeWithChildren(current).nodes.length > 1;
         // builds initial state and walks over it,
         // retrieving the collected result
-        const { collect } = await walk({
+        const { collect, comment, specificity } = await walk({
             cancellable: async () => {
                 await new Promise(resolve => {
                     setTimeout(resolve, 0);
                 });
-                signal?.throwIfAborted();
+                signal.throwIfAborted();
             },
             current,
             initial: {
@@ -271,17 +458,22 @@ export class Query {
                 nodes: new Set(),
                 edges: new Set(),
             },
+            comment: '',
             loose,
             partial: { nodes, edges },
             retries: this.#retries,
             signal,
             securityArchive: this.#securityArchive,
             specOptions: this.#specOptions,
+            scopeIDs,
             walk,
+            specificity: { idCounter: 0, commonCounter: 0 },
         });
         const res = {
             edges: this.#getQueryResponseEdges(collect.edges),
             nodes: this.#getQueryResponseNodes(collect.nodes),
+            comment,
+            specificity,
         };
         this.#cache.set(query, res);
         return res;
@@ -347,5 +539,12 @@ export class Query {
         processNode(ast(query));
         return tokens;
     }
+    /**
+     * Returns an {@link InteractiveBreadcrumb} list of items
+     * for a given query string.
+     */
+    static getBreadcrumbItems(query) {
+        return new InteractiveBreadcrumb(query);
+    }
 }
 //# sourceMappingURL=index.js.map