mirror of
https://github.com/larksuite/cli.git
synced 2026-09-14 18:42:53 +08:00
evandance
99e314fe0b
Every failure on the authentication, authorization, and configuration
path now surfaces as a typed structured error instead of an ad-hoc
envelope. Users and scripts that consume CLI output get:
- a fixed nine-category taxonomy on the wire, each mapped to a
stable shell exit code (authentication/authorization/config = 3,
network = 4, internal = 5, policy = 6, confirmation = 10)
- identity-aware detail fields (missing_scopes, requested_scopes,
granted_scopes, console_url, log_id, retryable, hint) carried
uniformly on the envelope
- a single canonical policy envelope at exit 6; the legacy
auth_error carve-out is retired
- per-subtype canonical message + hint that preserves Lark's
diagnostic phrasing and routes recovery to the right actor:
app developer (app_scope_not_applied), user (missing_scope,
token_scope_insufficient, user_unauthorized), or tenant admin
(app_unavailable, app_disabled)
- wrong app credentials classify as config/invalid_client whether
surfaced by the Open API endpoint (99991543) or the tenant
access-token mint endpoint (10003 / 10014), instead of
collapsing to a transport error or api/unknown
- local shortcut scope preflight emits the same
authorization/missing_scope envelope (identity + deterministic
missing-scope set) used by the post-call permission path, so AI
consumers read the same structured shape from precheck and from
server-returned permission denial
- streaming download/upload failures keep the same network subtype
split (timeout / TLS / DNS / transport) as the non-stream path
instead of collapsing every cause to a generic transport failure
- console_url is carried only on the bot-perspective
app_scope_not_applied envelope (where the recovery action is
"developer applies the scope at the developer console"); the
user-perspective missing_scope envelope drops the field, since
the only actionable user recovery is `lark-cli auth login --scope`
and pointing an end user at a console they cannot modify is
misleading
- bind workflows (Hermes / OpenClaw / lark-channel) flatten dynamic
Type tags to wire 'config' with the original module name kept
as a metric label
All 10 typed errors are cause-bearing, nil-safe on .Error() and
.Unwrap(), and defensively clone slice setter inputs. Four lint
rules (CheckNilSafeError / CheckBuilderImmutable / CheckUnwrapSymmetry
/ CheckBuildAPIErrorArms) lock these invariants on migrated paths.
69 lines
2.2 KiB
Go
69 lines
2.2 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package errscontract
|
|
|
|
import (
|
|
"go/parser"
|
|
"go/token"
|
|
)
|
|
|
|
// CheckUnwrapSymmetry enforces that every typed *Error struct embedding
|
|
// Problem defines its own nil-safe Unwrap() method, mirroring the Error()
|
|
// nil-guard contract enforced by CheckNilSafeError.
|
|
//
|
|
// Why: typed errors carry a Cause field and downstream callers traverse
|
|
// it via errors.Unwrap / errors.Is. A typed-nil holder
|
|
// (`var e *XxxError; var err error = e`) would otherwise dispatch through
|
|
// the embedded Problem.Unwrap (or panic when none exists), bypassing the
|
|
// type's own intent.
|
|
//
|
|
// Scope: errs/ package files. Unexported helper structs are skipped.
|
|
//
|
|
// Returns REJECT violations.
|
|
func CheckUnwrapSymmetry(path, src string) []Violation {
|
|
if !isErrsPackagePath(path) {
|
|
return nil
|
|
}
|
|
fset := token.NewFileSet()
|
|
file, err := parser.ParseFile(fset, path, src, parser.ParseComments)
|
|
if err != nil {
|
|
return nil
|
|
}
|
|
|
|
embedders := collectProblemEmbedders(file)
|
|
if len(embedders) == 0 {
|
|
return nil
|
|
}
|
|
|
|
unwrapMethods := collectMethodsNamed(file, "Unwrap")
|
|
|
|
var out []Violation
|
|
for name, pos := range embedders {
|
|
fn, ok := unwrapMethods[name]
|
|
if !ok {
|
|
out = append(out, Violation{
|
|
Rule: "unwrap_symmetry",
|
|
Action: ActionReject,
|
|
File: path,
|
|
Line: fset.Position(pos).Line,
|
|
Message: "typed error " + name + " embeds Problem but defines no own Unwrap() — typed-nil holders cannot be safely traversed by errors.Unwrap",
|
|
Suggestion: "add `func (e *" + name + ") Unwrap() error { if e == nil { return nil }; return e.Cause }` " +
|
|
"so the typed envelope and the standard errors.Is/Unwrap traversal stay in sync",
|
|
})
|
|
continue
|
|
}
|
|
if !hasNilReceiverGuard(fn) {
|
|
out = append(out, Violation{
|
|
Rule: "unwrap_symmetry",
|
|
Action: ActionReject,
|
|
File: path,
|
|
Line: fset.Position(fn.Pos()).Line,
|
|
Message: "typed error " + name + ".Unwrap() lacks `if e == nil { return nil }` nil-receiver guard",
|
|
Suggestion: "first statement of " + name + ".Unwrap() must be the nil-receiver guard so errors.Unwrap on a typed-nil holder returns nil instead of panicking",
|
|
})
|
|
}
|
|
}
|
|
return out
|
|
}
|