@codluv/versionguard 0.3.0 → 0.5.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
  * ```
  *
@@ -111,20 +154,21 @@ export declare function parse(version: string, calverFormat: CalVerFormat): CalV
  * @param version - Version string to validate.
  * @param calverFormat - Format expected for the version string.
  * @param preventFutureDates - Whether future dates should be reported as errors.
+ * @param schemeRules - Optional scheme rules for modifier validation and segment count warnings.
  * @returns A validation result containing any discovered errors and the parsed version on success.
  *
  * @example
  * ```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 +197,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 +208,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 +220,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 +232,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 +244,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 +255,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 +278,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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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"}

package/dist/changelog.d.ts

@@ -80,4 +80,56 @@ export declare function getLatestVersion(changelogPath: string): string | null;
  * ```
  */
 export declare function addVersionEntry(changelogPath: string, version: string, date?: string): void;
+/**
+ * Detects whether a changelog has been mangled by Changesets.
+ *
+ * @remarks
+ * Changesets prepends version content above the Keep a Changelog preamble,
+ * producing `## 0.4.0` (no brackets, no date) before the "All notable changes"
+ * paragraph. This function detects that pattern.
+ *
+ * @param changelogPath - Path to the changelog file.
+ * @returns `true` when the changelog appears to be mangled by Changesets.
+ *
+ * @example
+ * ```ts
+ * import { isChangesetMangled } from 'versionguard';
+ *
+ * if (isChangesetMangled('CHANGELOG.md')) {
+ *   fixChangesetMangling('CHANGELOG.md');
+ * }
+ * ```
+ *
+ * @public
+ * @since 0.4.0
+ */
+export declare function isChangesetMangled(changelogPath: string): boolean;
+/**
+ * Fixes a Changesets-mangled changelog into proper Keep a Changelog format.
+ *
+ * @remarks
+ * This function:
+ * 1. Extracts the version number and content prepended by Changesets
+ * 2. Converts Changesets section names (Minor Changes, Patch Changes) to
+ *    Keep a Changelog names (Added, Fixed)
+ * 3. Strips commit hashes from entry lines
+ * 4. Adds the date and brackets to the version header
+ * 5. Inserts the entry after `## [Unreleased]` in the correct position
+ * 6. Restores the preamble to its proper location
+ *
+ * @param changelogPath - Path to the changelog file to fix.
+ * @param date - Release date in `YYYY-MM-DD` format.
+ * @returns `true` when the file was modified, `false` when no fix was needed.
+ *
+ * @example
+ * ```ts
+ * import { fixChangesetMangling } from 'versionguard';
+ *
+ * const fixed = fixChangesetMangling('CHANGELOG.md');
+ * ```
+ *
+ * @public
+ * @since 0.4.0
+ */
+export declare function fixChangesetMangling(changelogPath: string, date?: string): boolean;
 //# sourceMappingURL=changelog.d.ts.map

package/dist/changelog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../src/changelog.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAc,EACtB,YAAY,GAAE,OAAc,GAC3B,yBAAyB,CAgD3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAA8C,GACnD,IAAI,CAmBN"}
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../src/changelog.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAc,EACtB,YAAY,GAAE,OAAc,GAC3B,yBAAyB,CAgD3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAA8C,GACnD,IAAI,CAmBN;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAMjE;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,MAA8C,GACnD,OAAO,CAoET"}