diff --git a/CHANGELOG.md b/CHANGELOG.md
index c60df2d..345e1ab 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
@@ -82,6 +82,34 @@ 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
@@ -89,6 +117,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..a4212b9 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 系统依赖。
@@ -498,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/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/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);
+ }
+}
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)]