@dzhechkov/harness-core 0.8.2 → 0.8.6

package/dist/cmd-usage.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Command-invocation accounting for `dz deadwood`.
+ *
+ * The write leg is a single best-effort append. The report leg is pure: callers
+ * inject log text, inventory, an allowlist, and a clock. A usage report is
+ * advisory only and never mutates the harness surface it describes.
+ *
+ * @packageDocumentation
+ */
+export declare const CMD_USAGE_LOG_RELATIVE = ".dz/cmd-usage.jsonl";
+export declare const CMD_USAGE_LOG_MAX_BYTES = 1048576;
+export declare const CMD_USAGE_COMPACT_TARGET_BYTES: number;
+export declare const CMD_USAGE_SCHEMA = 1;
+export declare const CMD_USAGE_V1_EPOCH_MS: number;
+export declare const DEADWOOD_FUTURE_TOLERANCE_MS = 86400000;
+export declare const DEADWOOD_MIN_OBSERVED_DAYS = 28;
+export declare const DEADWOOD_MIN_RECORDS = 100;
+export type DeadwoodSurfaceKind = 'command' | 'skill' | 'rule';
+export interface CmdUsageInvocationRecord {
+    readonly kind: 'cmd';
+    readonly cmd: string;
+    readonly ts: string;
+    readonly v: 1;
+}
+export interface CmdUsageAggregateRecord {
+    readonly kind: 'agg';
+    readonly cmd: string;
+    readonly runs: number;
+    readonly firstAt: string;
+    readonly lastAt: string;
+    readonly v: 1;
+}
+export type CmdUsageRecord = CmdUsageInvocationRecord | CmdUsageAggregateRecord;
+export interface ParsedCmdUsage {
+    readonly records: readonly CmdUsageRecord[];
+    readonly skipped: number;
+    readonly outOfRange: number;
+}
+export interface CmdUsageStat {
+    readonly cmd: string;
+    readonly runs: number;
+    readonly runsInWindow: number;
+    readonly firstAt: string;
+    readonly lastAt: string;
+}
+export interface DeadwoodAllowlistEntry {
+    readonly surface: string;
+    readonly kind: DeadwoodSurfaceKind;
+    readonly reason: string;
+}
+export interface DeadwoodInventoryItem {
+    readonly surface: string;
+    readonly kind: DeadwoodSurfaceKind;
+    /** Alternate typed command tokens folded into this canonical command candidate. */
+    readonly aliases?: readonly string[];
+}
+export type DeadwoodVerdict = 'insufficient-data' | 'ready';
+export interface DeadwoodUsedSurface {
+    readonly state: 'used';
+    readonly surface: string;
+    readonly kind: Exclude<DeadwoodSurfaceKind, 'skill'>;
+    readonly runs: number;
+    readonly runsInWindow: number;
+    readonly firstAt: string;
+    readonly lastAt: string;
+}
+export interface DeadwoodCandidate {
+    readonly state: 'zero-usage';
+    readonly surface: string;
+    readonly kind: Exclude<DeadwoodSurfaceKind, 'skill'>;
+    readonly runs: number;
+    readonly runsInWindow: 0;
+    readonly firstAt: string | null;
+    readonly lastAt: string | null;
+}
+export interface DeadwoodExemptSurface {
+    readonly state: 'excluded-safety';
+    readonly surface: string;
+    readonly kind: Exclude<DeadwoodSurfaceKind, 'skill'>;
+    readonly reason: string;
+    readonly runs: number;
+    readonly runsInWindow: 0;
+    readonly firstAt: string | null;
+    readonly lastAt: string | null;
+}
+export interface DeadwoodUnjudgedSurface {
+    readonly state: 'insufficient-data' | 'no-instrumentation';
+    readonly surface: string;
+    readonly kind: DeadwoodSurfaceKind;
+    readonly reason: string;
+}
+export interface DeadwoodReport {
+    readonly verdict: DeadwoodVerdict;
+    readonly windowWeeks: number;
+    readonly observedDays: number;
+    readonly recordCount: number;
+    readonly ruleObservedDays: number;
+    readonly ruleAuditCount: number;
+    readonly candidates: readonly DeadwoodCandidate[];
+    readonly exempt: readonly DeadwoodExemptSurface[];
+    readonly used: readonly DeadwoodUsedSurface[];
+    readonly insufficient: readonly DeadwoodUnjudgedSurface[];
+    readonly noInstrumentation: readonly DeadwoodUnjudgedSurface[];
+    readonly staleAllowlist: readonly DeadwoodAllowlistEntry[];
+    readonly skippedLines: number;
+    readonly outOfRange: number;
+}
+export interface DeadwoodInput {
+    readonly cmdUsageText: string;
+    readonly guardAuditText?: string;
+    readonly inventory: readonly DeadwoodInventoryItem[];
+    readonly allowlistText: string;
+    readonly weeks: number;
+    readonly now: Date;
+}
+/** Walk up to the nearest `.dz` directory without ever making telemetry throw. */
+export declare function resolveCmdUsageRoot(startDir: string): string;
+/** One append per parsed command, with no argv/cwd/env payload. Never throws. */
+export declare function recordCommandInvocation(root: string, cmd: string, now?: Date): void;
+/** ADR-compatible name retained for callers/tests written before the plan renamed the seam. */
+export declare const appendCommandUsage: typeof recordCommandInvocation;
+/** Parse independently per line; torn or schema-invalid rows are counted and skipped. */
+export declare function parseCmdUsageLines(text: string, now: Date): ParsedCmdUsage;
+/** Measured corpus span (first accepted event to last), or null when no event can be read. */
+export declare function measureCmdUsageDepthDays(text: string, now: Date): number | null;
+/** A verdict needs both a meaningful sample and history spanning the requested window. */
+export declare function decideDeadwoodWindow(depthDays: number, count: number, weeks: number): {
+    ok: boolean;
+    reason: string;
+};
+/** Fold raw and compacted rows into the same per-command accounting shape. */
+export declare function foldCmdUsage(records: readonly CmdUsageRecord[], weeks: number, now: Date): Map<string, CmdUsageStat>;
+/** Parse the committed safety allowlist; a reason-less exemption is refused, never skipped. */
+export declare function loadDeadwoodAllowlist(json: string): DeadwoodAllowlistEntry[];
+/** Build the single structure consumed by both the human and JSON renderers. */
+export declare function buildDeadwoodReport(input: DeadwoodInput): DeadwoodReport;
+/** Render one report object as either human text or stable JSON. */
+export declare function renderDeadwoodReport(report: DeadwoodReport, format: 'text' | 'json'): string;
+/**
+ * Lazily compact the invocation log on the cold read path.
+ *
+ * The named lock protects competing compactors. Emitters deliberately stay
+ * lock-free; this advisory log accepts a possible racing row rather than making
+ * every command wait on a lock. Every error is swallowed so compaction can never
+ * turn `dz deadwood` into a gate.
+ */
+export declare function compactCmdUsageIfNeeded(root: string): void;
+//# sourceMappingURL=cmd-usage.d.ts.map

package/dist/cmd-usage.d.ts.map

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