@csaf-rs/vers-like-specifier 0.1.2 → 0.1.3

package/README.md

@@ -3,13 +3,13 @@
 [![crates.io](https://img.shields.io/crates/v/vers-like-specifier.svg)](https://crates.io/crates/vers-like-specifier)
 [![npm](https://img.shields.io/npm/v/%40csaf-rs%2Fvers-like-specifier.svg)](https://www.npmjs.com/package/@csaf-rs/vers-like-specifier)
 
-A Rust library for parsing and validating **Vers-like Specifiers** (vls) as defined in [CSAF 2.0](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#31232-branches-type---name-under-product-version-range) and [CSAF 2.1](https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html#branches-type---name-under-product-version-range).
+A Rust library for parsing and validating **VERS-like Specifiers** (vls) as defined in [CSAF 2.0](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#31232-branches-type---name-under-product-version-range) and [CSAF 2.1](https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html#branches-type---name-under-product-version-range).
 
-vers-like-specifier is the `<constraints>` portion of a [vers](https://github.com/package-url/vers-spec) URL **without** the `vers:<type>/` prefix.
+VERS-like specifier is the `<constraints>` portion of a [VERS](https://github.com/package-url/vers-spec) URL **without** the `vers:<type>/` prefix.
 
 It represents a `|`-separated list of constraints each consisting of an implicit or explicit comparator and a version string.
 
-**Due to the undefined / unknown schema, it is nearly impossible for tools to reliably determine whether a given version is in the range or not. vls is a fallback option and SHOULD NOT be used unless really necessary.**
+**Due to the undefined / unknown VERS type, it is nearly impossible for tools to reliably determine whether a given version is in the range or not. vls is a fallback option and SHOULD NOT be used unless really necessary.**
 
 ## Minimum Supported Rust Version (MSRV)
 
@@ -27,7 +27,7 @@ vers-like-specifier = "0.1"
 ## Usage
 
 ```rust
-use vers_like_specifier::{Vls, Comparator};
+use vers_like_specifier::{Vls, Comparator, Containment};
 
 let vls: Vls = ">=1.0.0|<2.0.0".parse().unwrap();
 assert_eq!(vls.constraints().len(), 2);
@@ -39,28 +39,41 @@ assert_eq!(constraints[0].comparator(), &Comparator::GreaterThanOrEqual);
 assert_eq!(constraints[0].version().to_string(), "1.0.0");
 assert_eq!(constraints[1].comparator(), &Comparator::LessThan);
 assert_eq!(constraints[1].version().to_string(), "2.0.0");
+
+// Because the VERS type is unknown, `contains` can only resolve a definite
+// answer when a version exactly matches a constraint; otherwise it is `Undetermined`.
+assert_eq!(vls.contains("1.0.0"), Containment::Contained);
+assert_eq!(vls.contains("2.0.0"), Containment::NotContained);
+assert_eq!(vls.contains("1.5.0"), Containment::Undetermined);
+
+// The one exception: a vls pinning a single version is always decidable, since
+// containment then reduces to a plain string comparison.
+let pinned: Vls = "1.0.0".parse().unwrap();
+assert_eq!(pinned.contains("1.0.0"), Containment::Contained);
+assert_eq!(pinned.contains("2.0.0"), Containment::NotContained);
 ```
 
 ### JavaScript / WASM Usage
 
 ```js
-import init, { Vls, Constraint, Comparator } from "@csaf-rs/vers-like-specifier";
+import init, { Vls, Constraint, Comparator, Containment } from "@csaf-rs/vers-like-specifier";
 
 await init();
 
 const vls = Vls.parse(">=1.0.0|<2.0.0");
 console.log(vls.isSingleVersion()); // false
 
-const single = Vls.parse("=1.0.0");
-console.log(single.isSingleVersion()); // true
-
 const constraint = new Constraint(Comparator.GreaterThanOrEqual, "1.0.0");
 console.log(constraint.version); // "1.0.0"
 
+console.log(vls.contains("1.0.0") === Containment.Contained); // true (matches the >= constraint exactly)
+console.log(vls.contains("2.0.0") === Containment.NotContained); // true (2.0.0 < 2.0.0 is always false)
+console.log(vls.contains("1.5.0") === Containment.Undetermined); // true (can't be resolved; VERS type is unknown)
+
 try {
   Vls.parse("*");
 } catch (e) {
-  console.error(e); // Error: '*' (vers syntax for matching all versions) is not allowed as a vls string
+  console.error(e); // Error: '*' (VERS syntax for matching all versions) is not allowed as a vls string
 }
 ```
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@csaf-rs/vers-like-specifier",
   "type": "module",
   "description": "vls (vers-like specifier) parser",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/vers_like_specifier.d.ts

@@ -16,7 +16,7 @@ export type ConstraintError = "EmptyConstraint" | "EmptyConstraintVersion" | { I
 /**
  * Errors that can occur when parsing a vls string.
  */
-export type VlsError = "EmptyInput" | "ForbiddenAnyUsed" | { InvalidCharacters: string[] } | "ContainsVersPrefix" | "ContainsVersType" | { InvalidConstraints: ConstraintError[] } | { DuplicateConstraintVersions: string[] } | { Serialization: string };
+export type VlsError = "EmptyInput" | "ForbiddenAnyUsed" | { InvalidCharacters: string[] } | { InvalidConstraints: ConstraintError[] } | { DuplicateConstraintVersions: string[] } | { Serialization: string };
 
 
 /**
@@ -79,9 +79,47 @@ export class Constraint {
 }
 
 /**
- * A **Vers-like Specifier** (VLS).
+ * The result of a containment check performed by [`Vls::contains`].
+ *
+ * Because the VERS type of a [`Vls`] is unspecified, containment can usually only be
+ * resolved when the queried version exactly matches a constraint's version:
+ *
+ * * [`Comparator::Equal`], [`Comparator::GreaterThanOrEqual`], [`Comparator::LessThanOrEqual`]:
+ *   an exact match means the version is contained (`x = x`, `x >= x`, `x <= x` all hold) →
+ *   [`Containment::Contained`].
+ * * [`Comparator::NotEqual`], [`Comparator::LessThan`], [`Comparator::GreaterThan`]:
+ *   an exact match means the version is explicitly not contained (`x != x`, `x < x`, `x > x`
+ *   are always false) → [`Containment::NotContained`].
+ * * No constraint's version matches exactly: containment cannot be resolved, as the VERS
+ *   type is unknown / unspecified → [`Containment::Undetermined`].
+ *
+ * The one exception is a [`Vls`] that pins a single version (see [`Vls::is_single_version`]):
+ * since it has exactly one [`Comparator::Equal`] constraint, containment reduces to a plain
+ * string comparison and is always decidable, regardless of VERS type. In that case,
+ * *any* queried version resolves to either [`Containment::Contained`] or
+ * [`Containment::NotContained`], never [`Containment::Undetermined`].
+ */
+export enum Containment {
+    /**
+     * The version is contained in the specifier.
+     */
+    Contained = 0,
+    /**
+     * The version is explicitly not contained in the specifier.
+     */
+    NotContained = 1,
+    /**
+     * Containment could not be determined: the version does not exactly match any
+     * constraint, and the (unspecified) VERS type does not allow any further
+     * comparison.
+     */
+    Undetermined = 2,
+}
+
+/**
+ * A **VERS-like specifier** (vls).
  *
- * VLS is the `<constraints>` part of a [vers](https://github.com/package-url/vers-spec)
+ * vls is the `<constraints>` part of a [VERS](https://github.com/package-url/vers-spec)
  * URL *without* the `vers:<type>/` prefix.
  *
  * It is an ordered, `|`-separated list of [`Constraint`] values.
@@ -93,30 +131,14 @@ export class Constraint {
  *
  * # Syntax
  *
- * Derived from the [vers specification](https://www.packageurl.org/docs/vers/how-to-parse) and
+ * Derived from the [VERS specification](https://www.packageurl.org/docs/vers/how-to-parse),
  * its comments in
  * [CSAF 2.0](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#31232-branches-type---name-under-product-version-range)
  * and
  * [CSAF 2.1](https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html#branches-type---name-under-product-version-range).
  *
- * There currently is no "official" grammar for vers-like specifier / the `<constraints>` part of
- * vers. This is a best-effort attempt used for this library.
- *
- * **Note:** This grammar may need to be updated once vers has been ratified through ECMA / following changes
- * to / clarifications of CSAF 2.0 or CSAF 2.1.
- *
- * ```text
- * vls            = constraint *( "|" constraint )
- * constraint     = comparator version-string / version-string
- * comparator     = "!=" / "<=" / ">=" / "<" / ">"
- * version-string = 1*( ALPHA / DIGIT / "-" / "." / "_" / "+" / "~" )
- * ```
- *
- * For validation, this leads to two sets of characters allowed in the context of the grammar.
- *
- * For `constraints`: `ALPHA / DIGIT / "-" / "." / "_" / "+" / "~" / "=" / "!" / "<" / ">" / "|"`
- *
- * For `version-string`: `ALPHA / DIGIT / "-" / "." / "_" / "+" / "~"`
+ * There currently is no "official" grammar for VERS-like specifier / the `<constraints>` part of
+ * VERS. This is a best-effort attempt used for this library.
  *
  * # Examples
  *
@@ -135,6 +157,11 @@ export class Vls {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Return the [`Containment`] of the given `version` in this specifier, exposed as the
+     * instance method `vls.contains(version)` in JS.
+     */
+    contains(version: string): Containment;
     /**
      * Return `true` if this specifier pins exactly one version, exposed as the
      * instance method `vls.isSingleVersion()` in JS.
@@ -144,7 +171,7 @@ export class Vls {
      * Parse a `vls` as a [`Vls`] string, exposed as the static `Vls.parse(vls)` in JS.
      *
      * # Errors
-     * Throws a JS `Error` if `vls` is not a valid vers-like specifier.
+     * Throws a JS `Error` if `vls` is not a valid VERS-like specifier.
      */
     static parse(vls: string): Vls;
 }
@@ -158,14 +185,15 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
-    readonly __wbg_constraint_free: (a: number, b: number) => void;
+    readonly init: () => void;
     readonly __wbg_vls_free: (a: number, b: number) => void;
+    readonly vls_contains: (a: number, b: number, c: number) => number;
+    readonly vls_isSingleVersion: (a: number) => number;
+    readonly vls_parse: (a: number, b: number) => [number, number, number];
+    readonly __wbg_constraint_free: (a: number, b: number) => void;
     readonly constraint_comparator: (a: number) => number;
     readonly constraint_version: (a: number) => [number, number];
     readonly constraint_wasm_new: (a: number, b: number, c: number) => [number, number, number];
-    readonly vls_isSingleVersion: (a: number) => number;
-    readonly vls_parse: (a: number, b: number) => [number, number, number];
-    readonly init: () => void;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/vers_like_specifier.js

@@ -98,9 +98,48 @@ export class Constraint {
 if (Symbol.dispose) Constraint.prototype[Symbol.dispose] = Constraint.prototype.free;
 
 /**
- * A **Vers-like Specifier** (VLS).
+ * The result of a containment check performed by [`Vls::contains`].
  *
- * VLS is the `<constraints>` part of a [vers](https://github.com/package-url/vers-spec)
+ * Because the VERS type of a [`Vls`] is unspecified, containment can usually only be
+ * resolved when the queried version exactly matches a constraint's version:
+ *
+ * * [`Comparator::Equal`], [`Comparator::GreaterThanOrEqual`], [`Comparator::LessThanOrEqual`]:
+ *   an exact match means the version is contained (`x = x`, `x >= x`, `x <= x` all hold) →
+ *   [`Containment::Contained`].
+ * * [`Comparator::NotEqual`], [`Comparator::LessThan`], [`Comparator::GreaterThan`]:
+ *   an exact match means the version is explicitly not contained (`x != x`, `x < x`, `x > x`
+ *   are always false) → [`Containment::NotContained`].
+ * * No constraint's version matches exactly: containment cannot be resolved, as the VERS
+ *   type is unknown / unspecified → [`Containment::Undetermined`].
+ *
+ * The one exception is a [`Vls`] that pins a single version (see [`Vls::is_single_version`]):
+ * since it has exactly one [`Comparator::Equal`] constraint, containment reduces to a plain
+ * string comparison and is always decidable, regardless of VERS type. In that case,
+ * *any* queried version resolves to either [`Containment::Contained`] or
+ * [`Containment::NotContained`], never [`Containment::Undetermined`].
+ * @enum {0 | 1 | 2}
+ */
+export const Containment = Object.freeze({
+    /**
+     * The version is contained in the specifier.
+     */
+    Contained: 0, "0": "Contained",
+    /**
+     * The version is explicitly not contained in the specifier.
+     */
+    NotContained: 1, "1": "NotContained",
+    /**
+     * Containment could not be determined: the version does not exactly match any
+     * constraint, and the (unspecified) VERS type does not allow any further
+     * comparison.
+     */
+    Undetermined: 2, "2": "Undetermined",
+});
+
+/**
+ * A **VERS-like specifier** (vls).
+ *
+ * vls is the `<constraints>` part of a [VERS](https://github.com/package-url/vers-spec)
  * URL *without* the `vers:<type>/` prefix.
  *
  * It is an ordered, `|`-separated list of [`Constraint`] values.
@@ -112,30 +151,14 @@ if (Symbol.dispose) Constraint.prototype[Symbol.dispose] = Constraint.prototype.
  *
  * # Syntax
  *
- * Derived from the [vers specification](https://www.packageurl.org/docs/vers/how-to-parse) and
+ * Derived from the [VERS specification](https://www.packageurl.org/docs/vers/how-to-parse),
  * its comments in
  * [CSAF 2.0](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#31232-branches-type---name-under-product-version-range)
  * and
  * [CSAF 2.1](https://docs.oasis-open.org/csaf/csaf/v2.1/csaf-v2.1.html#branches-type---name-under-product-version-range).
  *
- * There currently is no "official" grammar for vers-like specifier / the `<constraints>` part of
- * vers. This is a best-effort attempt used for this library.
- *
- * **Note:** This grammar may need to be updated once vers has been ratified through ECMA / following changes
- * to / clarifications of CSAF 2.0 or CSAF 2.1.
- *
- * ```text
- * vls            = constraint *( "|" constraint )
- * constraint     = comparator version-string / version-string
- * comparator     = "!=" / "<=" / ">=" / "<" / ">"
- * version-string = 1*( ALPHA / DIGIT / "-" / "." / "_" / "+" / "~" )
- * ```
- *
- * For validation, this leads to two sets of characters allowed in the context of the grammar.
- *
- * For `constraints`: `ALPHA / DIGIT / "-" / "." / "_" / "+" / "~" / "=" / "!" / "<" / ">" / "|"`
- *
- * For `version-string`: `ALPHA / DIGIT / "-" / "." / "_" / "+" / "~"`
+ * There currently is no "official" grammar for VERS-like specifier / the `<constraints>` part of
+ * VERS. This is a best-effort attempt used for this library.
  *
  * # Examples
  *
@@ -168,6 +191,18 @@ export class Vls {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_vls_free(ptr, 0);
     }
+    /**
+     * Return the [`Containment`] of the given `version` in this specifier, exposed as the
+     * instance method `vls.contains(version)` in JS.
+     * @param {string} version
+     * @returns {Containment}
+     */
+    contains(version) {
+        const ptr0 = passStringToWasm0(version, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.vls_contains(this.__wbg_ptr, ptr0, len0);
+        return ret;
+    }
     /**
      * Return `true` if this specifier pins exactly one version, exposed as the
      * instance method `vls.isSingleVersion()` in JS.
@@ -181,7 +216,7 @@ export class Vls {
      * Parse a `vls` as a [`Vls`] string, exposed as the static `Vls.parse(vls)` in JS.
      *
      * # Errors
-     * Throws a JS `Error` if `vls` is not a valid vers-like specifier.
+     * Throws a JS `Error` if `vls` is not a valid VERS-like specifier.
      * @param {string} vls
      * @returns {Vls}
      */