Snider 8ffd10c2ac

Security Scan / security (push) Waiting to run

Details

Test / test (push) Waiting to run

Details

fix(session): address all CodeRabbit findings on PR #5

6+ findings dispositioned. AX-6 maintained (stale testify refs removed).

Code:
- parser_test.go: fixed EOF-truncated JSONL fixtures
- parser.go: ListSessionsSeq skips transcripts when quick scan fails;
  added oversized-line coverage
- parser.go: symlink pre-check replaced with O_NOFOLLOW descriptor
  opens + Fstat for FetchSession and ListSessionsSeq (TOCTOU-safe)
- test_helpers_test.go: assert* helpers changed from fatal to
  non-fatal reporting
- tests/cli/session/main.go: derived expectations from current code
  (CodeRabbit's suggested literals were incorrect for current impl)
  + filepath.Join nit; preserved correct behaviour

CI / config:
- .golangci.yml: migrated to v2 schema
- tests/cli/session/Taskfile.yaml: 'test' broadened to run go vet +
  go test + CLI smoke
- PR title: made specific

Doc:
- AX-2 docstring coverage: comments added to all Go funcs in touched
  files (closes pre-merge docstring warning)
- README + CLAUDE.md + CODEX.md + CONTEXT.md + TODO.md +
  docs/{architecture,development,index}.md + kb/Home.md: removed
  stale testify references, aligned to stdlib testing

Disposition:
- SonarCloud / GHAS: no separate PR comments/checks; gh pr checks
  only reports CodeRabbit. RESOLVED-COMMENT.

Verification: gofmt clean, golangci-lint v2 0 issues, GOWORK=off
go vet + go test -count=1 ./... pass with explicit cache paths,
task -d tests/cli/session clean.

Closes findings on https://github.com/dAppCore/go-session/pull/5

Co-authored-by: Codex <noreply@openai.com>

2026-04-27 18:17:50 +01:00

3.2 KiB

Raw Blame History

CODEX.md

This file provides guidance to Codex when working in this repository.

Claude Code JSONL transcript parser, analytics engine, and HTML/video renderer. Module: dappco.re/go/session

Commands

go test ./...                              # Run all tests
go test -v -run TestFunctionName_Context   # Run single test
go test -race ./...                        # Race detector
go test -bench=. -benchmem ./...           # Benchmarks
go vet ./...                               # Vet
golangci-lint run ./...                    # Lint (optional, config in .golangci.yml)

Architecture

Single-package library (package session) with five source files forming a pipeline:

parser.go — Core JSONL parser. Reads Claude Code session files line-by-line (8 MiB scanner buffer), correlates tool_use/tool_result pairs via a pendingTools map keyed by tool ID, and produces Session with []Event. Also handles session listing, fetching, and pruning.
analytics.go — Pure computation over []Event. Analyse() returns SessionAnalytics (per-tool counts, error rates, latency stats, token estimates). No I/O.
html.go — RenderHTML() generates a self-contained HTML file (inline CSS/JS, dark theme, collapsible panels, client-side search). All user content is html.EscapeString-escaped.
video.go — RenderMP4() generates a VHS .tape script and shells out to vhs. Requires vhs on PATH.
search.go — Search()/SearchSeq() does cross-session case-insensitive substring search over tool event inputs and outputs.

Both slice-returning and iter.Seq variants exist for ListSessions, Search, and Session.EventsSeq.

Adding a new tool type

Touch all layers: add input struct in parser.go → case in extractToolInput → label in html.go RenderHTML → tape entry in video.go generateTape → tests in parser_test.go.

Testing

Tests are white-box (package session). Test helpers in parser_test.go build synthetic JSONL in-memory — no fixture files. Use writeJSONL(t, dir, name, lines...) and the entry builders (toolUseEntry, toolResultEntry, userTextEntry, assistantTextEntry).

Naming convention: TestFile_Function_Good/Bad/Ugly (group by file, collapse the specific behaviour into the function segment, and suffix with happy path / expected errors / extreme edge cases).

Coverage target: maintain ≥90.9%.

Coding Standards

UK English throughout (colour, licence, initialise)
Explicit types on all function signatures and struct fields
Exported declarations must have Go doc comments beginning with the identifier name and include an Example: usage snippet
go test ./... and go vet ./... must pass before commit
SPDX header on all source files: // SPDX-Licence-Identifier: EUPL-1.2
Error handling: all package errors must use core.E(op, msg, err) from dappco.re/go/core; do not use core.NewError, fmt.Errorf, or errors.New
Banned imports in non-test Go files: errors, github.com/pkg/errors, and legacy forge.lthn.ai/... paths
Conventional commits: type(scope): description
Co-Author trailer: Co-Authored-By: Virgil <virgil@lethean.io>

The conventions test suite enforces banned imports, exported usage comments, and test naming via go test ./....

3.2 KiB Raw Blame History