@skill-harness/core 0.17.0 → 0.19.0

package/dist/affected.d.ts

@@ -1,88 +0,0 @@
-import type { Scenario } from "./spec.js";
-/**
- * Which scenarios could plausibly be affected by a change.
- *
- * The governing asymmetry: **an under-inclusive set is dangerous and an
- * over-inclusive one is merely expensive.** Missing a regression means shipping
- * it; running extra scenarios costs tokens. So every ambiguity resolves toward
- * selecting more, and anything the mapping cannot explain selects everything.
- *
- * An affected run is always partial and can never report SHIP. It is an
- * iteration tool — a full run is still what clears a skill for publishing.
- */
-export type SelectionReason = {
-    kind: "covers";
-    detail: string;
-} | {
-    kind: "critical";
-} | {
-    kind: "under-pressure";
-} | {
-    kind: "stimulus-changed";
-    detail: string;
-} | {
-    kind: "unmapped-change";
-    detail: string;
-} | {
-    kind: "no-covers-declared";
-};
-export interface SelectedScenario {
-    id: string;
-    reasons: SelectionReason[];
-}
-export interface AffectedResult {
-    selected: SelectedScenario[];
-    /** True when the mapping could not be trusted and everything was selected. */
-    conservative: boolean;
-    /** Human-readable account of why, when `conservative`. */
-    conservativeReason: string | null;
-    /** Files in the diff whose changed lines map to no covered section. A file nothing `covers` at all is not listed here — it selects everything (see `isInstructionText`) or is skipped as source. */
-    unmappedFiles: string[];
-}
-export interface DiffHunk {
-    file: string;
-    /**
-     * 1-based first changed line in the NEW file.
-     *
-     * For a pure deletion git emits `@@ -2,3 +1,0 @@`, so this is the line the
-     * deletion sits AFTER — 1 in that example, not 0. `selectAffected` maps
-     * sections from the real value; "fixing" it to 0 to match an earlier version
-     * of this comment would break deletion→section mapping.
-     */
-    start: number;
-    /** Number of changed lines; 0 for a pure deletion at `start`. */
-    count: number;
-}
-/**
- * Parse `git diff --unified=0` hunk headers.
- *
- * `--unified=0` matters: with context lines the hunk range covers unchanged text,
- * and a change at the top of one section would be attributed to the section above
- * it too. Over-selection is the safe direction, but only when it is *reasoned*
- * over-selection rather than an artefact of a flag.
- */
-export declare function parseDiffHunks(diff: string): DiffHunk[];
-/** Files the diff touched (added, modified or deleted). */
-export declare function parseDiffFiles(diff: string): string[];
-export interface AffectedOptions {
-    scenarios: Scenario[];
-    /** Dir `covers` and fixture paths resolve against. */
-    specDir: string;
-    /** Unified diff text (`git diff --unified=0 <base>`). */
-    diff: string;
-    /** Repo root the diff paths are relative to. */
-    repoRoot: string;
-}
-/** Run `git diff --unified=0 <base>` in a repo. Empty string when git fails. */
-export declare function gitDiff(repoRoot: string, base: string): Promise<string>;
-/**
- * Select the scenarios a change could affect.
- *
- * Always unions in every critical and every B-series scenario, whatever the diff
- * said. Those are the ship gates: if the mapping is wrong — and a mapping built
- * from author-written labels can be — the scenarios that decide releases are the
- * worst possible ones to skip.
- */
-export declare function selectAffected(opts: AffectedOptions): AffectedResult;
-/** One line per selected scenario, naming every reason it was picked. */
-export declare function formatAffected(result: AffectedResult, total: number): string;

package/dist/affected.js

@@ -1,222 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, dirname, relative } from "node:path";
-import { parseSections, sectionAtLine, parseCoversRef } from "./instruction-coverage.js";
-import { exec } from "./util/exec.js";
-/**
- * Parse `git diff --unified=0` hunk headers.
- *
- * `--unified=0` matters: with context lines the hunk range covers unchanged text,
- * and a change at the top of one section would be attributed to the section above
- * it too. Over-selection is the safe direction, but only when it is *reasoned*
- * over-selection rather than an artefact of a flag.
- */
-export function parseDiffHunks(diff) {
-    const hunks = [];
-    let file = null;
-    for (const line of diff.split("\n")) {
-        if (line.startsWith("+++ ")) {
-            const p = line.slice(4).trim();
-            file = p === "/dev/null" ? null : p.replace(/^b\//, "");
-            continue;
-        }
-        if (!line.startsWith("@@") || file === null)
-            continue;
-        const m = /@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
-        if (!m)
-            continue;
-        hunks.push({ file, start: Number(m[1]), count: m[2] === undefined ? 1 : Number(m[2]) });
-    }
-    return hunks;
-}
-/** Files the diff touched (added, modified or deleted). */
-export function parseDiffFiles(diff) {
-    const files = new Set();
-    for (const line of diff.split("\n")) {
-        const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
-        if (m) {
-            files.add(m[1]);
-            files.add(m[2]);
-        }
-    }
-    return [...files];
-}
-/** Run `git diff --unified=0 <base>` in a repo. Empty string when git fails. */
-export async function gitDiff(repoRoot, base) {
-    const r = await exec("git", ["diff", "--unified=0", base], { cwd: repoRoot, timeoutMs: 60_000 });
-    if (r.code !== 0)
-        throw new Error(`git diff --unified=0 ${base} failed: ${r.stderr.trim() || `exit ${r.code}`}`);
-    return r.stdout;
-}
-/**
- * Select the scenarios a change could affect.
- *
- * Always unions in every critical and every B-series scenario, whatever the diff
- * said. Those are the ship gates: if the mapping is wrong — and a mapping built
- * from author-written labels can be — the scenarios that decide releases are the
- * worst possible ones to skip.
- */
-export function selectAffected(opts) {
-    const { scenarios, specDir, diff, repoRoot } = opts;
-    const reasons = new Map();
-    const add = (id, reason) => {
-        const list = reasons.get(id) ?? [];
-        list.push(reason);
-        reasons.set(id, list);
-    };
-    const selectAll = (why) => {
-        for (const s of scenarios)
-            if (!reasons.has(s.id))
-                add(s.id, { kind: "unmapped-change", detail: why });
-        return {
-            selected: [...reasons.entries()].map(([id, rs]) => ({ id, reasons: rs })),
-            conservative: true,
-            conservativeReason: why,
-            unmappedFiles: [],
-        };
-    };
-    // The ship gates, unconditionally.
-    for (const s of scenarios) {
-        if (s.critical)
-            add(s.id, { kind: "critical" });
-        if (/^B/i.test(s.id))
-            add(s.id, { kind: "under-pressure" });
-    }
-    const hunks = parseDiffHunks(diff);
-    const changedFiles = parseDiffFiles(diff);
-    // A scenario with no `covers` cannot be excluded by a coverage mapping — there
-    // is nothing to consult. Selecting it is the only honest answer.
-    for (const s of scenarios) {
-        if (!s.covers || s.covers.length === 0)
-            add(s.id, { kind: "no-covers-declared" });
-    }
-    // Stimulus files: a changed fixture, post-test, agent file or extension changes
-    // what the scenario RUNS, regardless of any instruction text.
-    const stimulusFiles = (s) => {
-        const files = [];
-        if (s.fixture)
-            files.push(s.fixture);
-        if (s.assert?.post_test)
-            files.push(s.assert.post_test);
-        if (s.systemPromptFile)
-            files.push(s.systemPromptFile);
-        for (const e of s.extensions ?? [])
-            files.push(e);
-        return files;
-    };
-    const changedAbs = new Set(changedFiles.map((f) => resolve(repoRoot, f)));
-    for (const s of scenarios) {
-        for (const f of stimulusFiles(s)) {
-            const abs = resolve(specDir, f);
-            // Directory-ish match too: a fixture is a tree, and a change anywhere in it
-            // counts.
-            const hit = [...changedAbs].some((c) => c === abs || c.startsWith(`${abs}/`));
-            if (hit)
-                add(s.id, { kind: "stimulus-changed", detail: f });
-        }
-    }
-    // Reverse the covers map: changed line → section → scenarios.
-    const sectionsFor = new Map();
-    const load = (abs) => {
-        if (sectionsFor.has(abs))
-            return sectionsFor.get(abs);
-        const parsed = existsSync(abs) ? parseSections(readFileSync(abs, "utf8")) : null;
-        sectionsFor.set(abs, parsed);
-        return parsed;
-    };
-    const coversIndex = new Map(); // "abs#slug" | "abs" -> scenario ids
-    for (const s of scenarios) {
-        for (const raw of s.covers ?? []) {
-            const ref = parseCoversRef(raw);
-            const abs = resolve(specDir, ref.file);
-            const key = ref.slug === undefined ? abs : `${abs}#${ref.slug}`;
-            coversIndex.set(key, [...(coversIndex.get(key) ?? []), s.id]);
-        }
-    }
-    // The skill's own directory, minus its `tests/` subtree. Markdown here is
-    // instruction text the model reads; markdown elsewhere in the repo is not.
-    const skillRoot = dirname(specDir);
-    const isInstructionText = (abs) => abs.startsWith(`${skillRoot}/`) && !abs.startsWith(`${specDir}/`) && /\.(?:md|markdown)$/i.test(abs);
-    const unmappedFiles = new Set();
-    for (const hunk of hunks) {
-        const abs = resolve(repoRoot, hunk.file);
-        // Only instruction files participate; a changed source file is not a section.
-        const referenced = [...coversIndex.keys()].some((k) => k === abs || k.startsWith(`${abs}#`));
-        if (!referenced) {
-            // "No `covers` mentions it" is not the same as "it cannot matter". For
-            // instruction text inside the skill, it is the opposite: every scenario
-            // reads the skill, and nobody claimed this prose — so the mapping has no
-            // basis for ruling it out. `continue` here deselected scenarios the edit
-            // could well have broken, and did not even reach `unmappedFiles`, so the
-            // output said nothing about it. Under-inclusion is the one failure this
-            // module exists to avoid.
-            if (isInstructionText(abs)) {
-                return selectAll(`${relative(repoRoot, abs) || hunk.file} is instruction text that no scenario \`covers\` — the mapping cannot rule it out`);
-            }
-            continue;
-        }
-        const sections = load(abs);
-        if (sections === null) {
-            // The file is referenced but gone — a rename or delete. Nothing can be
-            // mapped, and guessing would be worse than admitting it.
-            return selectAll(`${hunk.file} is referenced by \`covers\` but is not readable — it may have been renamed or deleted`);
-        }
-        for (const id of coversIndex.get(abs) ?? [])
-            add(id, { kind: "covers", detail: `${hunk.file} (whole file)` });
-        const lines = hunk.count === 0 ? [hunk.start] : Array.from({ length: hunk.count }, (_, i) => hunk.start + i);
-        let mappedAny = false;
-        for (const line of lines) {
-            const section = sectionAtLine(sections, line);
-            if (!section)
-                continue; // preamble before the first heading
-            const ids = coversIndex.get(`${abs}#${section.slug}`) ?? [];
-            for (const id of ids)
-                add(id, { kind: "covers", detail: `${hunk.file}#${section.slug}` });
-            if (ids.length > 0)
-                mappedAny = true;
-        }
-        if (!mappedAny && (coversIndex.get(abs) ?? []).length === 0)
-            unmappedFiles.add(hunk.file);
-    }
-    // A wholesale rewrite defeats line mapping: every line looks changed, and the
-    // sections that "match" are an artefact of the rewrite's shape.
-    const rewritten = hunks.filter((h) => h.count > 200);
-    if (rewritten.length > 0) {
-        return selectAll(`${rewritten[0].file} changed by ${rewritten[0].count} lines in one hunk — too large to map to sections reliably`);
-    }
-    return {
-        selected: [...reasons.entries()].map(([id, rs]) => ({ id, reasons: rs })),
-        conservative: false,
-        conservativeReason: null,
-        unmappedFiles: [...unmappedFiles],
-    };
-}
-/** One line per selected scenario, naming every reason it was picked. */
-export function formatAffected(result, total) {
-    const out = [];
-    if (result.conservative) {
-        out.push(`selecting ALL ${total} scenario(s): ${result.conservativeReason}`);
-    }
-    else {
-        out.push(`selected ${result.selected.length}/${total} scenario(s):`);
-    }
-    for (const s of [...result.selected].sort((a, b) => a.id.localeCompare(b.id))) {
-        out.push(`  ${s.id}  ${s.reasons.map(describe).join(", ")}`);
-    }
-    if (result.unmappedFiles.length) {
-        out.push(`  note: changes in ${result.unmappedFiles.join(", ")} map to no covered section`);
-    }
-    out.push("");
-    out.push("an affected run is partial and never reports SHIP — a full run still gates a release");
-    return out.join("\n");
-}
-function describe(r) {
-    switch (r.kind) {
-        case "covers": return `covers ${r.detail}`;
-        case "critical": return "critical (always run)";
-        case "under-pressure": return "B-series (always run)";
-        case "stimulus-changed": return `stimulus changed: ${r.detail}`;
-        case "unmapped-change": return `conservative: ${r.detail}`;
-        case "no-covers-declared": return "declares no `covers` — cannot be ruled out";
-    }
-}
-//# sourceMappingURL=affected.js.map

package/dist/capture.d.ts

@@ -1,193 +0,0 @@
-import type { CaptureCaseV1, CaptureClassification, CaptureTarget, SanitizedArgs } from "./capture-trace-types.js";
-/**
- * Projection and sanitization for `/skill-harness capture` — turning a live pi
- * conversation into a reviewable regression case.
- *
- * Everything here is pure: entries in, plain data out. The pi extension owns the
- * UI and the filesystem; this module owns the rules that decide what a capture
- * is allowed to contain. That split is deliberate — the privacy rules are the
- * part that must be unit-testable without a running agent.
- *
- * Nothing in here calls a model. Checklist drafting is offline by default; any
- * LLM assistance is the extension's business and requires its own confirmation.
- */
-export interface SessionContentBlock {
-    type: string;
-    text?: string;
-    thinking?: string;
-    name?: string;
-    arguments?: unknown;
-    [k: string]: unknown;
-}
-export interface SessionMessage {
-    role: string;
-    content?: SessionContentBlock[];
-    toolName?: string;
-    isError?: boolean;
-    [k: string]: unknown;
-}
-/**
- * One entry from a pi session file.
- *
- * Entries form a linked list through `parentId`, NOT a flat log: forking and
- * rewinding leave sibling chains in the same file. Anything that reads a session
- * without resolving the branch first will happily mix two alternate histories
- * into one "conversation".
- */
-export interface SessionEntry {
-    type: string;
-    id?: string;
-    parentId?: string | null;
-    timestamp?: string;
-    message?: SessionMessage;
-    [k: string]: unknown;
-}
-/**
- * The chain of entries ending at `leafId`, in root→leaf order.
- *
- * With no `leafId`, the leaf is the last entry in file order — which is what
- * "the conversation I am currently in" means. Entries with no `id` (the
- * `session` header) are not part of the chain and are dropped.
- *
- * Cycles cannot occur in a well-formed file, but a corrupted one must not hang
- * the agent, so the walk is bounded by the entry count.
- */
-export declare function activeBranch(entries: SessionEntry[], leafId?: string): SessionEntry[];
-/** A tool call as it is summarized for review — never the result body. */
-export interface ToolCallSummary {
-    name: string;
-    args: SanitizedArgs;
-    isError: boolean;
-    /**
-     * pi's `toolCallId`, when the entry carried one.
-     *
-     * Correlation key for the matching result. Parallel tool calls complete out of
-     * issue order (measured on pi 0.83.0), so pairing by position is wrong the
-     * moment a conversation uses parallelism — which is exactly the kind of
-     * conversation worth capturing.
-     */
-    id?: string;
-    /** Byte length of the result content, when the result was present. */
-    resultBytes?: number;
-    /** SHA-256 of the result content, so identity is checkable without the body. */
-    resultSha256?: string;
-}
-/**
- * One user message and everything the agent did in reply, up to the next user
- * message.
- *
- * This is the selection unit for capture. pi exposes no public API for arbitrary
- * mouse-highlighted transcript text, so turn-level contiguous selection is the
- * supported contract — not a limitation we can quietly widen later.
- */
-export interface LogicalTurn {
-    index: number;
-    user: string;
-    /** Assistant text with thinking removed. Evidence for the human, never an oracle. */
-    assistantText: string;
-    toolCalls: ToolCallSummary[];
-    /** Entry ids covered by this turn. Local-only — never written to a committed capture. */
-    entryIds: string[];
-}
-/** Extract visible text from content blocks. Thinking is dropped unconditionally. */
-export declare function visibleText(blocks: SessionContentBlock[] | undefined): string;
-/**
- * Group an already-branch-resolved entry list into logical turns.
- *
- * Entries that are not messages (`model_change`, `thinking_level_change`,
- * compaction markers, custom extension entries) are skipped rather than
- * guessed at: an unknown entry type is not evidence about the conversation.
- * Anything before the first user message is dropped — it belongs to no turn.
- */
-export declare function projectTurns(entries: SessionEntry[], homeDir?: string): LogicalTurn[];
-/** Values longer than this are truncated rather than persisted whole. */
-export declare const MAX_VALUE_CHARS = 2000;
-/**
- * Redact secrets and machine paths from a free-text string.
- *
- * Home directories are replaced because a capture is meant to be committed, and
- * `/home/<name>/…` identifies a person as surely as a token identifies an
- * account. `homeDir` is a parameter rather than a read of `process.env.HOME` so
- * the behavior is testable and does not differ between a developer's machine
- * and CI.
- */
-export declare function redactText(input: string, homeDir?: string): string;
-/** Truncate with an explicit marker — silent truncation reads as complete evidence. */
-export declare function truncate(input: string, max?: number): string;
-/**
- * Sanitize tool-call arguments: drop secret-named values, redact secret-shaped
- * ones, truncate the oversized, and refuse to recurse without bound.
- */
-export declare function redactArgs(args: unknown, homeDir?: string, depth?: number): SanitizedArgs;
-/** Stable, sortable, collision-resistant enough for a per-skill directory. */
-export declare function captureId(seed: string, existing?: readonly string[]): string;
-export interface BuildCaptureOptions {
-    turns: LogicalTurn[];
-    /** Inclusive selected range over `turns`. */
-    range: {
-        start: number;
-        end: number;
-    };
-    classification: CaptureClassification;
-    expectedBehavior: string;
-    checklist: string[];
-    target: CaptureTarget;
-    sessionPath: string;
-    created: string;
-    subject?: {
-        provider: string;
-        model: string;
-    };
-    gitCommit?: string;
-    gitDirty?: boolean;
-    homeDir?: string;
-    existingIds?: readonly string[];
-}
-/**
- * Assemble a reviewed capture case.
- *
- * Only the USER turns are carried into the case: they are the stimulus, and they
- * are the only part that can be replayed. The assistant's historical prose is
- * evidence for the human writing the expectation, never an exact-output oracle —
- * so it lives in the git-ignored local sidecar, not here.
- *
- * The session path is hashed rather than stored: an absolute path names a
- * machine and a user, and a hash is enough to recognize the same session again.
- */
-export declare function buildCaptureCase(opts: BuildCaptureOptions): CaptureCaseV1;
-/**
- * Project a reviewed capture into a scenario object for `appendScenario`.
- *
- * Deliberately minimal: id, title, turns, checklist. No `critical`, no gates, no
- * fixture. Promotion is the moment a human takes responsibility for a test, and
- * a capture cannot know whether the behavior it saw is ship-blocking — guessing
- * `critical: true` here would let a captured one-off silently gate a release.
- */
-export declare function captureToScenario(capture: CaptureCaseV1, scenarioId: string, title: string): Record<string, unknown>;
-/**
- * Draft an orchestration assertion from subagent calls seen in the captured range.
- *
- * Returns null when the range contains none, so the capture UI can skip the
- * question entirely rather than offering an empty form.
- *
- * Deliberately proposes only `agent` and `count` — never `task_contains`. The
- * task text that happened to be sent is not the task text that is *required*;
- * turning one observed handoff into a required substring would manufacture a
- * brittle assertion the author never reasoned about. Required context is a
- * judgement, so the UI asks.
- */
-export declare function draftSubagentAssertion(turns: LogicalTurn[], toolNames?: readonly string[]): {
-    tool: string;
-    agent: string;
-    count: {
-        min: number;
-    };
-} | null;
-/**
- * Offline first-draft checklist from the human's expectation.
- *
- * Splits on sentence and bullet boundaries. This is a typing shortcut for the
- * editor step, not an understanding of the text — the UI always opens the result
- * for correction, and the plan makes LLM drafting a separate, paid, opt-in path.
- */
-export declare function draftChecklist(expectedBehavior: string): string[];