@vltpkg/dss-breadcrumb 0.0.0-14

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) vlt technology, Inc.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+   Subject to the terms and conditions of this license, each copyright holder and contributor hereby grants to those receiving rights under this license a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except for failure to satisfy the conditions of this license) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer this software, where such license applies only to those patent claims, already acquired or hereafter acquired, licensable by such copyright holder or contributor that are necessarily infringed by:
+
+(a) their Contribution(s) (the licensed copyrights of copyright holders and non-copyrightable additions of contributors, in source or binary form) alone; or
+(b) combination of their Contribution(s) with the work of authorship to which such Contribution(s) was added by such copyright holder or contributor, if, at the time the Contribution is added, such addition causes such combination to be necessarily infringed. The patent license shall not apply to any other combinations which include the Contribution.
+Except as expressly stated above, no rights or licenses from any copyright holder or contributor is granted under this license, whether expressly, by implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,23 @@
+# @vltpkg/dss-breadcrumb
+
+The Dependency Selector Syntax breadcrumb utilities used by the vlt
+client.
+
+A returned "Breadcrumb" object is a data structure that contains a
+linked list of items that where parsed from a given Dependency
+Selector Syntax query string that can be used to navigate through a
+given graph.
+
+## Usage
+
+```js
+import { parseBreadcrumb } from '@vltpkg/dss-breadcrumb'
+
+// Parse a selector string into a breadcrumb
+const breadcrumb = parseBreadcrumb(':root > #a')
+
+// Use the breadcrumb to navigate through the query
+console.log(breadcrumb.current.value) // :root
+breadcrumb.next()
+console.log(breadcrumb.current.value) // a
+```

package/dist/esm/index.d.ts

@@ -0,0 +1,75 @@
+import type { ModifierBreadcrumb, ModifierBreadcrumbItem, ModifierInteractiveBreadcrumb } from './types.ts';
+export * from './types.ts';
+/**
+ * The Breadcrumb class is used to represent a valid breadcrumb
+ * path that helps you traverse a graph and find a specific node or edge.
+ *
+ * Alongside the traditional analogy, "Breadcrumb" is also being used here
+ * as a term used to describe the subset of the query language that uses
+ * only root/workspace selectors, id selectors & combinators.
+ *
+ * The Breadcrumb implements a doubly-linked list of items
+ * that can be used to navigate through the breadcrumb.
+ * The InteractiveBreadcrumb can also be used to keep track of state
+ * of the current breadcrumb item that should be used for checks.
+ *
+ * It also validates that each element of the provided query string is
+ * valid according to the previous definition of a "Breadcrumb" query
+ * language subset.
+ */
+export declare class Breadcrumb implements ModifierBreadcrumb {
+    #private;
+    comment: string | undefined;
+    /**
+     * Initializes the interactive breadcrumb with a query string.
+     */
+    constructor(query: string);
+    /**
+     * Retrieves the first breadcrumb item.
+     */
+    get first(): ModifierBreadcrumbItem;
+    /**
+     * Retrieves the last breadcrumb item.
+     */
+    get last(): ModifierBreadcrumbItem;
+    /**
+     * Returns `true` if the breadcrumb is composed of a single item.
+     */
+    get single(): boolean;
+    [Symbol.iterator](): ArrayIterator<ModifierBreadcrumbItem>;
+    /**
+     * Empties the current breadcrumb list.
+     */
+    clear(): void;
+    /**
+     * Gets an {@link InteractiveBreadcrumb} instance that can be
+     * used to track state of the current breadcrumb item.
+     */
+    interactive(): InteractiveBreadcrumb;
+}
+/**
+ * The InteractiveBreadcrumb is used to keep track of state
+ * of the current breadcrumb item that should be used for checks.
+ */
+export declare class InteractiveBreadcrumb implements ModifierInteractiveBreadcrumb {
+    #private;
+    constructor(breadcrumb: Breadcrumb);
+    /**
+     * The current breadcrumb item.
+     */
+    get current(): ModifierBreadcrumbItem | undefined;
+    /**
+     * Returns `true` if the current breadcrumb has no more items left.
+     */
+    get done(): boolean;
+    /**
+     * The next breadcrumb item.
+     */
+    next(): this;
+}
+/**
+ * Returns an {@link Breadcrumb} list of items
+ * for a given query string.
+ */
+export declare const parseBreadcrumb: (query: string) => ModifierBreadcrumb;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,6BAA6B,EAC9B,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAE1B;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAW,YAAW,kBAAkB;;IAEnD,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAE3B;;OAEG;gBACS,KAAK,EAAE,MAAM;IAiHzB;;OAEG;IACH,IAAI,KAAK,IAAI,sBAAsB,CAKlC;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,sBAAsB,CAMjC;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC;IAIjB;;OAEG;IACH,KAAK;IAQL;;;OAGG;IACH,WAAW;CAGZ;AAED;;;GAGG;AACH,qBAAa,qBACX,YAAW,6BAA6B;;gBAG5B,UAAU,EAAE,UAAU;IAIlC;;OAEG;IACH,IAAI,OAAO,IAAI,sBAAsB,GAAG,SAAS,CAEhD;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI;CAIb;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,UAAW,MAAM,KAAG,kBACzB,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,203 @@
+import { isPostcssNodeWithChildren, isPseudoNode, isIdentifierNode, isCombinatorNode, isCommentNode, parse, } from '@vltpkg/dss-parser';
+import { error } from '@vltpkg/error-cause';
+export * from "./types.js";
+/**
+ * The Breadcrumb class is used to represent a valid breadcrumb
+ * path that helps you traverse a graph and find a specific node or edge.
+ *
+ * Alongside the traditional analogy, "Breadcrumb" is also being used here
+ * as a term used to describe the subset of the query language that uses
+ * only root/workspace selectors, id selectors & combinators.
+ *
+ * The Breadcrumb implements a doubly-linked list of items
+ * that can be used to navigate through the breadcrumb.
+ * The InteractiveBreadcrumb can also be used to keep track of state
+ * of the current breadcrumb item that should be used for checks.
+ *
+ * It also validates that each element of the provided query string is
+ * valid according to the previous definition of a "Breadcrumb" query
+ * language subset.
+ */
+export class Breadcrumb {
+    #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: query });
+            }
+            // 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);
+                // we define the last item as we iterate through the list of
+                // breadcrumb items so that this value can also be used to
+                // update previous items when needed
+                const lastItem = this.#items.length > 0 ?
+                    this.#items[this.#items.length - 1]
+                    : undefined;
+                // current node is ID, previous was workspace/project
+                // we fold the current node value into the same object
+                // and move on to the next ast item
+                if (isCurrentId && isPrevWorkspaceOrProject && lastItem) {
+                    // Modify the last item to include the ID
+                    lastItem.name = item.value;
+                    lastItem.value = `${lastItem.value}#${item.value}`;
+                    prevNode = undefined;
+                    continue;
+                }
+                // current node is workspace/project, previous was ID
+                // we fold the current node value into the same object
+                // and move on to the next ast item
+                if (isWorkspaceOrProject && isPrevId && lastItem) {
+                    // Modify the last item to include the pseudo
+                    lastItem.value = `${lastItem.value}${item.value}`;
+                    lastItem.importer = true;
+                    prevNode = undefined;
+                    continue;
+                }
+                const newItem = {
+                    value: item.type === 'id' ? `#${item.value}` : item.value,
+                    name: item.type === 'id' ? item.value : undefined,
+                    type: item.type,
+                    prev: lastItem,
+                    next: undefined,
+                    importer: allowedPseudoNodes,
+                };
+                if (lastItem) {
+                    lastItem.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,
+            });
+        }
+    }
+    /**
+     * Retrieves the first breadcrumb item.
+     */
+    get first() {
+        if (!this.#items[0]) {
+            throw error('Failed to find first breadcrumb item');
+        }
+        return this.#items[0];
+    }
+    /**
+     * Retrieves the last breadcrumb item.
+     */
+    get last() {
+        const lastItem = this.#items[this.#items.length - 1];
+        if (!lastItem) {
+            throw error('Failed to find first breadcrumb item');
+        }
+        return lastItem;
+    }
+    /**
+     * Returns `true` if the breadcrumb is composed of a single item.
+     */
+    get single() {
+        return this.#items.length === 1;
+    }
+    [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;
+    }
+    /**
+     * Gets an {@link InteractiveBreadcrumb} instance that can be
+     * used to track state of the current breadcrumb item.
+     */
+    interactive() {
+        return new InteractiveBreadcrumb(this);
+    }
+}
+/**
+ * The InteractiveBreadcrumb is used to keep track of state
+ * of the current breadcrumb item that should be used for checks.
+ */
+export class InteractiveBreadcrumb {
+    #current;
+    constructor(breadcrumb) {
+        this.#current = breadcrumb.first;
+    }
+    /**
+     * The current breadcrumb item.
+     */
+    get current() {
+        return this.#current;
+    }
+    /**
+     * Returns `true` if the current breadcrumb has no more items left.
+     */
+    get done() {
+        return !this.#current;
+    }
+    /**
+     * The next breadcrumb item.
+     */
+    next() {
+        this.#current = this.#current?.next;
+        return this;
+    }
+}
+/**
+ * Returns an {@link Breadcrumb} list of items
+ * for a given query string.
+ */
+export const parseBreadcrumb = (query) => new Breadcrumb(query);
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  isPostcssNodeWithChildren,\n  isPseudoNode,\n  isIdentifierNode,\n  isCombinatorNode,\n  isCommentNode,\n  parse,\n} from '@vltpkg/dss-parser'\nimport { error } from '@vltpkg/error-cause'\nimport type { PostcssNode } from '@vltpkg/dss-parser'\nimport type {\n  ModifierBreadcrumb,\n  ModifierBreadcrumbItem,\n  ModifierInteractiveBreadcrumb,\n} from './types.ts'\n\nexport * from './types.ts'\n\n/**\n * The Breadcrumb class is used to represent a valid breadcrumb\n * path that helps you traverse a graph and find a specific node or edge.\n *\n * Alongside the traditional analogy, \"Breadcrumb\" is also being used here\n * as a term used to describe the subset of the query language that uses\n * only root/workspace selectors, id selectors & combinators.\n *\n * The Breadcrumb implements a doubly-linked list of items\n * that can be used to navigate through the breadcrumb.\n * The InteractiveBreadcrumb can also be used to keep track of state\n * of the current breadcrumb item that should be used for checks.\n *\n * It also validates that each element of the provided query string is\n * valid according to the previous definition of a \"Breadcrumb\" query\n * language subset.\n */\nexport class Breadcrumb implements ModifierBreadcrumb {\n  #items: ModifierBreadcrumbItem[]\n  comment: string | undefined\n\n  /**\n   * Initializes the interactive breadcrumb with a query string.\n   */\n  constructor(query: string) {\n    this.#items = []\n    const ast = parse(query)\n\n    // Keep track of the previous AST node for consolidation\n    let prevNode: PostcssNode | undefined\n\n    // iterates only at the first level of the AST since\n    // any nested nodes are invalid syntax\n    for (const item of ast.first.nodes) {\n      const isWorkspaceOrProject =\n        isPseudoNode(item) &&\n        (item.value === ':workspace' || item.value === ':project')\n\n      const allowedPseudoNodes =\n        isPseudoNode(item) &&\n        (item.value === ':root' ||\n          item.value === ':workspace' ||\n          item.value === ':project')\n\n      const allowedTypes =\n        isIdentifierNode(item) ||\n        allowedPseudoNodes ||\n        (isCombinatorNode(item) && item.value === '>') ||\n        isCommentNode(item)\n\n      // Check if this is a nested selector that's not an allowed pseudo\n      const isNestedSelector =\n        isPostcssNodeWithChildren(item) &&\n        !(allowedPseudoNodes && item.nodes.length === 0)\n\n      // validation, only the root/workspace selectors, id selectors\n      // and combinators are valid ast node items\n      if (isNestedSelector || !allowedTypes) {\n        throw error('Invalid query', { found: query })\n      }\n\n      // combinators and comments are skipped\n      if (isCombinatorNode(item)) {\n        prevNode = undefined\n        continue\n      } else if (isCommentNode(item)) {\n        const cleanComment = item.value\n          .replace(/^\\/\\*/, '')\n          .replace(/\\*\\/$/, '')\n          .trim()\n        this.comment = cleanComment\n        prevNode = undefined\n      } else {\n        // check if we need to consolidate with previous item\n        const isPrevWorkspaceOrProject =\n          prevNode &&\n          isPseudoNode(prevNode) &&\n          (prevNode.value === ':workspace' ||\n            prevNode.value === ':project')\n\n        const isPrevId = prevNode && isIdentifierNode(prevNode)\n        const isCurrentId = isIdentifierNode(item)\n\n        // we define the last item as we iterate through the list of\n        // breadcrumb items so that this value can also be used to\n        // update previous items when needed\n        const lastItem =\n          this.#items.length > 0 ?\n            this.#items[this.#items.length - 1]\n          : undefined\n\n        // current node is ID, previous was workspace/project\n        // we fold the current node value into the same object\n        // and move on to the next ast item\n        if (isCurrentId && isPrevWorkspaceOrProject && lastItem) {\n          // Modify the last item to include the ID\n          lastItem.name = item.value\n          lastItem.value = `${lastItem.value}#${item.value}`\n          prevNode = undefined\n          continue\n        }\n\n        // current node is workspace/project, previous was ID\n        // we fold the current node value into the same object\n        // and move on to the next ast item\n        if (isWorkspaceOrProject && isPrevId && lastItem) {\n          // Modify the last item to include the pseudo\n          lastItem.value = `${lastItem.value}${item.value}`\n          lastItem.importer = true\n          prevNode = undefined\n          continue\n        }\n\n        const newItem = {\n          value: item.type === 'id' ? `#${item.value}` : item.value,\n          name: item.type === 'id' ? item.value : undefined,\n          type: item.type,\n          prev: lastItem,\n          next: undefined,\n          importer: allowedPseudoNodes,\n        }\n        if (lastItem) {\n          lastItem.next = newItem\n        }\n        this.#items.push(newItem)\n        prevNode = item\n      }\n    }\n    // the parsed query should have at least one item\n    // that is then going to be set as the current item\n    if (!this.#items[0]) {\n      throw error('Failed to parse query', {\n        found: query,\n      })\n    }\n  }\n\n  /**\n   * Retrieves the first breadcrumb item.\n   */\n  get first(): ModifierBreadcrumbItem {\n    if (!this.#items[0]) {\n      throw error('Failed to find first breadcrumb item')\n    }\n    return this.#items[0]\n  }\n\n  /**\n   * Retrieves the last breadcrumb item.\n   */\n  get last(): ModifierBreadcrumbItem {\n    const lastItem = this.#items[this.#items.length - 1]\n    if (!lastItem) {\n      throw error('Failed to find first breadcrumb item')\n    }\n    return lastItem\n  }\n\n  /**\n   * Returns `true` if the breadcrumb is composed of a single item.\n   */\n  get single(): boolean {\n    return this.#items.length === 1\n  }\n\n  [Symbol.iterator]() {\n    return this.#items.values()\n  }\n\n  /**\n   * Empties the current breadcrumb list.\n   */\n  clear() {\n    for (const item of this.#items) {\n      item.prev = undefined\n      item.next = undefined\n    }\n    this.#items.length = 0\n  }\n\n  /**\n   * Gets an {@link InteractiveBreadcrumb} instance that can be\n   * used to track state of the current breadcrumb item.\n   */\n  interactive() {\n    return new InteractiveBreadcrumb(this)\n  }\n}\n\n/**\n * The InteractiveBreadcrumb is used to keep track of state\n * of the current breadcrumb item that should be used for checks.\n */\nexport class InteractiveBreadcrumb\n  implements ModifierInteractiveBreadcrumb\n{\n  #current: ModifierBreadcrumbItem | undefined\n  constructor(breadcrumb: Breadcrumb) {\n    this.#current = breadcrumb.first\n  }\n\n  /**\n   * The current breadcrumb item.\n   */\n  get current(): ModifierBreadcrumbItem | undefined {\n    return this.#current\n  }\n\n  /**\n   * Returns `true` if the current breadcrumb has no more items left.\n   */\n  get done(): boolean {\n    return !this.#current\n  }\n\n  /**\n   * The next breadcrumb item.\n   */\n  next(): this {\n    this.#current = this.#current?.next\n    return this\n  }\n}\n\n/**\n * Returns an {@link Breadcrumb} list of items\n * for a given query string.\n */\nexport const parseBreadcrumb = (query: string): ModifierBreadcrumb =>\n  new Breadcrumb(query)\n"]}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A valid item of a given breadcrumb.
+ */
+export type ModifierBreadcrumbItem = {
+    name?: string;
+    value: string;
+    type: string;
+    importer: boolean;
+    prev: ModifierBreadcrumbItem | undefined;
+    next: ModifierBreadcrumbItem | undefined;
+};
+/**
+ * A breadcrumb is a linked list of items, where
+ * each item has a value and a type.
+ */
+export interface ModifierBreadcrumb extends Iterable<ModifierBreadcrumbItem> {
+    clear(): void;
+    comment: string | undefined;
+    first: ModifierBreadcrumbItem;
+    last: ModifierBreadcrumbItem;
+    single: boolean;
+    interactive: () => ModifierInteractiveBreadcrumb;
+}
+/**
+ * An interactive breadcrumb that holds state on what is the current item.
+ */
+export type ModifierInteractiveBreadcrumb = {
+    current: ModifierBreadcrumbItem | undefined;
+    done: boolean;
+    next: () => ModifierInteractiveBreadcrumb;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,sBAAsB,GAAG,SAAS,CAAA;IACxC,IAAI,EAAE,sBAAsB,GAAG,SAAS,CAAA;CACzC,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,kBACf,SAAQ,QAAQ,CAAC,sBAAsB,CAAC;IACxC,KAAK,IAAI,IAAI,CAAA;IACb,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,KAAK,EAAE,sBAAsB,CAAA;IAC7B,IAAI,EAAE,sBAAsB,CAAA;IAC5B,MAAM,EAAE,OAAO,CAAA;IACf,WAAW,EAAE,MAAM,6BAA6B,CAAA;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,sBAAsB,GAAG,SAAS,CAAA;IAC3C,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,6BAA6B,CAAA;CAC1C,CAAA"}

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * A valid item of a given breadcrumb.\n */\nexport type ModifierBreadcrumbItem = {\n  name?: string\n  value: string\n  type: string\n  importer: boolean\n  prev: ModifierBreadcrumbItem | undefined\n  next: ModifierBreadcrumbItem | undefined\n}\n\n/**\n * A breadcrumb is a linked list of items, where\n * each item has a value and a type.\n */\nexport interface ModifierBreadcrumb\n  extends Iterable<ModifierBreadcrumbItem> {\n  clear(): void\n  comment: string | undefined\n  first: ModifierBreadcrumbItem\n  last: ModifierBreadcrumbItem\n  single: boolean\n  interactive: () => ModifierInteractiveBreadcrumb\n}\n\n/**\n * An interactive breadcrumb that holds state on what is the current item.\n */\nexport type ModifierInteractiveBreadcrumb = {\n  current: ModifierBreadcrumbItem | undefined\n  done: boolean\n  next: () => ModifierInteractiveBreadcrumb\n}\n"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@vltpkg/dss-breadcrumb",
+  "description": "The Dependency Selector Syntax (DSS) breadcrumb utilities",
+  "version": "0.0.0-14",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vltpkg/vltpkg.git",
+    "directory": "src/dss-breadcrumb"
+  },
+  "tshy": {
+    "selfLink": false,
+    "liveDev": true,
+    "dialects": [
+      "esm"
+    ],
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@vltpkg/dss-parser": "0.0.0-14",
+    "@vltpkg/error-cause": "0.0.0-14"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@types/node": "^22.15.29",
+    "eslint": "^9.28.0",
+    "prettier": "^3.5.3",
+    "tap": "^21.1.0",
+    "tshy": "^3.0.2",
+    "typedoc": "~0.27.9",
+    "typescript": "5.7.3",
+    "typescript-eslint": "^8.33.1"
+  },
+  "license": "BSD-2-Clause-Patent",
+  "engines": {
+    "node": ">=22"
+  },
+  "tap": {
+    "extends": "../../tap-config.yaml"
+  },
+  "prettier": "../../.prettierrc.js",
+  "module": "./dist/esm/index.js",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "format": "prettier --write . --log-level warn --ignore-path ../../.prettierignore --cache",
+    "format:check": "prettier --check . --ignore-path ../../.prettierignore --cache",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "snap": "tap",
+    "test": "tap",
+    "posttest": "tsc --noEmit",
+    "tshy": "tshy",
+    "typecheck": "tsc --noEmit"
+  }
+}