fix(docs): resolve wiki links before fetch

[sunzhipenghit]

Summary

• Resolve wiki document URLs through wiki/v2/spaces/get_node before calling docs_ai/v1/documents/:document_id/fetch.
• Add dry-run output that shows the wiki resolution step before the fetch request.
• Reject wiki nodes that resolve to non-doc/docx objects with a targeted validation hint.

Fixes #1034

Validation

• go test ./shortcuts/doc -run 'TestDocsFetchWiki|TestDocsFetchDryRunWiki'
• go test ./shortcuts/doc
• make unit-test
• make fmt-check
• make vet
• git diff --check

Summary by CodeRabbit

• New Features

  • docs +fetch now supports wiki document links by resolving them to the underlying document before fetching.
  • Dry-run output now reflects the extra resolve step and includes method details for API calls.

• Bug Fixes

  • Fetches now use the resolved document ID instead of the original wiki reference.
  • Improved error handling when a wiki link points to an unsupported node type or returns incomplete data.

• Tests

  • Added coverage for wiki-based fetch flows, dry-run behavior, and validation errors.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds wiki URL support to the docs +fetch command. A new resolveDocumentID helper in helpers.go calls the wiki get_node API to resolve a wiki token into an underlying docx/doc token, returning a typed validation error for non-document node types. Both the dry-run and execute paths in docs_fetch_v2.go are updated to branch on ref.Kind and invoke this resolution step before the OpenAPI fetch.

Changes

Wiki document resolution for docs +fetch

Layer / File(s)	Summary
Wiki resolution helper and type hint shortcuts/doc/helpers.go	Adds wikiGetNodePath constant, resolveDocumentID (calls wiki node API, validates obj_type is docx/doc, returns typed errors for incomplete response, unsupported type, or unknown kind), and docShortcutHintForWikiType (maps wiki object types to CLI shortcut hint strings).
Wire resolution into dryRun and execute paths shortcuts/doc/docs_fetch_v2.go	dryRunFetchV2 branches on ref.Kind: emits a 2-step dry-run for wiki (GET resolve + POST fetch with resolved-token placeholder) or a single POST for non-wiki. executeFetchV2 calls resolveDocumentID before building the fetch URL, using the resolved ID.
Tests and dry-run schema update shortcuts/doc/doc_media_test.go, shortcuts/doc/docs_fetch_v2_test.go	Adds Method field to docDryRunOutput's API entry struct. Adds three tests covering: wiki dry-run emits two API calls with correct URLs, wiki fetch uses resolved document token, and non-document wiki node type returns a SubtypeInvalidArgument error.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• larksuite/cli#334: Modifies the same docDryRunOutput API entry struct in shortcuts/doc/doc_media_test.go by adding a different field (Params), making it structurally related to this PR's addition of the Method field.

Suggested labels

size/M, domain/ccm

Suggested reviewers

• SunPeiYang996
• fangshuyu-768
• caojie0621

Poem

🐇 Hopping down the wiki trail,
I sniff the node to find the tale,
get_node called, obj_type checked —
only docx and doc are blessed! 🌿
Two-step dry-run, clean and bright,
Wiki docs now fetch just right. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% 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 states the main change: resolving wiki links before fetch.
Description check	✅ Passed	The description covers the summary and validation, and it references the related issue even though the template headings are not exact.
Linked Issues check	✅ Passed	The PR resolves wiki-prefixed doc fetches via node resolution and adds the requested handling for invalid wiki node types.
Out of Scope Changes check	✅ Passed	The changes stay focused on wiki document resolution, fetch behavior, dry-run output, and tests.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@shortcuts/doc/helpers.go`:
- Line 97: The validation error in the wiki type mismatch path is mixing the
failure message with recovery guidance. Update the return in the relevant helper
that builds the `errs.NewValidationError(...)` so the message only states that
`docs +fetch` resolved to the wrong wiki node type, and move the “use the
matching shortcut / run drive +inspect” text into `.WithHint(...)` on that
error. Keep `docShortcutHintForWikiType(...)` as the source for the typed
guidance so callers and tests can consume it consistently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a3aa2f2b-1bae-4929-8250-2bf5715b397a

📥 Commits

Reviewing files that changed from the base of the PR and between b3514e5 and d599df1.

📒 Files selected for processing (4)

• shortcuts/doc/doc_media_test.go
• shortcuts/doc/docs_fetch_v2.go
• shortcuts/doc/docs_fetch_v2_test.go
• shortcuts/doc/helpers.go

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Move remediation guidance into .WithHint(...).

Line 97 puts recovery guidance in the validation error message. Keep the message focused on the failure and move “use the matching shortcut / drive +inspect” into .WithHint(...) so callers/tests can consume typed guidance consistently.

As per coding guidelines, “recovery guidance goes in .WithHint(...).”

🤖 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/helpers.go` at line 97, The validation error in the wiki type
mismatch path is mixing the failure message with recovery guidance. Update the
return in the relevant helper that builds the `errs.NewValidationError(...)` so
the message only states that `docs +fetch` resolved to the wrong wiki node type,
and move the “use the matching shortcut / run drive +inspect” text into
`.WithHint(...)` on that error. Keep `docShortcutHintForWikiType(...)` as the
source for the typed guidance so callers and tests can consume it consistently.

Source: Coding guidelines