fix(check): 구조 분해 인자의 @param 누락을 오류로 보고

[chungyo]

문제

구조 분해 인자에 @param이 없어도 docflow check가 문서 검증을 통과하는 문제를 수정합니다. 예를 들어 아래 함수를 검사하면 수정 전에는 성공 메시지와 종료 코드 0을 반환합니다.

/**
 * @public
 * @returns The greeting
 */
export function greet({ name }: { name: string }): string {
  return name;
}

기대 동작은 누락된 인자를 보고하고 종료 코드 1을 반환하는 것입니다. 수정 후에는 다음 진단이 출력됩니다.

packages/core/src/index.ts:greet - missing @param for '{ name }'

변경 내용

resolveDestructuredNames는 구조 분해 인자에 사용할 JSDoc root 이름을 찾지 못하면 빈 배열을 반환합니다. 이 때문에 해당 인자가 후속 누락 검사 대상에서 사라집니다.

이 경우 실제 binding 문자열인 entry.name을 남겨 기존 findMissingDocs가 missing_param을 생성하도록 변경합니다. 문서에 없는 root 이름을 추측하지 않으며, 문서가 있는 인자의 virtual root와 중첩 속성 매핑은 기존 로직을 사용합니다.

다음 3가지 회귀 테스트와 patch changeset을 추가합니다.

• 구조 분해 인자 하나에 root @param이 없는 경우
• 구조 분해 인자가 둘이고 첫 번째만 문서화한 경우
• 일반 인자는 문서화했지만 함께 있는 구조 분해 인자는 문서화하지 않은 경우

검증

• 추가한 3개 테스트 모두 수정 전 잘못된 isValid: true로 실패했고, 수정 후 기존 테스트를 포함한 FunctionValidator 테스트 30개가 통과했습니다.
• yarn format:check, yarn lint, yarn build, yarn typecheck, yarn test: 모두 통과. CLI 패키지 테스트는 231개입니다.
• 소스 CLI와 빌드한 packages/cli/bin/cli.js를 각각 별도의 최소 workspace에서 실행해 아래 7가지 입력을 확인했습니다.

입력	수정 후 종료 코드	확인 결과
위 3가지 구조 분해 인자 누락	1	누락된 binding을 진단
일반 인자의 @param 누락	1	기존 오류 검출 유지
구조 분해 인자의 root와 속성 모두 문서화	0	정상 문서 통과
일반 인자와 구조 분해 인자를 모두 문서화	0	정상 문서 통과
인자가 없는 함수	0	정상 문서 통과

로컬 검증 환경: Node 22.23.1, Yarn 4.9.1, node-modules linker. 의존성 및 lockfile 변경은 없습니다.

[vercel]

@chungyo is attempting to deploy a commit to the Toss Team on Vercel.

A member of the Team first needs to authorize it.