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

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)
 
@@ -21,13 +21,13 @@ Add `vers-like-specifier` to your `Cargo.toml`. The package is published on http
 
 ```toml
 [dependencies]
-vers-like-specifier = "0.1"
+vers-like-specifier = "0.2"
 ```
 
 ## 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);
@@ -35,32 +35,45 @@ assert_eq!(vls.to_string(), ">=1.0.0|<2.0.0");
 
 
 let constraints = vls.constraints();
-assert_eq!(constraints[0].comparator(), &Comparator::GreaterThanOrEqual);
+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].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 containing only exact-match comparators (equal, not equal) is always decidable, since
+// containment then reduces to a plain string comparison if there is a constraint with that version. If there isn't a
+// constraint with the version, it is not contained by default. 
+let exact_only: Vls = "1.0.0|!=2.0.0".parse().unwrap();
+assert_eq!(exact_only.contains("1.0.0"), Containment::Contained);
+assert_eq!(exact_only.contains("2.0.0"), Containment::NotContained);
+assert_eq!(exact_only.contains("3.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

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

package/vers_like_specifier.d.ts

@@ -9,14 +9,14 @@
 export type VersionString = string;
 
 /**
- * Errors specific to a single constraint within a VLS string.
+ * Errors specific to a single constraint within a vls string.
  */
 export type ConstraintError = "EmptyConstraint" | "EmptyConstraintVersion" | { InvalidConstraintVersionCharacters: string[] };
 
 /**
  * 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" | { SingleVersionNotAllowed: string } | { InvalidCharacters: string[] } | { InvalidConstraints: ConstraintError[] } | { DuplicateConstraintVersions: string[] } | { Serialization: string };
 
 
 /**
@@ -61,7 +61,7 @@ export class Constraint {
     [Symbol.dispose](): void;
     /**
      * Construct a new [`Constraint`] from a [`Comparator`] and a version string, validating
-     * the version string against the VLS grammar. Exposed as `new Constraint(comparator, version)`
+     * the version string against the vls grammar. Exposed as `new Constraint(comparator, version)`
      * in JS.
      *
      * # Errors
@@ -79,9 +79,48 @@ 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 uses only exact-match comparators (i.e.
+ * [`Comparator::Equal`] and/or [`Comparator::NotEqual`]).
+ * Here, containment is reduced 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`] depending on the exact-match comparator if there is a constraint with
+ * the queried version, and always to [`Containment::NotContained`] if there is no constraint with that version.
+ */
+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 +132,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
  *
@@ -136,15 +159,15 @@ export class Vls {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Return `true` if this specifier pins exactly one version, exposed as the
-     * instance method `vls.isSingleVersion()` in JS.
+     * Return the [`Containment`] of the given `version` in this specifier, exposed as the
+     * instance method `vls.contains(version)` in JS.
      */
-    isSingleVersion(): boolean;
+    contains(version: string): Containment;
     /**
      * 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 +181,14 @@ 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_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

@@ -75,7 +75,7 @@ export class Constraint {
     }
     /**
      * Construct a new [`Constraint`] from a [`Comparator`] and a version string, validating
-     * the version string against the VLS grammar. Exposed as `new Constraint(comparator, version)`
+     * the version string against the vls grammar. Exposed as `new Constraint(comparator, version)`
      * in JS.
      *
      * # Errors
@@ -98,9 +98,49 @@ 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 uses only exact-match comparators (i.e.
+ * [`Comparator::Equal`] and/or [`Comparator::NotEqual`]).
+ * Here, containment is reduced 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`] depending on the exact-match comparator if there is a constraint with
+ * the queried version, and always to [`Containment::NotContained`] if there is no constraint with that version.
+ * @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 +152,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
  *
@@ -169,19 +193,22 @@ export class Vls {
         wasm.__wbg_vls_free(ptr, 0);
     }
     /**
-     * Return `true` if this specifier pins exactly one version, exposed as the
-     * instance method `vls.isSingleVersion()` in JS.
-     * @returns {boolean}
+     * 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}
      */
-    isSingleVersion() {
-        const ret = wasm.vls_isSingleVersion(this.__wbg_ptr);
-        return ret !== 0;
+    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;
     }
     /**
      * 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}
      */