Conversation
- Replace human-oriented README with precise, AI-executable specification - Remove AGENTS.md (merged into README.md as single source of truth) - Use IF/THEN/NEVER format for rules, tables for field definitions - Number all critical rules (0.1-0.7) for cross-referencing - Add complete minimal examples (JSON API, HTML+JSON, embed.FS, middleware group) - Consolidate gin/echo/chi differences and "what xun does NOT have" - Add section and rule indexes for quick lookup Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #101 +/- ##
=======================================
Coverage 92.10% 92.10%
=======================================
Files 66 66
Lines 2102 2102
=======================================
Hits 1936 1936
Misses 136 136
Partials 30 30
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Reviewer's GuideReplaces the long, human-oriented README with a compact, rule-driven AI Agent specification that is now the single authoritative source of truth, merging AGENTS.md into it and restructuring all documentation around numbered critical rules, formal type/behavior descriptions, and minimal code examples. Sequence diagram for request handling and middleware chain in xunsequenceDiagram
actor Client
participant Server as httpServer
participant Mux as httpServeMux
participant App
participant Routing
participant Group as groupchain
participant MWA as MiddlewareA
participant MWB as MiddlewareB
participant Handler as HandleFunc
participant Ctx as Context
Client->>Server: HTTP request
Server->>Mux: ServeHTTP(request, response)
Mux->>App: wrappedHandler(response, request)
App->>Ctx: construct Context
App->>Routing: lookup Pattern and Routing
Routing->>Group: Next(HandleFunc)
Group->>MWA: apply middleware chain
MWA->>MWB: wrap(next HandleFunc)
MWB->>Handler: wrap(next HandleFunc)
Group-->>Routing: composed HandleFunc
Routing->>Ctx: Next(Ctx)
activate MWA
MWA->>MWB: next(Ctx)
activate MWB
MWB->>Handler: next(Ctx)
activate Handler
Handler-->>MWB: error or nil
deactivate Handler
MWB-->>MWA: error or ErrCancelled
deactivate MWB
MWA-->>Routing: error or ErrCancelled
deactivate MWA
Routing-->>App: error or nil
App-->>Mux: return
Mux-->>Server: return
Server-->>Client: HTTP response
Sequence diagram for Context.View viewer selection logicsequenceDiagram
participant Ctx as Context
participant Routing
participant Accept as AcceptHeaders
participant NamedV as NamedViewer
participant RouteVs as RouteViewers
participant FallbackV as FallbackViewer
participant Viewer as SelectedViewer
Ctx->>Routing: read Viewers for route
Ctx->>Accept: parse Accept() from request
alt named viewer provided
Ctx->>NamedV: lookup by name in appviewers
alt MimeType matches any Accept
Ctx->>Viewer: use NamedViewer
Viewer->>Ctx: Render(data)
else no Accept match for named viewer
Ctx->>RouteVs: iterate routingViewers with Accept
alt some viewer matches Accept
Ctx->>Viewer: use first matching viewer
Viewer->>Ctx: Render(data)
else no viewer matches Accept
Ctx->>FallbackV: use first viewer in routingViewers
alt FallbackV exists
FallbackV->>Ctx: Render(data)
else routingViewers empty
Ctx-->>Ctx: return ErrViewNotFound
end
end
end
else no named viewer
Ctx->>RouteVs: iterate routingViewers with Accept
alt some viewer matches Accept
Ctx->>Viewer: use first matching viewer
Viewer->>Ctx: Render(data)
else no viewer matches Accept
Ctx->>FallbackV: use first viewer in routingViewers
alt FallbackV exists
FallbackV->>Ctx: Render(data)
else routingViewers empty
Ctx-->>Ctx: return ErrViewNotFound
end
end
end
Class diagram for core xun types in the AI Agent specificationclassDiagram
class App {
-mux *http.ServeMux
-handlerViewers []Viewer
-fsys fs.FS
-watch bool
-interceptor Interceptor
-compressors []Compressor
-viewers mapstringViewer
-routes mapstringRouting
-funcMap templateFuncMap
+New(opts ...Option) App
+Get(pattern string, hf HandleFunc, opts ...RoutingOption)
+Post(pattern string, hf HandleFunc, opts ...RoutingOption)
+Put(pattern string, hf HandleFunc, opts ...RoutingOption)
+Delete(pattern string, hf HandleFunc, opts ...RoutingOption)
+Group(prefix string) group
+Start() void
+Close() void
}
class Context {
+Request *httpRequest
+Response ResponseWriter
+Routing Routing
+App *App
+TempData mapstringany
+View(data any, options ...string) error
+Redirect(url string, statusCode ...int) void
+AcceptLanguage() []string
+Accept() []MimeType
+RequestReferer() string
+WriteStatus(code int) void
+WriteHeader(key string, value string) void
+Get(key string) any
+Set(key string, value any) void
}
class Routing {
+Pattern string
+Handle HandleFunc
-chain chain
+Options *RoutingOptions
+Viewers []Viewer
+Next(ctx *Context) error
}
class RoutingOptions {
-metadata mapstringany
-viewers []Viewer
+WithViewer(v ...Viewer) RoutingOption
+WithMetadata(key string, value any) RoutingOption
+WithNavigation(name string, icon string, access string) RoutingOption
}
class group {
-prefix string
-middlewares []Middleware
-app *App
+Use(middleware ...Middleware) void
+Get(pattern string, hf HandleFunc, opts ...RoutingOption)
+HandleFunc(pattern string, hf HandleFunc, opts ...RoutingOption)
+Next(hf HandleFunc) HandleFunc
}
class Viewer {
<<interface>>
+MimeType() MimeType
+Render(ctx *Context, data any) error
}
class HtmlViewer {
+MimeType() MimeType
+Render(ctx *Context, data any) error
}
class JsonViewer {
+MimeType() MimeType
+Render(ctx *Context, data any) error
}
class TextViewer {
+MimeType() MimeType
+Render(ctx *Context, data any) error
}
class FileViewer {
+MimeType() MimeType
+Render(ctx *Context, data any) error
}
class ViewEngine {
<<interface>>
+Load(fsys fsFS, app *App) void
+FileChanged(fsys fsFS, app *App, event fsnotifyEvent) error
}
class StaticViewEngine {
+Load(fsys fsFS, app *App) void
+FileChanged(fsys fsFS, app *App, event fsnotifyEvent) error
}
class HtmlViewEngine {
+Load(fsys fsFS, app *App) void
+FileChanged(fsys fsFS, app *App, event fsnotifyEvent) error
}
class TextViewEngine {
+Load(fsys fsFS, app *App) void
+FileChanged(fsys fsFS, app *App, event fsnotifyEvent) error
}
class MimeType {
+Type string
+SubType string
}
class ResponseWriter {
<<interface>>
+Header() httpHeader
+Write(b []byte) int
+WriteHeader(statusCode int) void
+BodyBytesSent() int
+StatusCode() int
+Close() void
}
class Interceptor {
<<interface>>
+RequestReferer(c *Context) string
+Redirect(c *Context, url string, statusCode ...int) bool
}
class HandleFunc {
<<function>>
+invoke(c *Context) error
}
class Middleware {
<<function>>
+wrap(next HandleFunc) HandleFunc
}
class chain {
<<interface>>
+Next(hf HandleFunc) HandleFunc
}
class TEntityT {
+Data T
+Errors mapstringstring
+Validate(languages ...string) bool
}
App --> Context : creates
App --> Routing : owns
App --> ViewEngine : uses
App --> Viewer : registers handlerViewers
App --> Interceptor : uses
App --> Compressor : uses
Context --> App : backref
Context --> Routing : backref
Context --> ResponseWriter : uses
Context --> Viewer : selects in View
Context --> MimeType : via Accept
Routing --> HandleFunc : wraps
Routing --> chain : uses for middleware
group ..|> chain : implements
ViewEngine <|.. StaticViewEngine
ViewEngine <|.. HtmlViewEngine
ViewEngine <|.. TextViewEngine
Viewer <|.. HtmlViewer
Viewer <|.. JsonViewer
Viewer <|.. TextViewer
Viewer <|.. FileViewer
ResponseWriter <.. Context
HandleFunc <-- Middleware : wraps
TEntityT --> Context : used via form binding
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
 |
|
Overall Grade |
Security Reliability Complexity Hygiene |
Code Review Summary
| Analyzer | Status | Updated (UTC) | Details |
|---|---|---|---|
| Go |  |
Mar 31, 2026 1:14a.m. | Review ↗ |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="README.md" line_range="313" />
<code_context>
+ Handle HandleFunc
+ chain chain // *App or *group
+ Options *RoutingOptions
+ Viewers []Viewer // viewer's for this route
+}
```
</code_context>
<issue_to_address>
**suggestion (typo):** Fix typo in comment: "viewer’s" should be "viewers".
The comment on the `Viewers` field should use the plural "viewers" (e.g., `// viewers for this route`) rather than the possessive "viewer’s" to match the slice.
Suggested implementation:
```
Viewers []Viewer // viewers for this route
```
If the incorrect comment (`// viewer's for this route`) appears in multiple code examples or sections of the README, apply the same search/replace to each occurrence to keep the documentation consistent.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Before: "This is the authoritative specification..." → AI may skip as natural language header After: "Status: AUTHORITATIVE / Before writing any xun code, read this..." → Clear first-person directive, harder to skip Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changed
Fixed
Added
Tests
Tasks to complete before merging PR:
make unit-teststo check for any regressions 📋make lintto check for any issuesSummary by Sourcery
Rewrite the README into an AI-agent-focused, executable specification for building xun applications, consolidating prior agent-specific guidance into a single authoritative document.
Documentation: