Skip to content

refactor(apps): migrate errors to typed taxonomy#1288

Open
evandance wants to merge 1 commit into
mainfrom
feat/errs-migrate-apps
Open

refactor(apps): migrate errors to typed taxonomy#1288
evandance wants to merge 1 commit into
mainfrom
feat/errs-migrate-apps

Conversation

@evandance
Copy link
Copy Markdown
Collaborator

@evandance evandance commented Jun 5, 2026

Summary

Migrate the apps shortcut domain to the typed errs.* error taxonomy so validation, file handling, SDK/API failures, and Miaoda HTML publish errors emit structured typed envelopes.

Changes

  • Replace legacy apps-domain validation and file/API error producers with typed errs.* builders and typed helper functions.
  • Switch standard apps API calls from CallAPI to CallAPITyped; keep multipart HTML publish on DoAPI while classifying responses through ClassifyAPIResponse.
  • Add apps code metadata for stable app-not-found classification and preserve endpoint-specific HTML publish recovery hints.
  • Add apps to the golangci and errscontract migrated-path guards to prevent legacy error regressions.
  • Update apps tests to assert typed problems instead of legacy output.ExitError details.

Test Plan

  • Unit tests pass
    • go test ./shortcuts/apps ./internal/errclass
    • go test ./errscontract from the lint module
    • make unit-test
  • Manual local verification confirms the lark-cli apps <command> flow works as expected
    • lark-cli apps +create --name Demo --app-type HTML --dry-run --as user
    • lark-cli apps +html-publish --app-id app_x --path <site> --dry-run --as user
  • Additional checks:
    • go vet ./...
    • gofmt -l .
    • git diff --check
    • go mod tidy produced no go.mod / go.sum diff
    • go run -C lint . ..
    • golangci-lint v2.1.6 run --new-from-rev=origin/main

Related Issues

  • None

Summary by CodeRabbit

  • Refactor

    • Improved error handling in the apps command shortcuts with structured, typed error values for better consistency and clarity.
  • Tests

    • Updated app command test cases to align with new error handling approach.
  • Chores

    • Updated linting configuration to enforce typed error patterns across the apps domain.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 5, 2026

Review Change Stack

📝 Walkthrough

Walkthrough

This PR migrates the shortcuts/apps package from legacy output-based error handling to typed errors using the errs.Problem structure. It updates validation error constructors, API call patterns, and error wrapping throughout the apps commands, plus updates tests to validate structured problem fields.

Changes

Apps Domain Typed Error Migration

Layer / File(s) Summary
Error infrastructure and lint configuration
.golangci.yml, internal/errclass/codemeta_apps.go, lint/errscontract/*
Expand typed-error lint rule scoping to the apps domain, register error code 90002 with CategoryAPI/SubtypeNotFound for apps errors, and introduce centralized apps_errors.go helper functions for validation, file-IO, precondition, and API-boundary errors.
Simple command implementations
shortcuts/apps/apps_access_scope_get.go, shortcuts/apps/apps_create.go, shortcuts/apps/apps_list.go, shortcuts/apps/apps_update.go
Refactor list, create, and update commands to return appsValidationParamError instead of output.ErrValidation, remove internal/output imports, and switch API calls from CallAPI to CallAPITyped.
Access scope set validation and execution
shortcuts/apps/apps_access_scope_set.go
Update --app-id, --scope, and --targets flag validation to use appsValidationParamError with comprehensive error messages and cause-chaining for JSON unmarshal failures; switch PATCH request to CallAPITyped.
HTML publish command, client, and file operations
shortcuts/apps/apps_html_publish.go, shortcuts/apps/html_publish_client.go, shortcuts/apps/html_publish_tarball.go, shortcuts/apps/walk_html_publish_candidates.go
Replace validation and size-limit errors with appsValidationParamError(...).WithHint(), update client to use ClassifyAPIResponse for error wrapping, refactor tarball packing and path walking to use typed error constructors instead of fmt.Errorf, and wrap API errors via appsAPIBoundaryError and enrichHTMLPublishAPIError.
Test updates for error assertions
shortcuts/apps/apps_create_test.go, shortcuts/apps/apps_html_publish_test.go, shortcuts/apps/html_publish_client_test.go
Introduce requireAppsProblem test helper and category-specific wrappers to validate *errs.Problem structure; replace all output.ExitError detail inspections with assertion of structured problem fields (Message, Hint, Code, Subtype).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

  • larksuite/cli#1002: Introduces the "apps" typed-error domain that this PR builds upon, adding initial appsCodeMeta and error infrastructure.
  • larksuite/cli#1072: Modifies the same shortcuts/apps/apps_html_publish.go validation flow—credential-file sensitivity logic that the main PR refactors to use app-scoped typed errors.
  • larksuite/cli#1250: Related via the same typed-error lint enforcement pattern—expands migratedEnvelopePaths for another domain (mail) and follows the same internal/errclass/codemeta_*.go registration pattern.

Suggested labels

size/L, feature

Suggested reviewers

  • liangshuo-1

Poem

🐰 Hop, hop! The apps now speak in typed tongue,
No legacy output helpers to be wrung,
Each error bears a problem so profound,
With hints and codes all neatly bound.
The tests assert with categories true,
A cleaner migration, shiny and new!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 23.53% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: migrating the apps domain to a typed error taxonomy.
Description check ✅ Passed The description includes all required template sections with comprehensive details: summary, changes, test plan with verification steps, and related issues.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/errs-migrate-apps

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions github-actions Bot added the size/L Large or sensitive change across domains or core paths label Jun 5, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Jun 5, 2026

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@deb12ebc1a5363b0b9515dfb9f442e2d9acf73b1

🧩 Skill update

npx skills add larksuite/cli#feat/errs-migrate-apps -y -g

@codecov
Copy link
Copy Markdown

codecov Bot commented Jun 5, 2026

Codecov Report

❌ Patch coverage is 67.28972% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.33%. Comparing base (f3949f0) to head (deb12eb).

Files with missing lines Patch % Lines
shortcuts/apps/apps_errors.go 65.71% 6 Missing and 6 partials ⚠️
shortcuts/apps/apps_access_scope_set.go 60.86% 9 Missing ⚠️
shortcuts/apps/walk_html_publish_candidates.go 20.00% 4 Missing ⚠️
shortcuts/apps/apps_html_publish.go 81.25% 3 Missing ⚠️
shortcuts/apps/apps_create.go 50.00% 2 Missing ⚠️
shortcuts/apps/html_publish_tarball.go 71.42% 2 Missing ⚠️
shortcuts/apps/apps_access_scope_get.go 50.00% 1 Missing ⚠️
shortcuts/apps/apps_update.go 85.71% 1 Missing ⚠️
shortcuts/apps/html_publish_client.go 83.33% 1 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1288   +/-   ##
=======================================
  Coverage   70.33%   70.33%           
=======================================
  Files         672      674    +2     
  Lines       65322    65357   +35     
=======================================
+ Hits        45941    45966   +25     
- Misses      15728    15733    +5     
- Partials     3653     3658    +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
shortcuts/apps/html_publish_client_test.go (1)

21-31: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add config-dir isolation in the test runtime helper.

newAppsClientRuntime uses cmdutil.TestFactory but does not isolate config state. This can leak state across tests when config-backed paths are touched.

💡 Suggested fix
 func newAppsClientRuntime(t *testing.T) (*common.RuntimeContext, *httpmock.Registry) {
 	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	cfg := &core.CliConfig{
 		AppID:      "test-app-" + strings.ToLower(t.Name()),
 		AppSecret:  "test-secret",
 		Brand:      core.BrandFeishu,
 		UserOpenId: "ou_test",
 	}

As per coding guidelines: **/*_test.go must Use t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir()) to isolate config state in tests.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@shortcuts/apps/html_publish_client_test.go` around lines 21 - 31, The test
helper newAppsClientRuntime should isolate config state: before calling
cmdutil.TestFactory set the environment var LARKSUITE_CLI_CONFIG_DIR to a temp
dir via t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir()), so tests don't share
config-backed paths; update newAppsClientRuntime to call t.Setenv(...) as the
first action in the function (reference newAppsClientRuntime and the call site
cmdutil.TestFactory).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@shortcuts/apps/html_publish_client_test.go`:
- Around line 21-31: The test helper newAppsClientRuntime should isolate config
state: before calling cmdutil.TestFactory set the environment var
LARKSUITE_CLI_CONFIG_DIR to a temp dir via t.Setenv("LARKSUITE_CLI_CONFIG_DIR",
t.TempDir()), so tests don't share config-backed paths; update
newAppsClientRuntime to call t.Setenv(...) as the first action in the function
(reference newAppsClientRuntime and the call site cmdutil.TestFactory).

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cad262b6-f9b7-409c-93ee-75177089ac7c

📥 Commits

Reviewing files that changed from the base of the PR and between f3949f0 and deb12eb.

📒 Files selected for processing (17)
  • .golangci.yml
  • internal/errclass/codemeta_apps.go
  • lint/errscontract/rule_no_legacy_common_helper_call.go
  • lint/errscontract/rule_no_legacy_envelope_literal.go
  • shortcuts/apps/apps_access_scope_get.go
  • shortcuts/apps/apps_access_scope_set.go
  • shortcuts/apps/apps_create.go
  • shortcuts/apps/apps_create_test.go
  • shortcuts/apps/apps_errors.go
  • shortcuts/apps/apps_html_publish.go
  • shortcuts/apps/apps_html_publish_test.go
  • shortcuts/apps/apps_list.go
  • shortcuts/apps/apps_update.go
  • shortcuts/apps/html_publish_client.go
  • shortcuts/apps/html_publish_client_test.go
  • shortcuts/apps/html_publish_tarball.go
  • shortcuts/apps/walk_html_publish_candidates.go

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/L Large or sensitive change across domains or core paths

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant