@codluv/versionguard 0.4.0 → 0.6.0

package/dist/ckm/engine.d.ts

@@ -0,0 +1,92 @@
+/**
+ * CKM engine — auto-generates topic index from a ckm.json manifest.
+ *
+ * @remarks
+ * This module is designed to be reusable across any CLI tool that
+ * generates a `ckm.json` via forge-ts. It requires zero manual
+ * topic mapping — topics are derived from the CKM structure itself.
+ *
+ * ## How topics are derived
+ *
+ * 1. Each `*Config` concept becomes a topic (e.g., `CalVerConfig` → `calver`)
+ * 2. Config schema entries are grouped by their key prefix
+ * 3. Operations are linked to topics by keyword matching on their description
+ * 4. Constraints are linked by their `enforcedBy` field
+ *
+ * ## Integration pattern
+ *
+ * ```ts
+ * import { createCkmEngine } from './ckm/engine';
+ * import ckmRaw from '../docs/ckm.json?raw';
+ *
+ * const engine = createCkmEngine(JSON.parse(ckmRaw));
+ * console.log(engine.getTopicIndex());
+ * console.log(JSON.stringify(engine.getTopicJson('calver')));
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { CkmManifest, CkmTopic } from './types';
+/**
+ * The CKM engine — provides topic derivation, filtering, and output formatting.
+ *
+ * @remarks
+ * Instantiate via {@link createCkmEngine}. All topic data is derived
+ * from the CKM manifest at construction time with zero configuration.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmEngine {
+    /** All auto-derived topics. */
+    readonly topics: CkmTopic[];
+    /**
+     * Returns a formatted topic index for terminal display.
+     *
+     * @param toolName - CLI tool name for the usage line.
+     * @returns Formatted string.
+     */
+    getTopicIndex(toolName?: string): string;
+    /**
+     * Returns human-readable content for a topic.
+     *
+     * @param topicName - Topic slug.
+     * @returns Formatted content, or null if not found.
+     */
+    getTopicContent(topicName: string): string | null;
+    /**
+     * Returns CKM-filtered JSON for a topic (machine-readable).
+     *
+     * @param topicName - Topic slug, or undefined for full index.
+     * @returns JSON-serializable object.
+     */
+    getTopicJson(topicName?: string): object;
+    /**
+     * Returns the raw CKM manifest.
+     */
+    getManifest(): CkmManifest;
+}
+/**
+ * Creates a CKM engine from a parsed manifest.
+ *
+ * @remarks
+ * This is the main entry point for the reusable CKM module.
+ * Pass the parsed contents of `ckm.json` and get back an engine
+ * that auto-derives topics and provides formatted output.
+ *
+ * @param manifest - Parsed CKM manifest (from forge-ts `ckm.json`).
+ * @returns A configured CKM engine.
+ *
+ * @example
+ * ```ts
+ * import { createCkmEngine } from './ckm/engine';
+ *
+ * const engine = createCkmEngine(manifest);
+ * console.log(engine.getTopicIndex('mytool'));
+ * ```
+ *
+ * @public
+ * @since 0.4.0
+ */
+export declare function createCkmEngine(manifest: CkmManifest): CkmEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/ckm/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/ckm/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAkB,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA6CrE;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;IAE5B;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzC;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAElD;;;;;OAKG;IACH,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzC;;OAEG;IACH,WAAW,IAAI,WAAW,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAUhE"}

package/dist/ckm/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CKM (Codebase Knowledge Manifest) module.
+ *
+ * @remarks
+ * Reusable module for any CLI tool that generates `ckm.json` via forge-ts.
+ * Provides auto-derived topics, machine-readable JSON output, and
+ * human-readable terminal formatting — all with zero manual configuration.
+ *
+ * ## Quick start
+ *
+ * ```ts
+ * import { createCkmEngine } from './ckm';
+ * import ckmRaw from '../docs/ckm.json?raw';
+ *
+ * const engine = createCkmEngine(JSON.parse(ckmRaw));
+ *
+ * // Terminal: topic index
+ * console.log(engine.getTopicIndex('mytool'));
+ *
+ * // Terminal: specific topic
+ * console.log(engine.getTopicContent('calver'));
+ *
+ * // JSON: for LLM agents
+ * console.log(JSON.stringify(engine.getTopicJson('calver'), null, 2));
+ * ```
+ *
+ * @packageDocumentation
+ * @public
+ */
+export { type CkmEngine, createCkmEngine } from './engine';
+export type { CkmConcept, CkmConfigEntry, CkmConstraint, CkmInput, CkmManifest, CkmOperation, CkmProperty, CkmTopic, CkmWorkflow, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/ckm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ckm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,WAAW,GACZ,MAAM,SAAS,CAAC"}

package/dist/ckm/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * CKM (Codebase Knowledge Manifest) type definitions.
+ *
+ * @remarks
+ * These types describe the structure of a `ckm.json` file generated
+ * by forge-ts. Any CLI tool can consume this format to provide
+ * machine-readable help, auto-generated topic indexes, and
+ * LLM-consumable operational knowledge.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A domain concept extracted from an exported interface or type.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmConcept {
+    /** Unique concept identifier (e.g., `'concept-CalVerConfig'`). */
+    id: string;
+    /** Interface or type name (e.g., `'CalVerConfig'`). */
+    name: string;
+    /** One-line description from TSDoc summary. */
+    what: string;
+    /** Properties of the interface, if applicable. */
+    properties?: CkmProperty[];
+}
+/**
+ * A property within a concept.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmProperty {
+    /** Property name. */
+    name: string;
+    /** TypeScript type annotation. */
+    type: string;
+    /** Description from TSDoc. */
+    description: string;
+}
+/**
+ * A user-facing operation extracted from an exported function.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmOperation {
+    /** Unique operation identifier (e.g., `'op-validate'`). */
+    id: string;
+    /** Function name (e.g., `'validate'`). */
+    name: string;
+    /** One-line description from TSDoc summary. */
+    what: string;
+    /** Function parameters. */
+    inputs?: CkmInput[];
+    /** Return value description. */
+    outputs?: {
+        text: string;
+    };
+}
+/**
+ * A function parameter within an operation.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmInput {
+    /** Parameter name. */
+    name: string;
+    /** TypeScript type annotation. */
+    type: string;
+    /** Whether the parameter is required. */
+    required: boolean;
+    /** Description from TSDoc `@param` tag. */
+    description: string;
+}
+/**
+ * A constraint enforced by the tool.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmConstraint {
+    /** Unique constraint identifier. */
+    id: string;
+    /** The rule being enforced. */
+    rule: string;
+    /** Function or module that enforces it. */
+    enforcedBy: string;
+}
+/**
+ * A multi-step workflow for a common goal.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmWorkflow {
+    /** Unique workflow identifier. */
+    id: string;
+    /** What the workflow achieves. */
+    goal: string;
+    /** Ordered steps. */
+    steps: {
+        command?: string;
+        manual?: string;
+        note?: string;
+    }[];
+}
+/**
+ * A config schema entry with type, description, and default.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmConfigEntry {
+    /** Dotted key path (e.g., `'CalVerConfig.format'`). */
+    key: string;
+    /** TypeScript type. */
+    type: string;
+    /** Description from TSDoc. */
+    description: string;
+    /** Default value if specified via `@defaultValue`. */
+    default?: string;
+}
+/**
+ * The complete Codebase Knowledge Manifest.
+ *
+ * @remarks
+ * Generated by `forge-ts build` from TSDoc annotations.
+ * Consumed by CLI tools for structured help output.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmManifest {
+    /** Domain concepts (interfaces, types). */
+    concepts: CkmConcept[];
+    /** User-facing operations (exported functions). */
+    operations: CkmOperation[];
+    /** Enforced rules. */
+    constraints: CkmConstraint[];
+    /** Multi-step workflows. */
+    workflows: CkmWorkflow[];
+    /** Configuration schema entries. */
+    configSchema: CkmConfigEntry[];
+}
+/**
+ * An auto-generated topic derived from CKM data.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface CkmTopic {
+    /** Topic slug used as CLI argument (e.g., `'calver'`). */
+    name: string;
+    /** One-line summary. */
+    summary: string;
+    /** Related concept names from the CKM. */
+    concepts: CkmConcept[];
+    /** Related operations from the CKM. */
+    operations: CkmOperation[];
+    /** Related config entries from the CKM. */
+    configSchema: CkmConfigEntry[];
+    /** Related constraints from the CKM. */
+    constraints: CkmConstraint[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ckm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ckm/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,gCAAgC;IAChC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,mDAAmD;IACnD,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,sBAAsB;IACtB,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,4BAA4B;IAC5B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,oCAAoC;IACpC,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,uCAAuC;IACvC,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,2CAA2C;IAC3C,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,wCAAwC;IACxC,WAAW,EAAE,aAAa,EAAE,CAAC;CAC9B"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAmevC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,GAAE,MAAM,EAAiB,EAC7B,OAAO,GAAE,MAAwB,GAChC,OAAO,CAGT"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgDpC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,IAAI,OAAO,CA2jBvC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,GAAE,MAAM,EAAiB,EAC7B,OAAO,GAAE,MAAwB,GAChC,OAAO,CAWT"}