diffninja 0.1.0

package/dist/review/file-role.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Path-shape classification of test files, shared by the evidence scan and the
+ * report order. It is a deterministic fact about the path only: it says nothing
+ * about coverage, whether the file runs, or whether its change is harmless.
+ * Documentation is deliberately not a role here: prose can carry normative
+ * instructions, so it is ranked by its observations like any other source.
+ */
+/** True when the path looks like test code by directory or file-name convention. */
+export declare function testLikeFile(file: string): boolean;

package/dist/review/file-role.js

@@ -0,0 +1,29 @@
+/**
+ * Path-shape classification of test files, shared by the evidence scan and the
+ * report order. It is a deterministic fact about the path only: it says nothing
+ * about coverage, whether the file runs, or whether its change is harmless.
+ * Documentation is deliberately not a role here: prose can carry normative
+ * instructions, so it is ranked by its observations like any other source.
+ */
+/** A directory whose name marks test code, at any depth. */
+const TEST_DIRECTORY = /(?:^|\/)(?:tests?|__tests__|specs?)\//;
+/** File names that mark test code by convention, in any directory. */
+const TEST_FILE_NAMES = [
+    // foo.test.ts, foo.spec.jsx, and tsd type tests such as index.test-d.ts
+    /\.(?:test|spec)(?:-d)?\.[cm]?[jt]sx?$/,
+    // a module named test or tests, such as a package's root test.js
+    /(?:^|\/)tests?\.[cm]?[jt]sx?$/,
+    // pytest discovery: test_*.py and *_test.py
+    /(?:^|\/)test_[^/]+\.py$/,
+    /_test\.py$/,
+    // Go, Ruby
+    /_test\.go$/,
+    /_(?:spec|test)\.rb$/,
+    // JUnit / xUnit / XCTest class naming: FooTest.java, FooTests.cs
+    /(?:^|\/)[^/]+Tests?\.(?:java|kt|cs|swift)$/,
+];
+/** True when the path looks like test code by directory or file-name convention. */
+export function testLikeFile(file) {
+    const path = file.replace(/\\/g, "/");
+    return TEST_DIRECTORY.test(path) || TEST_FILE_NAMES.some((pattern) => pattern.test(path));
+}

package/dist/review/github.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Connected GitHub review.
+ *
+ * One explicit github.com pull request URL in, one canonical diff out, one
+ * human-authored review back. `gh` is the only GitHub client: it runs with an
+ * explicit argument array, no shell, no prompts, bounded time and output, and
+ * the credential the environment already gave it is the identity that is read.
+ *
+ * Safety invariants:
+ * - A snapshot (and therefore every anchor a review may use) is built solely
+ *   from the canonical pull request diff, and only after that diff was checked
+ *   against the paginated file list GitHub returns for the same pull request.
+ *   An added line anchors RIGHT, a deleted line anchors LEFT, a context line
+ *   anchors either side. Nothing else is commentable.
+ * - A review is submitted only for the same snapshot the caller previewed, with
+ *   the previewed payload byte for byte (including the explicit `commit_id`),
+ *   after re-reading the metadata and the raw diff and finding them unchanged,
+ *   and after the effective gh account was re-checked.
+ * - One review per session. An ambiguous write marks the session `unknown`,
+ *   never retried; only an exact match found on GitHub resolves it.
+ */
+export type ReviewEvent = "COMMENT" | "APPROVE" | "REQUEST_CHANGES";
+export type DiffSide = "LEFT" | "RIGHT";
+/** One anchor the reviewer wrote by hand; never generated prose. */
+export interface ReviewComment {
+    path: string;
+    line: number;
+    side: DiffSide;
+    body: string;
+}
+/** What the UI sends for preview and submit; it owns all draft text. */
+export interface ReviewInput {
+    snapshotId: string;
+    event: ReviewEvent;
+    body: string;
+    comments: ReviewComment[];
+}
+/** Exactly the body POSTed to the GitHub reviews endpoint. */
+export interface ReviewPayload {
+    commit_id: string;
+    event: ReviewEvent;
+    body: string;
+    comments: ReviewComment[];
+}
+export interface ConnectedIdentity {
+    login: string;
+    id: number;
+}
+/** One line of the canonical diff, in new-side order for context and additions. */
+export interface SnapshotLine {
+    path: string;
+    line: number;
+    side: DiffSide;
+    text: string;
+    kind: "add" | "delete" | "context";
+}
+export interface ConnectedSnapshot {
+    id: string;
+    url: string;
+    owner: string;
+    repo: string;
+    number: number;
+    baseSha: string;
+    headSha: string;
+    state: string;
+    title?: string;
+    body?: string;
+    lines: SnapshotLine[];
+    /** Set when the pull request exists but cannot be reviewed; `lines` may still be empty. */
+    unavailableReason?: string;
+}
+export interface ConnectedReceipt {
+    id: number;
+    url: string;
+    state: string;
+    commitId: string;
+}
+/**
+ * `empty` also covers a loaded pull request that cannot be reviewed
+ * (`snapshot.unavailableReason` says why); `ready` means the snapshot is bound
+ * and submittable; `unknown` means a write may or may not have landed and only
+ * reconciliation may resolve it.
+ */
+export type ConnectedStatus = "empty" | "ready" | "submitting" | "unknown" | "submitted";
+export interface ConnectedState {
+    identity?: ConnectedIdentity;
+    snapshot?: ConnectedSnapshot;
+    status: ConnectedStatus;
+    receipt?: ConnectedReceipt;
+    message?: string;
+}
+/** Lowest `gh` release whose `pr view --json` fields and `api --input -` this code needs. */
+export declare const MIN_GH_VERSION = "2.45.0";
+export interface GhResult {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface GhInvocation {
+    readonly args: string[];
+    readonly stdin?: string;
+    readonly timeoutMs: number;
+}
+/** Injectable `gh` transport; tests supply a fake, the app uses {@link ghCliRunner}. */
+export interface GhRunner {
+    run(invocation: GhInvocation): Promise<GhResult>;
+}
+/**
+ * A failed `gh` run. `gh api` prints GitHub's JSON error body to stdout and the
+ * HTTP status line to stderr, so both are carried for safe message extraction;
+ * neither is ever shown to the user verbatim.
+ */
+export declare class GhCommandError extends Error {
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(message: string, stdout: string, stderr: string);
+}
+export interface ConnectedReviewDeps {
+    runner?: GhRunner;
+    timeoutMs?: number;
+}
+/** Runs the real `gh` with an explicit argv (never a shell) and a hard deadline. */
+export declare function ghCliRunner(): GhRunner;
+/** The JSON data model, used to validate each `gh` payload field by field. */
+export type GhJson = string | number | boolean | null | GhJson[] | GhObject;
+export interface GhObject {
+    readonly [key: string]: GhJson;
+}
+/**
+ * One connected review session. Every method serializes behind the previous
+ * one, so an in-flight submission can never be double-fired.
+ */
+export declare class ConnectedReview {
+    private readonly runner;
+    private readonly timeoutMs;
+    private version;
+    private identity;
+    private snapshot;
+    private diff;
+    private anchors;
+    private status;
+    private receipt;
+    private message;
+    private previewed;
+    /** Review ids that already existed before this session's write attempt. */
+    private preexistingReviewIds;
+    private queue;
+    constructor(deps?: ConnectedReviewDeps);
+    getState(): ConnectedState;
+    /** Canonical patch from the last successfully bound snapshot, for static export. */
+    getDiff(): string;
+    load(url: string): Promise<ConnectedState>;
+    preview(input: ReviewInput): Promise<ReviewPayload>;
+    submit(input: ReviewInput): Promise<ConnectedState>;
+    reconcile(): Promise<ConnectedState>;
+    /** Run `work` after everything already queued; failures never break the chain. */
+    private serialize;
+    private call;
+    private ensureGhVersion;
+    /** The identity of the credential gh actually uses, re-read before each submit. */
+    private readIdentity;
+    private readMetadata;
+    private readCanonicalDiff;
+    private readChangedFiles;
+    /** Every review row of a pull request, across pages. */
+    private readReviews;
+    private readReviewIds;
+    /**
+     * Metadata plus the verified canonical diff; the only source of anchors. The
+     * metadata is read again after the diff and the file list, so a pull request
+     * that moved mid-read is rejected instead of producing a snapshot that mixes
+     * two revisions.
+     */
+    private readSnapshot;
+    /**
+     * One PR and one account per session: the first pull request that loads at all
+     * is bound, reviewable or not, because a session is about one pull request and
+     * switching targets silently is exactly what this mode refuses to do. Only a
+     * refresh of that same pull request is allowed.
+     */
+    private assertLoadable;
+    private runLoad;
+    private runPreview;
+    private runSubmit;
+    private postReview;
+    /**
+     * Resolve an ambiguous write. This never retries and never assumes: it looks
+     * for a review that matches this session exactly and was not already present
+     * before the attempt, so an identical older review cannot pass as proof.
+     */
+    private runReconcile;
+    private findMatchingReview;
+    private readReviewComments;
+    /**
+     * The only payload a submit can ever send is the previewed one, so both the
+     * anchor check and the preview check run before anything is written.
+     */
+    private buildPayload;
+    /**
+     * A comment is accepted only when it names a line of this pull request's diff
+     * and carries plain single-line text: the transport casts the request body, so
+     * shape is established here rather than assumed.
+     */
+    private validateComment;
+}