ushman-ledger 1.2.1 → 1.2.2

package/dist/cli.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import * as v from 'valibot';
+import { readPatchTextFromFile } from "./blobs.js";
 import { openLedger } from "./handle.js";
 import { deriveFilesChangedFromPatch } from "./patch-resolver.js";
 import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord, WorkspaceRelativePathSchema, } from "./schema/entry.js";
@@ -14,6 +15,8 @@ import { LEDGER_LIBRARY_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const DEFAULT_GIT_DIFF_TIMEOUT_MS = 30_000;
+const BOOLEAN_FLAG_NAMES = new Set(['from-stdin', 'help', 'json']);
+const GIT_DIFF_FORMAT_ARGS = ['--no-color', '--no-ext-diff', '--src-prefix=a/', '--dst-prefix=b/'];
 const RENDER_TARGETS = [
     'retro',
     'jsonl',
@@ -54,6 +57,15 @@ const renderValidValues = () => `Valid values:
   note subkinds: ${NoteSubkindSchema.options.join(', ')}
   render targets: ${RENDER_TARGETS.join(', ')}
 `;
+const renderRuntimeTuningHelp = () => `Runtime tuning env vars:
+  USHMAN_LEDGER_SCAN_BATCH_SIZE (default: 32)
+  USHMAN_LEDGER_SCAN_CONCURRENCY (default: 16)
+  USHMAN_LEDGER_READ_INDEX_REBUILD_BATCH_SIZE (default: USHMAN_LEDGER_SCAN_BATCH_SIZE)
+  USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
+  USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
+  USHMAN_LEDGER_BLOB_HASH_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
+  USHMAN_LEDGER_MAX_PATCH_BYTES (default: 10485760)
+`;
 const renderHelp = (commandName) => `${commandName}
 
 Commands:
@@ -64,28 +76,37 @@ Commands:
   ${commandName} tail [--workspace=<ws>] [--phase=<phase>] [--limit=<n>]
   ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
   ${commandName} archive [--workspace=<ws>] --out=<file.tgz>
-  ${commandName} doctor [--workspace=<ws>]
+  ${commandName} doctor [--workspace=<ws>] [--json]
   ${commandName} --version
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
 const renderCommandHelp = (commandName, command) => {
     switch (command) {
         case 'record':
             return `${renderRecordUsage(commandName)}
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
         case 'note':
             return `${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
         case 'list':
             return `${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
         case 'render':
             return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
 
-${renderValidValues()}`;
+${renderValidValues()}
+${renderRuntimeTuningHelp()}`;
+        case 'doctor':
+            return `${commandName} doctor [--workspace=<ws>] [--json]
+
+${renderRuntimeTuningHelp()}`;
         default:
             return renderHelp(commandName);
     }
@@ -111,7 +132,7 @@ const parseArgv = (argv) => {
             continue;
         }
         const next = argv[index + 1];
-        if (!next || next.startsWith('--')) {
+        if (BOOLEAN_FLAG_NAMES.has(name) || !next || next.startsWith('--')) {
             flags[name] = true;
             continue;
         }
@@ -211,11 +232,31 @@ const isGitDiffTimeoutError = (error) => {
         error.killed === true &&
         error.signal === 'SIGTERM');
 };
+const buildGitDiffArgs = (gitOptions, gitRef) => gitOptions.scopedPaths.length === 0
+    ? ['diff', ...GIT_DIFF_FORMAT_ARGS, gitRef]
+    : ['diff', ...GIT_DIFF_FORMAT_ARGS, gitRef, '--', ...gitOptions.scopedPaths];
+const throwGitDiffFailure = ({ error, gitOptions, gitRef, }) => {
+    if (getErrorCode(error) === 'ENOENT') {
+        throw new CliUsageError('git is required for --diff-from-git and was not found in PATH. Install git or use --diff with a patch file.');
+    }
+    if (isGitDiffTimeoutError(error)) {
+        throw new CliUsageError(`git diff ${gitRef} timed out after ${gitOptions.timeoutMs}ms. Narrow the diff or increase --git-diff-timeout-ms.`);
+    }
+    if (isGitDiffMaxBufferError(error)) {
+        throw new CliUsageError(`git diff ${gitRef} exceeded the configured stdout buffer (${gitOptions.maxBufferBytes} bytes). Narrow the diff or increase --git-diff-max-buffer-bytes.`);
+    }
+    const stderr = typeof error === 'object' && error !== null && 'stderr' in error
+        ? String(error.stderr ?? '').trim()
+        : '';
+    if (stderr.length > 0) {
+        throw new CliUsageError(`git diff ${gitRef} failed: ${stderr}`);
+    }
+    throw new CliUsageError(`git diff ${gitRef} failed. Ensure the ref exists and the workspace is a git repository.`);
+};
 const materializeGitDiff = async ({ gitOptions, gitRef, workspaceRoot, }) => {
     let tempDir;
     try {
-        const gitArgs = gitOptions.scopedPaths.length === 0 ? ['diff', gitRef] : ['diff', gitRef, '--', ...gitOptions.scopedPaths];
-        const { stdout } = await execFileAsync('git', gitArgs, {
+        const { stdout } = await execFileAsync('git', buildGitDiffArgs(gitOptions, gitRef), {
             cwd: workspaceRoot,
             maxBuffer: gitOptions.maxBufferBytes,
             timeout: gitOptions.timeoutMs,
@@ -229,16 +270,11 @@ const materializeGitDiff = async ({ gitOptions, gitRef, workspaceRoot, }) => {
         if (tempDir) {
             await rm(tempDir, { force: true, recursive: true });
         }
-        if (getErrorCode(error) === 'ENOENT') {
-            throw new CliUsageError('git is required for --diff-from-git and was not found in PATH.');
-        }
-        if (isGitDiffTimeoutError(error)) {
-            throw new CliUsageError(`git diff ${gitRef} timed out after ${gitOptions.timeoutMs}ms. Narrow the diff or increase --git-diff-timeout-ms.`);
-        }
-        if (isGitDiffMaxBufferError(error)) {
-            throw new CliUsageError(`git diff ${gitRef} exceeded the configured stdout buffer (${gitOptions.maxBufferBytes} bytes). Narrow the diff or increase --git-diff-max-buffer-bytes.`);
-        }
-        throw error;
+        return throwGitDiffFailure({
+            error,
+            gitOptions,
+            gitRef,
+        });
     }
 };
 const parseJsonInput = (text, sourceLabel) => {
@@ -252,6 +288,9 @@ const parseJsonInput = (text, sourceLabel) => {
 const print = (context, text) => {
     context.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
 };
+const printJson = (context, value) => {
+    print(context, JSON.stringify(value, null, 2));
+};
 const parseLimit = (flags) => getFlag(flags, 'limit')
     ? parsePositiveIntegerFlag({
         defaultValue: 0,
@@ -397,7 +436,7 @@ const assertDiffRecordKindSupported = (kind) => {
     }
     throw new CliUsageError('--diff and --diff-from-git are only supported for patch and change-log records.');
 };
-const readPatchText = async (diffPath) => readFile(diffPath, 'utf8');
+const readPatchText = async (diffPath) => readPatchTextFromFile(diffPath);
 const readPatchTextForRecordKind = async (kind, diffPath) => {
     if (kind === 'change-log' || kind === 'agent-patch' || kind === 'operator-patch') {
         return readPatchText(diffPath);
@@ -695,16 +734,22 @@ const runNoteCli = async (parsed, context) => {
 const runListCli = async (parsed, context) => {
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     if (hasFlag(parsed.flags, 'json')) {
-        const entries = [];
+        let wroteEntry = false;
+        context.stdout.write('[\n');
         for await (const entry of ledger.list({
             kind: parseOptionalKind(parsed.flags),
             limit: parseLimit(parsed.flags),
             phase: parseOptionalPhase(parsed.flags),
             since: parseSince(parsed.flags),
         })) {
-            entries.push(entry);
+            if (wroteEntry) {
+                context.stdout.write(',\n');
+            }
+            const renderedEntry = JSON.stringify(entry, null, 2).replaceAll('\n', '\n  ');
+            context.stdout.write(`  ${renderedEntry}`);
+            wroteEntry = true;
         }
-        print(context, JSON.stringify(entries, null, 2));
+        context.stdout.write(wroteEntry ? '\n]\n' : ']\n');
         return 0;
     }
     for await (const entry of ledger.list({
@@ -762,16 +807,29 @@ const runArchiveCli = async (parsed, context) => {
     print(context, result.integrityHash);
     return 0;
 };
+const formatDoctorFinding = (finding) => [`[${finding.code}] ${finding.message}`, `Next step: ${finding.remediation}`].join('\n');
+const printDoctorFindings = (context, report) => {
+    context.stderr.write(`doctor found ${report.issueCount} issue${report.issueCount === 1 ? '' : 's'}.\n`);
+    for (const [index, finding] of report.findings.entries()) {
+        context.stderr.write(`\n${formatDoctorFinding(finding)}`);
+        if (index < report.findings.length - 1) {
+            context.stderr.write('\n');
+        }
+    }
+    context.stderr.write('\n');
+};
 const runDoctorCli = async (parsed, context) => {
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const result = await ledger.doctor();
+    if (hasFlag(parsed.flags, 'json')) {
+        printJson(context, result);
+        return result.ok ? 0 : 1;
+    }
     if (result.ok) {
         print(context, 'ok');
         return 0;
     }
-    for (const issue of result.issues) {
-        context.stderr.write(`${issue}\n`);
-    }
+    printDoctorFindings(context, result);
     return 1;
 };
 const formatCliError = (error) => {
@@ -787,7 +845,7 @@ const formatCliError = (error) => {
         })
             .join('\n');
     }
-    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+    return error instanceof Error ? error.message : String(error);
 };
 export const runLedgerCli = async (argv, context = {}) => {
     const mergedContext = { ...DEFAULT_CONTEXT, ...context };

package/dist/coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAgGA,MAAM,MAAM,cAAc,GAAG;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAgDnF,CAAC"}
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AA+FA,MAAM,MAAM,cAAc,GAAG;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAiDnF,CAAC"}

package/dist/coverage.js

@@ -4,10 +4,10 @@ import { mapWithConcurrencyLimit } from "./async.js";
 import { CANDIDATE_EXCLUDE_GLOBS, CANDIDATE_FILE_GLOBS } from "./candidate-paths.js";
 import { readLabManifestMin } from "./lab-min.js";
 import { loadLedgerState } from "./recovery.js";
+import { getLedgerRuntimeConfig } from "./runtime-config.js";
 const EXCLUDED_ROOTS = new Set(CANDIDATE_EXCLUDE_GLOBS.map((glob) => glob.replace(/\/\*\*$/u, '')));
 const CANDIDATE_DIRECTORIES = CANDIDATE_FILE_GLOBS.filter((glob) => glob.endsWith('/**/*')).map((glob) => glob.slice(0, -5));
 const CANDIDATE_FILES = CANDIDATE_FILE_GLOBS.filter((glob) => !glob.endsWith('/**/*'));
-const FILE_STAT_CONCURRENCY = 16;
 const toPosix = (value) => value.replaceAll(path.sep, '/');
 const isMissingPathError = (error) => {
     const code = error.code;
@@ -85,13 +85,14 @@ const getWorkspaceInitMs = async (workspaceRoot) => {
     return labManifestStat.birthtimeMs || labManifestStat.mtimeMs;
 };
 export const computeCoverage = async (workspaceRoot) => {
+    const { coverageFileStatConcurrency } = getLedgerRuntimeConfig();
     const [{ readIndex }, candidateFiles, workspaceInitMs] = await Promise.all([
         loadLedgerState(workspaceRoot),
         collectCandidateFiles(workspaceRoot),
         getWorkspaceInitMs(workspaceRoot),
     ]);
     const coverageIndex = new Set(readIndex.coveredFiles.map((filePath) => toPosix(filePath)));
-    const candidateStats = await mapWithConcurrencyLimit(candidateFiles, FILE_STAT_CONCURRENCY, async (relativePath) => {
+    const candidateStats = await mapWithConcurrencyLimit(candidateFiles, coverageFileStatConcurrency, async (relativePath) => {
         try {
             return {
                 mtimeMs: (await stat(path.join(workspaceRoot, relativePath))).mtimeMs,

package/dist/doctor.d.ts

@@ -1,9 +1,22 @@
 import { type PreparedLedgerState } from './recovery.ts';
+export declare const DOCTOR_FINDING_CODES: readonly ["blob-corrupt", "blob-missing", "blob-unreadable", "change-log-rollback-missing-target", "change-log-smoke-failure-missing-rollback-plan", "manifest-entry-count-mismatch", "manifest-entry-location-missing", "manifest-entry-missing-on-disk", "manifest-last-sequence-mismatch", "manifest-per-phase-latest-mismatch", "manifest-phase-mismatch", "manifest-sequence-mismatch", "open-issue-stale", "phase-prev-entry-mismatch", "pre-change-checkpoint-stale", "read-failure"];
+export type DoctorFindingCode = (typeof DOCTOR_FINDING_CODES)[number];
+export type DoctorFindingMetadataValue = boolean | null | number | string;
+export type DoctorFinding = {
+    readonly code: DoctorFindingCode;
+    readonly message: string;
+    readonly metadata?: Record<string, DoctorFindingMetadataValue>;
+    readonly remediation: string;
+};
+export type DoctorReport = {
+    readonly checkedAt: string;
+    readonly findings: DoctorFinding[];
+    readonly issueCount: number;
+    readonly issues: string[];
+    readonly ok: boolean;
+};
 export declare const runLedgerDoctor: (workspaceRoot: string, options?: {
     readonly skipPrepare?: boolean;
     readonly state?: PreparedLedgerState;
-}) => Promise<{
-    issues: string[];
-    ok: boolean;
-}>;
+}) => Promise<DoctorReport>;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AA+V1E,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO;;;EAyCzF,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAS1E,eAAO,MAAM,oBAAoB,8dAiBvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,0BAA0B,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,aAAa,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACxB,CAAC;AAqjBF,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO,KACvF,OAAO,CAAC,YAAY,CAqCtB,CAAC"}