@cleocode/lafs 2026.3.74 → 2026.4.3

package/dist/src/deprecationRegistry.d.ts

@@ -1,13 +1,94 @@
-import type { LAFSEnvelope, Warning } from "./types.js";
+import type { LAFSEnvelope, Warning } from './types.js';
+/**
+ * A single deprecation rule in the registry.
+ *
+ * @remarks
+ * Each entry defines a detector function that inspects an envelope for
+ * deprecated usage patterns, along with metadata for generating warnings.
+ *
+ * @example
+ * ```typescript
+ * const entry: DeprecationEntry = {
+ *   id: "meta-mvi-boolean",
+ *   code: "W_DEPRECATED_META_MVI_BOOLEAN",
+ *   message: "_meta.mvi boolean values are deprecated",
+ *   deprecated: "1.0.0",
+ *   replacement: "Use _meta.mvi as one of: minimal|standard|full|custom",
+ *   removeBy: "2.0.0",
+ *   detector: (env) => typeof env._meta.mvi === "boolean",
+ * };
+ * ```
+ */
 export interface DeprecationEntry {
+    /** Unique identifier for this deprecation rule */
     id: string;
+    /** Warning code emitted when detected */
     code: string;
+    /** Human-readable deprecation message */
     message: string;
+    /** Version where the feature was deprecated */
     deprecated: string;
+    /**
+     * Suggested replacement or migration path.
+     * @defaultValue `undefined`
+     */
     replacement?: string;
+    /** Version where the deprecated feature will be removed */
     removeBy: string;
+    /** Predicate that returns `true` when the envelope uses the deprecated feature */
     detector: (envelope: LAFSEnvelope) => boolean;
 }
+/**
+ * Retrieve all registered deprecation entries.
+ *
+ * @returns Array of all {@link DeprecationEntry} rules in the registry
+ *
+ * @remarks
+ * Returns the internal registry array by reference. Callers should not
+ * mutate the returned array.
+ *
+ * @example
+ * ```typescript
+ * const entries = getDeprecationRegistry();
+ * console.log(entries.length); // number of registered deprecations
+ * ```
+ */
 export declare function getDeprecationRegistry(): DeprecationEntry[];
+/**
+ * Detect deprecated field usage in a LAFS envelope.
+ *
+ * @param envelope - The LAFS envelope to inspect
+ * @returns Array of {@link Warning} objects for each detected deprecation
+ *
+ * @remarks
+ * Runs all registered deprecation detectors against the envelope and returns
+ * warnings for each match. Returns an empty array if no deprecations are found.
+ *
+ * @example
+ * ```typescript
+ * const warnings = detectDeprecatedEnvelopeFields(envelope);
+ * for (const w of warnings) {
+ *   console.warn(`${w.code}: ${w.message}`);
+ * }
+ * ```
+ */
 export declare function detectDeprecatedEnvelopeFields(envelope: LAFSEnvelope): Warning[];
+/**
+ * Emit deprecation warnings by attaching them to the envelope metadata.
+ *
+ * @param envelope - The LAFS envelope to augment
+ * @returns A new envelope with deprecation warnings appended to `_meta.warnings`
+ *
+ * @remarks
+ * If no deprecations are detected, the original envelope is returned unchanged
+ * (no copy is made). Otherwise, a shallow copy is returned with the warnings
+ * array extended.
+ *
+ * @example
+ * ```typescript
+ * const enriched = emitDeprecationWarnings(envelope);
+ * console.log(enriched._meta.warnings); // includes any deprecation warnings
+ * ```
+ */
 export declare function emitDeprecationWarnings(envelope: LAFSEnvelope): LAFSEnvelope;
+//# sourceMappingURL=deprecationRegistry.d.ts.map

package/dist/src/deprecationRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecationRegistry.d.ts","sourceRoot":"","sources":["../../src/deprecationRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,OAAO,CAAC;CAC/C;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,EAAE,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,EAAE,CAUhF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,YAAY,GAAG,YAAY,CAc5E"}

package/dist/src/deprecationRegistry.js

@@ -1,17 +1,50 @@
 const DEPRECATION_REGISTRY = [
     {
-        id: "meta-mvi-boolean",
-        code: "W_DEPRECATED_META_MVI_BOOLEAN",
-        message: "_meta.mvi boolean values are deprecated",
-        deprecated: "1.0.0",
-        replacement: "Use _meta.mvi as one of: minimal|standard|full|custom",
-        removeBy: "2.0.0",
-        detector: (envelope) => typeof envelope._meta.mvi === "boolean",
+        id: 'meta-mvi-boolean',
+        code: 'W_DEPRECATED_META_MVI_BOOLEAN',
+        message: '_meta.mvi boolean values are deprecated',
+        deprecated: '1.0.0',
+        replacement: 'Use _meta.mvi as one of: minimal|standard|full|custom',
+        removeBy: '2.0.0',
+        detector: (envelope) => typeof envelope._meta.mvi === 'boolean',
     },
 ];
+/**
+ * Retrieve all registered deprecation entries.
+ *
+ * @returns Array of all {@link DeprecationEntry} rules in the registry
+ *
+ * @remarks
+ * Returns the internal registry array by reference. Callers should not
+ * mutate the returned array.
+ *
+ * @example
+ * ```typescript
+ * const entries = getDeprecationRegistry();
+ * console.log(entries.length); // number of registered deprecations
+ * ```
+ */
 export function getDeprecationRegistry() {
     return DEPRECATION_REGISTRY;
 }
+/**
+ * Detect deprecated field usage in a LAFS envelope.
+ *
+ * @param envelope - The LAFS envelope to inspect
+ * @returns Array of {@link Warning} objects for each detected deprecation
+ *
+ * @remarks
+ * Runs all registered deprecation detectors against the envelope and returns
+ * warnings for each match. Returns an empty array if no deprecations are found.
+ *
+ * @example
+ * ```typescript
+ * const warnings = detectDeprecatedEnvelopeFields(envelope);
+ * for (const w of warnings) {
+ *   console.warn(`${w.code}: ${w.message}`);
+ * }
+ * ```
+ */
 export function detectDeprecatedEnvelopeFields(envelope) {
     return getDeprecationRegistry()
         .filter((entry) => entry.detector(envelope))
@@ -23,6 +56,23 @@ export function detectDeprecatedEnvelopeFields(envelope) {
         removeBy: entry.removeBy,
     }));
 }
+/**
+ * Emit deprecation warnings by attaching them to the envelope metadata.
+ *
+ * @param envelope - The LAFS envelope to augment
+ * @returns A new envelope with deprecation warnings appended to `_meta.warnings`
+ *
+ * @remarks
+ * If no deprecations are detected, the original envelope is returned unchanged
+ * (no copy is made). Otherwise, a shallow copy is returned with the warnings
+ * array extended.
+ *
+ * @example
+ * ```typescript
+ * const enriched = emitDeprecationWarnings(envelope);
+ * console.log(enriched._meta.warnings); // includes any deprecation warnings
+ * ```
+ */
 export function emitDeprecationWarnings(envelope) {
     const detected = detectDeprecatedEnvelopeFields(envelope);
     if (detected.length === 0) {
@@ -37,3 +87,4 @@ export function emitDeprecationWarnings(envelope) {
         },
     };
 }
+//# sourceMappingURL=deprecationRegistry.js.map

package/dist/src/deprecationRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecationRegistry.js","sourceRoot":"","sources":["../../src/deprecationRegistry.ts"],"names":[],"mappings":"AA0CA,MAAM,oBAAoB,GAAuB;IAC/C;QACE,EAAE,EAAE,kBAAkB;QACtB,IAAI,EAAE,+BAA+B;QACrC,OAAO,EAAE,yCAAyC;QAClD,UAAU,EAAE,OAAO;QACnB,WAAW,EAAE,uDAAuD;QACpE,QAAQ,EAAE,OAAO;QACjB,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE,CACrB,OAAQ,QAAwC,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS;KAC3E;CACF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,8BAA8B,CAAC,QAAsB;IACnE,OAAO,sBAAsB,EAAE;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;SAC3C,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACf,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAsB;IAC5D,MAAM,QAAQ,GAAG,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,gBAAgB,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IACvD,OAAO;QACL,GAAG,QAAQ;QACX,KAAK,EAAE;YACL,GAAG,QAAQ,CAAC,KAAK;YACjB,QAAQ,EAAE,CAAC,GAAG,gBAAgB,EAAE,GAAG,QAAQ,CAAC;SAC7C;KACF,CAAC;AACJ,CAAC"}