wicked-crew 0.7.39 → 0.7.45

package/dist/api/chat-citations.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Chat citation verification (crew#561, F-RC1-117 — Wave 1 criterion 2).
+ *
+ * # The defect
+ *
+ * A chat seat answers with citations — repo-relative paths, `path:line` refs, `path:symbol` refs
+ * and commit SHAs — and the daemon relays that text UNTOUCHED. On the RC1 Phase 6 re-run the
+ * opencode seat answered "summarize the last 10 commits across all 9 repos" with 26 SHAs, of which
+ * **2 did not exist in any repo**, and three line refs were off by a few lines. Every citation
+ * rendered as plain text, so a reader could not tell a real SHA from an invented one — and these
+ * are exactly the tokens a reader pastes into `git show`, a PR or a commit message.
+ *
+ * The daemon is the ONE place that can tell: it already knows the chat's read roots (the scope it
+ * handed the seats), and `stat` + `git cat-file -e` are cheap. So it verifies, and says what it
+ * found — it never edits the seat's text. Mark, don't rewrite.
+ *
+ * # What is verified
+ *
+ * | kind     | citation                          | check |
+ * |----------|-----------------------------------|-------|
+ * | `path`   | `crew/src/api/routes.ts`          | the file exists under a read root |
+ * | `line`   | `routes.ts:2264`, `x.ts:80-90`    | the file exists AND has that many lines; when a symbol is named right before the ref, that the symbol is ON that line — otherwise the line it IS on, as a CORRECTION |
+ * | `symbol` | `execute_wrapped.rs:build_worker_command` | the file exists AND contains the symbol |
+ * | `sha`    | `6d77153`, 7–40 hex               | `git rev-parse --verify --quiet <sha>^{commit}` in the repo the text names, else in any read root |
+ *
+ * # Why a false positive is worse than a miss
+ *
+ * Prose looks like a path (`e.g`, `something.this`) and words look like SHAs. Flagging prose
+ * UNVERIFIED would train the reader to ignore the marks, which is worse than not marking. So:
+ *
+ *  - a bare `name.ext` token with no directory and no `:line`/`:symbol` suffix that resolves
+ *    nowhere is DROPPED, not marked — it was probably never a citation;
+ *  - a hex run with no digit or no `a-f` letter is not a SHA candidate (`effaced` is a word; the
+ *    price is that an all-digit short SHA — ~4% of 7-char prefixes — is not checked);
+ *  - a token WITH a separator or a `:line`/`:symbol` suffix IS a citation: unresolvable means
+ *    `unverified`, because that shape is not prose.
+ *
+ * # Bounded, and never in the reply's way
+ *
+ * The pass runs AFTER the `chatReply` frame is broadcast (`server.ts`), so a reply is never delayed
+ * by verification, and it is bounded twice: at most {@link DEFAULT_MAX_ITEMS} citations and
+ * {@link DEFAULT_BUDGET_MS} of wall clock. Whatever the budget did not reach is reported
+ * `unchecked` — a state of its own, never silently "verified".
+ *
+ * The verdicts ride `/ws` as ONE `chatCitations` frame per reply, stamped with the same `turn_id`
+ * the reply carries, and the studio marks the reply from it (badge + counter). The text on the wire
+ * and in the transcript is the seat's own.
+ */
+/** One read root of a chat's scope: the registered repo root and the name the seats were given. */
+export interface CitationRoot {
+    /** Resolved absolute path of the repo root. */
+    absRoot: string;
+    /** The repo's display name — the prefix the reply's rewritten paths carry (crew#618). */
+    name: string;
+}
+/** What class of thing a citation is. */
+export type ChatCitationKind = 'path' | 'line' | 'symbol' | 'sha';
+/**
+ * The verdict on one citation.
+ *  - `verified` — it exists, exactly as cited;
+ *  - `corrected` — the thing exists, but not where the reply said (the real place is `resolved`);
+ *  - `unverified` — it does not exist in the chat's scope (the fabricated-SHA case);
+ *  - `unchecked` — the bounded pass did not reach it. Not a claim either way.
+ */
+export type ChatCitationStatus = 'verified' | 'corrected' | 'unverified' | 'unchecked';
+/** One citation, as verified. `raw` is the token EXACTLY as it appears in the reply. */
+export interface ChatCitationItem {
+    raw: string;
+    kind: ChatCitationKind;
+    status: ChatCitationStatus;
+    /** Where the thing actually is, when the status is `corrected` (`routes.ts:2069`, `crew`). */
+    resolved?: string;
+    /** Why, in one short phrase — the hover text on the studio's badge. */
+    note?: string;
+}
+/** The `/ws` frame: one per verified `chatReply`, stamped with the reply's own `turn_id`. */
+export interface ChatCitationsFrame {
+    type: 'chatCitations';
+    chat: string;
+    cliKey: string;
+    turn_id?: string;
+    /** Counts, so a skin renders the header without walking `items`. */
+    verified: number;
+    unverifiable: number;
+    corrected: number;
+    unchecked: number;
+    items: ChatCitationItem[];
+    project_id?: string;
+}
+/** At most this many citations are checked per reply; the rest are `unchecked`. */
+export declare const DEFAULT_MAX_ITEMS = 80;
+/**
+ * Wall-clock budget for one reply's pass, ms. Overrun ⇒ the remainder is `unchecked`.
+ *
+ * 15 s, not 3: the pass runs entirely off the reply's path (nothing waits on it but the marks
+ * appearing a moment later), and the number worth protecting is COVERAGE, not latency. The RC1
+ * Phase 6 answer cited 26 SHAs over 9 repos — a fabricated one sweeps every root — and on a loaded
+ * desktop a `git cat-file` spawn is not always instant, so a 3 s budget would have reported most of
+ * that answer `unchecked`, which reads like the feature is not working. The budget exists so the
+ * work is BOUNDED, not so it is fast; it is re-read between citations AND between roots.
+ */
+export declare const DEFAULT_BUDGET_MS = 15000;
+/**
+ * The answer to "is this commit in this repo?" — THREE states, not two.
+ *
+ * `git cat-file -e` exits 1 for an object that is not there and something else (or nothing, on a
+ * timeout) when the CHECK failed. Collapsing those into `false` is how a real SHA gets branded
+ * UNVERIFIED on a loaded desktop, which is the one failure this feature must not have: a false mark
+ * teaches the reader to ignore marks.
+ */
+export type CommitCheck = 'present' | 'absent' | 'error';
+/** The reads the pass needs — injected so the whole thing is testable without a repo or git. */
+export interface ChatCitationDeps {
+    /** Does this absolute path exist as a FILE? */
+    fileExists(abs: string): boolean;
+    /** The file's lines, or `null` when it cannot be read (missing, too big, binary). */
+    readLines(abs: string): string[] | null;
+    /** Repo-relative paths tracked in the root, or `null` when the listing itself failed. */
+    listFiles(absRoot: string): Promise<string[] | null>;
+    /** `git cat-file -e <sha>^{commit}` in the root — see {@link CommitCheck}. */
+    commitExists(absRoot: string, sha: string): Promise<CommitCheck>;
+    now(): number;
+}
+/** A citation as EXTRACTED — before anything was checked. */
+export interface RawCitation {
+    raw: string;
+    kind: ChatCitationKind;
+    /** The path part of a path/line/symbol citation (`crew/src/x.ts`). */
+    path?: string;
+    /** The first line of a `line` citation. */
+    line?: number;
+    /** The symbol of a `symbol` citation, or the one the sentence named before a `line` citation. */
+    symbol?: string;
+    /** The repo a `sha` citation's sentence named, when it named one. */
+    repo?: string;
+}
+/** `wicked-crew` is cited as `crew` as often as by its name: every alias a reply may use. */
+export declare function repoAliases(root: CitationRoot): string[];
+/**
+ * Every citation in a reply, in text order, deduplicated by (kind, raw).
+ *
+ * Pure: no filesystem, no git. `roots` is read only for the repo aliases a SHA's sentence may name.
+ */
+export declare function extractCitations(text: string, roots: readonly CitationRoot[]): RawCitation[];
+/** The default deps: the real filesystem and the real git. */
+export declare function chatCitationDeps(): ChatCitationDeps;
+export interface VerifyOptions {
+    maxItems?: number;
+    budgetMs?: number;
+}
+/** The result of one reply's pass. `items` is in text order; the counts match it. */
+export interface ChatCitationsResult {
+    verified: number;
+    unverifiable: number;
+    corrected: number;
+    unchecked: number;
+    items: ChatCitationItem[];
+}
+/**
+ * Verify every citation in a reply, bounded. Never throws: a broken root, an unreadable file or a
+ * git that is not there is a verdict (`unverified` / `unchecked`), not an error.
+ */
+export declare function verifyCitations(text: string, roots: readonly CitationRoot[], deps?: ChatCitationDeps, opts?: VerifyOptions): Promise<ChatCitationsResult>;
+/**
+ * The `/ws` frame for one reply's verdicts, or `null` when there is nothing to say (no citation
+ * survived extraction — a chatty reply with no references marks nothing).
+ */
+export declare function citationsFrame(reply: {
+    chat: string;
+    cliKey: string;
+    turn_id?: string;
+    project_id?: string;
+}, result: ChatCitationsResult): ChatCitationsFrame | null;
+//# sourceMappingURL=chat-citations.d.ts.map

package/dist/api/chat-citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-citations.d.ts","sourceRoot":"","sources":["../../src/api/chat-citations.ts"],"names":[],"mappings":"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"}