@memberjunction/codegen-lib 5.29.0 → 5.30.1

package/dist/Misc/codegen-reporter.d.ts

@@ -0,0 +1,231 @@
+import { BaseSingleton } from '@memberjunction/global';
+/**
+ * Structured telemetry for a single CodeGen run.
+ *
+ * Captures phase timings (nested), per-entity work, LLM call details, and counters.
+ * Writes one JSON file per run to `~/.mj/codegen-state/run-<timestamp>.json`.
+ *
+ * Mirrors the file-based precedent set by `@memberjunction/metadata-sync`'s
+ * `~/.mj/sync-state/` pattern (PR #2330) rather than MJCore's runtime
+ * `TelemetryManager` (which is designed for live-app session tracking).
+ *
+ * @example
+ * ```ts
+ * const reporter = CodeGenReporter.Instance;
+ * reporter.startRun();
+ * reporter.mark('platform', 'sqlserver');
+ *
+ * await reporter.phase('manageMetadata', async () => {
+ *     // ... existing CodeGen code
+ * });
+ *
+ * await reporter.entityPhase('Customer', 'advancedGeneration', async () => {
+ *     // ... per-entity work
+ * });
+ *
+ * reporter.recordLLMCall({
+ *     entityName: 'Customer', promptName: 'SmartFieldIdentification',
+ *     model: 'gemini-3-flash-lite', tokensIn: 3421, tokensOut: 412,
+ *     costUSD: 0.00052, latencyMs: 1843,
+ * });
+ *
+ * reporter.counter('sqlStatements', 1);
+ *
+ * const reportPath = await reporter.endRun(true);
+ * ```
+ */
+/**
+ * A single phase span. Phases can nest via the stack held in `CodeGenReporter`.
+ */
+export type PhaseSpan = {
+    name: string;
+    /** Offset in ms from the start of the run (or start of parent for children). */
+    startMs: number;
+    /** Duration of this phase in ms. Set when the phase ends. */
+    durationMs: number;
+    /** Nested child phases, in order of entry. */
+    children: PhaseSpan[];
+};
+/**
+ * Per-entity breakdown entry, accumulated across phases.
+ */
+export type EntityEntry = {
+    name: string;
+    totalMs: number;
+    advancedGenerationMs: number;
+    llmCalls: number;
+    tokensIn: number;
+    tokensOut: number;
+    costUSD: number;
+    flags: {
+        new: boolean;
+        modified: boolean;
+        regenerated: boolean;
+    };
+};
+/**
+ * Record of a single LLM call made during the run.
+ */
+export type LLMCallEntry = {
+    entityName: string | null;
+    promptName: string;
+    model: string | null;
+    tokensIn: number;
+    tokensOut: number;
+    costUSD: number;
+    latencyMs: number;
+    /** Offset in ms from the start of the run. */
+    tsMs: number;
+};
+/**
+ * Free-form counters. `spCalls` is a nested dict keyed by SP name.
+ */
+export type RunCounters = {
+    entitiesProcessed: number;
+    entitiesNew: number;
+    entitiesModified: number;
+    entitiesRegenerated: number;
+    sqlStatements: number;
+    filesWritten: number;
+    spCalls: Record<string, number>;
+    [key: string]: number | Record<string, number>;
+};
+/**
+ * Shape of the JSON report written to disk.
+ */
+export type RunReport = {
+    runId: string;
+    startedAt: string;
+    finishedAt: string;
+    totalMs: number;
+    success: boolean;
+    context: Record<string, unknown>;
+    phases: PhaseSpan[];
+    entities: EntityEntry[];
+    llmCalls: LLMCallEntry[];
+    counters: RunCounters;
+    totalCostUSD: number;
+    totalTokensIn: number;
+    totalTokensOut: number;
+    notes: string[];
+};
+/**
+ * Compact summary returned by `listRuns()` for the report list CLI.
+ */
+export type RunSummary = {
+    runId: string;
+    startedAt: string;
+    totalMs: number;
+    success: boolean;
+    entitiesProcessed: number;
+    llmCalls: number;
+    totalCostUSD: number;
+    filePath: string;
+};
+/**
+ * Singleton reporter for CodeGen runs. Holds state for a single run at a time;
+ * call `startRun()` to begin, `endRun()` to emit and reset.
+ */
+export declare class CodeGenReporter extends BaseSingleton<CodeGenReporter> {
+    protected constructor();
+    static get Instance(): CodeGenReporter;
+    private _active;
+    private _runStartMs;
+    private _runStartIso;
+    private _phases;
+    private _phaseStack;
+    private _entities;
+    private _llmCalls;
+    private _counters;
+    private _context;
+    private _notes;
+    private _currentEntity;
+    /** True if a run is currently in progress. */
+    get IsActive(): boolean;
+    /** Begin capturing a new run. Resets all state from any prior run. */
+    startRun(): void;
+    /**
+     * Wrap an async block as a named phase. Phases nest automatically: any
+     * phases started while another is open are recorded as its children.
+     *
+     * If no run is active this becomes a pass-through — safe to call
+     * unconditionally.
+     */
+    phase<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Wrap per-entity work. Accumulates total time and sub-phase time on the
+     * entity record. Also sets the "current entity" so LLM calls recorded
+     * inside this block get attributed correctly.
+     */
+    entityPhase<T>(entityName: string, phaseName: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record a single LLM call. Attribution falls back to the entity set by
+     * the most recent `entityPhase()` if the caller doesn't supply one.
+     */
+    recordLLMCall(call: {
+        entityName?: string | null;
+        promptName: string;
+        model?: string | null;
+        tokensIn?: number;
+        tokensOut?: number;
+        costUSD?: number;
+        latencyMs: number;
+    }): void;
+    /** Increment a named counter (default 1). Unknown counter names are allowed. */
+    counter(name: string, delta?: number): void;
+    /** Increment a specific stored-procedure call count. */
+    spCallCounter(spName: string, delta?: number): void;
+    /** Set a one-time context value (platform, mjVersion, etc.). */
+    mark(key: string, value: unknown): void;
+    /** Flag an entity's change status. Used for attribution in the report. */
+    flagEntity(entityName: string, flag: 'new' | 'modified' | 'regenerated', value?: boolean): void;
+    /** Append a free-form note (warnings, unexpected conditions, etc.). */
+    note(message: string): void;
+    /**
+     * Finalize the run, write the JSON report to disk, and reset state.
+     * Returns the written file path (or null) and the report object.
+     *
+     * Safe to call even if `startRun()` wasn't called (becomes a no-op).
+     */
+    endRun(success: boolean): Promise<{
+        filePath: string | null;
+        report: RunReport | null;
+    }>;
+    /** Get the current in-memory report (snapshot). Mostly for tests. */
+    snapshot(): RunReport;
+    /**
+     * Print a human-readable summary of the completed run to stdout.
+     * Call after `endRun()` — operates on the saved report.
+     */
+    static printSummary(report: RunReport): void;
+    private static sumPhaseTime;
+    /** The directory where run JSON files are stored. */
+    static stateDir(): string;
+    /** List recent runs, newest first, with compact summaries. */
+    static listRuns(limit?: number): Promise<RunSummary[]>;
+    /** Load a single run by file name OR run id. Returns null if not found. */
+    static loadRun(runIdOrFile: string): Promise<RunReport | null>;
+    /**
+     * Prune `~/.mj/codegen-state/` to the most recent MAX_RETAINED_RUNS files.
+     * Non-fatal on errors.
+     */
+    static pruneOldRuns(): Promise<void>;
+    private getOrCreateEntity;
+    private emptyCounters;
+    private makeRunId;
+    /**
+     * Absolute start time of a phase (ms since epoch). The phase's own
+     * startMs is stored relative to its parent (or run start), so we have
+     * to walk up the stack to get an absolute.
+     */
+    private phaseStartAbs;
+}
+/** Shortcut: wrap a phase using the singleton. */
+export declare function reportPhase<T>(name: string, fn: () => Promise<T>): Promise<T>;
+/** Shortcut: wrap a per-entity phase using the singleton. */
+export declare function reportEntityPhase<T>(entityName: string, phaseName: string, fn: () => Promise<T>): Promise<T>;
+/** Shortcut: increment a counter using the singleton. */
+export declare function reportCounter(name: string, delta?: number): void;
+/** Shortcut: set a context mark using the singleton. */
+export declare function reportMark(key: string, value: unknown): void;
+//# sourceMappingURL=codegen-reporter.d.ts.map

package/dist/Misc/codegen-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen-reporter.d.ts","sourceRoot":"","sources":["../../src/Misc/codegen-reporter.ts"],"names":[],"mappings":"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"}