Documentation
¶
Index ¶
- Constants
- func Dir(dataRoot, key string) string
- func EncodeCommentsJSON(entries []ListedComment) ([]byte, error)
- func FormatCommentsText(entries []ListedComment, unresolvedOnly bool) string
- func IsAbsoluteOrTraversal(p string) bool
- func JSONPath(dir string) string
- func NormalizePath(p string) string
- func Now() string
- func ParseDocumentForm(d AttachedDocument) ([]form.Item, error)
- func ParseLineSpec(spec string) (start, end int, err error)
- func PlanCurrentPath(slug string) string
- func PlanSessionKey(cwd, slug string) string
- func PlanStorageDir(slug string) string
- func PlansDir() string
- func RandomCommentID() string
- func RandomReplyID() string
- func RandomReviewCommentID() string
- func RemoveSessionEntry(key string) error
- func ResolveSlug(content []byte) string
- func ReviewsRoot(dataRoot string) string
- func SavePlanVersionAt(dir string, content []byte) (int, error)
- func SessionKey(cwd, branch string, args []string) string
- func SessionsDir() string
- func Slugify(s string) string
- func SocketPathFor(key string) string
- func ValidSessionKey(s string) bool
- func WriteJSON(path string, value any) error
- type AttachedDocument
- type BulkCommentEntry
- type BulkStats
- type CodeFileStatus
- type CodeReviewStatus
- type Comment
- type CommentNotFoundError
- type CritJSON
- type CritJSONFile
- type DocumentAttachments
- type FormDocument
- type FormResult
- type FormState
- type ListedComment
- type Reply
- type ReviewInput
- type ReviewedFile
- type RoundState
- type Session
- func FindSavedSession(matches func(SessionEntry) bool) (*Session, error)
- func FindSessionsByCommentID(id, excludeKey string) ([]*Session, error)
- func NewSession(dataRoot string, meta SessionEntry) (*Session, error)
- func OpenCodeSession(dataRoot string) (*Session, error)
- func OpenCodeSessionWithArgs(dataRoot string, args []string) (*Session, error)
- func OpenDocSession(dataRoot, docPath string) (*Session, error)
- func OpenPlanSession(slug string) (*Session, error)
- func OpenSession(dataRoot, key string) (*Session, error)
- func OpenSessionAt(key, dir string) (*Session, error)
- func OpenSessionFromEntry(e SessionEntry) (*Session, error)
- func ResolveCode(dataRoot string) (*Session, error)
- func ResolveDocument(dataRoot, path string) (*Session, error)
- func ResolvePlan(slug string) (*Session, error)
- func ResolveTarget(dataRoot, sessionID string) (*Session, error)
- func (s *Session) AppendFileComment(path, body, author, userID string)
- func (s *Session) AppendLineComment(path string, startLine, endLine int, body, author, userID string)
- func (s *Session) AppendReply(commentID, body, author, userID string, resolve bool, filterPath string) error
- func (s *Session) AppendReviewComment(body, author, userID string)
- func (s *Session) ApplyBulk(entries []BulkCommentEntry, globalAuthor, userID string) (BulkStats, error)
- func (s *Session) ApplyBulkEntry(i int, e BulkCommentEntry, globalAuthor, userID string) error
- func (s *Session) BeginForms(input ReviewInput, docs []AttachedDocument) (FormState, error)
- func (s *Session) BeginRound(files map[string]SnapshotFile, rawDiff string) error
- func (s *Session) Clear() error
- func (s *Session) DiffPath() string
- func (s *Session) FileComments(path string) []Comment
- func (s *Session) HasAttachments() bool
- func (s *Session) LoadDocuments() (DocumentAttachments, error)
- func (s *Session) LoadForms() (FormState, error)
- func (s *Session) Path() string
- func (s *Session) ReplaceDocuments(docs []AttachedDocument) error
- func (s *Session) Save() error
- func (s *Session) SaveAttachment(data []byte) (string, error)
- func (s *Session) SaveDiff(p *git.Patch) error
- func (s *Session) SaveFormResult(result FormResult) error
- func (s *Session) SaveForms(state FormState) error
- func (s *Session) SetFileComments(path, status string, comments []Comment)
- func (s *Session) SetSubmission(verdict Verdict, body, author string)
- func (s *Session) SortedFiles() []string
- func (s *Session) SubmissionComment() *Comment
- func (s *Session) Update(fn func(*Session) error) error
- type SessionEntry
- type SnapshotFile
- type Verdict
Constants ¶
const MaxAttachmentBytes = 5 << 20
Variables ¶
This section is empty.
Functions ¶
func EncodeCommentsJSON ¶
func EncodeCommentsJSON(entries []ListedComment) ([]byte, error)
EncodeCommentsJSON marshals a listing, normalizing nil to [].
func FormatCommentsText ¶
func FormatCommentsText(entries []ListedComment, unresolvedOnly bool) string
FormatCommentsText renders the human-readable `comments` listing.
func IsAbsoluteOrTraversal ¶
IsAbsoluteOrTraversal rejects absolute paths and paths escaping the working tree. The check runs on the raw input before Clean, following crit, so Windows-style prefixes cannot slip through.
func NormalizePath ¶
NormalizePath cleans a user-supplied file path into the forward-slash form used both in session-key derivation and as Files map keys. Paths under the current working directory normalize to the same relative form whether given as absolute or relative, so all commands agree on keys.
func Now ¶
func Now() string
Now returns the current UTC time in the RFC 3339 format used throughout review.json.
func ParseDocumentForm ¶
func ParseDocumentForm(d AttachedDocument) ([]form.Item, error)
func ParseLineSpec ¶
ParseLineSpec parses "42" or "45-47" into a start/end line pair.
func PlanCurrentPath ¶
PlanCurrentPath returns the path of the plan's latest content.
func PlanSessionKey ¶
PlanSessionKey computes the session key for a plan review, matching crit's cwd + "__plan:"+slug derivation (the marker hashes in the branch position).
func PlanStorageDir ¶
PlanStorageDir returns the storage directory for a plan slug.
func RandomCommentID ¶
func RandomCommentID() string
RandomCommentID returns a random line/file comment ID (e.g. "c_a3f8b2").
func RandomReplyID ¶
func RandomReplyID() string
RandomReplyID returns a random reply ID (e.g. "rp_d7e2a0").
func RandomReviewCommentID ¶
func RandomReviewCommentID() string
RandomReviewCommentID returns a random review-level comment ID (e.g. "r_b4c9e1").
func RemoveSessionEntry ¶
RemoveSessionEntry deletes the registry entry for a key, ignoring missing files.
func ResolveSlug ¶
ResolveSlug derives a plan slug from its content: the first markdown heading plus today's date, or a timestamp fallback.
func ReviewsRoot ¶
ReviewsRoot returns the directory that holds all review folders, honoring an explicit data root (--output / config) when non-empty.
func SavePlanVersionAt ¶
SavePlanVersionAt saves content in a plan's storage directory as the next numbered version and updates current.md, returning the 1-based version.
func SessionKey ¶
SessionKey derives the stable 12-hex-char review session key, matching crit's algorithm: sha256 over the working directory plus either the file arguments (files mode; branch-independent) or the branch (git mode).
func SessionsDir ¶
func SessionsDir() string
SessionsDir returns the directory holding session registry entries.
func SocketPathFor ¶
SocketPathFor returns the Unix socket path for a session key.
func ValidSessionKey ¶
ValidSessionKey reports whether s looks like a session key.
Types ¶
type AttachedDocument ¶
type AttachedDocument struct {
ID string `json:"id"`
Source string `json:"source"`
Name string `json:"name"`
Content string `json:"content"`
Revision string `json:"revision"`
Removed bool `json:"removed,omitempty"`
}
AttachedDocument keeps the source identity separate from its comment path.
func ReadAttachedDocuments ¶
func ReadAttachedDocuments(paths []string) ([]AttachedDocument, error)
ReadAttachedDocuments validates all inputs before changing session state.
func (AttachedDocument) Path ¶
func (d AttachedDocument) Path() string
type BulkCommentEntry ¶
type BulkCommentEntry struct {
File string `json:"file,omitempty"`
Path string `json:"path,omitempty"` // alias for File
Line int `json:"-"` // parsed from "line" when int
LineSpec string `json:"-"` // parsed from "line" when string ("45-47")
EndLine int `json:"end_line,omitempty"` // defaults to Line
Body string `json:"body"`
Author string `json:"author,omitempty"` // per-entry override; falls back to global
Scope string `json:"scope,omitempty"` // "review", "file", or "" (inferred)
ReplyTo string `json:"reply_to,omitempty"`
Resolve bool `json:"resolve,omitempty"`
}
BulkCommentEntry is one element of the `comment --json` input array.
func (*BulkCommentEntry) UnmarshalJSON ¶
func (e *BulkCommentEntry) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts the "line" field as either an int (42) or a string line spec ("45-47").
type CodeFileStatus ¶
CodeFileStatus represents a single file's review status in aggregate output.
type CodeReviewStatus ¶
type CodeReviewStatus struct {
Files []CodeFileStatus `json:"files"`
TotalComments int `json:"total_comments"`
}
CodeReviewStatus is the aggregate status for all files in a code review.
func AggregateStatus ¶
func AggregateStatus(dataRoot string) (*CodeReviewStatus, error)
AggregateStatus summarizes the current code review session.
type Comment ¶
type Comment struct {
ID string `json:"id"`
StartLine int `json:"start_line"`
EndLine int `json:"end_line"`
Side string `json:"side,omitempty"`
Body string `json:"body"`
Quote string `json:"quote,omitempty"`
QuoteOffset *int `json:"quote_offset,omitempty"`
// Anchor is the full text of lines StartLine..EndLine at authoring time,
// used to re-locate the comment when line numbers drift across rounds.
Anchor string `json:"anchor,omitempty"`
Drifted bool `json:"drifted,omitempty"`
// DriftedOnRound is the round that newly classified this comment as
// drifted; preserved for crit compatibility.
DriftedOnRound int `json:"drifted_on_round,omitempty"`
Author string `json:"author,omitempty"`
UserID string `json:"user_id,omitempty"`
// Scope is "line", "file", or "review". Empty means "line".
Scope string `json:"scope,omitempty"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at"`
Resolved bool `json:"resolved,omitempty"`
// ResolvedRound is the review round during which Resolved transitioned
// false -> true; cleared to 0 when it transitions back.
ResolvedRound int `json:"resolved_round,omitempty"`
CarriedForward bool `json:"carried_forward,omitempty"`
ReviewRound int `json:"review_round,omitempty"`
Replies []Reply `json:"replies,omitempty"`
// Forge-sync fields written by crit; Critty preserves but never sets them.
GitHubID int64 `json:"github_id,omitempty"`
GitLabNoteID int64 `json:"gitlab_note_id,omitempty"`
GitLabDiscussionID string `json:"gitlab_discussion_id,omitempty"`
GitLabResolved *bool `json:"gitlab_resolved,omitempty"`
LastPushedBodyHash string `json:"last_pushed_body_hash,omitempty"`
HeadSHA string `json:"head_sha,omitempty"`
// DiffScope is "layer" or "full_stack" for Crit range-focus comments.
// Working-tree filters such as staged and unstaged intentionally leave it empty.
DiffScope string `json:"diff_scope,omitempty"`
FocusKey string `json:"focus_key,omitempty"`
}
Comment represents a single review comment: line-level, file-level, or review-level depending on Scope.
func CarryForwardFile ¶
CarryForwardFile maps a file's comments onto the file's new content. prevContent is the content the comments were authored against; now stamps UpdatedAt on the carried comments.
func CarryForwardPartial ¶
CarryForwardPartial preserves coordinates when missing context prevents a reliable line mapping. Changed snapshots flag line anchors for inspection.
type CommentNotFoundError ¶
type CommentNotFoundError struct{ ID string }
CommentNotFoundError reports a reply target missing from a review file.
func (*CommentNotFoundError) Error ¶
func (e *CommentNotFoundError) Error() string
type CritJSON ¶
type CritJSON struct {
RoundState RoundState `json:"critty_state,omitempty"`
Branch string `json:"branch"`
BaseRef string `json:"base_ref"`
UpdatedAt string `json:"updated_at"`
ReviewRound int `json:"review_round"`
ReviewComments []Comment `json:"review_comments,omitempty"`
CliArgs []string `json:"cli_args,omitempty"`
Files map[string]CritJSONFile `json:"files"`
// Sharing fields written by crit; preserved but unused by Critty.
DeleteToken string `json:"delete_token,omitempty"`
// ActiveDiffScope mirrors Crit's current range focus ("layer" or
// "full_stack"). It is empty for working-tree reviews, including staged.
ActiveDiffScope string `json:"active_diff_scope,omitempty"`
}
CritJSON is the top-level review.json document.
func NewCritJSON ¶
func NewCritJSON() CritJSON
NewCritJSON returns an empty review document at round 1.
func (*CritJSON) ContainsCommentID ¶
ContainsCommentID reports whether the review holds a comment with this ID.
func (*CritJSON) ListComments ¶
func (cj *CritJSON) ListComments(unresolvedOnly bool) []ListedComment
ListComments flattens a review into display order: review-level comments first, then files sorted by path, file-level before line-level, line-level sorted by start line.
func (*CritJSON) TotalComments ¶
TotalComments counts review-level and per-file comments.
type CritJSONFile ¶
type CritJSONFile struct {
Status string `json:"status"`
FileHash string `json:"file_hash,omitempty"`
Comments []Comment `json:"comments"`
}
CritJSONFile is the per-file section in review files.
type DocumentAttachments ¶
type DocumentAttachments struct {
Version int `json:"version"`
Documents []AttachedDocument `json:"documents"`
}
type FormDocument ¶
type FormResult ¶
type FormResult struct {
FormState
Session string `json:"session,omitempty"`
Approved bool `json:"approved"`
Verdict Verdict `json:"verdict,omitempty"`
ReviewComment *Comment `json:"review_comment,omitempty"`
Round int `json:"round"`
Consents map[string]map[string]bool `json:"consents,omitempty"`
}
FormResult is self-contained, including the exact inputs to each consent.
type FormState ¶
type FormState struct {
Version int `json:"version"`
Revision string `json:"review_revision"`
Input ReviewInput `json:"reviewed_target"`
Documents []FormDocument `json:"attachments"`
}
func (*FormState) Document ¶
func (state *FormState) Document(path string) *FormDocument
type ListedComment ¶
type ListedComment struct {
Scope string `json:"scope"`
Path *string `json:"path,omitempty"`
Comment
}
ListedComment is a comment flattened for CLI output, matching crit's `comments` format. It embeds Comment so new review.json fields flow through automatically; Scope and Path are the only additions.
type Reply ¶
type Reply struct {
ID string `json:"id"`
Body string `json:"body"`
Author string `json:"author,omitempty"`
UserID string `json:"user_id,omitempty"`
CreatedAt string `json:"created_at"`
// ReviewRound is the review round during which this reply was authored.
ReviewRound int `json:"review_round,omitempty"`
// ResolvedRound mirrors Comment.ResolvedRound for per-reply resolution.
ResolvedRound int `json:"resolved_round,omitempty"`
}
Reply represents a single reply in a comment thread.
type ReviewInput ¶
type ReviewInput struct {
Scope string `json:"scope"`
Source *git.ReviewSource `json:"source,omitempty"`
Files map[string]ReviewedFile `json:"files"`
Diff string `json:"diff,omitempty"`
}
type ReviewedFile ¶
type RoundState ¶
type RoundState struct {
Files map[string]SnapshotFile `json:"files,omitempty"`
Diff string `json:"diff,omitempty"`
Finished bool `json:"finished,omitempty"`
NewFeedback bool `json:"new_feedback,omitempty"`
Verdict Verdict `json:"verdict,omitempty"`
ReviewCommentID string `json:"review_comment_id,omitempty"`
FeedbackComments map[string]map[string]bool `json:"feedback_comments,omitempty"`
ReviewCommentDraft string `json:"review_comment_draft,omitempty"`
// Nil means no baseline was recorded; an empty array means no replies
// existed at submission. Preserve that distinction in saved sessions.
SubmittedReplies []string `json:"submitted_replies"`
}
RoundState is Critty's saved runtime context, separate from CritJSON comments.
type Session ¶
type Session struct {
Key string
Dir string
CJ CritJSON
Meta SessionEntry
// contains filtered or unexported fields
}
Session binds a review folder on disk to its loaded CritJSON document.
func FindSavedSession ¶
func FindSavedSession(matches func(SessionEntry) bool) (*Session, error)
FindSavedSession selects an unambiguous saved review in the current directory.
func FindSessionsByCommentID ¶
FindSessionsByCommentID scans every registered session for a comment ID, skipping the session with excludeKey. Used to redirect replies whose target lives in another review file.
func NewSession ¶
func NewSession(dataRoot string, meta SessionEntry) (*Session, error)
NewSession allocates independent storage even for identical review arguments.
func OpenCodeSession ¶
OpenCodeSession opens the git-mode review session for the current working directory and branch.
func OpenCodeSessionWithArgs ¶
OpenCodeSessionWithArgs isolates comments by the selected review source.
func OpenDocSession ¶
OpenDocSession opens the files-mode review session for a single document.
func OpenPlanSession ¶
OpenPlanSession opens the review session stored inside a plan directory.
func OpenSession ¶
OpenSession loads the review folder for key, creating an empty round-1 document when none exists yet.
func OpenSessionAt ¶
OpenSessionAt loads a review folder at an explicit directory.
func OpenSessionFromEntry ¶
func OpenSessionFromEntry(e SessionEntry) (*Session, error)
OpenSessionFromEntry opens the review folder a registry entry points at.
func ResolveCode ¶
func ResolveDocument ¶
func ResolvePlan ¶
func ResolveTarget ¶
ResolveTarget finds the review session a comment command should operate on: an explicit --session key, the single session registered for the current directory, or (when none is registered) the git-mode session for the current branch.
func (*Session) AppendFileComment ¶
AppendFileComment adds a file-level comment (no line reference).
func (*Session) AppendLineComment ¶
func (s *Session) AppendLineComment(path string, startLine, endLine int, body, author, userID string)
AppendLineComment adds a line-level comment, stamping the drift-correction anchor from the file's current content on disk when readable.
func (*Session) AppendReply ¶
func (s *Session) AppendReply(commentID, body, author, userID string, resolve bool, filterPath string) error
AppendReply adds a reply to the comment with the given ID, searching review-level comments first and then file comments. filterPath, when non-empty, restricts the file search to one path (for duplicated IDs).
Following crit: a resolving reply stamps Resolved/ResolvedRound; a non-resolving reply *un*resolves a previously-resolved comment so the new reply is not hidden by the resolution filter.
func (*Session) AppendReviewComment ¶
AppendReviewComment adds a review-level comment.
func (*Session) ApplyBulk ¶
func (s *Session) ApplyBulk(entries []BulkCommentEntry, globalAuthor, userID string) (BulkStats, error)
ApplyBulk validates and applies all entries to this session in one atomic write. Any entry error aborts the batch before anything is saved.
func (*Session) ApplyBulkEntry ¶
func (s *Session) ApplyBulkEntry(i int, e BulkCommentEntry, globalAuthor, userID string) error
ApplyBulkEntry routes one bulk entry to the matching authoring helper. globalAuthor fills entries without their own author; userID always comes from local config, never the payload (a payload user_id would be a spoof vector).
func (*Session) BeginForms ¶
func (s *Session) BeginForms(input ReviewInput, docs []AttachedDocument) (FormState, error)
func (*Session) BeginRound ¶
func (s *Session) BeginRound(files map[string]SnapshotFile, rawDiff string) error
BeginRound restores the persisted round and remaps anchors onto fresh content. A stopped, unfinished round keeps its number and feedback state.
func (*Session) Clear ¶
Clear removes the whole review folder and its registry entry. Missing folders are not an error.
func (*Session) FileComments ¶
FileComments returns the comments recorded for a (normalized) file path.
func (*Session) HasAttachments ¶
HasAttachments errs on the side of retaining images when the directory cannot be read. Approval cleanup must not remove an unread attachment.
func (*Session) LoadDocuments ¶
func (s *Session) LoadDocuments() (DocumentAttachments, error)
func (*Session) ReplaceDocuments ¶
func (s *Session) ReplaceDocuments(docs []AttachedDocument) error
ReplaceDocuments retains removed snapshots so their comments remain readable. Callers hold the session run lock while replacing review inputs.
func (*Session) Save ¶
Save merges local edits with updates since the last load or save, then writes the result atomically under an advisory file lock.
func (*Session) SaveAttachment ¶
SaveAttachment stores an image beside review.json and returns its Markdown path.
func (*Session) SaveFormResult ¶
func (s *Session) SaveFormResult(result FormResult) error
func (*Session) SetFileComments ¶
SetFileComments replaces the comments for a file, creating its entry when missing. An empty status leaves the recorded status untouched.
func (*Session) SetSubmission ¶
SetSubmission records a round's decision and its optional review-level comment. Reusing the comment ID makes failed saves safe to retry.
func (*Session) SortedFiles ¶
SortedFiles returns the session's file paths in stable sorted order.
func (*Session) SubmissionComment ¶
type SessionEntry ¶
type SessionEntry struct {
Project *string `json:"project,omitempty"`
Topic *string `json:"topic,omitempty"`
Mode string `json:"mode,omitempty"`
PlanSlug string `json:"plan_slug,omitempty"`
Key string `json:"key"`
CWD string `json:"cwd"`
Args []string `json:"args,omitempty"`
Branch string `json:"branch,omitempty"`
ReviewPath string `json:"review_path"`
StartedAt string `json:"started_at"`
PID int `json:"pid,omitempty"`
SocketPath string `json:"socket_path,omitempty"`
}
SessionEntry records where a review session's data lives, so commands run later (status, clear, comment) can find review folders belonging to a working directory without re-deriving every possible key.
func ListSessionEntries ¶
func ListSessionEntries() ([]SessionEntry, error)
ListSessionEntries returns all registered session entries.
func ReadSessionEntry ¶
func ReadSessionEntry(key string) (*SessionEntry, error)
ReadSessionEntry loads one registry entry.
type SnapshotFile ¶
type SnapshotFile struct {
Content string `json:"content"`
Partial bool `json:"partial,omitempty"`
}
SnapshotFile preserves the text used to anchor comments across TUI restarts.