From b06595dbd6fe0496bdc3af1c80b304b157419ac9 Mon Sep 17 00:00:00 2001 From: wubing7755 Date: Thu, 5 Nov 2026 15:34:00 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=90=88=E5=B9=B6=E5=90=8E?= =?UTF-8?q?=E5=AF=B9=E8=B4=A6=20CI=20=E7=8A=B6=E6=80=81=E5=B9=B6=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=E5=85=B1=E4=BA=AB=E7=B1=BB=E5=8F=AF=E8=A7=81=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - EditDistance / JsonValueConverter 由 public 改回 internal,避免反向扩大 public 面(F 裁决) - 新增 SharedHelpers_AreNotPartOfThePublicApi 护栏断言 - CHANGELOG / limitations / review-v1-grill §15 更新为合并后的真实状态:PR #1 已 MERGED 为 f07a096,dev 首次 push CI (41987481649) 通过 - 移除过时的「改动未提交 / dev 从未触发 CI」等精度边界,重列仍待执行项 --- CHANGELOG.md | 13 ++++--- docs/limitations.md | 7 ++-- docs/review-v1-grill.md | 35 +++++++++---------- src/ActionLens.Core/Text/EditDistance.cs | 2 +- .../Values/JsonValueConverter.cs | 2 +- .../Values/SharedConvertersTests.cs | 11 ++++++ 6 files changed, 42 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c60df2d..3beae69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,11 +36,11 @@ Gate 2 is all of the following, run locally first and then in `.github/workflows All seven held in the first real CI run: `gate2` on `main` at `2363021` (run [`41977057618`](https://github.com/HestiaLab/ActionLens/actions/runs/41977057618), 2026-11-05, -both `engine` and `browser` jobs green). **That run covers the initial commit only.** The `dev` -branch has not triggered CI yet, and the working-copy edits that add `dev` to the workflow's push -trigger are themselves uncommitted. No release, no Pages deployment and no "verified" claim follows -from a green run alone — publishing remains an explicit act. Gate 1's engine decision was never a -release decision. +both `engine` and `browser` jobs green). Subsequent runs are also green: the `dev`-gating and Q6 +changes on PR #1 (runs `41981780325`, `41986150317`), and the first `push` to `dev` after that PR was +merged at `f07a096` (run `41987481649`). No release, no Pages deployment and no "verified" claim +follows from a green run alone — publishing remains an explicit act. Gate 1's engine decision was +never a release decision. ### Added @@ -89,6 +89,9 @@ corrected two claims in `docs/review-v1-grill.md` §7: there are **two** Levensh (the third is a positional hint heuristic with different behaviour), and **two** JSON→value copies, not three (the third converts YAML, which needs scalar resolution and source positions). +- `Text/EditDistance.cs` and `Values/JsonValueConverter.cs` are `internal`, not `public`: they were + introduced as public by mistake, widening the surface decision F asks to narrow. A + `SharedHelpers_AreNotPartOfThePublicApi` assertion guards against a regression. - `Text/EditDistance.cs` now owns `LevenshteinIgnoreCase`; `JobGraphAnalyzer` and `RunnerLabelTypoRule` call it instead of carrying their own copies. The `WorkflowModelBuilder` heuristic stays separate, with a comment explaining why sharing it would change the suggestion a reader sees. diff --git a/docs/limitations.md b/docs/limitations.md index df93aab..9754637 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -103,6 +103,7 @@ table of [ADR 0003](adr/0003-local-first-no-backend.md), not shipped features. T **jobs, not job instances** and says so on screen; the instance count is reported separately. No package, container image or hosted Pages deployment has been published. The source repository is -live at `HestiaLab/ActionLens`. Gate 2 (`CHANGELOG.md`) first went green in real CI on `main` at -`2363021` (run `41977057618`); pushes to both `dev` and `main` are wired to `.github/workflows/gate2.yml`, -but the `dev` branch has not had a run yet. Publishing remains an explicit act. +live at `HestiaLab/ActionLens`. Gate 2 (`CHANGELOG.md`) is green in real CI on both branches: first on +`main` at `2363021` (run `41977057618`), then on `dev` at `f07a096` after PR #1 was merged (run +`41987481649`). Pushes to `dev` and `main` both run `.github/workflows/gate2.yml`. Publishing remains +an explicit act. diff --git a/docs/review-v1-grill.md b/docs/review-v1-grill.md index b608d8b..071e2ee 100644 --- a/docs/review-v1-grill.md +++ b/docs/review-v1-grill.md @@ -446,23 +446,20 @@ Ui 24 → 25(`WorkspaceRenderTests`);Playwright 6 → 8(DOM 身份保护 **当时未执行**:`.github/workflows/gate2.yml` 在真实 GitHub Actions 上跑一次、Pages 部署, 以及 Q6 第二批结构重构。按 Q5/F 的裁决,这些都不应在本地伪造为已完成。 -> **状态更新(2026-11-05 14:20)**:初始提交 `2363021` 已创建并推送到 -> `HestiaLab/ActionLens`,远端已有 `main` 与 `dev` 两个分支;本地已切到 `dev` 并跟踪 -> `origin/dev`,后续提交落到 `dev`。 -> **Gate 2 首次真实 CI 运行已通过**:`gate2` workflow run -> [`41977057618`](https://github.com/HestiaLab/ActionLens/actions/runs/41977057618), -> `push` / `main` / `2363021` / conclusion `success`,`engine` 与 `browser` 两个 job 均绿 -> (2026-11-05 05:55 UTC,耗时 2m56s)。这把 §12「尚待在真实 CI 上跑一次」与 §15 的原待办 -> 推到了「已执行」,Q5/F 裁决里以 Gate 2 绿灯为前置条件的事项(Pages 部署、Q6 第二批结构重构) -> 现在解锁,但**都还没有执行**。 -> **流程更新(2026-11-05 14:36)**:`dev` 已设置保护规则,不能直接 push。改为从 `dev` 开 -> 特性分支、推送后开 PR(base `dev`),由维护者合并;`dev` → `main` 另开一次评审 PR。 -> 相应的 PR 与合并分别触发一次 gate2,文档已同步到 `CONTRIBUTING.md` / `README.md`。 -> **精度边界**:该 run 跑的是初始提交,当时的 workflow 触发条件是 `[main]`、注释仍写 six criteria。 -> 本地 7 个未提交改动(把触发改为 `[main, dev]`、把注释改为 seven criteria、以及仓库状态文档对账) -> 尚未提交、未推送、未经过 CI;`dev` 分支本身也从未触发过 workflow。因此不能把它读作 -> 「`dev` 已验证」或「当前工作区已验证」。 -> **仍待执行**:把这些改动提交到 `dev` 并让 `dev` 首次跑绿、Pages 部署、Q6 第二批结构重构。 +> **状态更新(2026-11-05 15:30,合并后复核)**:PR #1 已 `MERGED`(squash 为 `f07a096`), +> 特性分支已从远端删除;`main` 仍在 `2363021`。`dev` 受保护,后续改动从 `dev` 开特性分支、 +> 开 PR(base `dev`)由维护者合并;`dev` → `main` 另开评审 PR。 +> **Gate 2 的全部真实 CI 运行均为 `success`**: +> - `41977057618` — `push` / `main` / `2363021`(首次,2m56s) +> - `41981780325`、`41986150317` — `pull_request` / PR #1 的两个提交(含改后 workflow) +> - `41987481649` — `push` / `dev` / `f07a096`(`dev` 分支首次,两 job 均绿) +> +> 因此上一版写的「精度边界」(改动尚未提交/推送/经过 CI、`dev` 从未触发 workflow)已全部解除: +> 改后的 workflow(触发 `[main, dev]`、seven criteria 注释、v5/v6 actions、`ubuntu-24.04`) +> 已在 PR 与 `dev` push 两种事件下跑绿。Q5/F 里以 Gate 2 绿灯为前置的 Pages 部署与 Q6 +> 第二批结构重构已解锁;后者已由 §16 完成去重与 CI 技术债部分。 +> **仍待执行**:`dev` → `main` 评审 PR、Pages 首次部署与首个 release、§16 明确留下的 +> 「收窄 public 面 / 拆超长文件」,以及 ADR 0003 Deferred 的产品功能(Q2 已否决,须重开 ADR)。 --- @@ -489,7 +486,9 @@ Gate 2 在真实 CI 绿灯后,按 F 裁决解锁的「收窄 public 面 + 抽 - `tests/ActionLens.Core.Tests/Values/SharedConvertersTests.cs`:编辑距离(含对称性、大小写)、 JSON 各类型映射、`ReadObject` 跳过键与 `TryWrap` 拒绝 null,共 7 条断言。 - **收窄 public 面 / 拆超长文件仍未做**:那会改变约 55 个 public 类型的可见性并牵动大量测试, - 属于独立的 API 决策,不在这一批。 + 属于独立的 API 决策,不在这一批。但本批新增的两个共享类最初误写成 `public`,等于反向扩大了 + public 面;合并后已改回 `internal`(`InternalsVisibleTo` 已配置,测试不受影响),并加 + `SharedHelpers_AreNotPartOfThePublicApi` 护栏断言防止回退。 CI 技术债(上轮两条 annotation): - `runner` 固定为 `ubuntu-24.04`,避免 `ubuntu-latest` 迁移到 Ubuntu 26 时静默改变 Chromium 系统依赖。 diff --git a/src/ActionLens.Core/Text/EditDistance.cs b/src/ActionLens.Core/Text/EditDistance.cs index e2ac8ed..6b4ef13 100644 --- a/src/ActionLens.Core/Text/EditDistance.cs +++ b/src/ActionLens.Core/Text/EditDistance.cs @@ -10,7 +10,7 @@ namespace ActionLens.Core.Text; /// still quotes the id or label with the spelling the author used. This is a suggestion heuristic, not /// a general-purpose string metric — callers own their own distance budget. /// -public static class EditDistance +internal static class EditDistance { /// The number of single-character edits between two strings, ignoring case. public static int LevenshteinIgnoreCase(string left, string right) diff --git a/src/ActionLens.Core/Values/JsonValueConverter.cs b/src/ActionLens.Core/Values/JsonValueConverter.cs index 19fe264..87b112d 100644 --- a/src/ActionLens.Core/Values/JsonValueConverter.cs +++ b/src/ActionLens.Core/Values/JsonValueConverter.cs @@ -12,7 +12,7 @@ namespace ActionLens.Core.Values; /// rules (plain scalars become numbers/booleans/null) and needs the source text and position, which a /// does not carry. /// -public static class JsonValueConverter +internal static class JsonValueConverter { /// Turns any JSON element into the workflow value its type implies. public static GitHubValue ToValue(JsonElement element) => element.ValueKind switch diff --git a/tests/ActionLens.Core.Tests/Values/SharedConvertersTests.cs b/tests/ActionLens.Core.Tests/Values/SharedConvertersTests.cs index f28119e..404ea45 100644 --- a/tests/ActionLens.Core.Tests/Values/SharedConvertersTests.cs +++ b/tests/ActionLens.Core.Tests/Values/SharedConvertersTests.cs @@ -11,6 +11,17 @@ namespace ActionLens.Core.Tests.Values; /// public sealed class SharedConvertersTests { + /// + /// These are implementation details shared inside the engine, not API. Decision F asks for a + /// narrower public surface; making a helper public again would work against it. + /// + [Fact] + public void SharedHelpers_AreNotPartOfThePublicApi() + { + Assert.False(typeof(EditDistance).IsPublic); + Assert.False(typeof(JsonValueConverter).IsPublic); + } + [Theory] [InlineData("build", "Build", 0)] [InlineData("build", "buidl", 2)] From 49a34500405a71336ab7c91d315d01fca229d48e Mon Sep 17 00:00:00 2001 From: wubing7755 Date: Thu, 5 Nov 2026 17:11:50 +0800 Subject: [PATCH 2/2] =?UTF-8?q?refactor(core):=20=E6=94=B6=E7=AA=84=20publ?= =?UTF-8?q?ic=20=E9=9D=A2=E5=B9=B6=E4=BF=AE=E5=A4=8D=E4=B8=8D=E4=B8=80?= =?UTF-8?q?=E8=87=B4=20graph=20=E5=AF=BC=E8=87=B4=E7=9A=84=E5=BC=82?= =?UTF-8?q?=E5=B8=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 复现 §7 记录的缺陷:ScenarioEngine.Run 接受独立的 workflow 与 graph,外部传入不匹配的一对会抛 KeyNotFoundException - ScenarioEngine 收窄为 internal,WorkflowAnalyzer 成为唯一 public 入口;ScenarioRunner 过滤无法定位的 job id 并为每个产出 INT001/Internal/Error 诊断,不抛异常也不编造结果 - 批量收窄 27 个实现细节类型为 internal;边界由编译器的可访问性规则决定,15 个被 public 签名引用的契约类型保留 public - 新增 ScenarioEngineMismatchTests(含 A/B 复现)与 PublicSurfaceTests(11 条护栏断言) - §17 / CHANGELOG 记录边界判定方法与仍未做的拆超长文件 --- CHANGELOG.md | 28 ++++++++ docs/review-v1-grill.md | 52 ++++++++++++++ .../Expressions/ConditionEvaluator.cs | 4 +- .../Expressions/ExpressionFunctions.cs | 2 +- .../Expressions/ExpressionNodes.cs | 16 ++--- src/ActionLens.Core/Linting/LintEngine.cs | 2 +- .../Linting/Rules/ActionNotPinnedRule.cs | 2 +- .../Rules/DeprecatedWorkflowCommandRule.cs | 2 +- .../Linting/Rules/MissingTimeoutRule.cs | 2 +- .../Linting/Rules/NeedsIntegrityRule.cs | 2 +- .../Linting/Rules/RunnerLabelTypoRule.cs | 2 +- .../Linting/Rules/ScriptInjectionRule.cs | 2 +- .../Linting/Rules/SecretsInConditionRule.cs | 2 +- .../Linting/Rules/UntrustedCheckoutRule.cs | 2 +- .../Scenarios/EvaluationPosition.cs | 2 +- .../Scenarios/EvaluationScope.cs | 4 +- .../Scenarios/JobPositionContext.cs | 2 +- .../Scenarios/ScenarioEngine.cs | 46 +++++++++++- .../Scenarios/ScenarioResults.cs | 4 +- .../Scenarios/StepPositionContext.cs | 2 +- .../PublicSurfaceTests.cs | 55 +++++++++++++++ .../Scenarios/ScenarioEngineMismatchTests.cs | 70 +++++++++++++++++++ 22 files changed, 275 insertions(+), 30 deletions(-) create mode 100644 tests/ActionLens.Core.Tests/PublicSurfaceTests.cs create mode 100644 tests/ActionLens.Core.Tests/Scenarios/ScenarioEngineMismatchTests.cs diff --git a/CHANGELOG.md b/CHANGELOG.md index 3beae69..345e1ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -82,6 +82,34 @@ never a release decision. `docs/gate1-report.md`, `docs/w4-verification.md`, `docs/review-v1-grill.md`, `SECURITY.md`, `CONTRIBUTING.md`, and `docs/notes/atlas-0.4.0-api.md`. +### Changed — one public entry point (2026-11-05) + +Decision F asked for a narrower public surface; §7 recorded roughly 55 of 60 Core files exposing a +public type. The boundary was determined by the compiler, not by guesswork: 41 candidate types never +named outside Core were made `internal`, and every type the compiler rejected (CS0050/51/53/60, +because a public signature references it) was restored. Three iterations converged. + +- 27 types are now internal: `ScenarioEngine`, `LintEngine`, the eight lint rule implementations, + `ScenarioEvaluation`/`JobScenarioResult`, `ConditionEvaluator`, `ExpressionFunctions`, expression + node subtypes, `EvaluationScope` and friends. +- 15 stay public because they *are* the contract: `ExpressionNode`, `ILintRule`, the lint result + types, `MatrixCombination`/`MatrixRun`, `JobGraphEdge`/`JobGraphAnalysisResult`, `StepDefinition`, + `DefaultsSection`, `ConcurrencySection`, `WorkflowInput`, `TemplateSegment`. +- `PublicSurfaceTests` (11 assertions) pins the boundary against a future "just make it public" edit; + the compiler already enforces the opposite direction. + +This also fixed a real defect §7 had only flagged by inspection. `ScenarioEngine.Run` took the +workflow and the job graph as two independent arguments and indexed `_jobs[jobId]` directly, so a +caller supplying a graph built from a different document got a raw `KeyNotFoundException`. Making the +engine internal removes that path for external callers; inside, `ScenarioRunner` now filters ids it +cannot place and emits an `INT001` diagnostic per unknown id instead of throwing or inventing a +result. `ScenarioEngineMismatchTests` reproduces the mismatch and an A/B check confirms it fails +again when the guard is removed. + +Splitting the long files (`WorkflowModelBuilder`, `TriggerEvaluator`, `ExpressionBodyParser`, +`AnalysisReportJson`) is mechanical and remains for a later batch. Pages deployment and the first +release are still explicit, unperformed acts. + ### Changed — Q6 second batch: shared conversions and CI currency (2026-11-05) Gate 2 went green in CI, unlocking the post-gate structural work (decision F). Reviewing the code diff --git a/docs/review-v1-grill.md b/docs/review-v1-grill.md index 071e2ee..a4212b9 100644 --- a/docs/review-v1-grill.md +++ b/docs/review-v1-grill.md @@ -497,3 +497,55 @@ CI 技术债(上轮两条 annotation): 不跳到 v7 以减小变更面。依据写在 workflow 顶部注释里。 **复测**:构建 0/0 · 格式 0 · Core **1416**(新增 7 条)· Ui 25 · Playwright **8 / 8**。 + +--- + +## 17. 收窄 public 面与修复不一致 graph(2026-11-05 续四) + +§16 把「收窄 public 面」标成独立的 API 决策留待后续。合并到 `dev`、Gate 2 在 `main`/`dev`/PR +三种事件下都跑绿之后,这一批开始动它。**先复现再修,修正了 §7 的一处描述**: + +### 17.1 真实缺陷:不一致的 workflow 与 graph + +§7 记 `ScenarioEngine.Run`(`:141`、`:214`)用 `_jobs[jobId]` 直接索引,外部传入不一致的 +graph 会抛 `KeyNotFoundException`。本轮写了 +`tests/ActionLens.Core.Tests/Scenarios/ScenarioEngineMismatchTests.cs` 复现:把 `one.yml` 的模型 +与 `two.yml` 的 graph 一起传入,得到 `KeyNotFoundException: 'build'`。`WorkflowAnalyzer` 内部 +总是传匹配的一对(且有 INT001 兜底),但 `ScenarioEngine.Run` 本身是 public,外部可绕过入口。 + +修复(两条,方向都是「唯一入口」): +- `ScenarioEngine` 由 `public` 收窄为 `internal`——`WorkflowAnalyzer` 是唯一 public 入口, + 外部不再能构造不一致的一对。测试靠 `InternalsVisibleTo` 仍可直接调用。 +- `ScenarioRunner.Run` 在遍历 `TopologicalOrder` / `BlockedJobs` 前用 `_jobs.ContainsKey` 过滤, + 并新增 `ReportGraphJobsMissingFromWorkflow()`:每个无法定位的 job id 产出一条 INT001 / Internal / + Error 诊断,说明「graph 含该 id 但 workflow 没有」,建议从同一个 workflow 建 graph。 + 不抛异常、不给这些 job 编造结果(`Jobs` 为空),符合「宁可诚实未知,也不自信给错答案」。 + +**A/B**:临时恢复裸索引 → 复现用例重新抛 `KeyNotFoundException`;恢复修复后通过。 + +### 17.2 批量收窄,边界交给编译器 + +方法:先筛出「Ui / App / 两个测试程序集里从未按名字引用」的 41 个 Core public 类型; +批量改成 `internal` 后编译,按 CS0050/CS0051/CS0053/CS0060 报出的「可访问性不一致」逐个回退, +迭代 3 轮收敛。**这不是靠猜的边界**——被 public 签名引用的类型无法改成 internal,编译器会拒绝。 + +结果: +- **27 个类型收窄**(41 个候选中 26 个 + `LintEngine`),包括 `ScenarioEngine`、 + `ScenarioEvaluation` / `JobScenarioResult`、8 个 lint 规则类、`ConditionEvaluator` / + `ExpressionFunctions` / `ConditionOutcome`、表达式节点派生类、`EvaluationScope` 等内部构件。 +- **15 个保留 public**:`ExpressionNode`、`ILintRule`、`LintContext` / `LintResult` / + `LintFinding` / `LintCondition`、`MatrixCombination` / `MatrixRun`、`JobGraphEdge` / + `JobGraphAnalysisResult`、`StepDefinition` / `DefaultsSection` / `ConcurrencySection` / + `WorkflowInput` / `TemplateSegment`。它们出现在 public 属性/方法签名里,是 JSON 导出与 UI 真正 + 依赖的契约,不是「忘了收窄」。 +- 新增 `tests/ActionLens.Core.Tests/PublicSurfaceTests.cs`(11 条断言):契约类型保持 public、 + 实现类型不重新导出、public 的 `*Engine` 里不含 `ScenarioEngine` / `LintEngine`。 + 编译器保证另一半边界(public 签名不能引用 internal 类型),护栏保证这一半不回退。 + +### 17.3 仍未做 + +拆超长文件(`WorkflowModelBuilder` 1444、`TriggerEvaluator` 903、`ExpressionBodyParser` 757、 +`AnalysisReportJson` 559)是纯机械重构,独立于 API 决策,留到下一批;Pages 部署与首个 release、 +ADR 0003 Deferred 产品功能(Q2 已否决)同样未动。 + +**复测**:构建 0/0 · 格式 0 · Core **1430** · Ui 25 · Playwright **8 / 8**。 diff --git a/src/ActionLens.Core/Expressions/ConditionEvaluator.cs b/src/ActionLens.Core/Expressions/ConditionEvaluator.cs index 2e586a3..06d8169 100644 --- a/src/ActionLens.Core/Expressions/ConditionEvaluator.cs +++ b/src/ActionLens.Core/Expressions/ConditionEvaluator.cs @@ -7,7 +7,7 @@ namespace ActionLens.Core.Expressions; /// /// The answer to one if: condition, with everything that explains it. /// -public sealed record ConditionOutcome +internal sealed record ConditionOutcome { public required TriValue Value { get; init; } @@ -35,7 +35,7 @@ public sealed record ConditionOutcome /// github.ref == 'refs/heads/main' still does not run when an ancestor failed. Evaluating the /// bare condition instead would report jobs as running that GitHub would skip. /// -public sealed class ConditionEvaluator +internal sealed class ConditionEvaluator { private static readonly string[] StatusFunctionNames = ["success", "failure", "always", "cancelled"]; diff --git a/src/ActionLens.Core/Expressions/ExpressionFunctions.cs b/src/ActionLens.Core/Expressions/ExpressionFunctions.cs index f905a5f..7cceb00 100644 --- a/src/ActionLens.Core/Expressions/ExpressionFunctions.cs +++ b/src/ActionLens.Core/Expressions/ExpressionFunctions.cs @@ -18,7 +18,7 @@ namespace ActionLens.Core.Expressions; /// both implementations accept format(null) and format(''), so we do not reject one. /// /// -public static class ExpressionFunctions +internal static class ExpressionFunctions { private static readonly Dictionary Signatures = new(StringComparer.OrdinalIgnoreCase) { diff --git a/src/ActionLens.Core/Expressions/ExpressionNodes.cs b/src/ActionLens.Core/Expressions/ExpressionNodes.cs index 87d8bb4..8e18460 100644 --- a/src/ActionLens.Core/Expressions/ExpressionNodes.cs +++ b/src/ActionLens.Core/Expressions/ExpressionNodes.cs @@ -11,7 +11,7 @@ namespace ActionLens.Core.Expressions; public abstract record ExpressionNode(SourceRange Range); /// A quoted string, a number, or one of true, false, null. -public sealed record LiteralNode(GitHubValue Value, SourceRange Range) : ExpressionNode(Range); +internal sealed record LiteralNode(GitHubValue Value, SourceRange Range) : ExpressionNode(Range); /// /// The root of a context path: github in github.event.action. Whether the name is a @@ -23,7 +23,7 @@ public sealed record ContextNode(string Name, SourceRange Range) : ExpressionNod public sealed record MemberAccessNode(ExpressionNode Target, string Name, SourceRange Range) : ExpressionNode(Range); /// a['b'] or a[0]. The index is any expression, because GitHub allows one. -public sealed record IndexAccessNode(ExpressionNode Target, ExpressionNode Index, SourceRange Range) : ExpressionNode(Range); +internal sealed record IndexAccessNode(ExpressionNode Target, ExpressionNode Index, SourceRange Range) : ExpressionNode(Range); /// /// a.*, also written a[*]: the value of one link across every element or property of what @@ -38,13 +38,13 @@ public sealed record IndexAccessNode(ExpressionNode Target, ExpressionNode Index /// stands on its own instead of being an with a special index: the shape of /// the path, not the value of an index, decides whether the following access maps or reads. /// -public sealed record WildcardAccessNode(ExpressionNode Target, SourceRange Range) : ExpressionNode(Range); +internal sealed record WildcardAccessNode(ExpressionNode Target, SourceRange Range) : ExpressionNode(Range); /// !x. -public sealed record UnaryNotNode(ExpressionNode Operand, SourceRange Range) : ExpressionNode(Range); +internal sealed record UnaryNotNode(ExpressionNode Operand, SourceRange Range) : ExpressionNode(Range); /// Logical operators, in the order the source writes them. -public enum LogicalOperator +internal enum LogicalOperator { And, Or, @@ -58,13 +58,13 @@ public enum LogicalOperator /// and a chain of the same operator is left-associative, so a flat list is both smaller and closer to /// what the runner does than a binary tree. /// -public sealed record LogicalNode( +internal sealed record LogicalNode( LogicalOperator Operator, IReadOnlyList Operands, SourceRange Range) : ExpressionNode(Range); /// The six comparison operators. -public enum ComparisonOperator +internal enum ComparisonOperator { Equal, NotEqual, @@ -75,7 +75,7 @@ public enum ComparisonOperator } /// a == b, a < b and friends. -public sealed record ComparisonNode( +internal sealed record ComparisonNode( ComparisonOperator Operator, ExpressionNode Left, ExpressionNode Right, diff --git a/src/ActionLens.Core/Linting/LintEngine.cs b/src/ActionLens.Core/Linting/LintEngine.cs index f66a923..29efe82 100644 --- a/src/ActionLens.Core/Linting/LintEngine.cs +++ b/src/ActionLens.Core/Linting/LintEngine.cs @@ -17,7 +17,7 @@ namespace ActionLens.Core.Linting; /// than of eight authors' good intentions. /// /// -public static class LintEngine +internal static class LintEngine { /// Every rule ActionLens ships, in id order — AL001 through AL008. public static IReadOnlyList Rules { get; } = diff --git a/src/ActionLens.Core/Linting/Rules/ActionNotPinnedRule.cs b/src/ActionLens.Core/Linting/Rules/ActionNotPinnedRule.cs index 25358a7..441d780 100644 --- a/src/ActionLens.Core/Linting/Rules/ActionNotPinnedRule.cs +++ b/src/ActionLens.Core/Linting/Rules/ActionNotPinnedRule.cs @@ -13,7 +13,7 @@ namespace ActionLens.Core.Linting.Rules; /// the only accepted pin — a short SHA is called out as truncated rather than counted as pinned. /// /// -public sealed class ActionNotPinnedRule : ILintRule +internal sealed class ActionNotPinnedRule : ILintRule { public LintRuleDescriptor Descriptor => LintRuleTable.ActionNotPinned; diff --git a/src/ActionLens.Core/Linting/Rules/DeprecatedWorkflowCommandRule.cs b/src/ActionLens.Core/Linting/Rules/DeprecatedWorkflowCommandRule.cs index 23b055b..c43f5ee 100644 --- a/src/ActionLens.Core/Linting/Rules/DeprecatedWorkflowCommandRule.cs +++ b/src/ActionLens.Core/Linting/Rules/DeprecatedWorkflowCommandRule.cs @@ -14,7 +14,7 @@ namespace ActionLens.Core.Linting.Rules; /// parser this layer is not; the limit is stated here rather than hidden. /// /// -public sealed class DeprecatedWorkflowCommandRule : ILintRule +internal sealed class DeprecatedWorkflowCommandRule : ILintRule { private static readonly (string Command, string Replacement)[] Deprecated = [ diff --git a/src/ActionLens.Core/Linting/Rules/MissingTimeoutRule.cs b/src/ActionLens.Core/Linting/Rules/MissingTimeoutRule.cs index 5e5960c..73421b3 100644 --- a/src/ActionLens.Core/Linting/Rules/MissingTimeoutRule.cs +++ b/src/ActionLens.Core/Linting/Rules/MissingTimeoutRule.cs @@ -12,7 +12,7 @@ namespace ActionLens.Core.Linting.Rules; /// job has no timeout-minutes key to write, so asking for one would be a finding nobody can fix. /// /// -public sealed class MissingTimeoutRule : ILintRule +internal sealed class MissingTimeoutRule : ILintRule { public LintRuleDescriptor Descriptor => LintRuleTable.MissingTimeout; diff --git a/src/ActionLens.Core/Linting/Rules/NeedsIntegrityRule.cs b/src/ActionLens.Core/Linting/Rules/NeedsIntegrityRule.cs index 522d111..15ae96d 100644 --- a/src/ActionLens.Core/Linting/Rules/NeedsIntegrityRule.cs +++ b/src/ActionLens.Core/Linting/Rules/NeedsIntegrityRule.cs @@ -16,7 +16,7 @@ namespace ActionLens.Core.Linting.Rules; /// graph stage produced it before any condition was evaluated. /// /// -public sealed class NeedsIntegrityRule : ILintRule +internal sealed class NeedsIntegrityRule : ILintRule { public LintRuleDescriptor Descriptor => LintRuleTable.NeedsIntegrity; diff --git a/src/ActionLens.Core/Linting/Rules/RunnerLabelTypoRule.cs b/src/ActionLens.Core/Linting/Rules/RunnerLabelTypoRule.cs index 10a6c56..d1ac861 100644 --- a/src/ActionLens.Core/Linting/Rules/RunnerLabelTypoRule.cs +++ b/src/ActionLens.Core/Linting/Rules/RunnerLabelTypoRule.cs @@ -24,7 +24,7 @@ namespace ActionLens.Core.Linting.Rules; /// belong to the organisation. /// /// -public sealed class RunnerLabelTypoRule : ILintRule +internal sealed class RunnerLabelTypoRule : ILintRule { /// /// The documented hosted labels, kept small on purpose: the rule only judges near-misses, so an entry the diff --git a/src/ActionLens.Core/Linting/Rules/ScriptInjectionRule.cs b/src/ActionLens.Core/Linting/Rules/ScriptInjectionRule.cs index 85f2785..c6dc759 100644 --- a/src/ActionLens.Core/Linting/Rules/ScriptInjectionRule.cs +++ b/src/ActionLens.Core/Linting/Rules/ScriptInjectionRule.cs @@ -19,7 +19,7 @@ namespace ActionLens.Core.Linting.Rules; /// run: | body is not on the field's line. /// /// -public sealed class ScriptInjectionRule : ILintRule +internal sealed class ScriptInjectionRule : ILintRule { private static readonly string[] UntrustedRoots = ["github.event", "github.head_ref"]; diff --git a/src/ActionLens.Core/Linting/Rules/SecretsInConditionRule.cs b/src/ActionLens.Core/Linting/Rules/SecretsInConditionRule.cs index 162e104..ab8eea3 100644 --- a/src/ActionLens.Core/Linting/Rules/SecretsInConditionRule.cs +++ b/src/ActionLens.Core/Linting/Rules/SecretsInConditionRule.cs @@ -22,7 +22,7 @@ namespace ActionLens.Core.Linting.Rules; /// parses it, whatever this analysis decided to evaluate. /// /// -public sealed class SecretsInConditionRule : ILintRule +internal sealed class SecretsInConditionRule : ILintRule { /// /// The engine marks a context that is illegal in its position with the offending named value in diff --git a/src/ActionLens.Core/Linting/Rules/UntrustedCheckoutRule.cs b/src/ActionLens.Core/Linting/Rules/UntrustedCheckoutRule.cs index e6f4236..0d44e9f 100644 --- a/src/ActionLens.Core/Linting/Rules/UntrustedCheckoutRule.cs +++ b/src/ActionLens.Core/Linting/Rules/UntrustedCheckoutRule.cs @@ -22,7 +22,7 @@ namespace ActionLens.Core.Linting.Rules; /// job selector in the workflow syntax to check instead. /// /// -public sealed class UntrustedCheckoutRule : ILintRule +internal sealed class UntrustedCheckoutRule : ILintRule { private static readonly string[] HeadRefPaths = ["github.head_ref", "github.event.pull_request.head"]; diff --git a/src/ActionLens.Core/Scenarios/EvaluationPosition.cs b/src/ActionLens.Core/Scenarios/EvaluationPosition.cs index 3247ebc..c141f74 100644 --- a/src/ActionLens.Core/Scenarios/EvaluationPosition.cs +++ b/src/ActionLens.Core/Scenarios/EvaluationPosition.cs @@ -20,7 +20,7 @@ namespace ActionLens.Core.Scenarios; /// reason travels with the value in every unknown the evaluator produces. /// /// -public abstract class EvaluationPosition : IContextProvider +internal abstract class EvaluationPosition : IContextProvider { /// /// What jobs.<job_id>.if may read. env, matrix, strategy, diff --git a/src/ActionLens.Core/Scenarios/EvaluationScope.cs b/src/ActionLens.Core/Scenarios/EvaluationScope.cs index 4f71c0d..de50223 100644 --- a/src/ActionLens.Core/Scenarios/EvaluationScope.cs +++ b/src/ActionLens.Core/Scenarios/EvaluationScope.cs @@ -10,7 +10,7 @@ namespace ActionLens.Core.Scenarios; /// legality question the engine has to answer before any knowledge question — and it is the reason the /// seam exists at all. /// -public enum EvaluationPositionKind +internal enum EvaluationPositionKind { /// /// jobs.<job_id>.if. Evaluated before the job starts and, per the context availability @@ -35,7 +35,7 @@ public enum EvaluationPositionKind /// a caller must not be able to build a step position whose matrix belongs to another job. Everything in /// here is data the analysis already has; nothing is fetched, timed or generated. /// -public sealed record EvaluationScope +internal sealed record EvaluationScope { public required WorkflowDocument Workflow { get; init; } diff --git a/src/ActionLens.Core/Scenarios/JobPositionContext.cs b/src/ActionLens.Core/Scenarios/JobPositionContext.cs index 38b9286..d7475d2 100644 --- a/src/ActionLens.Core/Scenarios/JobPositionContext.cs +++ b/src/ActionLens.Core/Scenarios/JobPositionContext.cs @@ -13,7 +13,7 @@ namespace ActionLens.Core.Scenarios; /// from the upstream jobs the engine already resolved, which is why this class takes the computed /// instead of asking the run anything. /// -public sealed class JobPositionContext : EvaluationPosition +internal sealed class JobPositionContext : EvaluationPosition { public JobPositionContext(EvaluationScope scope) : base(scope, EvaluationPositionKind.Job) diff --git a/src/ActionLens.Core/Scenarios/ScenarioEngine.cs b/src/ActionLens.Core/Scenarios/ScenarioEngine.cs index f785103..8734dd0 100644 --- a/src/ActionLens.Core/Scenarios/ScenarioEngine.cs +++ b/src/ActionLens.Core/Scenarios/ScenarioEngine.cs @@ -13,6 +13,9 @@ namespace ActionLens.Core.Scenarios; /// evaluator — into one answer for one scenario: which jobs run, which do not, and why. /// /// +/// Internal on purpose: is the one entry point, and it always builds the +/// graph from the workflow it passes here. Exposing this as a public entry point let a caller supply a +/// graph from a different document and get a KeyNotFoundException from the middle of the walk. /// The engine walks the graph in topological order and never looks ahead, so a job's needs always /// hold finished outcomes by the time its condition is read. Two rules do most of the work: /// @@ -29,7 +32,7 @@ namespace ActionLens.Core.Scenarios; /// position either: their state is unknown with a reason naming the cycle, even when their condition would /// have evaluated to true. /// -public static class ScenarioEngine +internal static class ScenarioEngine { /// /// Evaluates one workflow under one scenario. @@ -106,16 +109,25 @@ internal ScenarioRunner( internal ScenarioEvaluation Run() { ReportPinsThatNameNoJob(); + ReportGraphJobsMissingFromWorkflow(); var outputs = CollectJobOutputs(); foreach (var jobId in _graph.TopologicalOrder) { - Place(jobId, outputs); + // A graph built from a different workflow names ids this model cannot place. Say so and + // keep walking the rest rather than throwing from the middle of the pass. + if (_jobs.ContainsKey(jobId)) + { + Place(jobId, outputs); + } } foreach (var jobId in _graph.BlockedJobs) { - PlaceWithoutOrder(jobId, outputs); + if (_jobs.ContainsKey(jobId)) + { + PlaceWithoutOrder(jobId, outputs); + } } var jobs = new List(_graph.JobIds.Count); @@ -289,6 +301,34 @@ private void ReportConflictWithNeeds(string jobId, ScenarioJobState pin, IReadOn } } + /// + /// The workflow and the graph arrive as two independent arguments. + /// always passes a matching pair, but a caller of the API can pass a graph built from a different + /// document. Those ids have no definition to place, so name them as an internal failure instead of + /// letting a dictionary index throw from inside the walk. + /// + private void ReportGraphJobsMissingFromWorkflow() + { + foreach (var jobId in _graph.JobIds) + { + if (_jobs.ContainsKey(jobId)) + { + continue; + } + + _findings.Add(new Diagnostic + { + Code = DiagnosticCodes.AnalysisFailed, + Severity = DiagnosticSeverity.Error, + Stage = DiagnosticStage.Internal, + Message = $"The job graph contains '{jobId}', but the workflow has no job with that id, " + + "so that job's run cannot be evaluated.", + Range = SourceRange.Unknown, + Suggestion = "Build the graph from the same workflow that is passed to the scenario engine.", + }); + } + } + private void ReportPinsThatNameNoJob() { foreach (var pair in _scenario.JobStates.OrderBy(entry => entry.Key, StringComparer.Ordinal)) diff --git a/src/ActionLens.Core/Scenarios/ScenarioResults.cs b/src/ActionLens.Core/Scenarios/ScenarioResults.cs index c8d8025..402480e 100644 --- a/src/ActionLens.Core/Scenarios/ScenarioResults.cs +++ b/src/ActionLens.Core/Scenarios/ScenarioResults.cs @@ -83,7 +83,7 @@ public sealed record MatrixRun } /// What the scenario decided about one job. -public sealed record JobScenarioResult +internal sealed record JobScenarioResult { public required string JobId { get; init; } @@ -120,7 +120,7 @@ public sealed record JobScenarioResult /// The whole run the scenario describes: every job in document order, with its state, its condition /// trace and its steps, plus the findings the three positions made on the way. /// -public sealed record ScenarioEvaluation +internal sealed record ScenarioEvaluation { public required IReadOnlyList Jobs { get; init; } diff --git a/src/ActionLens.Core/Scenarios/StepPositionContext.cs b/src/ActionLens.Core/Scenarios/StepPositionContext.cs index 1f403b4..8d5df99 100644 --- a/src/ActionLens.Core/Scenarios/StepPositionContext.cs +++ b/src/ActionLens.Core/Scenarios/StepPositionContext.cs @@ -20,7 +20,7 @@ namespace ActionLens.Core.Scenarios; /// its own condition does not make a later step's success() false. /// /// -public sealed class StepPositionContext : EvaluationPosition +internal sealed class StepPositionContext : EvaluationPosition { public StepPositionContext(EvaluationScope scope) : base(scope, EvaluationPositionKind.Step) diff --git a/tests/ActionLens.Core.Tests/PublicSurfaceTests.cs b/tests/ActionLens.Core.Tests/PublicSurfaceTests.cs new file mode 100644 index 0000000..995e69b --- /dev/null +++ b/tests/ActionLens.Core.Tests/PublicSurfaceTests.cs @@ -0,0 +1,55 @@ +namespace ActionLens.Core.Tests; + +/// +/// Decision F asks for one public entry point. §7 recorded that roughly 55 of 60 Core files exposed a +/// public type; after the post-gate narrowing pass, the model and finding types that the JSON export +/// and the UI actually consume remain public, while implementation details are internal. +/// This test pins that boundary so a future "make it public, it's easier" edit cannot quietly widen +/// the API again. The compiler already enforces the other direction: a type used in a public signature +/// cannot be made internal (CS0050/CS0051/CS0053/CS0060). +/// +public sealed class PublicSurfaceTests +{ + /// The types that are genuinely part of the contract the reader and the UI rely on. + [Theory] + [InlineData("ActionLens.Core.WorkflowAnalyzer")] + [InlineData("ActionLens.Core.Reporting.AnalysisReport")] + [InlineData("ActionLens.Core.Diagnostics.Diagnostic")] + [InlineData("ActionLens.Core.Scenarios.Scenario")] + public void ContractTypes_ArePublic(string fullName) + { + var type = typeof(WorkflowAnalyzer).Assembly.GetType(fullName); + Assert.NotNull(type); + Assert.True(type!.IsPublic, $"{fullName} is part of the observable contract and must stay public."); + } + + /// These are internal machinery; exposing them again would widen the API for no reason. + [Theory] + [InlineData("ActionLens.Core.Scenarios.ScenarioEngine")] + [InlineData("ActionLens.Core.Scenarios.ScenarioRunner")] + [InlineData("ActionLens.Core.Expressions.ConditionEvaluator")] + [InlineData("ActionLens.Core.Expressions.ExpressionFunctions")] + [InlineData("ActionLens.Core.Linting.Rules.ScriptInjectionRule")] + [InlineData("ActionLens.Core.Linting.Rules.RunnerLabelTypoRule")] + public void ImplementationTypes_AreNotExported(string fullName) + { + var type = typeof(WorkflowAnalyzer).Assembly.GetType(fullName); + Assert.NotNull(type); + Assert.False(type!.IsVisible, $"{fullName} is internal machinery and must not be exported."); + } + + [Fact] + public void NoMoreThanOneEntryPointHasTheWordEngine() + { + // A coarse guard: only the analyzer is a public "engine". ScenarioEngine, LintEngine and the + // evaluators are stages it drives, not alternative front doors. + var publicEngines = typeof(WorkflowAnalyzer).Assembly.GetExportedTypes() + .Where(type => type.Name.EndsWith("Engine", StringComparison.Ordinal)) + .Select(type => type.Name) + .ToArray(); + + Assert.DoesNotContain("ScenarioEngine", publicEngines); + Assert.DoesNotContain("LintEngine", publicEngines); + Assert.NotNull(typeof(WorkflowAnalyzer).Assembly.GetType("ActionLens.Core.WorkflowAnalyzer")); + } +} diff --git a/tests/ActionLens.Core.Tests/Scenarios/ScenarioEngineMismatchTests.cs b/tests/ActionLens.Core.Tests/Scenarios/ScenarioEngineMismatchTests.cs new file mode 100644 index 0000000..7826d1d --- /dev/null +++ b/tests/ActionLens.Core.Tests/Scenarios/ScenarioEngineMismatchTests.cs @@ -0,0 +1,70 @@ +using ActionLens.Core.Diagnostics; +using ActionLens.Core.Graph; +using ActionLens.Core.Scenarios; +using ActionLens.Core.Yaml; + +namespace ActionLens.Core.Tests.Scenarios; + +/// +/// §7 recorded that ScenarioEngine.Run takes the workflow and the job graph as two independent +/// arguments and indexes _jobs[jobId] directly. The in-repo caller always passes a matching pair, +/// but the API is public: a mismatched pair used to escape as a raw KeyNotFoundException from deep inside +/// the walk, which is neither a diagnostic nor an honest unknown. +/// +public sealed class ScenarioEngineMismatchTests +{ + private const string TwoJobs = """ + name: two + on: push + jobs: + build: + runs-on: ubuntu-latest + deploy: + needs: [build] + runs-on: ubuntu-latest + """; + + private const string OneJob = """ + name: one + on: push + jobs: + solo: + runs-on: ubuntu-latest + """; + + [Fact] + public void MismatchedGraph_DoesNotThrow_AndReportsTheUnknownJob() + { + var workflow = WorkflowLoader.Load(OneJob, "one.yml").Workflow!; + var otherGraph = JobGraph.Build(WorkflowLoader.Load(TwoJobs, "two.yml").Workflow!).Graph; + + // The graph names build/deploy; the workflow only defines solo. + Assert.DoesNotContain("build", workflow.Jobs.Select(job => job.Id)); + + var evaluation = ScenarioEngine.Run(workflow, otherGraph, null); + + // No raw KeyNotFoundException, and no confident answer about a job with no definition. + Assert.Empty(evaluation.Jobs); + Assert.Equal(2, evaluation.Diagnostics.Count); + Assert.All(evaluation.Diagnostics, finding => + { + Assert.Equal(DiagnosticCodes.AnalysisFailed, finding.Code); + Assert.Equal(DiagnosticStage.Internal, finding.Stage); + Assert.Equal(DiagnosticSeverity.Error, finding.Severity); + Assert.Contains("same workflow", finding.Suggestion ?? string.Empty, StringComparison.Ordinal); + }); + Assert.Contains(evaluation.Diagnostics, finding => finding.Message.Contains("build", StringComparison.Ordinal)); + Assert.Contains(evaluation.Diagnostics, finding => finding.Message.Contains("deploy", StringComparison.Ordinal)); + } + + /// + /// Decision F asks for one entry point. ScenarioEngine used to be public specifically so a caller + /// could supply an unrelated graph; narrowing it removes that whole class of misuse. + /// + [Fact] + public void ScenarioEngine_IsInternal_WithWorkflowAnalyzerAsThePublicEntryPoint() + { + Assert.False(typeof(ScenarioEngine).IsPublic); + Assert.True(typeof(WorkflowAnalyzer).IsPublic); + } +}