@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/scripts/lib/review-execution-telemetry.js

@@ -0,0 +1,215 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export function deriveReviewOutcomeDisposition(options) {
+    if (options.status === 'succeeded') {
+        return options.terminationBoundary ? 'bounded-success' : 'clean-success';
+    }
+    return options.terminationBoundary ? 'failed-boundary' : 'failed-other';
+}
+export function coerceReviewOutcomeDisposition(value) {
+    switch (value) {
+        case 'clean-success':
+        case 'bounded-success':
+        case 'failed-boundary':
+        case 'failed-other':
+            return value;
+        default:
+            return null;
+    }
+}
+export function resolveReviewOutcomeDisposition(payload) {
+    const derivedDisposition = deriveReviewOutcomeDisposition({
+        status: payload.status,
+        terminationBoundary: payload.termination_boundary
+    });
+    const explicitDisposition = coerceReviewOutcomeDisposition(payload.review_outcome ?? null);
+    return explicitDisposition === derivedDisposition ? explicitDisposition : derivedDisposition;
+}
+export function formatReviewOutcomeSummary(payload) {
+    const disposition = resolveReviewOutcomeDisposition(payload);
+    const boundaryKind = payload.termination_boundary?.kind ?? null;
+    switch (disposition) {
+        case 'clean-success':
+            return 'clean success';
+        case 'bounded-success':
+            return boundaryKind
+                ? `bounded success via ${boundaryKind}; not a wrapper failure`
+                : 'bounded success with preserved termination boundary; not a wrapper failure';
+        case 'failed-boundary':
+            return boundaryKind
+                ? `review-wrapper failure via ${boundaryKind}`
+                : 'review-wrapper failure via explicit termination boundary';
+        case 'failed-other':
+            return 'review command failed without termination-boundary classification; not an explicit wrapper-boundary failure';
+    }
+}
+export function buildReviewTelemetryPayload(options) {
+    const terminationBoundary = sanitizeTerminationBoundaryForPersistence(options.terminationBoundary ?? null, options.includeRawTelemetry, options.telemetryDebugEnvKey);
+    return {
+        version: 1,
+        generated_at: new Date().toISOString(),
+        status: options.status,
+        review_outcome: deriveReviewOutcomeDisposition({
+            status: options.status,
+            terminationBoundary
+        }),
+        error: sanitizeTelemetryErrorForPersistence(options.error ?? null, options.includeRawTelemetry, options.telemetryDebugEnvKey),
+        output_log_path: path.relative(options.repoRoot, options.outputLogPath),
+        launch_context: options.launchContext ?? null,
+        termination_boundary: terminationBoundary,
+        summary: sanitizeTelemetrySummaryForPersistence(options.summary, options.includeRawTelemetry, options.telemetryDebugEnvKey)
+    };
+}
+export async function persistReviewTelemetry(options) {
+    await writeFile(options.telemetryPath, `${JSON.stringify(options.payload, null, 2)}\n`, 'utf8');
+    return options.payload;
+}
+export async function writeReviewExecutionTelemetry(options) {
+    try {
+        const payloadOptions = {
+            status: options.status,
+            error: options.error ?? null,
+            outputLogPath: options.outputLogPath,
+            repoRoot: options.repoRoot,
+            includeRawTelemetry: options.includeRawTelemetry,
+            telemetryDebugEnvKey: options.telemetryDebugEnvKey,
+            launchContext: options.launchContext ?? null
+        };
+        if (Object.prototype.hasOwnProperty.call(options, 'terminationBoundary')) {
+            payloadOptions.terminationBoundary = options.terminationBoundary;
+        }
+        const payload = options.state.buildTelemetryPayload(payloadOptions);
+        return await persistReviewTelemetry({
+            payload,
+            telemetryPath: options.telemetryPath
+        });
+    }
+    catch (telemetryError) {
+        const telemetryMessage = telemetryError instanceof Error ? telemetryError.message : String(telemetryError);
+        const logPersistFailure = options.logPersistFailure ??
+            ((message) => {
+                console.error(`[run-review] failed to persist review telemetry: ${message}`);
+            });
+        logPersistFailure(telemetryMessage);
+        return null;
+    }
+}
+export function logReviewTelemetrySummary(payload, telemetryPath, options) {
+    const summary = payload.summary;
+    console.error(`[run-review] review outcome: ${formatReviewOutcomeSummary(payload)}.`);
+    console.error(`[run-review] review telemetry: ${summary.commandStarts.length} command start(s), ${summary.heavyCommandStarts.length} heavy command start(s), ${summary.startupEvents} delegation startup event(s), ${summary.reviewProgressSignals} review progress signal(s).`);
+    if (summary.commandIntentViolationCount > 0) {
+        console.error(`[run-review] command-intent violations detected: ${summary.commandIntentViolationCount} sample(s) across ${summary.commandIntentViolationKinds.join(', ')}.`);
+    }
+    if (payload.termination_boundary) {
+        console.error(`[run-review] termination boundary: ${payload.termination_boundary.kind} (${payload.termination_boundary.provenance}).`);
+    }
+    const lastCommand = summary.commandStarts.at(-1);
+    if (lastCommand) {
+        if (options.debugTelemetry) {
+            console.error(`[run-review] last command started: ${lastCommand}`);
+        }
+        else {
+            console.error(`[run-review] last command started: [redacted] (set ${options.telemetryDebugEnvKey}=1 to print raw command text).`);
+        }
+    }
+    if (summary.completionCount < summary.commandStarts.length) {
+        console.error(`[run-review] command completions observed: ${summary.completionCount}; possible in-flight command at termination.`);
+    }
+    if (summary.heavyCommandStarts.length > 0) {
+        if (options.debugTelemetry) {
+            console.error(`[run-review] heavy commands detected: ${summary.heavyCommandStarts.join(' | ')}`);
+        }
+        else {
+            console.error(`[run-review] heavy commands detected: ${summary.heavyCommandStarts.length} sample(s) captured (set ${options.telemetryDebugEnvKey}=1 to print raw command text).`);
+        }
+    }
+    if (summary.metaSurfaceSignals > 0) {
+        console.error(`[run-review] meta-surface signals detected: ${summary.metaSurfaceSignals} sample(s) across ${summary.distinctMetaSurfaces} surface kind(s) [${summary.metaSurfaceKinds.join(', ')}]; max repeated surface hits ${summary.maxMetaSurfaceHits}.`);
+    }
+    if (summary.lastLines.length > 0) {
+        if (options.debugTelemetry) {
+            console.error(`[run-review] output tail: ${summary.lastLines.join(' || ')}`);
+        }
+        else {
+            console.error(`[run-review] output tail captured: ${summary.lastLines.length} line(s) hidden by default (set ${options.telemetryDebugEnvKey}=1 to print raw tail).`);
+        }
+    }
+    console.error(`[run-review] review telemetry saved to: ${telemetryPath}`);
+}
+export function inferTerminationBoundaryKindsFromErrorMessage(errorMessage) {
+    if (!errorMessage) {
+        return [];
+    }
+    const kinds = [];
+    if (errorMessage.includes('codex review timed out after')) {
+        kinds.push('timeout');
+    }
+    if (errorMessage.includes('codex review stalled with no output for')) {
+        kinds.push('stall');
+    }
+    if (errorMessage.includes('bounded command-intent boundary')) {
+        kinds.push('command-intent');
+    }
+    if (errorMessage.includes('shell-probe boundary violated')) {
+        kinds.push('shell-probe');
+    }
+    if (errorMessage.includes('appears stuck in delegation startup loop')) {
+        kinds.push('startup-loop');
+    }
+    if (errorMessage.includes('active-closeout-bundle reread boundary violated')) {
+        kinds.push('active-closeout-bundle-reread');
+    }
+    if (errorMessage.includes('startup-anchor boundary violated')) {
+        kinds.push('startup-anchor');
+    }
+    if (errorMessage.includes('meta-surface expansion detected')) {
+        kinds.push('meta-surface-expansion');
+    }
+    if (errorMessage.includes('relevant-reinspection dwell boundary violated')) {
+        kinds.push('relevant-reinspection-dwell');
+    }
+    if (errorMessage.includes('verdict-stability drift detected')) {
+        kinds.push('verdict-stability');
+    }
+    return kinds;
+}
+function sanitizeTerminationBoundaryForPersistence(boundary, includeRawTelemetry, telemetryDebugEnvKey) {
+    if (!boundary) {
+        return null;
+    }
+    if (includeRawTelemetry) {
+        return boundary;
+    }
+    const redactedSample = boundary.sample
+        ? `[redacted ${boundary.kind} sample; set ${telemetryDebugEnvKey}=1 to persist raw sample]`
+        : null;
+    return {
+        ...boundary,
+        reason: boundary.sample && redactedSample
+            ? boundary.reason.split(boundary.sample).join(redactedSample)
+            : boundary.reason,
+        sample: redactedSample
+    };
+}
+function sanitizeTelemetrySummaryForPersistence(summary, includeRawTelemetry, telemetryDebugEnvKey) {
+    if (includeRawTelemetry) {
+        return summary;
+    }
+    return {
+        ...summary,
+        commandStarts: redactTelemetryLines(summary.commandStarts, 'command', telemetryDebugEnvKey),
+        heavyCommandStarts: redactTelemetryLines(summary.heavyCommandStarts, 'heavy-command', telemetryDebugEnvKey),
+        commandIntentViolationSamples: redactTelemetryLines(summary.commandIntentViolationSamples, 'command-intent', telemetryDebugEnvKey),
+        lastLines: redactTelemetryLines(summary.lastLines, 'output-line', telemetryDebugEnvKey)
+    };
+}
+function redactTelemetryLines(lines, label, telemetryDebugEnvKey) {
+    return lines.map((_line, index) => `[redacted ${label} ${index + 1}; set ${telemetryDebugEnvKey}=1 to persist raw values]`);
+}
+function sanitizeTelemetryErrorForPersistence(error, includeRawTelemetry, telemetryDebugEnvKey) {
+    if (!error || includeRawTelemetry) {
+        return error;
+    }
+    return `[redacted error; set ${telemetryDebugEnvKey}=1 to persist raw values]`;
+}

package/dist/scripts/lib/review-inspection-target-parsing.js

@@ -0,0 +1,78 @@
+import { extractShellCommandPayload, normalizeCommandToken, splitShellControlSegments, stripLeadingEnvAssignments, tokenizeShellSegment, unwrapEnvCommandTokens } from './review-shell-command-parser.js';
+import { expandMetaSurfaceOperandCandidates, extractMetaSurfaceOperands, isTouchedReviewScopePathFamilyOperand, isTouchedScopePath, normalizeScopePath, relativizeOperandToRepoRoot } from './review-meta-surface-normalization.js';
+const REVIEW_INSPECTION_TARGET_PATH_RE = /^(?:[A-Za-z0-9_./-]+\.(?:[cm]?[jt]sx?|json|md|ya?ml|toml|py|rb|php|go|rs|java|c|cc|cpp|cxx|h|hh|hpp|cs|swift|kt|kts|scala|exs?|sh|bash|zsh|fish|ps1|sql|html?|css|scss|less))$/u;
+const REVIEW_INSPECTION_TARGET_RE = /([A-Za-z0-9_./-]+\.(?:[cm]?[jt]sx?|json|md|ya?ml|toml|py|rb|php|go|rs|java|c|cc|cpp|cxx|h|hh|hpp|cs|swift|kt|kts|scala|exs?|sh|bash|zsh|fish|ps1|sql|html?|css|scss|less))/gu;
+export function extractInspectionTargets(commandLine, options = {}) {
+    const normalized = commandLine.replace(/\\/gu, '/');
+    if (options.touchedPaths && options.touchedPaths.size > 0) {
+        const parsedTargets = extractParsedInspectionTargets(normalized, options.touchedPaths, options.repoRoot ?? null);
+        if (parsedTargets.length > 0) {
+            return parsedTargets;
+        }
+    }
+    const targets = new Set();
+    for (const match of normalized.matchAll(REVIEW_INSPECTION_TARGET_RE)) {
+        const target = match[1]?.trim();
+        if (!target) {
+            continue;
+        }
+        targets.add(target.replace(/^\.\/+/u, ''));
+    }
+    return [...targets];
+}
+export function extractParsedInspectionTargets(commandLine, touchedPaths, repoRoot) {
+    const touchedTargets = new Set();
+    const genericTargets = new Set();
+    for (const segment of splitShellControlSegments(commandLine)) {
+        collectParsedInspectionTargetsFromSegment(segment, touchedPaths, repoRoot, touchedTargets, genericTargets);
+    }
+    return touchedTargets.size > 0 ? [...touchedTargets] : [...genericTargets];
+}
+export function collectParsedInspectionTargetsFromSegment(segment, touchedPaths, repoRoot, touchedTargets, genericTargets, depth = 0) {
+    const strippedTokens = stripLeadingEnvAssignments(tokenizeShellSegment(segment));
+    if (strippedTokens.length === 0) {
+        return;
+    }
+    const tokens = unwrapEnvCommandTokens(strippedTokens);
+    if (tokens.length === 0) {
+        return;
+    }
+    if (depth < 3) {
+        const payload = extractShellCommandPayload(tokens);
+        if (payload) {
+            for (const nestedSegment of splitShellControlSegments(payload)) {
+                collectParsedInspectionTargetsFromSegment(nestedSegment, touchedPaths, repoRoot, touchedTargets, genericTargets, depth + 1);
+            }
+            return;
+        }
+    }
+    const command = normalizeCommandToken(tokens[0] ?? '');
+    const args = tokens.slice(1);
+    for (const operand of extractMetaSurfaceOperands(command, args)) {
+        for (const candidate of expandMetaSurfaceOperandCandidates(command, args, operand, new Map(), new Map(), new Set(), repoRoot)) {
+            const matchedTouchedPath = resolveTouchedInspectionTarget(candidate, touchedPaths, repoRoot);
+            if (matchedTouchedPath) {
+                touchedTargets.add(matchedTouchedPath);
+                continue;
+            }
+            const normalizedCandidate = relativizeOperandToRepoRoot(candidate, repoRoot).replace(/^\.\/+/u, '');
+            if (REVIEW_INSPECTION_TARGET_PATH_RE.test(normalizedCandidate)) {
+                genericTargets.add(normalizedCandidate);
+            }
+        }
+    }
+}
+export function resolveTouchedInspectionTarget(candidate, touchedPaths, repoRoot) {
+    for (const touchedPath of touchedPaths) {
+        const normalizedTouchedPath = normalizeScopePath(touchedPath);
+        if (!normalizedTouchedPath) {
+            continue;
+        }
+        const touchedPathSet = new Set([normalizedTouchedPath]);
+        if (isTouchedScopePath(candidate, touchedPathSet, repoRoot) ||
+            isTouchedReviewScopePathFamilyOperand(candidate, touchedPathSet, repoRoot)) {
+            return normalizedTouchedPath;
+        }
+    }
+    return null;
+}