@compaction/cli 0.1.0

package/dist/core/adapter-validation.js

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { assertTraceAdapterSource, getTraceAdapter, parseTraceAdapterRawContent } from "./trace-adapters.js";
+const adapterValidationRoot = path.join(".compaction", "adapter-validations");
+const validationHarnessLimitations = [
+    "Adapter Fixture Harness v0 is local and file-based only.",
+    "It validates exported or synthetic fixture files through the existing adapter contract and registry.",
+    "It does not mutate the source fixture file.",
+    "It does not upload data or call model/provider APIs.",
+    "It is not a live Claude Code, Codex, Cursor, OpenAI, Anthropic, LangChain, GitHub, or provider/runtime integration.",
+    "Codex exec JSONL support validates local export files only; live provider/runtime integrations remain future work."
+];
+function markdownList(values, emptyText) {
+    if (values.length === 0) {
+        return `- ${emptyText}`;
+    }
+    return values.map((value) => `- ${value}`).join("\n");
+}
+function buildValidationId(inputPath, source, generatedAt, rawContent) {
+    const digest = createHash("sha256").update(`${inputPath}\n${source}\n${generatedAt}\n${rawContent}`).digest("hex").slice(0, 10);
+    const timestamp = generatedAt.replace(/[-:.]/g, "").replace("T", "-").replace("Z", "");
+    return `adapter-validation-${timestamp}-${digest}`;
+}
+function formatAdapterValidationMarkdown(report) {
+    return [
+        "# Adapter Validation Report",
+        "",
+        "## Summary",
+        "",
+        `- Validation ID: ${report.validation_id}`,
+        `- Status: ${report.status}`,
+        `- Supported format detected: ${report.supported_format_detected ? "yes" : "no"}`,
+        `- Output trace ID: ${report.output_trace_id ?? "none"}`,
+        `- Message count: ${report.message_count}`,
+        `- Generated at: ${report.generated_at}`,
+        "",
+        "## Source",
+        "",
+        `- Input path: ${report.input_path}`,
+        `- Requested source: ${report.source}`,
+        "",
+        "## Adapter",
+        "",
+        `- Adapter ID: ${report.adapter_id}`,
+        "- Adapter selected from the local trace adapter registry.",
+        "- Live provider/runtime integration: no",
+        "",
+        "## Normalization",
+        "",
+        markdownList(report.normalization_steps, "No normalization steps were applied."),
+        "",
+        "## Warnings",
+        "",
+        markdownList(report.warnings, "No warnings."),
+        "",
+        "## Failures",
+        "",
+        markdownList(report.failures, "No failures."),
+        "",
+        "## Recommended Next Command",
+        "",
+        report.recommended_next_command ? `\`${report.recommended_next_command}\`` : "No next command is recommended until validation succeeds.",
+        "",
+        "## Limitations",
+        "",
+        markdownList(report.limitations, "No limitations recorded."),
+        ""
+    ].join("\n");
+}
+function buildReport(params) {
+    return {
+        validation_id: params.validationId,
+        generated_at: params.generatedAt,
+        input_path: params.inputPath,
+        source: params.source,
+        adapter_id: params.adapterId,
+        status: params.status,
+        output_trace_id: params.outputTraceId,
+        message_count: params.messageCount,
+        supported_format_detected: params.supportedFormatDetected,
+        warnings: params.warnings,
+        failures: params.failures,
+        normalization_steps: params.normalizationSteps,
+        skipped_fields: params.skippedFields,
+        limitations: params.limitations,
+        recommended_next_command: params.status === "fail" ? null : `compaction analyze ${params.normalizedTracePath}`
+    };
+}
+async function writeAdapterValidationArtifacts(outputDirectory, report, normalizedTrace) {
+    await mkdir(outputDirectory, { recursive: true });
+    const normalizedTracePath = path.join(outputDirectory, "normalized-trace.json");
+    const validationReportJsonPath = path.join(outputDirectory, "adapter-validation.json");
+    const validationReportMarkdownPath = path.join(outputDirectory, "adapter-validation.md");
+    if (normalizedTrace) {
+        await writeFile(normalizedTracePath, `${JSON.stringify(normalizedTrace, null, 2)}\n`, "utf8");
+    }
+    await writeFile(validationReportJsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    await writeFile(validationReportMarkdownPath, formatAdapterValidationMarkdown(report), "utf8");
+    return {
+        report,
+        normalizedTrace,
+        paths: {
+            outputDirectory,
+            normalizedTracePath,
+            validationReportJsonPath,
+            validationReportMarkdownPath
+        }
+    };
+}
+export async function validateAdapterFixtureFile(inputPath, source, outputRoot = adapterValidationRoot) {
+    assertTraceAdapterSource(source);
+    const rawContent = await readFile(inputPath, "utf8");
+    const generatedAt = new Date().toISOString();
+    const validationId = buildValidationId(inputPath, source, generatedAt, rawContent);
+    const outputDirectory = path.join(outputRoot, validationId);
+    const normalizedTracePath = path.join(outputDirectory, "normalized-trace.json");
+    const adapter = getTraceAdapter(source);
+    const limitations = [...validationHarnessLimitations, ...adapter.limitations];
+    const parsedInput = parseTraceAdapterRawContent(rawContent, source);
+    if (parsedInput.failures.length > 0 || parsedInput.input === null) {
+        const report = buildReport({
+            validationId,
+            generatedAt,
+            inputPath,
+            source,
+            adapterId: adapter.id,
+            status: "fail",
+            outputTraceId: null,
+            messageCount: 0,
+            supportedFormatDetected: false,
+            warnings: [],
+            failures: parsedInput.failures,
+            normalizationSteps: [...parsedInput.normalization_steps, "Skipped adapter canHandle and normalize because the fixture could not be parsed."],
+            skippedFields: [],
+            limitations,
+            normalizedTracePath
+        });
+        return writeAdapterValidationArtifacts(outputDirectory, report, null);
+    }
+    const normalizationSteps = [...parsedInput.normalization_steps, `Selected adapter ${adapter.id} from the local adapter registry.`];
+    const canHandle = adapter.canHandle(parsedInput.input);
+    normalizationSteps.push(`Ran adapter canHandle for source ${source}: ${canHandle ? "supported" : "unsupported"}.`);
+    if (!canHandle) {
+        const report = buildReport({
+            validationId,
+            generatedAt,
+            inputPath,
+            source,
+            adapterId: adapter.id,
+            status: "fail",
+            outputTraceId: null,
+            messageCount: 0,
+            supportedFormatDetected: false,
+            warnings: [],
+            failures: [`Adapter ${adapter.id} cannot handle this fixture shape for source ${source}.`],
+            normalizationSteps: [...normalizationSteps, "Skipped normalize because canHandle returned false."],
+            skippedFields: [],
+            limitations,
+            normalizedTracePath
+        });
+        return writeAdapterValidationArtifacts(outputDirectory, report, null);
+    }
+    const result = adapter.normalize(parsedInput.input, { rawContent });
+    const normalizedTrace = result.status === "fail" ? null : result.trace;
+    const report = buildReport({
+        validationId,
+        generatedAt,
+        inputPath,
+        source,
+        adapterId: adapter.id,
+        status: result.status,
+        outputTraceId: normalizedTrace?.id ?? null,
+        messageCount: normalizedTrace?.messages.length ?? 0,
+        supportedFormatDetected: result.trace !== null,
+        warnings: result.warnings,
+        failures: result.failures,
+        normalizationSteps: [...normalizationSteps, "Ran adapter normalize for the local fixture.", ...result.normalization_steps],
+        skippedFields: result.skipped_fields,
+        limitations,
+        normalizedTracePath
+    });
+    return writeAdapterValidationArtifacts(outputDirectory, report, normalizedTrace);
+}
+//# sourceMappingURL=adapter-validation.js.map

package/dist/core/adapters/claude-code-adapter.d.ts

@@ -0,0 +1,51 @@
+import type { CaptureAdapter, CaptureAdapterInput, CapturedRun } from "../capture-adapter.js";
+export declare const PRIVACY_WARNING: string;
+/**
+ * Lightweight metadata for a single discoverable Claude Code session.
+ *
+ * Computed by reusing the existing adapter parser (`readJsonlEntries` +
+ * `processEntries` + `discoverSubagentJSONLFiles`) so the counts match what
+ * `normalize()` would produce — NOT a re-implemented parser. This is metadata
+ * ONLY: no session message content is surfaced.
+ */
+export interface ClaudeCodeSessionMetadata {
+    /** Absolute path to the session JSONL file (ready for `--session <path>`). */
+    sessionPath: string;
+    /** Project slug (the `<slug>` directory name under projects root). */
+    projectSlug: string;
+    /** Decoded project working directory, if recoverable from the slug / entries. */
+    projectDir: string | undefined;
+    /** Session ID parsed from the session entries, or null if unknown. */
+    sessionId: string | null;
+    /** Earliest entry timestamp (ISO 8601), or undefined if none present. */
+    firstTimestamp: string | undefined;
+    /** Latest entry timestamp (ISO 8601), or undefined if none present. */
+    lastTimestamp: string | undefined;
+    /**
+     * Message count as the adapter would produce for the MAIN session
+     * (subagent messages are only merged when --include-subagents is passed,
+     * so they are NOT counted here, matching the default capture).
+     */
+    messageCount: number;
+    /** Number of subagent JSONL files discoverable under <session-id>/subagents/. */
+    subagentCount: number;
+    /**
+     * True when at least one assistant entry carries a provider `usage` object —
+     * i.e. the capture would set provider_reported_tokens: true.
+     */
+    providerReportedUsagePresent: boolean;
+}
+/**
+ * Scan a single Claude Code session JSONL file for discovery metadata.
+ *
+ * Reuses the existing parser exactly (no re-implementation): it reads the same
+ * entries `normalize()` reads, runs the same `processEntries` over the main
+ * session, and counts subagent files via the same `discoverSubagentJSONLFiles`.
+ * Reads only the given session file (and lists its subagents directory).
+ * Surfaces metadata only; never returns message content.
+ */
+export declare function scanSessionMetadata(sessionPath: string, projectSlug: string): Promise<ClaudeCodeSessionMetadata>;
+export declare class ClaudeCodeAdapter implements CaptureAdapter {
+    readonly id = "claude-code";
+    normalize(input: CaptureAdapterInput): Promise<CapturedRun>;
+}