@codluv/versionguard 0.3.0 → 0.4.0

package/dist/calver.d.ts

@@ -1,9 +1,43 @@
 /**
  * Calendar version parsing, formatting, and comparison helpers.
  *
+ * @remarks
+ * Supports the full calver.org specification with all standard tokens:
+ * Year (`YYYY`, `YY`, `0Y`), Month (`MM`, `M`, `0M`), Week (`WW`, `0W`),
+ * Day (`DD`, `D`, `0D`), and Counter (`MICRO`/`PATCH`).
+ *
+ * `MICRO` is the CalVer-standard name for the counter segment.
+ * `PATCH` is accepted as a SemVer-familiar alias and behaves identically.
+ *
  * @packageDocumentation
  */
-import type { CalVer, CalVerFormat, ValidationResult } from './types';
+import type { CalVer, CalVerFormat, SchemeRules, ValidationResult } from './types';
+/**
+ * Validates that a CalVer format string is composed of valid tokens
+ * and follows structural rules.
+ *
+ * @remarks
+ * Structural rules enforced:
+ * - Must have at least 2 segments
+ * - First segment must be a year token
+ * - Week tokens and Month/Day tokens are mutually exclusive
+ * - Counter (MICRO/PATCH) can only appear as the last segment
+ *
+ * @param formatStr - Format string to validate.
+ * @returns `true` when the format is valid.
+ *
+ * @example
+ * ```ts
+ * import { isValidCalVerFormat } from 'versionguard';
+ *
+ * isValidCalVerFormat('YYYY.MM.MICRO'); // true
+ * isValidCalVerFormat('INVALID');        // false
+ * ```
+ *
+ * @public
+ * @since 0.3.0
+ */
+export declare function isValidCalVerFormat(formatStr: string): formatStr is CalVerFormat;
 /**
  * Parsed token layout for a supported CalVer format string.
  *
@@ -15,11 +49,19 @@ export interface ParsedCalVerFormat {
     /**
      * Year token captured from the format string.
      */
-    year: 'YYYY' | 'YY';
+    year: 'YYYY' | 'YY' | '0Y';
+    /**
+     * Month token captured from the format string when present.
+     *
+     * @defaultValue undefined
+     */
+    month?: 'MM' | 'M' | '0M';
     /**
-     * Month token captured from the format string.
+     * Week token captured from the format string when present.
+     *
+     * @defaultValue undefined
      */
-    month: 'MM' | 'M' | '0M';
+    week?: 'WW' | '0W';
     /**
      * Day token captured from the format string when present.
      *
@@ -27,18 +69,19 @@ export interface ParsedCalVerFormat {
      */
     day?: 'DD' | 'D' | '0D';
     /**
-     * Patch token captured from the format string when present.
+     * Counter token captured from the format string when present.
+     * Both `MICRO` and `PATCH` map to the same numeric counter.
      *
      * @defaultValue undefined
      */
-    patch?: 'PATCH';
+    counter?: 'MICRO' | 'PATCH';
 }
 /**
  * Breaks a CalVer format string into its component tokens.
  *
  * @remarks
  * This helper is used internally by parsing, formatting, and version generation helpers
- * to decide which date parts or patch counters are present in a given CalVer layout.
+ * to decide which date parts or counters are present in a given CalVer layout.
  *
  * @param calverFormat - Format string to inspect.
  * @returns The parsed token definition for the requested format.
@@ -47,8 +90,8 @@ export interface ParsedCalVerFormat {
  * ```ts
  * import { parseFormat } from 'versionguard';
  *
- * parseFormat('YYYY.MM.PATCH');
- * // => { year: 'YYYY', month: 'MM', patch: 'PATCH' }
+ * parseFormat('YYYY.MM.MICRO');
+ * // => { year: 'YYYY', month: 'MM', counter: 'MICRO' }
  * ```
  *
  * @public
@@ -92,7 +135,7 @@ export declare function getRegexForFormat(calverFormat: CalVerFormat): RegExp;
  * ```ts
  * import { parse } from 'versionguard';
  *
- * parse('2026.03.21', 'YYYY.0M.0D')?.month;
+ * parse('2026.3.0', 'YYYY.M.MICRO')?.month;
  * // => 3
  * ```
  *
@@ -117,14 +160,14 @@ export declare function parse(version: string, calverFormat: CalVerFormat): CalV
  * ```ts
  * import { validate } from 'versionguard';
  *
- * validate('2026.03.21', 'YYYY.0M.0D', false).valid;
+ * validate('2026.3.0', 'YYYY.M.MICRO', false).valid;
  * // => true
  * ```
  *
  * @public
  * @since 0.1.0
  */
-export declare function validate(version: string, calverFormat: CalVerFormat, preventFutureDates?: boolean): ValidationResult;
+export declare function validate(version: string, calverFormat: CalVerFormat, preventFutureDates?: boolean, schemeRules?: SchemeRules): ValidationResult;
 /**
  * Formats a parsed CalVer object back into a version string.
  *
@@ -153,8 +196,8 @@ export declare function format(version: CalVer): string;
  * Creates the current CalVer string for a format.
  *
  * @remarks
- * This helper derives its values from the provided date and initializes any patch token to `0`.
- * It is useful for generating a same-day baseline before incrementing patch-based formats.
+ * This helper derives its values from the provided date and initializes any counter to `0`.
+ * It is useful for generating a same-day baseline before incrementing counter-based formats.
  *
  * @param calverFormat - Format to generate.
  * @param now - Date used as the source for year, month, and day values.
@@ -164,7 +207,7 @@ export declare function format(version: CalVer): string;
  * ```ts
  * import { getCurrentVersion } from 'versionguard';
  *
- * getCurrentVersion('YYYY.MM.PATCH', new Date('2026-03-21T00:00:00Z'));
+ * getCurrentVersion('YYYY.M.MICRO', new Date('2026-03-21T00:00:00Z'));
  * // => '2026.3.0'
  * ```
  *
@@ -176,8 +219,8 @@ export declare function getCurrentVersion(calverFormat: CalVerFormat, now?: Date
  * Compares two CalVer strings using a shared format.
  *
  * @remarks
- * Comparison is performed component-by-component in year, month, day, then patch order.
- * Missing day and patch values are treated as `0` during comparison.
+ * Comparison is performed component-by-component in year, month, day, then counter order.
+ * Missing day and counter values are treated as `0` during comparison.
  *
  * @param a - Left-hand version string.
  * @param b - Right-hand version string.
@@ -188,7 +231,7 @@ export declare function getCurrentVersion(calverFormat: CalVerFormat, now?: Date
  * ```ts
  * import { compare } from 'versionguard';
  *
- * compare('2026.03.2', '2026.03.1', 'YYYY.MM.PATCH');
+ * compare('2026.3.2', '2026.3.1', 'YYYY.M.MICRO');
  * // => 1
  * ```
  *
@@ -200,8 +243,8 @@ export declare function compare(a: string, b: string, calverFormat: CalVerFormat
  * Increments a CalVer string.
  *
  * @remarks
- * Patch-based formats increment the existing patch number. Formats without a patch token are
- * promoted to a patch-based output by appending `.PATCH` semantics with an initial value of `0`.
+ * Counter-based formats increment the existing counter. Formats without a counter are
+ * promoted to a counter-based output by appending `.MICRO` with an initial value of `0`.
  *
  * @param version - Current version string.
  * @param calverFormat - Format used to parse the current version.
@@ -211,7 +254,7 @@ export declare function compare(a: string, b: string, calverFormat: CalVerFormat
  * ```ts
  * import { increment } from 'versionguard';
  *
- * increment('2026.03.1', 'YYYY.MM.PATCH');
+ * increment('2026.3.1', 'YYYY.M.MICRO');
  * // => '2026.3.2'
  * ```
  *
@@ -234,7 +277,7 @@ export declare function increment(version: string, calverFormat: CalVerFormat):
  * ```ts
  * import { getNextVersions } from 'versionguard';
  *
- * getNextVersions('2026.03.1', 'YYYY.MM.PATCH').length;
+ * getNextVersions('2026.3.1', 'YYYY.M.MICRO').length;
  * // => 2
  * ```
  *

package/dist/calver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calver.d.ts","sourceRoot":"","sources":["../src/calver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAmB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpB;;OAEG;IACH,KAAK,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAEzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAExB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,kBAAkB,CAkB1E;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAIpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAmChF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,kBAAkB,GAAE,OAAc,GACjC,gBAAgB,CA0ElB;AAcD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAa9C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAkB5F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAiBhF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAsB7E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAE5F"}
+{"version":3,"file":"calver.d.ts","sourceRoot":"","sources":["../src/calver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,YAAY,EAEZ,WAAW,EAEX,gBAAgB,EACjB,MAAM,SAAS,CAAC;AA8BjB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,IAAI,YAAY,CAoBhF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAE3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAE1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEnB;;;;OAIG;IACH,GAAG,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAExB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,kBAAkB,CAoB1E;AAyCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAKpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAqDhF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,kBAAkB,GAAE,OAAc,EAClC,WAAW,CAAC,EAAE,WAAW,GACxB,gBAAgB,CA6GlB;AAgBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsB9C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAY5F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAiBhF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAqB7E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAE5F"}