Merge remote-tracking branch 'origin/claude/r8-f5-small-fixes-f40412' into claude/integration-r8-a4196a

# Conflicts:
#	docs/upgrade/2026-11-maturity-review.md
This commit is contained in:
DongHyeonka
2026-11-07 01:41:00 +09:00
13 changed files with 567 additions and 119 deletions
+6 -3
View File
@@ -98,8 +98,11 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을
`&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나
부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태
함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), 세는 job이 부르지 않는
`workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore`
필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches`
없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이
부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는
job.
(3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른
명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤,
`bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를
@@ -112,7 +115,7 @@ root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을
변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다.
commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다.
예외는 하나다: 작업 지시(brief)가 허용하면 그 작업의 자기 브랜치에만 commit·push한다. main 병합,
예외는 하나다: brief가 허용한 것만(commit과 push는 따로) 그 작업의 자기 브랜치에 한다. main 병합,
다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」).
## 강제 수준
File diff suppressed because one or more lines are too long
+1
View File
@@ -181,6 +181,7 @@
| 에이전트가 원칙에서 바로 정한 것 | Kafka 주소 키 하나, composition이 persistence-jpa를 함께 가져옴 등 7건 | 기본값 | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 끝 목록 |
| 묶음별 기본값 | 각 라운드 처리 표의 「결정」 칸(예: SES replay 창 1h, Retry-After 30) | 기본값 | `1101` 13·14·16절, `1103` 6·10·12·15·16·17절 표 |
| 경로 필터 workflow와 단계 검사 | `paths:`·`paths-ignore:` trigger만 있는 workflow는 strict lane 단계 실행으로 세지 않는다 | 소유자 | `1103` 18.4절(RR7-05-01), 2026-11-06 |
| 태그·릴리스 workflow와 단계 검사 | `push`에 `tags:`만 있거나(`branches`·`paths` 없이) `release` trigger만 있는 workflow는 `releaseCheck` 단계에서만 실행으로 센다. 다른 단계(pull request·main·nightly)로는 세지 않는다 | 소유자 | `1103` 18.4절(round7 05 Declined ①), 2026-11-07 |
## 3. 새 결정을 기록하는 법
+2 -2
View File
@@ -3,7 +3,7 @@
`src/` 는 Gradle 멀티모듈 루트입니다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT 입니다.
이 문서는 [build.gradle](build.gradle) 과 [.env](.env) 의 코드 주석에서 덜어낸 **설정 항목 설명과
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
결정 근거**를 모아둔 참조용 기록입니다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명합니다.
@@ -28,7 +28,7 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
| `integrationCheck` | 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `integration-main.yml` `performance-check`가 main·nightly에 같은 명령으로 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow, `releaseCheck` 밖의 단계를 태그 push·`release`로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 |
| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + sample 전체 기동(`:sample-portfolio:systemTest`) + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
+1 -1
View File
@@ -10,7 +10,7 @@ verification reads that registry. Module rules live in [CLAUDE.md](CLAUDE.md).
Transport, security, configuration and operations contracts live in `docs/fileserver/`. For the
repository-level choice between this Fileserver platform and Object Storage, see
[`docs/storage-capability-boundary.md`](../../../docs/storage-capability-boundary.md).
[`docs/storage-capability-boundary.md`](../../../../docs/storage-capability-boundary.md).
## Activation
@@ -169,6 +169,11 @@ public final class ClientRuntimeRegistry implements AutoCloseable {
* the executor reports termination from inside the worker before that thread exits, so under load
* the thread could still be listed when close returned. Joining the thread is what makes "no
* thread left" true when this returns.
*
* <p>An interrupt does not cut the wait short; the flag is restored once the wait is over. A
* closing thread that was already interrupted used to give up at the first wait and return
* normally with the drain thread still running — the one failure path that said nothing (review
* 2026-11-06 RR7-02-01).
*/
private void stopDrainThread() {
ScheduledExecutorService scheduler = drainScheduler.getAndSet(null);
@@ -177,23 +182,38 @@ public final class ClientRuntimeRegistry implements AutoCloseable {
}
scheduler.shutdownNow();
long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(SHUTDOWN_AWAIT_MILLIS);
boolean interrupted = false;
try {
if (!scheduler.awaitTermination(SHUTDOWN_AWAIT_MILLIS, TimeUnit.MILLISECONDS)) {
throw new IllegalStateException("http client drain scheduler did not terminate");
}
for (Thread thread : drainThreads) {
long remaining = TimeUnit.NANOSECONDS.toMillis(deadline - System.nanoTime());
thread.join(Math.max(1L, remaining));
if (thread.isAlive()) {
throw new IllegalStateException("http client drain thread did not exit");
while (true) {
try {
awaitDrainThreadExit(scheduler, deadline);
return;
} catch (InterruptedException interruptedWait) {
interrupted = true;
}
}
drainThreads.clear();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
} finally {
if (interrupted) {
Thread.currentThread().interrupt();
}
}
}
private void awaitDrainThreadExit(ScheduledExecutorService scheduler, long deadline)
throws InterruptedException {
if (!scheduler.awaitTermination(deadline - System.nanoTime(), TimeUnit.NANOSECONDS)) {
throw new IllegalStateException("http client drain scheduler did not terminate");
}
for (Thread thread : drainThreads) {
long remaining = TimeUnit.NANOSECONDS.toMillis(deadline - System.nanoTime());
thread.join(Math.max(1L, remaining));
if (thread.isAlive()) {
throw new IllegalStateException("http client drain thread did not exit");
}
}
drainThreads.clear();
}
private AtomicReference<ClientRuntime> holder(ClientProfileName name) {
AtomicReference<ClientRuntime> holder = runtimes.get(name);
if (holder == null) {
@@ -7,7 +7,10 @@ import dev.caskeleton.adapter.outbound.httpclient.testkit.ClientProfiles;
import java.time.Duration;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class ClientRuntimeRegistryTest {
@@ -83,6 +86,56 @@ class ClientRuntimeRegistryTest {
assertThat(liveDrainThreads()).isEmpty();
}
@Test
@DisplayName("interrupt된 스레드에서 닫아도 drain 스레드가 끝난 뒤에 돌아오고 interrupt 상태는 남긴다")
void closingFromAnInterruptedThreadStillWaitsForTheDrainThread() throws InterruptedException {
// given: the drain thread is busy closing the old generation, and ignores the interrupt
// shutdownNow sends it, when the registry closes
CountDownLatch drainStarted = new CountDownLatch(1);
ClientRuntime busy =
new ClientRuntime(
ClientProfiles.builder("payment").build(),
new RuntimeGeneration(1),
() -> {
drainStarted.countDown();
sleepIgnoringInterrupts(Duration.ofMillis(500));
});
ClientRuntimeRegistry registry = new ClientRuntimeRegistry(Map.of(busy.name(), busy));
ClientRuntimeLease lease = registry.acquire(busy.name());
registry.swap(busy.name(), running(2), Duration.ofMillis(1));
assertThat(drainStarted.await(5, TimeUnit.SECONDS)).isTrue();
// when
Thread.currentThread().interrupt();
boolean stillInterrupted;
try {
registry.close();
} finally {
stillInterrupted = Thread.interrupted();
}
// then
Set<String> left = liveDrainThreads();
lease.close();
assertThat(left).isEmpty();
assertThat(stillInterrupted).isTrue();
}
private static void sleepIgnoringInterrupts(Duration duration) {
long end = System.nanoTime() + duration.toNanos();
boolean interrupted = false;
for (long left = duration.toNanos(); left > 0; left = end - System.nanoTime()) {
try {
Thread.sleep(Duration.ofNanos(left));
} catch (InterruptedException ignored) {
interrupted = true;
}
}
if (interrupted) {
Thread.currentThread().interrupt();
}
}
private static Set<String> liveDrainThreads() {
return Thread.getAllStackTraces().keySet().stream()
.filter(Thread::isAlive)
+1 -1
View File
@@ -11,7 +11,7 @@ in `docs/superpowers/specs/2026-07-28-objectstorage-production-capability-design
evidence claims in `docs/registries/object-storage-readiness.yaml`.
For when to use this capability rather than the HTTP Fileserver platform, see
[`docs/storage-capability-boundary.md`](../../../docs/storage-capability-boundary.md).
[`docs/storage-capability-boundary.md`](../../../../docs/storage-capability-boundary.md).
## Current readiness
File diff suppressed because one or more lines are too long
@@ -33,7 +33,8 @@ import org.gradle.api.execution.TaskExecutionGraph;
* as a workflow runs it — a lane the command removes with {@code -x} is not covered, matched
* the way Gradle matches it, abbreviations included ({@link TaskSelectors});
* <li>every declared stage is executed by a workflow. Not counted ({@code NOT_COUNTED}; review
* 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04, RR5-02-02, 2026-11-05 RR6-04-01..06): a command
* 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04, RR5-02-02, 2026-11-05 RR6-04-01..06, 2026-11-06
* RR7-05-01, owner decision 2026-11-07 on the release flow): a command
* after which Gradle runs no task ({@code --dry-run}, {@code -v}, {@code --help}, …) or that
* Gradle rejects (a short-option bundle such as {@code -mx}), one for another build, and one
* that does not gate for one of three reasons — its failure may not fail its step, it may not
@@ -66,13 +67,17 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
+ " script's last command, after set +e or a trap that exits 0, continue-on-error); one"
+ " that may not run (after ||, inside if/while/for/case or a function, after an exit 0,"
+ " exec or set -n, under an if: other than always()/success()/!cancelled(), in a"
+ " workflow that starts only on a request or a reusable one no counted job calls, in a"
+ " job that needs a job that may be skipped); and one this check does not read although"
+ " workflow that starts only on a request, or on changes only through a paths or"
+ " paths-ignore filter, or a reusable one no counted job calls, in a"
+ " job that needs a job that may be skipped, and for any stage but :releaseCheck in a"
+ " workflow that starts only on a tag push or a release); and one this check does not"
+ " read although"
+ " its failure"
+ " would fail the step (|| exit 1, inside { } or ( ), $( ), bash -c, gradlew as"
+ " another command's argument, after a cd it does not follow, a shell other than bash"
+ " or sh, a runner that may be Windows). Run the stage as ./gradlew on a line of its"
+ " own, in a step and job that run on every push, pull request or schedule";
+ " own, in a step and job that run on every push, pull request or schedule, with no"
+ " paths or paths-ignore filter (:releaseCheck may run on a tag push or a release)";
@Override
public void apply(Project project) {
@@ -228,7 +233,7 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
+ ": gradlew "
+ String.join(" ", invocation.tasks())
+ " — "
+ invocation.whyNotExecuting(buildDirectory))));
+ invocation.whyNotExecuting(stage, buildDirectory))));
return lines.isEmpty()
? ""
: "; commands that name it but do not count:\n " + String.join("\n ", lines);
@@ -2,6 +2,7 @@ package dev.caskeleton.buildlogic.strictlane;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Deque;
import java.util.HashSet;
import java.util.LinkedHashMap;
@@ -44,7 +45,13 @@ import java.util.regex.Pattern;
* <p><b>When a workflow runs.</b> A workflow counts when one of its triggers is part of the change
* or release flow: {@code push}, {@code pull_request} or {@code pull_request_target} (with a {@code
* types} list, only when it holds {@code opened}, {@code synchronize} or {@code reopened}), {@code
* merge_group}, {@code schedule}, {@code release}. One that starts only on other events — {@code
* merge_group}, {@code schedule}, {@code release} — and has no {@code paths} or {@code
* paths-ignore} filter: a change that touches none of the listed paths, or only ignored ones, does
* not start it (owner decision 2026-11-06, review RR7-05-01). A workflow whose only such triggers
* are the release flow — {@code release}, or a {@code push} with {@code tags} or {@code
* tags-ignore} and no {@code branches} or {@code branches-ignore}, which a branch push does not
* start — counts only for {@code :releaseCheck}, the tag-only stage (owner decision 2026-11-07).
* One that starts only on other events — {@code
* workflow_dispatch}, {@code repository_dispatch}, {@code issue_comment}, a {@code labeled} pull
* request, {@code workflow_run} and the rest — runs only when someone or something asks (review
* 2026-11-04 RR2-04-04, RR6-04-06). A workflow that starts only on {@code workflow_call} counts
@@ -98,6 +105,15 @@ public final class WorkflowGradleInvocations {
/** The pull-request activity types that come with every new change. */
private static final Set<String> PULL_REQUEST_CHANGE_TYPES =
Set.of("opened", "synchronize", "reopened");
/** The trigger filters that start a workflow only for changes to some files. */
private static final List<String> PATH_FILTERS = List.of("paths", "paths-ignore");
/** The push filters that start it for tags; with no branch filter, a branch push does not. */
private static final List<String> TAG_FILTERS = List.of("tags", "tags-ignore");
private static final List<String> BRANCH_FILTERS = List.of("branches", "branches-ignore");
private static final List<String> FILTERS =
List.of("paths", "paths-ignore", "tags", "tags-ignore", "branches", "branches-ignore");
/** The only stage a workflow of the release flow counts for: the tag-only one. */
private static final String RELEASE_STAGE = ":releaseCheck";
private static final String REUSABLE_WORKFLOWS = "./.github/workflows/";
/**
* Gradle 9.0's command-line options that take a value, by every name it accepts. Probed against
@@ -171,6 +187,8 @@ public final class WorkflowGradleInvocations {
* @param uncountedReason why the command gates nothing although it names tasks — it may not run,
* its failure may not fail its step, this reader does not read it, or Gradle runs no task —
* or {@code null}
* @param releaseFlowReason why the command gates only {@code :releaseCheck} — its workflow
* starts, of the triggers that need no request, only on the release flow — or {@code null}
*/
public record Invocation(
String workingDirectory,
@@ -178,12 +196,18 @@ public final class WorkflowGradleInvocations {
List<String> tasks,
boolean dryRun,
List<String> excludedTasks,
String uncountedReason) {
String uncountedReason,
String releaseFlowReason) {
public Invocation {
tasks = List.copyOf(tasks);
excludedTasks = List.copyOf(excludedTasks);
}
private Invocation releaseFlowOnly(String reason) {
return new Invocation(
workingDirectory, projectDir, tasks, dryRun, excludedTasks, uncountedReason, reason);
}
/**
* The directory of the build this command starts, from the repository root: the step's working
* directory joined with {@code -p}. {@code .} is the repository root.
@@ -201,11 +225,24 @@ public final class WorkflowGradleInvocations {
* the repository root such as {@code src}.
*/
public boolean executes(String taskPath, String buildDirectory) {
return requests(taskPath) && whyNotExecuting(buildDirectory) == null;
return requests(taskPath) && whyNotExecuting(taskPath, buildDirectory) == null;
}
/**
* Why this command does not execute and gate on the tasks it names in the build in {@code
* Why this command does not execute and gate on the task at {@code taskPath} in the build in
* {@code buildDirectory}, or {@code null} when it does: a reason that holds for every task it
* names, or that its workflow is of the release flow and the task is not {@code :releaseCheck}.
*/
public String whyNotExecuting(String taskPath, String buildDirectory) {
String reason = whyNotExecuting(buildDirectory);
if (reason != null || releaseFlowReason == null) {
return reason;
}
return absolute(taskPath).equals(RELEASE_STAGE) ? null : releaseFlowReason;
}
/**
* Why this command does not execute and gate on any task it names in the build in {@code
* buildDirectory}, or {@code null} when it does: its uncounted reason, another build, or a dry
* run.
*/
@@ -256,9 +293,49 @@ public final class WorkflowGradleInvocations {
ShellScript.Options shell,
String uncountedReason) {}
/** One workflow file: its name, its lines, its triggers with their {@code types}, its jobs. */
/** One workflow file: its name, its lines, its triggers by event name, its jobs. */
private record Workflow(
String file, List<String> lines, Map<String, List<String>> triggers, Map<String, Job> jobs) {}
String file, List<String> lines, Map<String, Trigger> triggers, Map<String, Job> jobs) {}
/**
* One trigger's filters that decide whether it runs on every change.
*
* @param types its {@code types} list, or {@code null} when it has none
* @param pathFilters which of {@code paths} and {@code paths-ignore} it has
* @param tagsOnly whether it filters tags and no branches, so that only a tag push starts it
*/
private record Trigger(List<String> types, List<String> pathFilters, boolean tagsOnly) {
private static final Trigger UNFILTERED = new Trigger(null, List.of(), false);
private static Trigger of(List<String> types, Collection<String> filters) {
return new Trigger(
types,
PATH_FILTERS.stream().filter(filters::contains).toList(),
TAG_FILTERS.stream().anyMatch(filters::contains)
&& BRANCH_FILTERS.stream().noneMatch(filters::contains));
}
}
/** How a trigger takes part in the stages (owner decisions 2026-11-06 and 2026-11-07). */
private enum Flow {
/** Starts on every change: counts for every stage. */
CHANGE,
/** Starts on a release or a tag push: counts for {@code :releaseCheck} only. */
RELEASE,
/** Starts on a change only when it touches some files: counts for no stage. */
PATH_FILTERED,
/** Starts only when someone or something asks: counts for no stage. */
REQUEST
}
/**
* When a workflow starts, as the stages see it: on every change (both {@code null}), only on
* the release flow ({@code releaseFlow} says why it counts for {@code :releaseCheck} alone), or
* not without being asked ({@code notStarted} says why).
*/
private record Start(String notStarted, String releaseFlow) {
private static final Start EVERY_CHANGE = new Start(null, null);
}
/** A job: its id, the line of its key, and the column of its own keys (-1 when it has none). */
private record Job(String id, int header, int keyIndent) {}
@@ -289,10 +366,13 @@ public final class WorkflowGradleInvocations {
workflowsByFile.forEach((file, text) -> workflows.put(file, parse(file, text)));
Map<String, List<Invocation>> invocations = new LinkedHashMap<>();
for (Workflow workflow : workflows.values()) {
String notStarted = startReason(workflow, workflows, new HashSet<>());
Start start = start(workflow, workflows, new HashSet<>());
List<Invocation> commands = new ArrayList<>();
for (RunStep step : runSteps(workflow, notStarted)) {
commands.addAll(stepInvocations(step));
for (RunStep step : runSteps(workflow, start.notStarted())) {
for (Invocation command : stepInvocations(step)) {
commands.add(
start.releaseFlow() == null ? command : command.releaseFlowOnly(start.releaseFlow()));
}
}
invocations.put(workflow.file(), List.copyOf(commands));
}
@@ -476,12 +556,9 @@ public final class WorkflowGradleInvocations {
// ---------------------------------------------------------------------------------------------
// When the workflow runs
/**
* The workflow's triggers, each with its {@code types} list, or {@code null} when it has none;
* empty when no {@code on:} is written.
*/
private static Map<String, List<String>> triggers(List<String> lines) {
Map<String, List<String>> triggers = new LinkedHashMap<>();
/** The workflow's triggers with their filters; empty when no {@code on:} is written. */
private static Map<String, Trigger> triggers(List<String> lines) {
Map<String, Trigger> triggers = new LinkedHashMap<>();
for (int index = 0; index < lines.size(); index++) {
Matcher on = TRIGGER_KEY.matcher(lines.get(index));
if (!on.matches()) {
@@ -494,7 +571,7 @@ public final class WorkflowGradleInvocations {
int colon = entry.indexOf(':');
triggers.put(
stripScalarComment(colon < 0 ? entry : entry.substring(0, colon)),
colon < 0 ? null : flowTypes(entry.substring(colon + 1).trim()));
colon < 0 ? Trigger.UNFILTERED : flowTrigger(entry.substring(colon + 1).trim()));
}
} else if (!inline.isEmpty()) {
String list =
@@ -502,7 +579,7 @@ public final class WorkflowGradleInvocations {
? inline.substring(1, inline.length() - 1)
: inline;
for (String trigger : flowItems(list)) {
triggers.put(trigger, null);
triggers.put(trigger, Trigger.UNFILTERED);
}
} else {
blockTriggers(lines, index, triggers);
@@ -514,7 +591,7 @@ public final class WorkflowGradleInvocations {
/** The triggers of a block {@code on:} at {@code onLine}: a mapping or a list. */
private static void blockTriggers(
List<String> lines, int onLine, Map<String, List<String>> triggers) {
List<String> lines, int onLine, Map<String, Trigger> triggers) {
int childIndent = childIndent(lines, onLine);
for (int next = onLine + 1; next < lines.size(); next++) {
String line = lines.get(next);
@@ -532,61 +609,111 @@ public final class WorkflowGradleInvocations {
boolean item = key.startsWith("-");
key = item ? key.substring(1).trim() : key;
int colon = key.indexOf(':');
List<String> types = null;
Trigger trigger = Trigger.UNFILTERED;
String inlineDetail = colon < 0 ? "" : key.substring(colon + 1).trim();
if (!item && inlineDetail.startsWith("{")) {
types = flowTypes(stripScalarComment(inlineDetail));
trigger = flowTrigger(stripScalarComment(inlineDetail));
} else if (!item && colon >= 0) {
int detailIndent = childIndent(lines, next);
int typesLine =
detailIndent > childIndent ? mappingKey(lines, next + 1, detailIndent, "types") : -1;
types = typesLine < 0 ? null : listValue(lines, typesLine);
if (detailIndent > childIndent) {
int typesLine = mappingKey(lines, next + 1, detailIndent, "types");
List<String> filters = new ArrayList<>();
for (String filter : FILTERS) {
if (mappingKey(lines, next + 1, detailIndent, filter) >= 0) {
filters.add(filter);
}
}
trigger = Trigger.of(typesLine < 0 ? null : listValue(lines, typesLine), filters);
}
}
triggers.put(stripScalarComment(colon < 0 ? key : key.substring(0, colon)), types);
triggers.put(stripScalarComment(colon < 0 ? key : key.substring(0, colon)), trigger);
}
}
/** The {@code types} of a flow-mapping trigger value such as {@code {types: [created]}}. */
private static List<String> flowTypes(String value) {
if (!value.startsWith("{") || !value.endsWith("}")) {
return null;
}
for (String entry : flowItems(value.substring(1, value.length() - 1))) {
int colon = entry.indexOf(':');
if (colon >= 0 && stripScalarComment(entry.substring(0, colon)).equals("types")) {
String types = entry.substring(colon + 1).trim();
return types.startsWith("[") && types.endsWith("]")
? flowItems(types.substring(1, types.length() - 1))
: List.of(stripScalarComment(types));
}
}
return null;
}
/**
* Why the workflow does not run on every change, or {@code null} when it does or writes no {@code
* on:}. A reusable workflow runs through its callers ({@code visiting} guards a cycle).
* The filters of a flow-mapping trigger value such as {@code {types: [created]}} or {@code
* {paths: [docs/**]}}.
*/
private static String startReason(
Workflow workflow, Map<String, Workflow> workflows, Set<String> visiting) {
Map<String, List<String>> triggers = workflow.triggers();
if (triggers.isEmpty()) {
return null;
private static Trigger flowTrigger(String value) {
if (!value.startsWith("{") || !value.endsWith("}")) {
return Trigger.UNFILTERED;
}
for (Map.Entry<String, List<String>> trigger : triggers.entrySet()) {
if (runsOnChanges(trigger.getKey(), trigger.getValue())) {
return null;
List<String> types = null;
List<String> filters = new ArrayList<>();
for (String entry : flowItems(value.substring(1, value.length() - 1))) {
int colon = entry.indexOf(':');
if (colon < 0) {
continue;
}
String key = stripScalarComment(entry.substring(0, colon));
String detail = entry.substring(colon + 1).trim();
if (key.equals("types")) {
types =
detail.startsWith("[") && detail.endsWith("]")
? flowItems(detail.substring(1, detail.length() - 1))
: List.of(stripScalarComment(detail));
} else if (FILTERS.contains(key)) {
filters.add(key);
}
}
return Trigger.of(types, filters);
}
/**
* When the workflow starts, as the stages see it; on every change when it writes no {@code on:}.
* A reusable workflow runs through its callers ({@code visiting} guards a cycle).
*/
private static Start start(
Workflow workflow, Map<String, Workflow> workflows, Set<String> visiting) {
Map<String, Trigger> triggers = workflow.triggers();
if (triggers.isEmpty()) {
return Start.EVERY_CHANGE;
}
Map<String, Trigger> pathFiltered = new LinkedHashMap<>();
Map<String, Trigger> releaseFlow = new LinkedHashMap<>();
for (Map.Entry<String, Trigger> trigger : triggers.entrySet()) {
switch (flow(trigger.getKey(), trigger.getValue())) {
case CHANGE -> {
return Start.EVERY_CHANGE;
}
case PATH_FILTERED -> pathFiltered.put(trigger.getKey(), trigger.getValue());
case RELEASE -> releaseFlow.put(trigger.getKey(), trigger.getValue());
case REQUEST -> {
// counted only through a caller, below, when it is workflow_call
}
}
}
String release =
releaseFlow.isEmpty()
? null
: "its workflow starts without a request or a path filter only on the release flow ("
+ describe(releaseFlow)
+ "), not on every push, pull request or schedule, so it counts only for "
+ RELEASE_STAGE;
String described = describe(triggers);
if (!triggers.containsKey("workflow_call")) {
return "its workflow starts only on "
+ described
+ ", which happen only when someone or something asks, not on every push, pull request"
+ " or schedule, so it may not run";
if (release != null) {
return new Start(null, release);
}
if (!pathFiltered.isEmpty()) {
return new Start(
"its workflow starts on changes only through "
+ describe(pathFiltered)
+ ", which a change that touches none of the listed paths, or only ignored ones,"
+ " does not start, so it may not run",
null);
}
return new Start(
"its workflow starts only on "
+ described
+ ", which happen only when someone or something asks, not on every push, pull"
+ " request or schedule, so it may not run",
null);
}
if (!visiting.add(workflow.file())) {
return "its workflow is called only through a cycle of workflow_call";
return release != null
? new Start(null, release)
: new Start("its workflow is called only through a cycle of workflow_call", null);
}
List<String> callers = new ArrayList<>();
for (Workflow caller : workflows.values()) {
@@ -600,38 +727,73 @@ public final class WorkflowGradleInvocations {
reason = needsReason(caller, job);
}
if (reason == null) {
reason = startReason(caller, workflows, new HashSet<>(visiting));
}
if (reason == null) {
return null;
Start callerStart = start(caller, workflows, new HashSet<>(visiting));
if (callerStart.equals(Start.EVERY_CHANGE)) {
return Start.EVERY_CHANGE;
}
if (callerStart.notStarted() == null && release == null) {
release =
"its workflow is called by "
+ caller.file()
+ " job "
+ job.id()
+ ", and "
+ callerStart.releaseFlow();
}
reason =
callerStart.notStarted() == null
? callerStart.releaseFlow()
: callerStart.notStarted();
}
callers.add(caller.file() + " job " + job.id() + ": " + reason);
}
}
return "its workflow starts only on "
+ described
+ ", and no workflow that runs on every change calls it ("
+ (callers.isEmpty()
? "no workflow in this directory calls it"
: String.join("; ", callers))
+ "), so it may not run";
}
private static boolean runsOnChanges(String trigger, List<String> types) {
if (!CHANGE_TRIGGERS.contains(trigger)) {
return false;
if (release != null) {
return new Start(null, release);
}
return types == null
|| !trigger.startsWith("pull_request")
|| types.stream().anyMatch(PULL_REQUEST_CHANGE_TYPES::contains);
return new Start(
"its workflow starts only on "
+ described
+ ", and no workflow that runs on every change calls it ("
+ (callers.isEmpty()
? "no workflow in this directory calls it"
: String.join("; ", callers))
+ "), so it may not run",
null);
}
private static String describe(Map<String, List<String>> triggers) {
private static Flow flow(String name, Trigger trigger) {
if (!CHANGE_TRIGGERS.contains(name)) {
return Flow.REQUEST;
}
if (trigger.types() != null
&& name.startsWith("pull_request")
&& trigger.types().stream().noneMatch(PULL_REQUEST_CHANGE_TYPES::contains)) {
return Flow.REQUEST;
}
if (!trigger.pathFilters().isEmpty()) {
return Flow.PATH_FILTERED;
}
if (name.equals("release") || name.equals("push") && trigger.tagsOnly()) {
return Flow.RELEASE;
}
return Flow.CHANGE;
}
private static String describe(Map<String, Trigger> triggers) {
List<String> described = new ArrayList<>();
triggers.forEach(
(trigger, types) ->
described.add(
types == null ? trigger : trigger + " (types: " + String.join(", ", types) + ")"));
(name, trigger) -> {
List<String> filters = new ArrayList<>();
if (trigger.types() != null) {
filters.add("types: " + String.join(", ", trigger.types()));
}
filters.addAll(trigger.pathFilters());
if (trigger.tagsOnly()) {
filters.add("tags only");
}
described.add(filters.isEmpty() ? name : name + " (" + String.join("; ", filters) + ")");
});
return String.join(", ", described);
}
@@ -1220,7 +1382,7 @@ public final class WorkflowGradleInvocations {
if (reason == null) {
reason = rejected != null ? rejected : runsNoTask;
}
return new Invocation(workingDirectory, projectDir, tasks, dryRun, excluded, reason);
return new Invocation(workingDirectory, projectDir, tasks, dryRun, excluded, reason, null);
}
private static boolean isFlag(String name) {
@@ -698,6 +698,63 @@ class StrictLaneStagesFunctionalTest {
.doesNotContain("stage :ci is executed by no workflow");
}
@Test
@DisplayName("태그 push로만 도는 workflow의 단계 명령은 releaseCheck에만 세고, 다른 단계는 실행되지 않은 것으로 본다")
void aReleaseFlowWorkflowCountsOnlyForTheReleaseStage() throws Exception {
// given
Files.writeString(
gradleRoot.resolve("build.gradle"),
"""
plugins { id 'ca.strict-lane-stages' }
tasks.register('ci') { dependsOn ':leaf:check' }
tasks.register('integrationCheck') { dependsOn ':leaf:integrationTestLaneCheck' }
tasks.register('releaseCheck')
strictLaneStages {
stage ':ci', ':integrationCheck', ':releaseCheck'
workflowDirectory = layout.projectDirectory.dir('../.github/workflows')
}
""");
leafLanes(
"""
lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' }
""");
workflow(
"""
on: pull_request
jobs:
gate:
runs-on: ubuntu-latest
steps:
- working-directory: src
run: ./gradlew :ci --stacktrace
""");
Files.writeString(
repository.resolve(".github/workflows/release.yml"),
"""
on:
push:
tags: ['v*']
jobs:
release:
runs-on: ubuntu-latest
steps:
- working-directory: src
run: ./gradlew :releaseCheck
- working-directory: src
run: ./gradlew :integrationCheck --continue
""");
// when
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail();
// then
assertThat(result.getOutput())
.contains("stage :integrationCheck is executed by no workflow")
.contains("release.yml: gradlew :integrationCheck")
.contains("counts only for :releaseCheck")
.doesNotContain("stage :releaseCheck is executed by no workflow");
}
private void leafLanes(String lanes) throws Exception {
Files.writeString(
gradleRoot.resolve("leaf/build.gradle"),
@@ -1218,8 +1218,8 @@ class WorkflowGradleInvocationsTest {
}
@Test
@DisplayName("push·pull_request·merge_group·schedule·release 중 하나로도 시작하는 workflow의 명령은 센다")
void aWorkflowThatAlsoStartsOnTheChangeOrReleaseFlowCounts() {
@DisplayName("push·pull_request·merge_group·schedule 중 하나로도 시작하는 workflow의 명령은 센다")
void aWorkflowThatAlsoStartsOnTheChangeFlowCounts() {
// given
List<String> workflows =
List.of(
@@ -1252,16 +1252,6 @@ class WorkflowGradleInvocationsTest {
run: ./gradlew :ci
""",
"""
on:
release:
types: [published]
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""",
"""
on:
pull_request:
types: [opened, synchronize, labeled]
@@ -1279,10 +1269,167 @@ class WorkflowGradleInvocationsTest {
// then
assertThat(invocations)
.hasSize(5)
.hasSize(4)
.allSatisfy(invocation -> assertThat(invocation.executes(":ci", "src")).isTrue());
}
@Test
@DisplayName("paths·paths-ignore 필터가 붙은 change trigger로만 시작하는 workflow의 명령은 세지 않는다")
void aWorkflowThatStartsOnChangesOnlyThroughAPathFilterGatesNothing() {
// given
List<String> workflows =
List.of(
"""
on:
pull_request:
paths: ["docs/**"]
push:
branches: [main]
paths:
- "docs/**"
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""",
"""
on: {push: {paths-ignore: ["docs/**"]}, workflow_dispatch: {}}
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""",
"""
on:
pull_request: {types: [opened, synchronize], paths: ["src/**"]}
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""");
// when
List<Invocation> invocations =
workflows.stream().flatMap(workflow -> WorkflowGradleInvocations.read(workflow).stream())
.toList();
// then
assertThat(invocations)
.hasSize(3)
.allSatisfy(invocation -> assertThat(invocation.executes(":ci", "src")).isFalse());
assertThat(invocations).extracting(Invocation::uncountedReason)
.satisfiesExactly(
reason -> assertThat(reason).contains("pull_request (paths)", "push (paths)"),
reason -> assertThat(reason).contains("push (paths-ignore)"),
reason ->
assertThat(reason).contains("pull_request (types: opened, synchronize; paths)"));
}
@Test
@DisplayName("paths 필터가 붙은 trigger 옆에 필터 없는 change trigger가 있으면 그 workflow의 명령은 센다")
void aWorkflowWithAnUnfilteredChangeTriggerBesidesAPathFilterCounts() {
// given
String workflow =
"""
on:
pull_request:
paths: ["docs/**"]
schedule:
- cron: '0 3 * * *'
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :ci
""";
// when
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
// then
assertThat(invocations).singleElement().satisfies(
invocation -> assertThat(invocation.executes(":ci", "src")).isTrue());
}
@Test
@DisplayName("태그 push나 release로만 시작하는 workflow의 명령은 releaseCheck에만 센다")
void aWorkflowThatStartsOnlyOnTheReleaseFlowCountsOnlyForReleaseCheck() {
// given
List<String> workflows =
List.of(
"""
on:
push:
tags: ['v*']
jobs:
release:
steps:
- working-directory: src
run: ./gradlew :releaseCheck :integrationCheck
""",
"""
on:
release:
types: [published]
workflow_dispatch:
jobs:
release:
steps:
- working-directory: src
run: ./gradlew :releaseCheck :integrationCheck
""",
"""
on: {push: {tags-ignore: ['nightly-*']}}
jobs:
release:
steps:
- working-directory: src
run: ./gradlew :releaseCheck :integrationCheck
""");
// when
List<Invocation> invocations =
workflows.stream().flatMap(workflow -> WorkflowGradleInvocations.read(workflow).stream())
.toList();
// then
assertThat(invocations)
.hasSize(3)
.allSatisfy(
invocation -> {
assertThat(invocation.executes(":releaseCheck", "src")).isTrue();
assertThat(invocation.executes(":integrationCheck", "src")).isFalse();
});
}
@Test
@DisplayName("태그와 함께 브랜치도 받는 push로 시작하는 workflow의 명령은 모든 단계에 센다")
void aPushWithBranchesBesidesTagsCountsForEveryStage() {
// given
String workflow =
"""
on:
push:
branches: [main]
tags: ['v*']
jobs:
main:
steps:
- working-directory: src
run: ./gradlew :integrationCheck
""";
// when
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
// then
assertThat(invocations).singleElement().satisfies(
invocation -> assertThat(invocation.executes(":integrationCheck", "src")).isTrue());
}
@Test
@DisplayName("workflow_call로만 시작하는 재사용 workflow의 명령은 매 변경에 도는 호출 job이 있을 때만 센다")
void aReusableWorkflowCountsOnlyThroughACallerThatRunsOnEveryChange() {