mirror of
https://github.com/larksuite/cli.git
synced 2026-07-03 14:02:43 +08:00
fe72e41fb2
Introduce a typed error contract framework for lark-cli so in-process
Go callers can branch via errors.As(&errs.XxxError{}) and shell scripts,
AI agents, and protocol adapters can branch on stable JSON type/subtype
fields instead of regex-parsing free-form messages.
Adds:
- Canonical taxonomy under errs/ (9 categories + typed Error structs
embedding a shared Problem, RFC 7807-aligned)
- Centralized Lark code metadata + identity-aware BuildAPIError dispatch
- Typed JSON envelope writer alongside the legacy envelope writer
- MCP / OAuth (RFC 6750 Bearer) projection adapters
- Five CI lint guards preventing ad-hoc taxonomy drift
Backward compatibility: legacy *output.ExitError producers (ErrAPI,
ErrWithHint, Errorf, ErrBare) and business shortcuts that use them
continue to render the legacy envelope unchanged. SecurityPolicyError
wire format and exit code are preserved via a carve-out; taxonomy
migration is deferred to PR 2. Domain-specific business migration is
staged across PR 3+.
Framework-direct paths now return typed *errs.*Error: ErrAuth /
ErrValidation / ErrNetwork emit category literals on the wire
(authentication / validation / network), *core.ConfigError is promoted
at the cmd/root boundary with exit code aligned from 2 to 3, and Lark
API permission denials classified by BuildAPIError exit 3.
At the SDK boundary, WrapDoAPIError preserves any already-classified
error (legacy *output.ExitError or typed *errs.*) so output.ErrAuth
from missing credentials surfaces with the auth category and exit 3
intact instead of being downgraded to a network error. Policy responses
classified by BuildAPIError (codes 21000 / 21001) extract challenge_url
and the canonical hint from the response body, matching what the
auth transport already surfaces at the HTTP layer; non-https
challenge URLs are dropped.
First PR in the feat/error-contract-* series.
77 lines
2.2 KiB
Go
77 lines
2.2 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package errscontract
|
|
|
|
import (
|
|
"go/ast"
|
|
"go/parser"
|
|
"go/token"
|
|
"strings"
|
|
)
|
|
|
|
// CheckProblemEmbed enforces the errs/ typed-error contract on a single
|
|
// source file: every exported struct whose name ends in "Error" must embed the
|
|
// package-local Problem (or errs.Problem when imported).
|
|
//
|
|
// Predicate + test-coverage parity are checked at the directory level by
|
|
// CheckErrsContract; this AST-only entry is the unit-testable core.
|
|
func CheckProblemEmbed(path, src string) []Violation {
|
|
fset := token.NewFileSet()
|
|
file, err := parser.ParseFile(fset, path, src, parser.ParseComments)
|
|
if err != nil {
|
|
return nil
|
|
}
|
|
var out []Violation
|
|
ast.Inspect(file, func(n ast.Node) bool {
|
|
typeSpec, ok := n.(*ast.TypeSpec)
|
|
if !ok {
|
|
return true
|
|
}
|
|
structType, ok := typeSpec.Type.(*ast.StructType)
|
|
if !ok {
|
|
return true
|
|
}
|
|
name := typeSpec.Name.Name
|
|
// Only enforce CheckProblemEmbed on EXPORTED *Error types — unexported helper
|
|
// structs that happen to end in "Error" are internal scratch types,
|
|
// not part of the typed taxonomy.
|
|
if !ast.IsExported(name) || !strings.HasSuffix(name, "Error") {
|
|
return true
|
|
}
|
|
if !embedsProblem(structType) {
|
|
out = append(out, Violation{
|
|
Rule: "problem_embed",
|
|
Action: ActionReject,
|
|
File: path,
|
|
Line: fset.Position(typeSpec.Pos()).Line,
|
|
Message: "typed error " + name + " must embed errs.Problem (RFC 7807-aligned canonical shape)",
|
|
Suggestion: "add `errs.Problem` (or `Problem` if in errs package) as the first embedded field",
|
|
})
|
|
}
|
|
return true
|
|
})
|
|
return out
|
|
}
|
|
|
|
// embedsProblem reports whether the struct embeds the canonical Problem type
|
|
// (bare `Problem` when defined in errs, or `errs.Problem` when imported).
|
|
func embedsProblem(s *ast.StructType) bool {
|
|
for _, f := range s.Fields.List {
|
|
if len(f.Names) != 0 {
|
|
continue // not embedded
|
|
}
|
|
switch t := f.Type.(type) {
|
|
case *ast.Ident:
|
|
if t.Name == "Problem" {
|
|
return true
|
|
}
|
|
case *ast.SelectorExpr:
|
|
if x, ok := t.X.(*ast.Ident); ok && x.Name == "errs" && t.Sel != nil && t.Sel.Name == "Problem" {
|
|
return true
|
|
}
|
|
}
|
|
}
|
|
return false
|
|
}
|