ushman-characterize 0.4.0

package/dist/instrument.js

@@ -0,0 +1,605 @@
+import path from 'node:path';
+import generate from '@babel/generator';
+import traverse, {} from '@babel/traverse';
+import * as t from '@babel/types';
+import { parseModuleAst } from "./babel-config.js";
+import { TRACE_RUNTIME_VERSION } from "./constants.js";
+import { getAnonymousDefaultExportBindingName } from "./default-export.js";
+import { isTrivialGetterLike } from "./function-utils.js";
+const MARKER = 'ushman-characterize:instrumented';
+const GENERATED_MARKER = '__ushmanCharacterizeGenerated';
+const SOURCE_MAP_COMMENT_PREFIXES = ['# sourceMappingURL=', '@ sourceMappingURL='];
+const TRACE_AWAIT_HELPER_NAME = '__ushmanTraceAwait';
+const assertSourceMapMode = (mode) => {
+    if (mode === 'external' || mode === 'inline' || mode === 'off') {
+        return;
+    }
+    throw new Error(`Unsupported sourceMapMode "${mode}". Use "external", "inline", or "off".`);
+};
+const helperTemplates = parseModuleAst({
+    source: `
+async function ${TRACE_AWAIT_HELPER_NAME}(callId, value) {
+  // Native await suspends outside our wrapper body, so we temporarily leave the
+  // sync stack and restore the same call id when the awaited work resumes.
+  const tracer = globalThis.__USHMAN_TRACER__;
+  tracer?.leaveSyncFrame?.(callId);
+  try {
+    return await value;
+  } finally {
+    tracer?.enterAsyncFrame?.(callId);
+  }
+}
+
+function __ushmanTraceInvoke(meta, args, thisArg, fn, passCallId) {
+  const tracer = globalThis.__USHMAN_TRACER__;
+  if (!tracer) {
+    return fn.apply(thisArg, args);
+  }
+  const callId = tracer.enter(meta, args, thisArg);
+  let result;
+  try {
+    if (passCallId) {
+      tracer.pushInvocationCallId?.(callId);
+    }
+    result = fn.apply(thisArg, args);
+  } catch (error) {
+    tracer.exit(callId, undefined, error);
+    throw error;
+  } finally {
+    if (passCallId) {
+      tracer.popInvocationCallId?.(callId);
+    }
+  }
+  if (result && typeof result.then === 'function') {
+    // Async wrappers hand control to ${TRACE_AWAIT_HELPER_NAME} at each await,
+    // but promise-returning functions with no explicit await still need one
+    // sync-to-async handoff here so later resolution exits the right call.
+    tracer.leaveSyncFrame?.(callId);
+    return result.then(
+      (value) => {
+        tracer.exit(callId, value, undefined);
+        return value;
+      },
+      (error) => {
+        tracer.exit(callId, undefined, error);
+        throw error;
+      },
+    );
+  }
+  tracer.exit(callId, result, undefined);
+  return result;
+}
+`,
+    sourcePath: `inline://${TRACE_RUNTIME_VERSION}/instrument-helper.ts`,
+}).program.body;
+const createMetaLiteral = ({ bindingName, className, functionName, memberKind, methodName, }) => t.objectExpression([
+    t.objectProperty(t.identifier('bindingName'), t.stringLiteral(bindingName)),
+    t.objectProperty(t.identifier('className'), className ? t.stringLiteral(className) : t.nullLiteral()),
+    t.objectProperty(t.identifier('functionName'), t.stringLiteral(functionName)),
+    t.objectProperty(t.identifier('memberKind'), t.stringLiteral(memberKind)),
+    t.objectProperty(t.identifier('methodName'), methodName ? t.stringLiteral(methodName) : t.nullLiteral()),
+]);
+const isGeneratedFunction = (path) => Boolean(path.node[GENERATED_MARKER]);
+const isGeneratedVariableDeclaration = (path) => Boolean(path.node[GENERATED_MARKER]);
+const isSourceMapComment = (comment) => SOURCE_MAP_COMMENT_PREFIXES.some((prefix) => comment.value.trimStart().startsWith(prefix));
+const stripSourceMapComments = (ast) => {
+    ast.comments = ast.comments?.filter((comment) => !isSourceMapComment(comment)) ?? [];
+    traverse(ast, {
+        enter(path) {
+            path.node.leadingComments = path.node.leadingComments?.filter((comment) => !isSourceMapComment(comment));
+            path.node.innerComments = path.node.innerComments?.filter((comment) => !isSourceMapComment(comment));
+            path.node.trailingComments = path.node.trailingComments?.filter((comment) => !isSourceMapComment(comment));
+        },
+    });
+};
+const isSkippableFunctionLike = ({ body, generator, params, }) => generator || isTrivialGetterLike({ body, params });
+const toFunctionBody = (body) => t.isBlockStatement(body) ? t.cloneNode(body, true) : t.blockStatement([t.returnStatement(t.cloneNode(body, true))]);
+const createHelperParams = ({ params, }) => params.map((parameter) => t.cloneNode(parameter, true));
+const createTraceCallIdDeclaration = (callIdId) => {
+    const statement = parseModuleAst({
+        source: `const ${callIdId.name} = globalThis.__USHMAN_TRACER__?.peekInvocationCallId?.();`,
+        sourcePath: `inline://${TRACE_RUNTIME_VERSION}/instrument-call-id.ts`,
+    }).program.body[0];
+    if (!statement || !t.isVariableDeclaration(statement)) {
+        throw new Error('Failed to build the async call id declaration template.');
+    }
+    return statement;
+};
+const wrapAwaitArgument = ({ argument, callIdId, }) => t.callExpression(t.identifier(TRACE_AWAIT_HELPER_NAME), [t.cloneNode(callIdId), argument]);
+const createHelperBody = ({ async, body, callIdId, }) => {
+    if (!async) {
+        return t.cloneNode(body, true);
+    }
+    if (!callIdId) {
+        throw new Error('Async helper bodies require a generated call id identifier.');
+    }
+    const rootFunction = t.functionExpression(null, [], t.cloneNode(body, true), false, true);
+    rootFunction.body.body.unshift(createTraceCallIdDeclaration(callIdId));
+    const file = t.file(t.program([t.expressionStatement(rootFunction)]));
+    traverse(file, {
+        AwaitExpression(path) {
+            path.replaceWith(t.awaitExpression(wrapAwaitArgument({
+                argument: t.cloneNode(path.node.argument, true),
+                callIdId,
+            })));
+            path.skip();
+        },
+        Function(path) {
+            if (path.node !== rootFunction) {
+                path.skip();
+            }
+        },
+    });
+    return file.program.body[0].expression.body;
+};
+const createOriginalVariableInitializer = ({ callIdId, init, }) => {
+    const helperParams = createHelperParams({
+        params: init.params,
+    });
+    const helperBody = createHelperBody({
+        async: init.async,
+        body: toFunctionBody(init.body),
+        callIdId,
+    });
+    if (t.isArrowFunctionExpression(init)) {
+        return t.arrowFunctionExpression(helperParams, helperBody, init.async);
+    }
+    return t.functionExpression(init.id ? t.cloneNode(init.id, true) : null, helperParams, helperBody, init.generator, init.async);
+};
+const buildVariableWrapperInitializer = ({ helperId, init, symbolName, }) => {
+    const argsId = t.identifier('__ushmanArgs');
+    const traceInvoke = t.callExpression(t.identifier('__ushmanTraceInvoke'), [
+        createMetaLiteral({
+            bindingName: symbolName,
+            className: null,
+            functionName: symbolName,
+            memberKind: 'function',
+            methodName: null,
+        }),
+        argsId,
+        t.isArrowFunctionExpression(init) ? t.identifier('undefined') : t.thisExpression(),
+        helperId,
+        t.booleanLiteral(init.async),
+    ]);
+    if (t.isArrowFunctionExpression(init)) {
+        return t.arrowFunctionExpression([t.restElement(argsId)], traceInvoke, false);
+    }
+    return t.functionExpression(null, [t.restElement(argsId)], t.blockStatement([t.returnStatement(traceInvoke)]), false, false);
+};
+const flushVariableStatement = ({ declarators, exportNamed, kind, statements, }) => {
+    if (declarators.length === 0) {
+        return;
+    }
+    const declaration = t.variableDeclaration(kind, declarators);
+    statements.push(exportNamed ? t.exportNamedDeclaration(declaration) : declaration);
+};
+const instrumentTopLevelClassExpression = ({ className, instrumentedSymbols, skippedSymbols, variableDeclaratorPath, }) => {
+    const initPath = variableDeclaratorPath.get('init');
+    if (!initPath.isClassExpression()) {
+        return;
+    }
+    for (const memberPath of initPath.get('body.body')) {
+        if (!memberPath.isClassMethod()) {
+            continue;
+        }
+        instrumentClassMethod({
+            className,
+            instrumentedSymbols,
+            memberPath,
+            skippedSymbols,
+        });
+    }
+};
+const getInstrumentableVariableInit = (declarator) => {
+    if (!t.isIdentifier(declarator.id) || !declarator.init) {
+        return null;
+    }
+    if (!t.isArrowFunctionExpression(declarator.init) && !t.isFunctionExpression(declarator.init)) {
+        return null;
+    }
+    return declarator.init;
+};
+const shouldSkipVariableDeclarator = ({ declarator: _declarator, init, }) => isSkippableFunctionLike({
+    body: toFunctionBody(init.body),
+    generator: t.isFunctionExpression(init) ? init.generator : false,
+    params: init.params,
+});
+const createInstrumentedVariableStatements = ({ declarationPath, exportNamed, init, symbolName, }) => {
+    const helperId = declarationPath.scope.generateUidIdentifier(`ushmanOriginal_${symbolName}`);
+    const callIdId = init.async ? declarationPath.scope.generateUidIdentifier('ushmanTraceCallId') : undefined;
+    const helperDeclaration = t.variableDeclaration('const', [
+        t.variableDeclarator(helperId, createOriginalVariableInitializer({
+            callIdId,
+            init,
+        })),
+    ]);
+    helperDeclaration[GENERATED_MARKER] = true;
+    const wrapperDeclaration = t.variableDeclaration(declarationPath.node.kind, [
+        t.variableDeclarator(t.identifier(symbolName), buildVariableWrapperInitializer({
+            helperId,
+            init,
+            symbolName,
+        })),
+    ]);
+    wrapperDeclaration[GENERATED_MARKER] = true;
+    return [helperDeclaration, exportNamed ? t.exportNamedDeclaration(wrapperDeclaration) : wrapperDeclaration];
+};
+const createInstrumentedDefaultExportStatements = ({ exportPath, init, symbolName, }) => {
+    const helperId = exportPath.scope.generateUidIdentifier(`ushmanOriginal_${symbolName}`);
+    const callIdId = init.async ? exportPath.scope.generateUidIdentifier('ushmanTraceCallId') : undefined;
+    const helperDeclaration = t.variableDeclaration('const', [
+        t.variableDeclarator(helperId, createOriginalVariableInitializer({
+            callIdId,
+            init,
+        })),
+    ]);
+    helperDeclaration[GENERATED_MARKER] = true;
+    const wrapperDeclaration = t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier(symbolName), buildVariableWrapperInitializer({
+            helperId,
+            init,
+            symbolName,
+        })),
+    ]);
+    wrapperDeclaration[GENERATED_MARKER] = true;
+    return [helperDeclaration, wrapperDeclaration, t.exportDefaultDeclaration(t.identifier(symbolName))];
+};
+const instrumentTopLevelVariableDeclaration = ({ declarationPath, instrumentedSymbols, skippedSymbols, }) => {
+    if (isGeneratedVariableDeclaration(declarationPath)) {
+        return;
+    }
+    const parent = declarationPath.parentPath;
+    const exportNamed = parent.isExportNamedDeclaration() && parent.parentPath?.isProgram();
+    const isTopLevel = parent.isProgram() || exportNamed;
+    if (!isTopLevel) {
+        return;
+    }
+    const replacementStatements = [];
+    const untouchedDeclarators = [];
+    let changed = false;
+    for (const declarator of declarationPath.node.declarations) {
+        const declaratorPath = declarationPath
+            .get('declarations')
+            .find((candidatePath) => candidatePath.node === declarator);
+        if (declaratorPath && t.isIdentifier(declarator.id) && t.isClassExpression(declarator.init)) {
+            instrumentTopLevelClassExpression({
+                className: declarator.id.name,
+                instrumentedSymbols,
+                skippedSymbols,
+                variableDeclaratorPath: declaratorPath,
+            });
+            untouchedDeclarators.push(t.cloneNode(declarator, true));
+            continue;
+        }
+        const init = getInstrumentableVariableInit(declarator);
+        if (!init || !t.isIdentifier(declarator.id)) {
+            untouchedDeclarators.push(t.cloneNode(declarator, true));
+            continue;
+        }
+        if (shouldSkipVariableDeclarator({
+            declarator: declarator,
+            init,
+        })) {
+            skippedSymbols.push(declarator.id.name);
+            untouchedDeclarators.push(t.cloneNode(declarator, true));
+            continue;
+        }
+        changed = true;
+        flushVariableStatement({
+            declarators: untouchedDeclarators.splice(0, untouchedDeclarators.length),
+            exportNamed: Boolean(exportNamed),
+            kind: declarationPath.node.kind,
+            statements: replacementStatements,
+        });
+        replacementStatements.push(...createInstrumentedVariableStatements({
+            declarationPath,
+            exportNamed: Boolean(exportNamed),
+            init,
+            symbolName: declarator.id.name,
+        }));
+        instrumentedSymbols.push(declarator.id.name);
+    }
+    if (!changed) {
+        return;
+    }
+    flushVariableStatement({
+        declarators: untouchedDeclarators,
+        exportNamed: Boolean(exportNamed),
+        kind: declarationPath.node.kind,
+        statements: replacementStatements,
+    });
+    if (exportNamed) {
+        parent.replaceWithMultiple(replacementStatements);
+        parent.skip();
+        return;
+    }
+    declarationPath.replaceWithMultiple(replacementStatements);
+    declarationPath.skip();
+};
+const hasUnsafeMethodFeatures = (path) => {
+    let unsafe = false;
+    path.traverse({
+        PrivateName(inner) {
+            unsafe = true;
+            inner.stop();
+        },
+        Super(inner) {
+            unsafe = true;
+            inner.stop();
+        },
+    });
+    return unsafe;
+};
+const createOriginalFunctionExpression = ({ async, body, callIdId, generator, params, }) => t.functionExpression(null, createHelperParams({
+    params,
+}), createHelperBody({
+    async,
+    body,
+    callIdId,
+}), generator, async);
+const instrumentClassMethod = ({ className, instrumentedSymbols, memberPath, skippedSymbols, }) => {
+    const methodName = t.isIdentifier(memberPath.node.key) && !memberPath.node.computed ? memberPath.node.key.name : null;
+    if (!methodName) {
+        return;
+    }
+    const displayName = `${className}.${methodName}`;
+    if (memberPath.node.kind !== 'method' || hasUnsafeMethodFeatures(memberPath)) {
+        skippedSymbols.push(displayName);
+        return;
+    }
+    if (isSkippableFunctionLike(memberPath.node)) {
+        skippedSymbols.push(displayName);
+        return;
+    }
+    const isAsync = memberPath.node.async;
+    const helperId = memberPath.scope.generateUidIdentifier(`ushmanOriginal_${className}_${methodName}`);
+    const callIdId = isAsync ? memberPath.scope.generateUidIdentifier('ushmanTraceCallId') : undefined;
+    const helper = t.variableDeclaration('const', [
+        t.variableDeclarator(helperId, createOriginalFunctionExpression({
+            async: isAsync,
+            body: memberPath.node.body,
+            callIdId,
+            generator: memberPath.node.generator,
+            params: memberPath.node.params,
+        })),
+    ]);
+    memberPath.node.async = false;
+    memberPath.node.generator = false;
+    memberPath.node.params = [t.restElement(t.identifier('__ushmanArgs'))];
+    memberPath.node.body = t.blockStatement([
+        helper,
+        t.returnStatement(t.callExpression(t.identifier('__ushmanTraceInvoke'), [
+            createMetaLiteral({
+                bindingName: className,
+                className,
+                functionName: displayName,
+                memberKind: 'method',
+                methodName,
+            }),
+            t.identifier('__ushmanArgs'),
+            t.thisExpression(),
+            helperId,
+            t.booleanLiteral(isAsync),
+        ])),
+    ]);
+    instrumentedSymbols.push(displayName);
+};
+const createInstrumentedFunctionReplacement = ({ callIdId, className, functionName, originalFunction, }) => {
+    const helperId = t.identifier(`__ushmanOriginal_${functionName}`);
+    const helper = t.functionDeclaration(helperId, createHelperParams({
+        params: originalFunction.params,
+    }), createHelperBody({
+        async: originalFunction.async,
+        body: originalFunction.body,
+        callIdId,
+    }), originalFunction.generator, originalFunction.async);
+    helper.leadingComments = [{ type: 'CommentBlock', value: ` ${MARKER} ` }];
+    helper[GENERATED_MARKER] = true;
+    const wrapper = t.functionDeclaration(t.identifier(functionName), [t.restElement(t.identifier('__ushmanArgs'))], t.blockStatement([
+        t.returnStatement(t.callExpression(t.identifier('__ushmanTraceInvoke'), [
+            createMetaLiteral({
+                bindingName: functionName,
+                className,
+                functionName,
+                memberKind: 'function',
+                methodName: null,
+            }),
+            t.identifier('__ushmanArgs'),
+            t.thisExpression(),
+            helperId,
+            t.booleanLiteral(originalFunction.async),
+        ])),
+    ]), false, false);
+    wrapper[GENERATED_MARKER] = true;
+    return {
+        helper,
+        wrapper,
+    };
+};
+const instrumentTopLevelFunction = ({ anonymousDefaultExportBindingName, instrumentedSymbols, path, skippedSymbols, }) => {
+    if (isGeneratedFunction(path)) {
+        return;
+    }
+    const parent = path.parentPath;
+    const isTopLevel = parent.isProgram() ||
+        ((parent.isExportNamedDeclaration() || parent.isExportDefaultDeclaration()) && parent.parentPath?.isProgram());
+    const functionName = path.node.id?.name ??
+        (parent.isExportDefaultDeclaration() && parent.parentPath?.isProgram()
+            ? anonymousDefaultExportBindingName
+            : undefined);
+    if (!functionName || !isTopLevel) {
+        return;
+    }
+    if (isSkippableFunctionLike(path.node)) {
+        skippedSymbols.push(functionName);
+        return;
+    }
+    const replacement = createInstrumentedFunctionReplacement({
+        callIdId: path.node.async ? path.scope.generateUidIdentifier('ushmanTraceCallId') : undefined,
+        className: null,
+        functionName,
+        originalFunction: path.node,
+    });
+    if (parent.isExportNamedDeclaration()) {
+        parent.replaceWithMultiple([replacement.helper, t.exportNamedDeclaration(replacement.wrapper)]);
+        parent.skip();
+    }
+    else if (parent.isExportDefaultDeclaration()) {
+        parent.replaceWithMultiple([replacement.helper, t.exportDefaultDeclaration(replacement.wrapper)]);
+        parent.skip();
+    }
+    else {
+        path.replaceWithMultiple([replacement.helper, replacement.wrapper]);
+        path.skip();
+    }
+    instrumentedSymbols.push(functionName);
+};
+const instrumentAnonymousDefaultExportExpression = ({ anonymousDefaultExportBindingName, exportPath, instrumentedSymbols, skippedSymbols, }) => {
+    const declarationPath = exportPath.get('declaration');
+    if (!anonymousDefaultExportBindingName) {
+        return;
+    }
+    if (!declarationPath.isArrowFunctionExpression() && !declarationPath.isFunctionExpression()) {
+        return;
+    }
+    if (isSkippableFunctionLike({
+        body: toFunctionBody(declarationPath.node.body),
+        generator: declarationPath.isFunctionExpression() ? declarationPath.node.generator : false,
+        params: declarationPath.node.params,
+    })) {
+        skippedSymbols.push(anonymousDefaultExportBindingName);
+        return;
+    }
+    exportPath.replaceWithMultiple(createInstrumentedDefaultExportStatements({
+        exportPath,
+        init: declarationPath.node,
+        symbolName: anonymousDefaultExportBindingName,
+    }));
+    exportPath.skip();
+    instrumentedSymbols.push(anonymousDefaultExportBindingName);
+};
+/**
+ * Instrument a bundle source string with the characterization tracer wrappers.
+ */
+export const instrumentBundleSource = ({ source, sourceMapFile, sourceMapMode = 'off', sourcePath, }) => {
+    assertSourceMapMode(sourceMapMode);
+    if (source.includes(MARKER)) {
+        return {
+            code: source,
+            instrumentedSymbols: [],
+            map: null,
+            skippedSymbols: [],
+        };
+    }
+    if (helperTemplates.length === 0 || helperTemplates.some((statement) => !t.isFunctionDeclaration(statement))) {
+        throw new Error('Failed to build the characterization helper template.');
+    }
+    const ast = parseModuleAst({
+        source,
+        sourcePath,
+    });
+    stripSourceMapComments(ast);
+    const anonymousDefaultExportBindingName = getAnonymousDefaultExportBindingName(ast.program.body) ?? undefined;
+    const instrumentedSymbols = [];
+    const skippedSymbols = [];
+    traverse(ast, {
+        ClassDeclaration(path) {
+            const className = path.node.id?.name;
+            if (!className) {
+                return;
+            }
+            for (const memberPath of path.get('body.body')) {
+                if (!memberPath.isClassMethod()) {
+                    continue;
+                }
+                instrumentClassMethod({
+                    className,
+                    instrumentedSymbols,
+                    memberPath,
+                    skippedSymbols,
+                });
+            }
+        },
+        ExportDefaultDeclaration(path) {
+            instrumentAnonymousDefaultExportExpression({
+                anonymousDefaultExportBindingName,
+                exportPath: path,
+                instrumentedSymbols,
+                skippedSymbols,
+            });
+        },
+        FunctionDeclaration(path) {
+            instrumentTopLevelFunction({
+                anonymousDefaultExportBindingName,
+                instrumentedSymbols,
+                path,
+                skippedSymbols,
+            });
+        },
+        VariableDeclaration(path) {
+            instrumentTopLevelVariableDeclaration({
+                declarationPath: path,
+                instrumentedSymbols,
+                skippedSymbols,
+            });
+        },
+    });
+    const helperNodes = helperTemplates.map((statement, index) => {
+        const helperNode = t.cloneNode(statement, true);
+        helperNode.leadingComments = index === 0 ? [{ type: 'CommentBlock', value: ` ${MARKER} ` }] : [];
+        helperNode[GENERATED_MARKER] = true;
+        return helperNode;
+    });
+    ast.program.body.unshift(...helperNodes);
+    const generated = generate(ast, {
+        comments: true,
+        compact: false,
+        sourceFileName: sourcePath,
+        sourceMaps: sourceMapMode !== 'off',
+    }, source);
+    const map = generated.map ?? null;
+    if (sourceMapMode === 'inline' && map) {
+        const inlinePayload = Buffer.from(JSON.stringify(map), 'utf8').toString('base64');
+        return {
+            code: `${generated.code}\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${inlinePayload}`,
+            instrumentedSymbols,
+            map,
+            skippedSymbols,
+        };
+    }
+    if (sourceMapMode === 'external' && map) {
+        const mappingUrl = sourceMapFile ? path.basename(sourceMapFile) : `${path.basename(sourcePath)}.map`;
+        return {
+            code: `${generated.code}\n//# sourceMappingURL=${mappingUrl}`,
+            instrumentedSymbols,
+            map,
+            skippedSymbols,
+        };
+    }
+    return {
+        code: generated.code,
+        instrumentedSymbols,
+        map,
+        skippedSymbols,
+    };
+};
+export const instrumentBundle = async ({ bundlePath, outputPath, sourceMapMode = 'external', }) => {
+    assertSourceMapMode(sourceMapMode);
+    const source = await Bun.file(bundlePath).text();
+    const mapPath = sourceMapMode === 'external' ? `${outputPath}.map` : null;
+    const result = instrumentBundleSource({
+        source,
+        sourceMapFile: mapPath ?? undefined,
+        sourceMapMode,
+        sourcePath: bundlePath,
+    });
+    await Bun.write(outputPath, `${result.code.trimEnd()}\n`);
+    if (mapPath && result.map) {
+        await Bun.write(mapPath, `${JSON.stringify(result.map, null, 2)}\n`);
+    }
+    return {
+        ...result,
+        mapPath,
+        outputPath,
+    };
+};

package/dist/ledger.d.ts

@@ -0,0 +1,19 @@
+export declare const writeCharacterizeReport: ({ payload, prefix, workspaceRoot, }: {
+    readonly payload: unknown;
+    readonly prefix: string;
+    readonly workspaceRoot: string;
+}) => Promise<string>;
+export declare const recordCharacterizeValidatorResult: ({ affectedFiles, metrics, resultPath, summary, verdict, workspaceRoot, }: {
+    readonly affectedFiles?: readonly string[];
+    readonly metrics?: Record<string, unknown>;
+    readonly resultPath?: string;
+    readonly summary: string;
+    readonly verdict: "green" | "red" | "yellow";
+    readonly workspaceRoot: string;
+}) => Promise<void>;
+export declare const recordCharacterizeToolingGap: ({ body, summary, workspaceRoot, }: {
+    readonly body: string;
+    readonly summary: string;
+    readonly workspaceRoot: string;
+}) => Promise<void>;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,uBAAuB,GAAU,qCAI3C;IACC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,oBAMA,CAAC;AAEF,eAAO,MAAM,iCAAiC,GAAU,0EAOrD;IACC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,kBAiBA,CAAC;AAEF,eAAO,MAAM,4BAA4B,GAAU,mCAIhD;IACC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,kBAOA,CAAC"}

package/dist/ledger.js

@@ -0,0 +1,50 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { buildValidatorResultRecord, openLedger } from '@ushman/ledger';
+import { nowIso } from "./time.js";
+import { workspaceHarnessPaths } from "./trace-format.js";
+const sanitizeTimestamp = (value) => value.replace(/[:.]/gu, '-');
+let cachedPackageVersion = null;
+const readPackageVersion = async () => {
+    if (!cachedPackageVersion) {
+        cachedPackageVersion = (async () => {
+            const packageJsonPath = new URL('../package.json', import.meta.url);
+            const packageJson = (await Bun.file(packageJsonPath).json());
+            return typeof packageJson.version === 'string' && packageJson.version.length > 0
+                ? packageJson.version
+                : '0.0.0';
+        })();
+    }
+    return cachedPackageVersion;
+};
+export const writeCharacterizeReport = async ({ payload, prefix, workspaceRoot, }) => {
+    const harnessPaths = workspaceHarnessPaths(workspaceRoot);
+    await mkdir(harnessPaths.reportsDir, { recursive: true });
+    const reportPath = path.join(harnessPaths.reportsDir, `${prefix}-${sanitizeTimestamp(nowIso())}.json`);
+    await Bun.write(reportPath, `${JSON.stringify(payload, null, 2)}\n`);
+    return reportPath;
+};
+export const recordCharacterizeValidatorResult = async ({ affectedFiles, metrics, resultPath, summary, verdict, workspaceRoot, }) => {
+    const ledger = await openLedger(workspaceRoot);
+    await ledger.record(buildValidatorResultRecord({
+        emitter: {
+            tool: '@ushman/characterize',
+            version: await readPackageVersion(),
+        },
+        links: affectedFiles && affectedFiles.length > 0 ? { affectedFiles: [...affectedFiles] } : undefined,
+        metrics,
+        phase: 'characterize',
+        resultPath,
+        summary,
+        validator: 'characterize',
+        verdict,
+    }));
+};
+export const recordCharacterizeToolingGap = async ({ body, summary, workspaceRoot, }) => {
+    const ledger = await openLedger(workspaceRoot);
+    await ledger.note('tooling-gap', {
+        body,
+        phase: 'characterize',
+        summary,
+    });
+};