@videlic/connect 0.1.1 → 0.1.7

package/README.md

@@ -23,6 +23,10 @@ Code already ships with, so macOS, Windows, and Linux use the identical command.
 ## Notes
 
 - The hook only runs when a session **ends** — nothing in the background.
+- On each stop it asks [`gh`](https://cli.github.com) which pull request the
+  current branch is on (`gh pr view`, read-only). No `gh`, no login, or no pull
+  request yet — the session is still sent, and the hook says so in one line in
+  your terminal.
 - Sessions that started **before** install are skipped (consent guard).
 - Remove it by deleting the `Stop` entry in `~/.claude/settings.json`.
 - `VIDELIC_API_URL` overrides the API endpoint (defaults to production).

package/evidence.d.mts

@@ -0,0 +1,172 @@
+/**
+ * Types for `evidence.mjs`.
+ *
+ * The collector is plain JavaScript because it is copied to `~/.claude` and run
+ * by `node` with nothing around it — no build, no loader, no `node_modules`.
+ * This file exists so the ONE place that reads it inside the monorepo, the
+ * cross-producer parity test, is type-checked like everything else rather than
+ * silently `any`: the test's whole job is to prove two implementations agree,
+ * and a test that could pass the wrong shape to one of them would be the last
+ * place to want an untyped call.
+ *
+ * Shapes are imported from `@ao/types`, never re-declared. A hand-written copy
+ * of `EvidenceBundle` here would be a third definition of the thing whose
+ * second definition this package already is, and the type is precisely what
+ * both producers are supposed to share. The import is compile-time only and
+ * reaches nothing at runtime — `evidence.mjs` still imports `node:` and
+ * nothing else, which `hook.test.mjs` holds it to.
+ */
+import type {
+  EvidenceBundle,
+  EvidenceEdgeKind,
+  EvidenceListTests,
+  EvidenceManifest,
+  EvidenceSection,
+  EvidenceSent,
+} from "@ao/types/src/report/evidence";
+
+export const EVIDENCE_V: 1;
+export const EVIDENCE_GRAPH_FORMAT: 2;
+export const COLLECT_BUDGET_MS: number;
+export const LIST_TESTS_BUDGET_MS: number;
+export const TREE_CAP: number;
+export const BODY_CAP_BYTES: number;
+
+/** The edge kinds the graph carries — the bundle's own vocabulary, not a copy of it. */
+export interface ModuleEdge {
+  specifier: string;
+  kind: EvidenceEdgeKind;
+}
+
+export interface ModuleEdgeOptions {
+  declaration?: boolean;
+  jsx?: boolean;
+  typescript?: boolean;
+  script?: boolean;
+}
+
+export function isDeclarationFile(path: string): boolean;
+export function moduleEdgeOptions(path: string): ModuleEdgeOptions;
+export function maskModuleSource(src: string, opts?: ModuleEdgeOptions): string;
+export function moduleDoubt(content: string, opts?: ModuleEdgeOptions): number;
+export function extractModuleEdges(content: string, opts?: ModuleEdgeOptions, report?: { doubtAt: number }): ModuleEdge[];
+export const MANIFEST_FIELD_MAX_DEPTH: number;
+export const MANIFEST_FIELD_MAX_BYTES: number;
+export function manifestFieldFits(v: unknown): boolean;
+export function manifestName(body: string | null | undefined): string | null;
+export function readManifest(path: string, body: string | null | undefined): EvidenceManifest;
+export function isTestPath(path: string): boolean;
+export function expectedTestPaths(sourcePath: string): string[];
+export function isGraphSource(path: string): boolean;
+
+export interface EvidenceSelection {
+  manifests: string[];
+  sources: string[];
+  changed: string[];
+  pairedTests: string[];
+}
+export function selectEvidence(treePaths: ReadonlySet<string>, changedPaths: readonly string[]): EvidenceSelection;
+
+/**
+ * Which sections to BUILD — the budget's decision, made by the caller.
+ *
+ * `listTests` is absent from every rebuild literal on purpose and therefore
+ * optional here: a selection a runner has already given costs nothing to carry
+ * and has no relationship to the clock that cut the file read, so it survives a
+ * rebuild by construction rather than by every literal remembering to name it.
+ */
+export interface EvidenceWant {
+  tree?: boolean;
+  graph: boolean;
+  packageMap: boolean;
+  contents: boolean;
+  listTests?: boolean;
+}
+
+/** One Bash command line the session ran, with the directory it ran in. */
+export interface TranscriptCommand {
+  command: string;
+  cwd: string | null;
+}
+
+/** A runner question: which runner, in which repo-relative directory, with which arguments. */
+export interface ListTestsPlanItem {
+  runner: "jest" | "vitest";
+  dir: string;
+  args: string[];
+  command: string;
+}
+
+export function runnerInvocations(
+  commandLine: string,
+  from?: string,
+  root?: string | null,
+): { runner: "jest" | "vitest"; dir: string; args: string[] }[];
+export function commandsFromTranscript(sessionData: string): TranscriptCommand[];
+export function listTestsPlan(entries: readonly (TranscriptCommand | string)[], root: string): ListTestsPlanItem[];
+export function runnerBinary(root: string, dir: string, runner: "jest" | "vitest"): string | null;
+export function askRunner(input: {
+  root: string;
+  plan: ListTestsPlanItem;
+  timeoutMs: number;
+  now: () => number;
+}): { ok: true; entry: EvidenceListTests } | { ok: false; reason: "tool-missing" | "off-repo" };
+export function collectListTests(input: {
+  root: string;
+  plan: readonly ListTestsPlanItem[];
+  budgetMs: number;
+  now: () => number;
+  headOf: () => string;
+}): { entries: EvidenceListTests[]; absence: EvidenceAbsences[EvidenceSection] | null };
+export function normaliseListTests(
+  entries: readonly EvidenceListTests[] | undefined,
+): EvidenceListTests[] | undefined;
+
+/** Why a section that was not built is missing. `sent` is derived from this and from what was built. */
+export type EvidenceAbsences = Partial<Record<EvidenceSection, Exclude<EvidenceSent[EvidenceSection], true>>>;
+
+export function buildEvidence(input: {
+  head: string;
+  defaultBranch?: string | null;
+  porcelainClean: boolean;
+  collectedAt: string;
+  clientVersion?: string;
+  tree: { paths: ReadonlySet<string>; truncated: boolean };
+  read: (paths: readonly string[]) => Map<string, string | null>;
+  changedPaths: readonly string[];
+  listTests?: readonly EvidenceListTests[];
+  want?: EvidenceWant;
+  absences?: EvidenceAbsences;
+  partial: EvidenceBundle["partial"];
+}): EvidenceBundle;
+
+export function defaultBranchOf(root: string, timeoutMs: number): string | null;
+export function changedPathsOf(root: string, defaultBranch: string | null, timeoutMs: number): string[];
+
+/** `bundle: null` with a `reason` is a repository we could not read — not an empty one. */
+export interface CollectResult {
+  bundle: EvidenceBundle | null;
+  reason: string | null;
+  spentMs: number;
+  defaultBranch?: string | null;
+  bytes?: number;
+}
+
+export function collectEvidence(opts: {
+  root: string;
+  clientVersion?: string;
+  budgetMs?: number;
+  /** Injectable clock — the budget tests need one, and `Date.now` is not a fact a test may wait for. */
+  now?: () => number;
+  defaultBranch?: string | null;
+  changedPaths?: readonly string[];
+  /**
+   * The session's own Bash command lines, newest first, each with the directory
+   * it ran in. `undefined` means the caller did not ask for a selection at all
+   * — `sent.listTests` then says `not-collected`, which is a different fact
+   * from a repository that runs no tests and must not be spelled the same way.
+   */
+  testCommands?: readonly (TranscriptCommand | string)[];
+}): CollectResult;
+
+export type { EvidenceBundle, EvidenceSection, EvidenceSent };