wip

Gumball12 · Gumball12 · commit dc3309b4eed1 · 2025-11-18T12:27:48.000+09:00
diff --git a/docs/WHY.md b/docs/WHY.md
@@ -1,3 +1,5 @@
+<!-- 업데이트 -->
+
 # Why Yuki-no
 
 Technical docs translation helps more people use technology and grows the open-source community. Many translation projects build their own processes using open-source tools instead of commercial solutions. This choice offers better cost control, scalability, flexibility, and data ownership.
@@ -36,7 +38,7 @@ _Example: Yuki-no automatically creates an issue for new commits in the head rep
 Yuki-no improves on existing solutions with several reliability enhancements:
 
 - Keeps tracking accurate even when Actions fail by using successful run timestamps
-- Uses retry systems for GitHub API failures
+- Built-in retry and rate-limit handling for GitHub API calls
 - Provides detailed logs for better troubleshooting
 
 These improvements ensure no commits are missed, even in challenging situations like Action failures or API rate limits. By tracking only successful Action runs as checkpoints, Yuki-no prevents losing commits during temporary failures. It automatically resumes from the last successful point. This makes it especially reliable for projects with frequent documentation updates.
@@ -65,6 +67,12 @@ Yuki-no addresses these diverse requirements through an extensible [plugin archi
 - **Custom Workflow Integration:** Hook into various stages of the tracking process to match your specific needs
 - **Modular Functionality:** Enable only the features you need, keeping your setup simple or complex as required
 - **Community Contributions:** Develop and share plugins with the community for common use cases
+- **Zero Install in Repo:** Plugins are automatically installed in GitHub Actions; you only list them in the workflow
+
+Built-in/official plugins illustrate how the system scales:
+
+- `@yuki-no/plugin-release-tracking`: Tracks release status per commit and updates labels/comments automatically
+- `@yuki-no/plugin-batch-pr`: Collects open translation issues and creates a single pull request consolidating changes (with exclusion patterns and optional root-dir mapping)
 
 For instance, the built-in `release-tracking` plugin provides automated release status tracking using Issue Comments and Labels for projects where release management is critical. This plugin-based approach allows teams to build exactly the translation management system they need, whether simple or complex, while maintaining compatibility and ease of use.
 
@@ -81,7 +89,7 @@ Yuki-no enhances GitHub Issues-based workflows with organizational features. The
 - Filter and manage translation tasks easily
 - Keep translation issues separate from general issues
 
-These improvements create a more organized and efficient translation process while using GitHub's familiar interface.
+These improvements create a more organized and efficient translation process while using GitHub's familiar interface. When combined with plugins like `release-tracking` and `batch-pr`, teams can coordinate what is ready for release and consolidate approved work into streamlined pull requests.
 
 ### Yuki-no
 
@@ -91,6 +99,7 @@ Yuki-no delivers all three essential features for technical docs translation pro
 - Offers simpler and clearer configuration
 - Provides `include` and `exclude` options based on [Glob patterns](https://github.com/micromatch/picomatch?tab=readme-ov-file#advanced-globbing)
 - Includes a `verbose` option for detailed logging
+- Supports an official plugin ecosystem (release tracking, batch PR)
 
 If you want to start a translation project or add Yuki-no to an existing one, check out the [main guide](../README.md). For users of issue-based translation processes like Ryu-Cho, we have a [migration guide](./MIGRATION.md). For real examples, see the [vite/docs-ko repo](https://github.com/vitejs/docs-ko/blob/main/.github/workflows/sync.yml).
 
diff --git a/packages/batch-pr/README.md b/packages/batch-pr/README.md
@@ -7,6 +7,17 @@ Collects opened Yuki-no translation issues and creates a single pull request to
 ## Usage
 
 ```yaml
+permissions:
+  # Default yuki-no permissions
+  issues: write
+  actions: read
+
+  # Required for branch creation and push operations
+  contents: write
+
+  # Required for batch PR creation
+  pull-requests: write
+
 - uses: Gumball12/yuki-no@v1
   env:
     # [optional]
@@ -15,7 +26,8 @@ Collects opened Yuki-no translation issues and creates a single pull request to
     YUKI_NO_BATCH_PR_ROOT_DIR: head-repo-dirname
 
     # [optional]
-    # file patterns that should be excluded from batch PR
+    # file patterns based on `head-repo`
+    # that should be excluded from batch PR
     YUKI_NO_BATCH_PR_EXCLUDE: |
       head-repo-patterns
   with:
diff --git a/packages/batch-pr/utils/createPrBody.ts b/packages/batch-pr/utils/createPrBody.ts
@@ -11,6 +11,8 @@ type PrBodyOptions = {
   excludedFiles?: string[];
 };
 
+// TODO: YUKI_NO_BATCH_PR_ROOT_DIR 이용해 여기 기준으로 excluded files 필터링 & 명시해야 함
+// 안그럼 필요하지도 않은 애들까지 포함되어서 너무 길어지고 많아진다...
 export const createPrBody = (
   issueStatus: BatchIssueStatus[],
   { excludedFiles } = {} as PrBodyOptions,
diff --git a/packages/core/index.ts b/packages/core/index.ts
@@ -83,7 +83,10 @@ const syncCommits = async (
     await p.onBeforeCompare?.({ ...ctx });
   }
 
-  const latestSuccessfulRun = await getLatestSuccessfulRunISODate(github);
+  const latestSuccessfulRun = await getLatestSuccessfulRunISODate(
+    github,
+    false,
+  );
   const commits = getCommits(config, git, latestSuccessfulRun);
   const notCreatedCommits = await lookupCommitsInIssues(github, commits);
 
diff --git a/packages/core/tests/mockedRequests.test.ts b/packages/core/tests/mockedRequests.test.ts
@@ -14,6 +14,7 @@ const ALLOWED_REPO = `${TEST_REPO.owner}/${TEST_REPO.repo}`;
 const auth = process.env.MOCKED_REQUEST_TEST;
 const shouldRunTests = isCI && currRepo === ALLOWED_REPO && auth;
 
+// TODO: race condition 발생되지 않도록 테스트별로 서로 분리된 이슈 하나 만들어 그 안에서 진행
 describe('GitHub API Integration Tests', () => {
   if (!shouldRunTests) {
     it.skip('Skipping tests - not in CI environment or not in allowed repository', () => {
diff --git a/packages/core/tests/utils-infra/getLatestSuccessfulRunISODate.test.ts b/packages/core/tests/utils-infra/getLatestSuccessfulRunISODate.test.ts
@@ -1,61 +1,115 @@
 import { GitHub } from '../../infra/github';
 import { getLatestSuccessfulRunISODate } from '../../utils-infra/getLatestSuccessfulRunISODate';
 
-import { beforeEach, expect, it, vi } from 'vitest';
-
-const ACTION_NAME = 'yuki-no';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 const mockListWorkflowRunsForRepo = vi.fn();
 
 vi.mock('../../infra/github', () => ({
   GitHub: vi.fn().mockImplementation(() => ({
-    api: { actions: { listWorkflowRunsForRepo: mockListWorkflowRunsForRepo } },
+    api: {
+      rest: {
+        actions: {
+          listWorkflowRunsForRepo: mockListWorkflowRunsForRepo,
+        },
+      },
+    },
+    ownerAndRepo: { owner: 'test-owner', repo: 'test-repo' },
+    configuredLabels: ['label1', 'label2'],
   })),
 }));
 
-const MOCK_CONFIG = {
-  accessToken: 'test-token',
-  labels: ['test-label'],
-  repoSpec: {
-    owner: 'test-owner',
-    name: 'test-repo',
-    branch: 'main',
-  },
-};
+vi.mock('../../utils-infra/getTranslationIssues', () => ({
+  getTranslationIssues: vi.fn(),
+}));
 
-const mockGitHub = new GitHub(MOCK_CONFIG);
+const mockGitHub = new GitHub({} as any);
 
-beforeEach(() => {
-  vi.clearAllMocks();
-});
+const mockGetTranslationIssues = (
+  await import('../../utils-infra/getTranslationIssues')
+).getTranslationIssues as unknown as ReturnType<typeof vi.fn>;
 
-it('Should return undefined when there are no successful workflow runs', async () => {
-  mockListWorkflowRunsForRepo.mockResolvedValue({
-    data: {
-      workflow_runs: [],
-    },
+describe('getLatestSuccessfulRunISODate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
   });
 
-  const result = await getLatestSuccessfulRunISODate(mockGitHub);
+  it('First execution confirmed when (hint && no previous success && no issues) -> returns undefined', async () => {
+    const hint = true;
 
-  expect(result).toBeUndefined();
-});
+    mockListWorkflowRunsForRepo.mockResolvedValue({
+      data: { total_count: 0, workflow_runs: [] },
+    });
+    mockGetTranslationIssues.mockResolvedValue([]);
 
-it('Should return the last execution time when an action with the matching workflow name exists', async () => {
-  const EXPECTED_LAST_CREATED_AT = '2023-01-04T12:00:00Z';
-
-  mockListWorkflowRunsForRepo.mockResolvedValue({
-    data: {
-      workflow_runs: [
-        { name: ACTION_NAME, created_at: '2023-01-03T12:00:00Z' },
-        { name: 'other-action', created_at: '2023-01-03T12:00:00Z' },
-        { name: 'another-action', created_at: '2023-01-02T12:00:00Z' },
-        { name: ACTION_NAME, created_at: EXPECTED_LAST_CREATED_AT },
-      ],
-    },
+    const result = await getLatestSuccessfulRunISODate(mockGitHub, hint);
+
+    expect(result).toBeUndefined();
+    expect(mockGetTranslationIssues).toHaveBeenCalledWith(mockGitHub, 'all');
   });
 
-  const result = await getLatestSuccessfulRunISODate(mockGitHub);
+  it('Not first execution when previous successful runs exist -> returns latest created_at by name match', async () => {
+    const hint = true;
+    const EXPECTED_LAST_CREATED_AT = '2023-01-04T12:00:00Z';
+
+    mockListWorkflowRunsForRepo.mockResolvedValue({
+      data: {
+        total_count: 3,
+        workflow_runs: [
+          {
+            created_at: '2023-01-05T12:00:00Z',
+            conclusion: 'success',
+            name: 'other',
+          },
+          {
+            created_at: EXPECTED_LAST_CREATED_AT,
+            conclusion: 'success',
+            name: 'yuki-no',
+          },
+          {
+            created_at: '2023-01-03T12:00:00Z',
+            conclusion: 'failure',
+            name: 'yuki-no',
+          },
+        ],
+      },
+    });
 
-  expect(result).toBe(EXPECTED_LAST_CREATED_AT);
+    const result = await getLatestSuccessfulRunISODate(mockGitHub, hint);
+
+    expect(result).toBe(EXPECTED_LAST_CREATED_AT);
+  });
+
+  it('No successful runs (but completed exist) and not first-run -> throws due to API inconsistency', async () => {
+    mockListWorkflowRunsForRepo.mockResolvedValue({
+      data: {
+        total_count: 2,
+        workflow_runs: [
+          {
+            created_at: '2023-01-05T12:00:00Z',
+            conclusion: 'failure',
+            name: 'yuki-no',
+          },
+          {
+            created_at: '2023-01-04T12:00:00Z',
+            conclusion: 'cancelled',
+            name: 'yuki-no',
+          },
+        ],
+      },
+    });
+    mockGetTranslationIssues.mockResolvedValue([
+      {
+        number: 1,
+        body: 'existing',
+        labels: ['l1'],
+        hash: 'h',
+        isoDate: '2023-01-01T00:00:00Z',
+      },
+    ]);
+
+    await expect(
+      getLatestSuccessfulRunISODate(mockGitHub, false),
+    ).rejects.toThrow();
+  });
 });
diff --git a/packages/core/utils-infra/getLatestSuccessfulRunISODate.ts b/packages/core/utils-infra/getLatestSuccessfulRunISODate.ts
@@ -1,30 +1,47 @@
 import type { GitHub } from '../infra/github';
 import { log } from '../utils/log';
 
+import { getTranslationIssues } from './getTranslationIssues';
+
+import type { RestEndpointMethodTypes } from '@octokit/rest';
+
 const WORKFLOW_NAME = 'yuki-no';
 
 export const getLatestSuccessfulRunISODate = async (
   github: GitHub,
+  hintFirstRun: boolean,
 ): Promise<string | undefined> => {
   log(
     'I',
     'getLatestSuccessfulRunISODate :: Extracting last successful GitHub Actions run time',
   );
-  const { data } = await github.api.actions.listWorkflowRunsForRepo({
-    ...github.ownerAndRepo,
-    status: 'success',
-  });
 
-  const latestSuccessfulRun = data.workflow_runs
-    .sort((a, b) => a.created_at.localeCompare(b.created_at))
-    .findLast(run => run.name === WORKFLOW_NAME);
+  const { run: latestSuccessfulRun, successfulCount } =
+    await getLatestSuccessfulRun(github);
+  const maybeFirstExecution =
+    hintFirstRun && successfulCount === 0 && latestSuccessfulRun === undefined;
+
+  if (maybeFirstExecution) {
+    const allIssues = await getTranslationIssues(github, 'all');
+    const isFirstExecution = allIssues.length === 0;
+
+    if (isFirstExecution) {
+      log(
+        'I',
+        'getLatestSuccessfulRunISODate :: No last successful GitHub Actions run time found (first execution confirmed)',
+      );
+      return;
+    }
+  }
 
   if (!latestSuccessfulRun) {
     log(
-      'I',
-      'getLatestSuccessfulRunISODate :: No last successful GitHub Actions run time found',
+      'W',
+      `getLatestSuccessfulRunISODate :: API inconsistency detected: totalCount=${successfulCount}, but no successful run found`,
+    );
+    throw new Error(
+      'GitHub API data inconsistency detected. This might indicate API instability.',
     );
-    return;
   }
 
   const latestSuccessfulRunDate = latestSuccessfulRun.created_at;
@@ -36,3 +53,32 @@ export const getLatestSuccessfulRunISODate = async (
 
   return latestSuccessfulRunDate;
 };
+
+type WorkflowRun =
+  RestEndpointMethodTypes['actions']['listWorkflowRunsForRepo']['response']['data']['workflow_runs'][number];
+
+const getLatestSuccessfulRun = async (
+  github: GitHub,
+): Promise<{ run: WorkflowRun | undefined; successfulCount: number }> => {
+  const { data } = await github.api.rest.actions.listWorkflowRunsForRepo({
+    ...github.ownerAndRepo,
+    status: 'completed',
+    per_page: 100,
+  });
+
+  log(
+    'I',
+    `getLatestSuccessfulRunISODate :: Found ${data.total_count} completed / ${data.workflow_runs.length} runs on first page`,
+  );
+
+  const successfulYukiNoRun = data.workflow_runs.filter(
+    ({ conclusion, name }) =>
+      conclusion === 'success' && name === WORKFLOW_NAME,
+  );
+  const [latestSuccessfulRun] = successfulYukiNoRun;
+
+  return {
+    run: latestSuccessfulRun,
+    successfulCount: successfulYukiNoRun.length,
+  };
+};
diff --git a/packages/core/utils-infra/getOpenedIssues.ts b/packages/core/utils-infra/getOpenedIssues.ts
diff --git a/packages/core/utils-infra/getTranslationIssues.ts b/packages/core/utils-infra/getTranslationIssues.ts
