feat(docs): add reference map flags#1547
Merged
Merged
Conversation
github-actions
Bot
added
domain/ccm
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (10)
✅ Files skipped from review due to trivial changes (2)
🚧 Files skipped from review as they are similar to previous changes (8)
📝 WalkthroughWalkthroughAdds ChangesReference-map support for docs v2 flows
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1547 +/- ##
=======================================
Coverage 74.71% 74.71%
=======================================
Files 810 810
Lines 81839 81881 +42
=======================================
+ Hits 61142 61178 +36
- Misses 16131 16135 +4
- Partials 4566 4568 +2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@e21b7144d18f8e9698e5fe08a4960bfd13baa62c🧩 Skill updatenpx skills add larksuite/cli#codex/fetch-doc-user-cite-reference-map -y -g |
SunPeiYang996
force-pushed
the
codex/fetch-doc-user-cite-reference-map
branch
3 times, most recently
from
8061f01 to
48aed20
Compare
SunPeiYang996
changed the title
SunPeiYang996
force-pushed
the
codex/fetch-doc-user-cite-reference-map
branch
from
48aed20 to
b13b7e0
Compare
SunPeiYang996
changed the title
SunPeiYang996
force-pushed
the
codex/fetch-doc-user-cite-reference-map
branch
9 times, most recently
from
83753a6 to
65fb8b5
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
shortcuts/doc/docs_update_test.go (1)
119-166: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAssert cause preservation on the invalid-JSON case.
parseUpdateReferenceMapwraps JSON decode failures with.WithCause(err), but this table test only verifies the validation subtype/param. A regression that dropserrors.Unwrapsemantics would still pass here. As per coding guidelines, "Error-path tests must assert typed metadata viaerrs.ProblemOf(category/subtype/param) and cause preservation, not message substrings alone".Suggested test tightening
+import "errors" ... tests := []struct { name string setFlags map[string]string + wantCause bool }{ { name: "invalid json", setFlags: map[string]string{ "reference-map": "{", }, + wantCause: true, }, ... err := validateUpdateV2(context.Background(), runtime) if err == nil { t.Fatal("validateUpdateV2() succeeded, want error") } assertValidationContract(t, err, errs.SubtypeInvalidArgument, "--reference-map") + if tt.wantCause && errors.Unwrap(err) == nil { + t.Fatal("validateUpdateV2() error lost underlying JSON cause") + } }) } }🤖 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/doc/docs_update_test.go` around lines 119 - 166, The invalid-JSON case in TestValidateUpdateV2RejectsInvalidReferenceMap only checks subtype and param, so it can miss regressions where parseUpdateReferenceMap stops preserving the underlying decode error. Tighten the table test for the "invalid json" input by also asserting cause preservation with errors.Unwrap or equivalent on the returned error, while keeping the existing errs.ProblemOf-style metadata checks via assertValidationContract for validateUpdateV2 and --reference-map.Source: Coding guidelines
🤖 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.
Nitpick comments:
In `@shortcuts/doc/docs_update_test.go`:
- Around line 119-166: The invalid-JSON case in
TestValidateUpdateV2RejectsInvalidReferenceMap only checks subtype and param, so
it can miss regressions where parseUpdateReferenceMap stops preserving the
underlying decode error. Tighten the table test for the "invalid json" input by
also asserting cause preservation with errors.Unwrap or equivalent on the
returned error, while keeping the existing errs.ProblemOf-style metadata checks
via assertValidationContract for validateUpdateV2 and --reference-map.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 14686fc5-ddee-4d0b-9d6a-0d87891bd02e
📒 Files selected for processing (10)
shortcuts/doc/docs_fetch_v2.goshortcuts/doc/docs_fetch_v2_test.goshortcuts/doc/docs_update_test.goshortcuts/doc/docs_update_v2.goshortcuts/drive/drive_export_test.goskills/lark-doc/references/lark-doc-update.mdtests/cli_e2e/docs/coverage.mdtests/cli_e2e/docs/docs_update_dryrun_test.gotests/cli_e2e/drive/coverage.mdtests/cli_e2e/drive/drive_export_dryrun_test.go
✅ Files skipped from review due to trivial changes (2)
- tests/cli_e2e/drive/coverage.md
- tests/cli_e2e/docs/coverage.md
🚧 Files skipped from review as they are similar to previous changes (4)
- tests/cli_e2e/docs/docs_update_dryrun_test.go
- tests/cli_e2e/drive/drive_export_dryrun_test.go
- shortcuts/drive/drive_export_test.go
- shortcuts/doc/docs_update_v2.go
Collaborator
|
Non-blocking test suggestion: for the invalid JSON case of |
SunPeiYang996
force-pushed
the
codex/fetch-doc-user-cite-reference-map
branch
from
65fb8b5 to
e21b714
Compare
fangshuyu-768
approved these changes
Jun 30, 2026
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
2 participants
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.
Summary
docs +update --reference-mapas the write-side sidecar for content that uses externalreference_mapentries.docs +fetchwithout a--reference-mapCLI field; fetch now sendsextra_param={"enable_user_cite_reference_map":true}by default.return_html5_block_dataand legacyreference_map_modeout of the docs fetch/update reference-map path, and keep drive markdown export on its no-extra_parampath.Changes
--reference-mapflag; always includeextra_param={"enable_user_cite_reference_map":true}indocs +fetchrequest body.--reference-mapas a non-empty JSON object and send it as request bodyreference_map; support direct JSON, relative@reference-map.json, and stdin via the existing flag input resolver.--reference-mapmust be used with content-bearing update commands and must accompany--content.--reference-mapfrom fetch docs; keep generic updatereference_mapsidecar wording aligned withdocs +update --help.extra_param, fetch not exposing--reference-map, update request bodyreference_map, invalid update reference-map input, and drive markdown non-impact.Test Plan
go test ./shortcuts/doc -run "TestDocsFetchV2ReferenceMapFlagIsNotAvailable|TestBuildFetchBodyIncludesFetchExtraParamByDefault|TestDocsUpdateV2ReferenceMapFlagIsPublicFileInput|TestBuildUpdateBodyIncludesReferenceMap|TestValidateUpdateV2RejectsInvalidReferenceMap" -count=1 && make build >/tmp/lark-cli-fetch-default-extra-param-build.log && ! ./lark-cli docs +fetch --help | grep -F -- "--reference-map" && ./lark-cli docs +update --help | grep -F "@reference-map.json" | grep -F "相对路径"make build >/tmp/lark-cli-fetch-default-extra-param-e2e-build.log && go test ./tests/cli_e2e/docs -run "TestDocs_DryRunDefaultsToV2OpenAPI" -count=1make build >/tmp/lark-cli-fetch-default-extra-param-unknown-build.log; then./lark-cli docs +fetch --doc doxcnDryRunE2E --reference-map --dry-runexits 2 withunknown flag "--reference-map" for "lark-cli docs +fetch".go test ./shortcuts/drive -run "TestDriveExportMarkdownWritesFile|TestDriveExportMarkdownUsesProvidedFileName|TestDriveExportDryRunIncludesLocalFileNameMetadata|TestDriveExportMarkdownFallsBackToTokenWhenTitleLookupFails" -count=1make build >/tmp/lark-cli-drive-export-e2e-build.log && go test ./tests/cli_e2e/drive -run "TestDriveExportDryRun_MarkdownFetchAPI" -count=1docs +update --reference-map "{...}"anddocs +update --reference-map @reference-map.jsonwithout--dry-run; both returnedresult=success, and a follow-updocs +fetchfound both appended markers.skills/lark-doc; it currently fails on the repository-existingversionfrontmatter key, which is present across the lark skill set and unrelated to the new--reference-maptext.Related Issues
Summary by CodeRabbit
docs +updateoption--reference-mapto send a structured reference mapping in the request body.extra_paramtoggle for citation reference handling.--reference-mapinput (only allowed for supported update commands, requires non-empty--content, and rejects invalid/empty JSON).extra_param.docs +updateparameter docs and refreshed dry-run/coverage expectations for fetch and update.