Skip to content

Commit ba3b224

Browse files
efraespadaefraespada
committed
bugfix-319-setup-crash-on-repository-with-no-issues: improve issue label fetching error handling and add new documentation files for agent context.
1 parent ea74425 commit ba3b224

10 files changed

Lines changed: 415 additions & 32 deletions

File tree

‎_agent/docs/architecture.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
name: Architecture
3+
description: Project architecture, entry points, and use case flows.
4+
---
5+
6+
# Architecture & Key Paths
7+
8+
## Entry and main flow
9+
10+
1. **GitHub Action**: `src/actions/github_action.ts` reads inputs, builds `Execution`, calls `mainRun(execution)` from `common_action.ts`.
11+
2. **CLI**: `src/actions/local_action.ts` same flow with CLI/config inputs.
12+
3. **common_action.ts**: Sets up; calls `waitForPreviousRuns(execution)` (sequential workflow); then:
13+
- **Single action** → `SingleActionUseCase`
14+
- **Issue** → `IssueCommentUseCase` or `IssueUseCase`
15+
- **Pull request** → `PullRequestReviewCommentUseCase` or `PullRequestUseCase`
16+
- **Push** → `CommitUseCase`
17+
18+
## Key paths
19+
20+
| Area | Path | Purpose |
21+
|------|------|--------|
22+
| Action entry | `src/actions/github_action.ts` | Reads inputs, builds Execution |
23+
| CLI entry | `src/cli.ts` → `local_action.ts` | Same flow, local inputs |
24+
| Shared flow | `src/actions/common_action.ts` | mainRun, waitForPreviousRuns, dispatch to use cases |
25+
| Use cases | `src/usecase/` | issue_use_case, pull_request_use_case, commit_use_case, single_action_use_case |
26+
| Single actions | `src/usecase/actions/` | check_progress, detect_errors, recommend_steps, think, initial_setup, create_release, create_tag, publish_github_action, deployed_action |
27+
| Steps (issue) | `src/usecase/steps/issue/` | check_permissions, close_not_allowed_issue, assign_members, update_title, update_issue_type, link_issue_project, check_priority_issue_size, prepare_branches, remove_issue_branches, remove_not_needed_branches, label_deploy_added, label_deployed_added, move_issue_to_in_progress, answer_issue_help_use_case (question/help on open). On issue opened: RecommendStepsUseCase (non release/question/help) or AnswerIssueHelpUseCase (question/help). |
28+
| Steps (PR) | `src/usecase/steps/pull_request/` | update_title, assign_members (issue), assign_reviewers_to_issue, link_pr_project, link_pr_issue, sync_size_and_progress_from_issue, check_priority_pull_request_size, update_description (AI), close_issue_after_merging |
29+
| Steps (commit) | `src/usecase/steps/commit/` | notify commit, check size |
30+
| Steps (issue comment) | `src/usecase/steps/issue_comment/` | check_issue_comment_language (translation) |
31+
| Steps (PR review comment) | `src/usecase/steps/pull_request_review_comment/` | check_pull_request_comment_language (translation) |
32+
| Bugbot autofix & user request | `src/usecase/steps/commit/bugbot/` + `user_request_use_case.ts` | detect_bugbot_fix_intent_use_case (plan agent: is_fix_request, is_do_request, target_finding_ids), BugbotAutofixUseCase + runBugbotAutofixCommitAndPush (fix findings), DoUserRequestUseCase + runUserRequestCommitAndPush (generic “do this”). Permission: ProjectRepository.isActorAllowedToModifyFiles (org member or repo owner). |
33+
| Manager (content) | `src/manager/` | description handlers, configuration_handler, markdown_content_hotfix_handler (PR description, hotfix changelog content) |
34+
| Models | `src/data/model/` | Execution, Issue, PullRequest, SingleAction, etc. |
35+
| Repos | `src/data/repository/` | branch_repository, issue_repository, workflow_repository, ai_repository (OpenCode), file_repository, project_repository |
36+
| Config | `src/utils/constants.ts` | INPUT_KEYS, ACTIONS, defaults |
37+
| Metadata | `action.yml` | Action inputs and defaults |
38+
39+
## Schematic overview of use case flows
40+
41+
Entry point: `mainRun(execution)` in `src/actions/common_action.ts`. After `execution.setup()` and optionally `waitForPreviousRuns`, the dispatch is:
42+
43+
```
44+
mainRun
45+
├── runnedByToken && singleAction → SingleActionUseCase (only if validSingleAction)
46+
├── issueNumber === -1 → SingleActionUseCase (only if isSingleActionWithoutIssue) or skip
47+
├── welcome → log boxen and continue
48+
└── try:
49+
├── isSingleAction → SingleActionUseCase
50+
├── isIssue → issue.isIssueComment ? IssueCommentUseCase : IssueUseCase
51+
├── isPullRequest → pullRequest.isPullRequestReviewComment ? PullRequestReviewCommentUseCase : PullRequestUseCase
52+
├── isPush → CommitUseCase
53+
└── else → core.setFailed
54+
```
55+
56+
### 1. IssueUseCase (`on: issues`, not a comment)
57+
58+
**Step order:**
59+
60+
1. **CheckPermissionsUseCase** → if it fails (not allowed): CloseNotAllowedIssueUseCase and return.
61+
2. **RemoveIssueBranchesUseCase** (only if `cleanIssueBranches`).
62+
3. **AssignMemberToIssueUseCase**
63+
4. **UpdateTitleUseCase**
64+
5. **UpdateIssueTypeUseCase**
65+
6. **LinkIssueProjectUseCase**
66+
7. **CheckPriorityIssueSizeUseCase**
67+
8. **PrepareBranchesUseCase** (if `isBranched`) **or** **RemoveIssueBranchesUseCase** (if not).
68+
9. **RemoveNotNeededBranchesUseCase**
69+
10. **DeployAddedUseCase** (deploy label)
70+
11. **DeployedAddedUseCase** (deployed label)
71+
12. If **issue.opened**:
72+
- If not release and not question/help → **RecommendStepsUseCase**
73+
- If question or help → **AnswerIssueHelpUseCase**
74+
75+
### 2. IssueCommentUseCase (`on: issue_comment`)
76+
77+
**Step order:**
78+
79+
1. **CheckIssueCommentLanguageUseCase** (translation)
80+
2. **DetectBugbotFixIntentUseCase** → payload: `isFixRequest`, `isDoRequest`, `targetFindingIds`, `context`, `branchOverride`
81+
3. **ProjectRepository.isActorAllowedToModifyFiles(owner, actor, token)** (permission to modify files)
82+
4. Branch A – **if runAutofix && allowed**:
83+
- **BugbotAutofixUseCase** → **runBugbotAutofixCommitAndPush** → if committed: **markFindingsResolved**
84+
5. Branch B – **if !runAutofix && canRunDoUserRequest && allowed**:
85+
- **DoUserRequestUseCase** → **runUserRequestCommitAndPush**
86+
6. **If no file-modifying action ran** → **ThinkUseCase**
87+
88+
### 3. PullRequestReviewCommentUseCase (`on: pull_request_review_comment`)
89+
90+
Same flow as **IssueCommentUseCase**, with:
91+
92+
- CheckIssueCommentLanguageUseCase → **CheckPullRequestCommentLanguageUseCase**
93+
- User comment: `param.pullRequest.commentBody`
94+
- DetectBugbotFixIntentUseCase may use **parent comment** (commentInReplyToId) in the prompt.
95+
96+
### 4. PullRequestUseCase (`on: pull_request`, not a review comment)
97+
98+
**Branches by PR state:**
99+
100+
- **pullRequest.isOpened**:
101+
1. UpdateTitleUseCase
102+
2. AssignMemberToIssueUseCase
103+
3. AssignReviewersToIssueUseCase
104+
4. LinkPullRequestProjectUseCase
105+
5. LinkPullRequestIssueUseCase
106+
6. SyncSizeAndProgressLabelsFromIssueToPrUseCase
107+
7. CheckPriorityPullRequestSizeUseCase
108+
8. If AI PR description: **UpdatePullRequestDescriptionUseCase**
109+
110+
- **pullRequest.isSynchronize** (new pushes):
111+
- If AI PR description: **UpdatePullRequestDescriptionUseCase**
112+
113+
- **pullRequest.isClosed && isMerged**:
114+
- **CloseIssueAfterMergingUseCase**
115+
116+
### 5. CommitUseCase (`on: push`)
117+
118+
**Precondition:** `param.commit.commits.length > 0` (if 0, return with no steps).
119+
120+
**Order:**
121+
122+
1. **NotifyNewCommitOnIssueUseCase**
123+
2. **CheckChangesIssueSizeUseCase**
124+
3. **CheckProgressUseCase** (OpenCode: progress + size labels on issue and PRs)
125+
4. **DetectPotentialProblemsUseCase** (Bugbot: detection, publish to issue/PR, resolved markers)
126+
127+
### 6. SingleActionUseCase
128+
129+
Invoked when:
130+
- `runnedByToken && isSingleAction && validSingleAction`, or
131+
- `issueNumber === -1 && isSingleAction && isSingleActionWithoutIssue`, or
132+
- `isSingleAction` in the main try block.
133+
134+
**Dispatch by action (one per run):**
135+
136+
| Action | Use case |
137+
|--------|----------|
138+
| `deployed_action` | DeployedActionUseCase |
139+
| `publish_github_action` | PublishGithubActionUseCase |
140+
| `create_release` | CreateReleaseUseCase |
141+
| `create_tag` | CreateTagUseCase |
142+
| `think_action` | ThinkUseCase |
143+
| `initial_setup` | InitialSetupUseCase |
144+
| `check_progress_action` | CheckProgressUseCase |
145+
| `detect_potential_problems_action` | DetectPotentialProblemsUseCase |
146+
| `recommend_steps_action` | RecommendStepsUseCase |

‎_agent/docs/bugbot.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
name: Bugbot
3+
description: Detailed technical reference for Bugbot (detection, markers, context, intent, autofix, do user request, permissions).
4+
---
5+
6+
# Bugbot – technical reference
7+
8+
Bugbot has two main modes: **detection** (on push or single action) and **fix/do** (on issue comment or PR review comment). All Bugbot code lives under `src/usecase/steps/commit/bugbot/` and `src/usecase/steps/commit/` (DetectPotentialProblemsUseCase, user_request_use_case).
9+
10+
## 1. Detection flow (push or single action)
11+
12+
**Entry:** `CommitUseCase` (on push) calls `DetectPotentialProblemsUseCase`; or `SingleActionUseCase` when action is `detect_potential_problems_action`.
13+
14+
**Steps:**
15+
16+
1. **Guard:** OpenCode must be configured; `issueNumber !== -1`.
17+
2. **Load context:** `loadBugbotContext(param)` → issue comments + PR review comments parsed for markers; builds `existingByFindingId`, `issueComments`, `openPrNumbers`, `previousFindingsBlock`, `prContext`, `unresolvedFindingsWithBody`. Branch is `param.commit.branch` (or `options.branchOverride` when provided). PR context includes `prHeadSha`, `prFiles`, `pathToFirstDiffLine` for the first open PR.
18+
3. **Build prompt:** `buildBugbotPrompt(param, context)` – repo context, head/base branch, issue number, optional `ai-ignore-files`, and `previousFindingsBlock` (task 2: which previous findings are now resolved). OpenCode is asked to compute the diff itself and return `findings` + `resolved_finding_ids`.
19+
4. **Call OpenCode:** `askAgent(OPENCODE_AGENT_PLAN, prompt, BUGBOT_RESPONSE_SCHEMA)`.
20+
5. **Process response:** Filter findings: safe path (`isSafeFindingFilePath`), not in `ai-ignore-files` (`fileMatchesIgnorePatterns`), `meetsMinSeverity` (min from `bugbot-severity`), `deduplicateFindings`. Apply `applyCommentLimit(findings, bugbot-comment-limit)` → `toPublish`, `overflowCount`, `overflowTitles`.
21+
6. **Mark resolved:** `markFindingsResolved(execution, context, resolvedFindingIds, normalizedResolvedIds)` – for each existing finding in context whose id is in resolved set, update issue comment (and PR review comment if any) via `replaceMarkerInBody` to set `resolved:true`; if PR comment, call `resolveReviewThread` when applicable.
22+
7. **Publish:** `publishFindings(execution, context, toPublish, overflowCount?, overflowTitles?)` – for each finding: add or update **issue comment** (always); add or update **PR review comment** only when `finding.file` is in `prContext.prFiles` (using `pathToFirstDiffLine` when finding has no line). Each comment body is built with `buildCommentBody(finding, resolved)` and includes the **marker** `<!-- copilot-bugbot finding_id:"id" resolved:false -->`. Overflow: one extra issue comment summarizing excess findings.
23+
24+
## 2. Marker format and context
25+
26+
**Marker:** Hidden HTML comment in every finding comment (issue and PR):
27+
28+
`<!-- copilot-bugbot finding_id:"<id>" resolved:true|false -->`
29+
30+
- **Parse:** `parseMarker(body)` returns `{ findingId, resolved }[]`. Used when loading context from issue comments and PR review comments.
31+
- **Build:** `buildMarker(findingId, resolved)`. IDs are sanitized (`sanitizeFindingIdForMarker`) so they cannot break HTML (no `-->`, `<`, `>`, newlines, etc.).
32+
- **Update:** `replaceMarkerInBody(body, findingId, newResolved)` – used when marking a finding as resolved (same comment, body updated with `resolved:true`).
33+
34+
## 3. Fix intent and file-modifying actions (issue comment / PR review comment)
35+
36+
**Entry:** `IssueCommentUseCase` or `PullRequestReviewCommentUseCase` (after language check).
37+
38+
**Steps:**
39+
40+
1. **Intent:** `DetectBugbotFixIntentUseCase.invoke(param)`
41+
- Guards: OpenCode configured, issue number set, comment body non-empty, branch (or branchOverride from `getHeadBranchForIssue` when commit.branch empty).
42+
- `loadBugbotContext(param, { branchOverride })` → unresolved findings.
43+
- Build `UnresolvedFindingSummary[]` (id, title from `extractTitleFromBody`, description = fullBody.slice(0, 4000)).
44+
- If PR review comment and `commentInReplyToId`: fetch parent comment body (`getPullRequestReviewCommentBody`), slice(0,1500).trim for prompt.
45+
- `buildBugbotFixIntentPrompt(commentBody, unresolvedFindings, parentCommentBody?)` → prompt asks: is_fix_request?, target_finding_ids?, is_do_request?
46+
- `askAgent(OPENCODE_AGENT_PLAN, prompt, BUGBOT_FIX_INTENT_RESPONSE_SCHEMA)` → `{ is_fix_request, target_finding_ids, is_do_request }`.
47+
- Payload: `isFixRequest`, `isDoRequest`, `targetFindingIds` (filtered to valid unresolved ids), `context`, `branchOverride`.
48+
49+
2. **Permission:** `ProjectRepository.isActorAllowedToModifyFiles(owner, actor, token)`.
50+
- If owner is Organization: `orgs.checkMembershipForUser` (204 = allowed).
51+
- If owner is User: allowed only if `actor === owner`.
52+
53+
3. **Branch A – Bugbot autofix** (when `canRunBugbotAutofix(payload)` and `allowedToModifyFiles`):
54+
- `BugbotAutofixUseCase.invoke({ execution, targetFindingIds, userComment, context, branchOverride })`
55+
- Load context if not provided; filter targets to valid unresolved ids; `buildBugbotFixPrompt(...)` with repo, findings block (truncated fullBody per finding), user comment, verify commands; `copilotMessage(ai, prompt)` (build agent).
56+
- If success: `runBugbotAutofixCommitAndPush(execution, { branchOverride, targetFindingIds })` – optional checkout if branchOverride, run verify commands (from `getBugbotFixVerifyCommands`, max 20), git add/commit/push (message `fix(#N): bugbot autofix - resolve ...`).
57+
- If committed and context: `markFindingsResolved({ execution, context, resolvedFindingIds, normalizedResolvedIds })`.
58+
59+
4. **Branch B – Do user request** (when `!runAutofix && canRunDoUserRequest(payload)` and `allowedToModifyFiles`):
60+
- `DoUserRequestUseCase.invoke({ execution, userComment, branchOverride })`
61+
- `buildUserRequestPrompt(execution, userComment)` – repo context + sanitized user request; `copilotMessage(ai, prompt)`.
62+
- If success: `runUserRequestCommitAndPush(execution, { branchOverride })` – same verify/checkout/add/commit/push with message `chore(#N): apply user request` or `chore: apply user request`.
63+
64+
5. **Think** (when no file-modifying action ran): `ThinkUseCase.invoke(param)` – answers the user (e.g. question).

‎_agent/docs/code-conventions.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: CodeConventions
3+
description: Coding standards, logging, and adding new inputs.
4+
---
5+
6+
# Code Conventions
7+
8+
## Logging and constants
9+
10+
- Use **logger**: `logInfo`, `logError`, `logDebugInfo` from `src/utils/logger`. No ad-hoc `console.log`.
11+
- Use **constants**: `INPUT_KEYS` and `ACTIONS` from `src/utils/constants.ts` for input names and action names. No hardcoded strings for these.
12+
13+
## Adding a new action input
14+
15+
1. **`action.yml`**: Add the input with `description` and `default` (if any).
16+
2. **`src/utils/constants.ts`**: Add the key to `INPUT_KEYS` (e.g. `NEW_INPUT: 'new-input'`).
17+
3. **`src/actions/github_action.ts`**: Read the input (e.g. `core.getInput(INPUT_KEYS.NEW_INPUT)`) and pass it into the object used to build `Execution`.
18+
4. **Optional**: If the CLI must support it, add to `local_action.ts` and the corresponding CLI option.
19+
20+
## Where to change content/descriptions
21+
22+
- **PR description** (template filling, AI content): `src/manager/description/` (configuration_handler, content interfaces).
23+
- **Hotfix/release changelog** (markdown extraction, formatting): `src/manager/description/markdown_content_hotfix_handler.ts`.
24+
25+
## Build and bundles
26+
27+
- The project uses **`@vercel/ncc`** to bundle the action and CLI. Keep imports and dependencies compatible with ncc (no dynamic requires that ncc cannot see).
28+
- **Do not** edit or rely on `build/`; it is generated. Run tests and lint only on `src/`.
29+
30+
## Style and lint
31+
32+
- Prefer TypeScript; avoid `any` (lint rule: no-explicit-any).
33+
- Run `npm run lint` before committing; use `npm run lint:fix` when possible.

‎_agent/docs/commit-messages.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: CommitMessages
3+
description: Specific nomenclature and branch-prefix requirements for commits.
4+
---
5+
6+
# Commit messages
7+
8+
The commit message must use the **current branch name as prefix**, with any `/` replaced by `-`.
9+
10+
## Format
11+
12+
```
13+
<normalized-branch>: <short description>
14+
15+
[optional body]
16+
```
17+
18+
- **Prefix**: current branch name, replacing `/` with `-`. Example: branch `feature/292-github-action-rename` → prefix `feature-292-github-action-rename`.
19+
- **Description**: imperative, lowercase, no trailing period. You may optionally include conventional type (`feat`, `fix`, `docs`, etc.) in the description.
20+
21+
## Examples
22+
23+
Branch `feature-292-github-action-rename`:
24+
25+
- `feature-292-github-action-rename: add concurrency and permissions to ci_check`
26+
- `feature-292-github-action-rename: fix docs callouts (Info instead of Note/Tip)`
27+
28+
Branch `fix/123-docs-anchor` (normalized to `fix-123-docs-anchor`):
29+
30+
- `fix-123-docs-anchor: remove invalid MDX heading anchors`
31+
32+
When suggesting or writing a commit message, use the current branch with `/` replaced by `-` as the prefix. If you don't know the branch, tell the user to use their branch name as the prefix.

‎_agent/docs/project-context.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: ProjectContext
3+
description: High-level overview, common commands, and ignore paths.
4+
---
5+
6+
# Copilot – Project Context
7+
8+
## Quick read (for fast understanding)
9+
10+
- **What it is**: GitHub Action + CLI that automates Git-Flow: creates branches from issue labels, links issues/PRs to projects, tracks commits; AI via OpenCode (progress, errors, PR descriptions).
11+
- **Entry points**: GitHub Action → `src/actions/github_action.ts`; CLI → `src/cli.ts`. Shared logic in `src/actions/common_action.ts` (single actions vs issue/PR/push).
12+
- **Do**: Use Node 20, run from repo root; edit only `src/`; use `INPUT_KEYS`/`ACTIONS` and `logInfo`/`logError`/`logDebugInfo`. When adding inputs: update `action.yml`, `constants.ts` (INPUT_KEYS), and `github_action.ts` (and optionally `local_action.ts`).
13+
- **Don’t**: Edit or depend on `build/` (generated by `ncc`); run tests/lint on `build/`.
14+
15+
## Commands (repo root)
16+
17+
```bash
18+
nvm use 20
19+
npm install
20+
npm run build
21+
npm test
22+
npm run test:watch
23+
npm run test:coverage
24+
npm run lint
25+
npm run lint:fix
26+
```
27+
28+
- **Build**: `npm run build` → bundles `github_action.ts` and `cli.ts` into `build/`.
29+
- **Tests**: Jest; `npm run test:watch` / `npm run test:coverage` as needed.
30+
- **Lint**: ESLint + typescript-eslint on `src/`; `npm run lint:fix` to auto-fix.
31+
32+
## What to ignore
33+
34+
- **`build/`** – Generated output; do not edit or run tests/lint against it.
35+
- **`.agent-sessions/`** – Session data; ignore unless debugging.

0 commit comments

Comments
 (0)