Evaluate YAML parser support for scalar source maps

[kjanat]

Context

PR #2 reconstructs source positions for ShellCheck diagnostics from the decoded run: value and the original workflow text. The local mapper deliberately supports plain and literal scalars and falls back to the run: key when an exact mapping is unsafe.

The current go.yaml.in/yaml/v4 public Node API exposes the decoded value, scalar style, and starting line/column, but not the raw scalar text, byte offsets, end mark, or decoded-character mapping. Its internal scanner/parser carries start and end marks, but the composer does not retain all of them on Node.

Option 1: propose support in go-yaml

Investigate an upstream issue or pull request for one or more of:

• raw scalar source text or a stable source slice;
• start and end byte/line/column marks on nodes;
• decoded-scalar-to-source mapping spans produced while resolving escapes, indentation, folding, and chomping;
• a lower-level public token/event API that retains this information without changing ordinary decoding.

Relevant implementation: yaml/go-yaml Node, internal marks, and composer.

Option 2: evaluate goccy/go-yaml

goccy/go-yaml exposes AST tokens with decoded Value, raw Origin, and Position.Offset, which may be sufficient to construct comprehensive mappings for plain, literal, folded, single-quoted, and double-quoted scalars. It does not appear to expose the final per-character mapping directly.

Evaluate:

• correctness across escapes, folding, chomping, blank lines, Unicode, tabs, comments, anchors, and aliases;
• the open offset correctness report goccy/go-yaml#858;
• parser compatibility with GitHub workflow syntax and actionlint fixtures;
• performance and dependency cost;
• a full parser migration versus using only its lexer/parser as a source-location sidecar.

Relevant implementation: token API and AST scalar nodes.

Decision criteria

Prefer an approach only if it materially expands exact coverage beyond plain and literal scalars without weakening parse compatibility, diagnostics, or maintenance. Keep the existing conservative fallback when no trustworthy mapping is available.

Research findings (2026-08-20)

Decision

Keep go.yaml.in/yaml/v4 as the semantic parser. Do not adopt goccy/go-yaml as either a source-location sidecar or a full parser replacement. Extend the existing source mapper directly from the original workflow text, and accept a mapping only when its reconstructed decoded value exactly matches yaml.Node.Value.

This keeps the script passed to ShellCheck under the current parser's control. The mapping layer supplies positions only; it must never replace or reinterpret the effective run: value.

Corrections to the original investigation

• goccy/go-yaml#858 is unrelated to offsets. It requests a different custom marshaling API.
• The applicable open offset report is goccy/go-yaml#856: every preceding comment shifts subsequent offsets.
• Related open position defects include incorrect CRLF line counting in goccy/go-yaml#560 and end-like positions for multiline tokens in goccy/go-yaml#813.
• A matching go-yaml request already exists. yaml/go-yaml#373 asks for node indentation and end marks specifically for actionlint's ShellCheck mapping use case.
• yaml/go-yaml#391 is an open, mergeable PR adding EndLine and EndColumn. It does not add indentation, raw source, byte offsets, or decoded-character mapping, and no released version contains it yet.
• The public token/event direction has already met resistance upstream. The CLI work merged in yaml/go-yaml#140 exposes parser internals only inside the module rather than as a supported public library API.

goccy/go-yaml evaluation

The proposed Origin plus Position.Offset design is not safe:

• Position.Offset is not a stable byte offset. The scanner operates on []rune and advances offsets by rune counts. In a probe where run: followed café, its reported position was one byte short of the 1-based byte position.
• Comments additionally shift offsets, reproducing #856.
• CRLF input reproduced the line-number problem from Support yaml anchors rhysd/actionlint#560.
• Literal and folded scalar content tokens reported positions at the end of their multiline content rather than its start, matching #813.
• Origin is not reliably source-identical. For a double-quoted \u00e9 escape, v1.19.2 omitted the escape text from Origin; current master retains the scanner path that does not append the x, u, or U escape digits to the origin buffer.
• The API still provides no decoded-character-to-source spans. Escapes, quote collapsing, folding, indentation, and chomping would still have to be reconstructed in actionlint.

Semantic probes also rule out a full migration:

• yes, no, and on decoded as strings, matching YAML 1.2 expectations.
• Duplicate keys were rejected.
• 010 decoded as octal 8; goccy/go-yaml#894 tracks this YAML 1.1 behavior. GitHub's runner applies YAML 1.2 decimal handling.
• Merge keys were expanded. This differs from actionlint's intended GitHub compatibility behavior and would require separate hosted-service validation.

The GitHub implementations remain useful references. The current runner uses YAML 1.2 core scalar resolution, while @actions/workflow-parser retains decoded values, raw scalar source, block-scalar headers, and source ranges. The latter demonstrates that preserving source tokens is practical, but it does not provide the per-character map needed here.

Performance and dependency cost

A local five-sample parser benchmark used a synthetic 32,818-byte workflow containing 30 jobs and 360 steps across all scalar styles:

Operation	Time	Bytes allocated	Allocations
Existing go-yaml node parse	about 1.61 ms	about 0.70 MB	10,781
Additional goccy AST parse	about 4.02 ms	about 2.47 MB	42,878
Goccy tokenization only	about 1.95 ms	about 1.28 MB	21,357

Adding the AST sidecar would make the YAML parsing stage about 3.5 times slower and 4.5 times heavier in allocated bytes before lint rules run. Whole-lint impact would be smaller when external checks dominate.

goccy/go-yaml has no external module dependencies. In a minimal linked-binary comparison, adding its parser alongside go-yaml increased the binary by about 734 KB. Correctness remains the blocking concern; the performance and binary costs are secondary.

Implementation plan

1. Preserve a single semantic authority

• Continue parsing workflows and deriving run: values exclusively with go.yaml.in/yaml/v4.
• Keep the source mapper internal to parser metadata. It must not change the public AST or the script sent to ShellCheck.
• Do not add goccy/go-yaml.

2. Build a scalar mapping corpus

Add table-driven parser tests for:

• plain, literal, folded, single-quoted, and double-quoted scalars;
• |, |-, |+, >, >-, and >+;
• escaped characters and escaped physical line breaks;
• doubled single quotes;
• folded line joins, more-indented lines, blank lines, and chomping;
• leading and trailing indentation, tabs where valid, comments, Unicode, CRLF, anchors, and aliases.

Each case must record the expected decoded script and expected YAML positions for selected script characters. The reconstructed decoded bytes must equal yaml.Node.Value before any mapping is accepted.

3. Extend the existing mapper incrementally

Implement independent style-specific decoders in this order:

1. single-line and multiline single-quoted scalars;
2. double-quoted scalars, including escapes and escaped line breaks;
3. folded block scalars, including folding and chomping rules.

Each decoder should emit sparse scriptSourceSpan records while reconstructing the decoded script. Source characters that synthesize no decoded character, and decoded whitespace synthesized by YAML folding, should remain outside mapped spans.

4. Enforce conservative per-diagnostic fallback

• Reject the entire candidate map if reconstructed bytes differ from yaml.Node.Value or if the scalar boundary cannot be established safely.
• Preserve gaps for synthesized characters rather than guessing a position.
• Use exact source ranges only when both ShellCheck endpoints map safely.
• Otherwise report that diagnostic at run.RunPos, preserving the existing behavior.

5. Track the upstream improvement without blocking

• Follow Record node end positions (EndLine/EndColumn) yaml/go-yaml#391 and use released end positions when available to simplify scalar-boundary detection.
• If more upstream support is pursued, continue Provide more node information like indent and end marks yaml/go-yaml#373 rather than opening a duplicate. The most useful addition would be opt-in raw scalar/source-span metadata or decoded-to-source spans; EndLine and EndColumn alone do not solve scalar transformations.
• Do not depend on an unreleased go-yaml commit for this work.

6. Keep hosted compatibility testing separate

A GitHub-hosted conformance probe remains valuable for actionlint's parser compatibility as a whole, especially for scalar resolution and rejecting constructs. It is not a prerequisite for this mapping implementation because the mapper does not become a semantic parser.

If the hosted probe is implemented, record dated observations for accepted values and isolate parser-rejection cases into separate workflow revisions so one invalid construct cannot mask the rest of the corpus.

Acceptance criteria

• Exact mapping expands beyond plain and literal scalars with no new YAML parser dependency.
• Every accepted mapping reproduces yaml.Node.Value byte-for-byte.
• Unsafe scalar boundaries, transformations, and diagnostic endpoints retain the run:-key fallback.
• Existing plain/literal mappings and Unicode-aware ShellCheck ranges remain unchanged.
• Parser and ShellCheck fixtures cover all supported and fallback cases.
• go test ./..., go test -race ./..., go vet ./..., the repository's static checks, and git diff --check pass.

[coderabbitai]

🔗 Related PRs

#2 - Report ShellCheck errors at source locations [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Treat this as an evaluation spike with a measurable corpus first. No parser gets adopted on faith. That is non-negotiable, savvy.
• Prototype goccy/go-yaml as a source-location sidecar, because it already exposes raw text (token.Origin) and byte offsets (token.Position.Offset), while keeping go.yaml.in/yaml/v4 as the main parser.
• Investigate the upstream go-yaml change in parallel and draft a proposal, but do not block the ticket on an unmerged, rc-stage dependency.
• Adopt a change only if it widens exact scalar coverage without hurting compatibility, diagnostics, or maintenance. Always keep the conservative fallback to run.RunPos. When the mapping finally lands clean, that is the good day, and I will be insufferably pleased about it.

Design Choices

Design Choice 1: Which option should the evaluation prototype first and treat as the leading candidate?

Options Considered:

1. Prototype Option 2 (goccy/go-yaml) first as a source-location sidecar, keep go.yaml.in/yaml/v4 as the main parser, and pursue Option 1 only as a parallel upstream investigation.
2. Prototype Option 1 (upstream go-yaml) first and block on upstream acceptance.
3. Attempt a full parser migration to goccy/go-yaml immediately.

Chosen Option: 1

Rationale: The ticket presents two options and demands evidence before any change. The findings already show that go.yaml.in/yaml/v4 does not expose byte offsets, end marks, or raw scalar text on Node, and that its internal composer discards StartMark.Index/EndMark.Index. So Option 1 needs an upstream change that the project does not control and that has no existing issue or PR. goccy/go-yaml already exposes token.Origin (raw text) and token.Position.Offset (byte offset), which is exactly the raw material the mapper needs. Option 1 (prototype goccy/go-yaml as a sidecar first) is chosen: it uses public API that already carries raw text and offsets, it does not depend on an unmerged upstream change, and it avoids the risk of a full migration against actionlint's deep yaml.Node/Kind/Style/Tag/LoadErrors usage.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Establish the evaluation baseline and the test corpus

This phase pins down what "correct" means before any parser is judged. The goal is a repeatable measurement, not a vibe. It records the current mapper behaviour and builds a fixture set that exercises every scalar style so that each candidate is scored against the same evidence.

Task 1: Document the current mapper behaviour and its exact coverage

Capture what PR #2 already does so the evaluation has a clear baseline.

• Record the current flow in rule_shellcheck.go: ShellCheck runs on run.Run.Value, findings report at run.RunPos, and the in-script line:col is embedded in the message text only.
• State the confirmed limitation from the codebase: no back-mapping exists, Node.Style is only used for the Quoted flag, and the AST keeps no byte offsets or raw span.
• Define the two coverage tiers to improve: exact mapping (currently plain and literal scalars per the ticket) and conservative fallback (the run: key position).

Task 2: Build a scalar-style test corpus

Create fixtures that stress every mapping edge case named in the ticket.

• Add YAML fixtures under testdata/ that cover plain, single-quoted, double-quoted, literal |, and folded > scalars, each with chomping indicators (|-, |+, >-, >+).
• Include cases with escapes, folded line joins, blank lines, leading and trailing indentation, tabs, multi-byte Unicode, comments, anchors, and aliases.
• For each fixture, record the expected original-file line:col for a known token inside the run: script, so mapping output can be compared automatically.

🤖 Prompt for AI agents

Implement Phase 1 of the ShellCheck source-mapping evaluation: build the
baseline record and the test corpus that all later candidate comparisons depend
on.

- Write up the current mapper behaviour as a baseline document. State that
`rule_shellcheck.go` runs ShellCheck on `run.Run.Value` and reports every
finding at `run.RunPos` (the `run:` key position). State that the in-script
`line:col` from ShellCheck exists only inside the message text and is never
mapped back to the YAML file.
- Confirm and record the known limitation: there is no back-mapping mechanism,
`Node.Style` is used only to set the `Quoted` flag, and the AST stores no byte
offsets or raw source span.
- Define two named coverage tiers for use in later phases: 'exact mapping'
(currently limited to plain and literal scalars) and 'conservative fallback'
(reporting at the `run:` key position).
- Build a set of YAML fixtures under `testdata/` covering every scalar style:
plain, single-quoted, double-quoted, literal (`|`), and folded (`>`), each
combined with chomping indicators `|-`, `|+`, `>-`, `>+`.
- Extend the fixtures with edge cases: escapes, folded line joins, blank lines,
leading/trailing indentation, tabs, multi-byte Unicode characters, comments,
anchors, and aliases.
- For every fixture, record the expected original-file `line:col` for a known
token inside the `run:` script, so that any candidate mapper's output can be
automatically checked against these expected values in later phases.

Phase 2: Evaluate goccy/go-yaml as a source-location sidecar

This phase tests the leading candidate. The goal is to prove or disprove that goccy/go-yaml gives exact source spans for more scalar styles, without replacing the main parser and without weakening diagnostics. Keep goccy/go-yaml inside a throwaway prototype branch or a temporary package; do not wire it into the default lint path yet.

Task 1: Prototype a sidecar mapping pass

Build a minimal, isolated pass that reconstructs source positions from raw tokens.

• Add goccy/go-yaml as a prototype dependency in go.mod/go.sum; note that the module graph has no YAML conflicts, so this is additive.
• Create a prototype helper in a new directory (for example internal/scalarmap/) that lexes the original workflow bytes with goccy/go-yaml, locates the run: scalar by position, and uses token.Origin plus token.Position.Offset to map an in-script offset back to a file line:col.
• Thread the raw content []byte from linter.go check into the prototype only; do not change the Rule/Pass public surface for the spike. A SetSource([]byte) style hook is the intended shape if the option is later adopted.

Task 2: Measure mapping correctness against the corpus

Score the sidecar against the Phase 1 fixtures. Perfectionist rules apply: a wrong column is a failure, not a rounding error.

• Run the prototype over every fixture and compare produced line:col against the expected values.
• Verify behaviour across escapes, folding, chomping, blank lines, Unicode, tabs, comments, anchors, and aliases.
• Reproduce and assess goccy/go-yaml#858: confirm whether token.Position.Offset is wrong after multi-byte characters, and record the impact on the Unicode fixtures.
• Note that StringNode.String() output is not guaranteed byte-identical to input; rely on Origin and offsets, not re-rendered node text.

Task 3: Assess compatibility, performance, and dependency cost

Judge whether the sidecar is safe to ship, not just whether it maps well on happy paths.

• Parse the existing actionlint workflow fixtures with goccy/go-yaml and confirm it accepts GitHub Actions workflow syntax that go.yaml.in/yaml/v4 accepts today.
• Measure added lint time and memory for a second parse pass per file; record the overhead.
• Record the added dependency weight and maintenance cost of a second YAML library.
• Decide the integration shape: sidecar lexer/parser only (recommended default) versus a full parser migration (which would require rewriting all yaml.Node/Kind/Style/Tag/LoadErrors usage in parse.go, config.go, action_metadata.go, reusable_workflow.go, and others).

🤖 Prompt for AI agents

Implement Phase 2 of the evaluation: build and score a prototype sidecar that
uses `goccy/go-yaml` to reconstruct exact source positions, without touching the
default lint path or the main parser.

- Add `goccy/go-yaml` to `go.mod`/`go.sum` as a prototype-only dependency.
Confirm the module graph has no YAML conflicts with the existing
`go.yaml.in/yaml/v4` dependency; this addition is additive only.
- Create a new prototype package, for example `internal/scalarmap/`, that: lexes
the original workflow bytes with `goccy/go-yaml`, locates the `run:` scalar by
position, and uses `token.Origin` (raw text) plus `token.Position.Offset` (byte
offset) to map an in-script offset back to a file `line:col`.
- Thread the raw `content []byte` from `linter.go`'s `check` function into the
prototype only, for this spike. Do not change the public `Rule`/`Pass` surface
yet. Keep in mind the intended future shape is a small additive
`SetSource([]byte)` hook, if the option is adopted later.
- Run the prototype over every Phase 1 fixture and compare the produced
`line:col` against the recorded expected values. Check behaviour specifically
for escapes, folded line joins, chomping indicators, blank lines, Unicode, tabs,
comments, anchors, and aliases.
- Reproduce and assess `goccy/go-yaml#858`: check whether
`token.Position.Offset` is incorrect after multi-byte characters, and record its
effect on the Unicode fixtures.
- Do not rely on `StringNode.String()` output for mapping, since it is not
guaranteed to be byte-identical to the input. Use `Origin` and offsets only.
- Parse the existing actionlint workflow fixtures with `goccy/go-yaml` and
confirm that it accepts all GitHub Actions workflow syntax that
`go.yaml.in/yaml/v4` currently accepts.
- Measure the added lint time and memory cost of running a second parse pass per
file, and record these numbers.
- Record the dependency weight and maintenance cost of adding a second YAML
library to the project.
- Decide and record the integration shape: a sidecar lexer/parser only (the
recommended default), versus a full parser migration. Note that a full migration
would require rewriting all `yaml.Node`/`Kind`/`Style`/`Tag`/`LoadErrors` usage
across `parse.go`, `config.go`, `action_metadata.go`, `reusable_workflow.go`,
and other files.

Phase 3: Investigate the upstream go-yaml option in parallel

This phase pursues Option 1 without blocking on it. The goal is a concrete upstream ask and an honest read of its feasibility.

Confirm the upstream gap and draft a proposal

Document exactly what go.yaml.in/yaml/v4 lacks and what change would fix it.

• Confirm from the internal implementation that Event carries StartMark/EndMark with a 0-based byte Index, but the composer only keeps Line/Column on Node.
• Draft an upstream issue or pull request proposal for one of: raw scalar source text, start and end marks on Node, a decoded-to-source mapping span, or a lower-level public token/event API.
• Record that no matching upstream issue or PR currently exists, that v4 is still at rc, and that the project chose go.yaml.in/yaml deliberately as the maintained successor. Treat upstream as a longer-term path, not a blocker for this ticket.

🤖 Prompt for AI agents

Implement Phase 3 of the evaluation: investigate the upstream `go-yaml` gap in
parallel with the sidecar prototype, and produce a proposal draft without
blocking the ticket on it.

- Confirm, from the internal implementation of `go.yaml.in/yaml/v4`, that
`Event` carries `StartMark`/`EndMark` with a 0-based byte `Index`, but that the
composer discards this and keeps only `Line`/`Column` on `Node`.
- Draft an upstream issue or pull request proposal that requests one of the
following: raw scalar source text, start and end marks exposed on `Node`, a
decoded-to-source mapping span, or a lower-level public token/event API.
- Record that no matching upstream issue or PR currently exists, that
`go.yaml.in/yaml/v4` is still at `rc` stage, and that the project deliberately
chose `go.yaml.in/yaml` as the maintained successor library.
- Treat this upstream investigation as a longer-term path only. Do not block the
ticket's decision on its outcome.

Phase 4: Decide, document, and preserve the fallback

This phase turns evidence into a decision. The goal is a written recommendation that satisfies the decision criteria and keeps the conservative fallback intact.

Produce the recommendation and gate the change

Write the decision and the rule that guards it.

• Compare Option 1 and Option 2 against the ticket criteria: material expansion of exact coverage beyond plain and literal scalars, no loss of parse compatibility, no loss of diagnostics, acceptable maintenance.
• Adopt a candidate only if the corpus proves wider exact coverage and the compatibility and performance costs are acceptable; otherwise keep the current mapper and record why.
• Require that any adopted mapping falls back to run.RunPos whenever a span is unsafe or the multi-byte offset defect from goccy/go-yaml#858 is in scope.
• Capture the decision and the supporting numbers in a short design note under docs/ or in the ticket record.

🤖 Prompt for AI agents

Implement Phase 4 of the evaluation: turn the Phase 2 and Phase 3 evidence into
a documented, gated recommendation.

- Compare Option 1 (upstream `go-yaml` change) and Option 2 (`goccy/go-yaml`
sidecar) against the ticket's decision criteria: material expansion of exact
coverage beyond plain and literal scalars, no loss of parse compatibility, no
loss of diagnostics, and acceptable maintenance cost.
- Adopt a candidate only if the test corpus proves wider exact coverage and the
compatibility and performance costs are acceptable. If the evidence does not
support adoption, keep the current mapper and record the reasons why.
- Set a hard rule for any adopted mapping: it must fall back to `run.RunPos`
whenever a source span is unsafe, or whenever the multi-byte offset defect
described in `goccy/go-yaml#858` is in scope for that input.
- Write a short design note capturing the decision, the supporting corpus
scores, the `goccy/go-yaml#858` finding, and the upstream proposal draft. Place
this note under `docs/` or in the ticket record.

Research

Arr, here be the lay o' the land, and I checked every plank twice. rule_shellcheck.go runs ShellCheck on the decoded run: script and reports every finding at run.RunPos, which is the position of the run: key. The real in-script line:col from ShellCheck is only embedded in the message text, not back-mapped to the YAML file. parse.go decodes the whole file with yaml.Unmarshal into a yaml.Node tree, then hand-walks it into plain AST structs and throws the node tree overboard. ast.go keeps only Pos{Line, Col}, String{Value, Quoted, Pos}, and ExecRun{..., RunPos}; no byte offsets, no end marks, no raw source slice. Node.Style is read once, only to set the Quoted flag. Rules never receive the raw []byte; linter.go holds content and only reuses it afterwards in error.go for snippet printing. There is no hidden sourcemap anywhere, only an honest comment at rule_shellcheck.go admitting the limitation. The sole YAML dependency is go.yaml.in/yaml/v4 v4.0.0-rc.6, with no vendoring and no replace directives.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1 of the ShellCheck source-mapping evaluation: build the
baseline record and the test corpus that all later candidate comparisons depend
on.

- Write up the current mapper behaviour as a baseline document. State that
`rule_shellcheck.go` runs ShellCheck on `run.Run.Value` and reports every
finding at `run.RunPos` (the `run:` key position). State that the in-script
`line:col` from ShellCheck exists only inside the message text and is never
mapped back to the YAML file.
- Confirm and record the known limitation: there is no back-mapping mechanism,
`Node.Style` is used only to set the `Quoted` flag, and the AST stores no byte
offsets or raw source span.
- Define two named coverage tiers for use in later phases: 'exact mapping'
(currently limited to plain and literal scalars) and 'conservative fallback'
(reporting at the `run:` key position).
- Build a set of YAML fixtures under `testdata/` covering every scalar style:
plain, single-quoted, double-quoted, literal (`|`), and folded (`>`), each
combined with chomping indicators `|-`, `|+`, `>-`, `>+`.
- Extend the fixtures with edge cases: escapes, folded line joins, blank lines,
leading/trailing indentation, tabs, multi-byte Unicode characters, comments,
anchors, and aliases.
- For every fixture, record the expected original-file `line:col` for a known
token inside the `run:` script, so that any candidate mapper's output can be
automatically checked against these expected values in later phases.
===============================================================================

Task: 2

Implement Phase 2 of the evaluation: build and score a prototype sidecar that
uses `goccy/go-yaml` to reconstruct exact source positions, without touching the
default lint path or the main parser.

- Add `goccy/go-yaml` to `go.mod`/`go.sum` as a prototype-only dependency.
Confirm the module graph has no YAML conflicts with the existing
`go.yaml.in/yaml/v4` dependency; this addition is additive only.
- Create a new prototype package, for example `internal/scalarmap/`, that: lexes
the original workflow bytes with `goccy/go-yaml`, locates the `run:` scalar by
position, and uses `token.Origin` (raw text) plus `token.Position.Offset` (byte
offset) to map an in-script offset back to a file `line:col`.
- Thread the raw `content []byte` from `linter.go`'s `check` function into the
prototype only, for this spike. Do not change the public `Rule`/`Pass` surface
yet. Keep in mind the intended future shape is a small additive
`SetSource([]byte)` hook, if the option is adopted later.
- Run the prototype over every Phase 1 fixture and compare the produced
`line:col` against the recorded expected values. Check behaviour specifically
for escapes, folded line joins, chomping indicators, blank lines, Unicode, tabs,
comments, anchors, and aliases.
- Reproduce and assess `goccy/go-yaml#858`: check whether
`token.Position.Offset` is incorrect after multi-byte characters, and record its
effect on the Unicode fixtures.
- Do not rely on `StringNode.String()` output for mapping, since it is not
guaranteed to be byte-identical to the input. Use `Origin` and offsets only.
- Parse the existing actionlint workflow fixtures with `goccy/go-yaml` and
confirm that it accepts all GitHub Actions workflow syntax that
`go.yaml.in/yaml/v4` currently accepts.
- Measure the added lint time and memory cost of running a second parse pass per
file, and record these numbers.
- Record the dependency weight and maintenance cost of adding a second YAML
library to the project.
- Decide and record the integration shape: a sidecar lexer/parser only (the
recommended default), versus a full parser migration. Note that a full migration
would require rewriting all `yaml.Node`/`Kind`/`Style`/`Tag`/`LoadErrors` usage
across `parse.go`, `config.go`, `action_metadata.go`, `reusable_workflow.go`,
and other files.
===============================================================================

Task: 3

Implement Phase 3 of the evaluation: investigate the upstream `go-yaml` gap in
parallel with the sidecar prototype, and produce a proposal draft without
blocking the ticket on it.

- Confirm, from the internal implementation of `go.yaml.in/yaml/v4`, that
`Event` carries `StartMark`/`EndMark` with a 0-based byte `Index`, but that the
composer discards this and keeps only `Line`/`Column` on `Node`.
- Draft an upstream issue or pull request proposal that requests one of the
following: raw scalar source text, start and end marks exposed on `Node`, a
decoded-to-source mapping span, or a lower-level public token/event API.
- Record that no matching upstream issue or PR currently exists, that
`go.yaml.in/yaml/v4` is still at `rc` stage, and that the project deliberately
chose `go.yaml.in/yaml` as the maintained successor library.
- Treat this upstream investigation as a longer-term path only. Do not block the
ticket's decision on its outcome.
===============================================================================

Task: 4

Implement Phase 4 of the evaluation: turn the Phase 2 and Phase 3 evidence into
a documented, gated recommendation.

- Compare Option 1 (upstream `go-yaml` change) and Option 2 (`goccy/go-yaml`
sidecar) against the ticket's decision criteria: material expansion of exact
coverage beyond plain and literal scalars, no loss of parse compatibility, no
loss of diagnostics, and acceptable maintenance cost.
- Adopt a candidate only if the test corpus proves wider exact coverage and the
compatibility and performance costs are acceptable. If the evidence does not
support adoption, keep the current mapper and record the reasons why.
- Set a hard rule for any adopted mapping: it must fall back to `run.RunPos`
whenever a source span is unsafe, or whenever the multi-byte offset defect
described in `goccy/go-yaml#858` is in scope for that input.
- Write a short design note capturing the decision, the supporting corpus
scores, the `goccy/go-yaml#858` finding, and the upstream proposal draft. Place
this note under `docs/` or in the ticket record.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[kjanat]

GitHub compatibility is the target

GitHub.com's hosted workflow parser is the final authority for actionlint. The YAML specification is still useful as the documented baseline and because GitHub's open runner parser explicitly applies the YAML 1.2 core schema, but conformance to the specification is not an independent goal when GitHub behaves differently.

There are two separate requirements for a source-mapping parser or sidecar:

1. It must produce the same effective workflow values and run: script as GitHub.
2. It must retain enough raw source information to map characters in that decoded script back to the workflow.

Matching only the second requirement would let actionlint produce precise locations in the wrong script.

Compatibility cases to include

• YAML 1.1 versus 1.2 booleans:

  env:
    ENABLED: yes
    DISABLED: no

  A YAML 1.1-style parser may produce booleans. GitHub's YAML 1.2 handling produces the strings yes and no. The same historical ambiguity applies to the workflow key on.

• Leading-zero numbers:

  env:
    VALUE: 010

  Current go.yaml.in/yaml/v4 retains 010 on a yaml.Node, but decoding into any produces integer 8. GitHub's YAML 1.2 reader treats the token as decimal 10, which the Actions schema then converts to a string where a string is expected. A migration from node-based parsing to generic decoded values could therefore change semantics.

• Duplicate keys:

  env:
    TARGET: first
    TARGET: second

  Parsers variously keep the first value, keep the last value, or reject the document. GitHub's template reader explicitly reports duplicate mapping keys.

• Anchors versus merge keys:

  env: &defaults
    COLOUR: blue
  jobs:
    test:
      runs-on: ubuntu-latest
      env:
        <<: *defaults

  Generic go-yaml decoding expands <<, but support for anchors and aliases does not by itself imply support for YAML merge keys. This must be checked against the hosted service rather than inherited accidentally from a parser library.

• Scalar transformations which may have identical semantics but difficult source maps:

  - run: "echo one\necho $FOO"
  - run: >
      echo one
      echo "$FOO"

  The double-quoted value places two decoded script lines on one YAML source line. The folded value places multiple YAML source lines on one decoded script line. These are not necessarily parser disagreements, but they prevent simple line-offset reconstruction.

Relevant GitHub implementations

• The open runner reader performs YAML 1.2 core scalar resolution: https://github.com/actions/runner/blob/258d6c857db3519913f7deb6004b60172f8043ae/src/Sdk/DTPipelines/Pipelines/ObjectTemplating/YamlObjectReader.cs#L69-L95
• The template reader rejects duplicate keys: https://github.com/actions/runner/blob/258d6c857db3519913f7deb6004b60172f8043ae/src/Sdk/DTObjectTemplating/ObjectTemplating/TemplateReader.cs#L203-L218
• GitHub's open @actions/workflow-parser uses the JavaScript yaml package with keepSourceTokens: true: https://github.com/actions/languageservices/blob/4043eda158e16579cc5fb1b0b07a4bce2a76f0b5/workflow-parser/src/workflows/yaml-object-reader.ts#L20-L30
• That reader carries the decoded scalar value, original scalar source, block-scalar header, and source range forward: https://github.com/actions/languageservices/blob/4043eda158e16579cc5fb1b0b07a4bce2a76f0b5/workflow-parser/src/workflows/yaml-object-reader.ts#L106-L139

The language-service implementation is particularly relevant to this issue: it demonstrates that retaining source tokens alongside decoded scalar values is a practical design. It is not proof that GitHub.com's production parser is identical.

Hosted parser probe

A small GitHub-hosted conformance probe would give us empirical results for the production service and catch later behavior changes.

One valid workflow can assert observable values for:

• yes, no, on, 010, 0o10, and 0x10 in string-valued Actions fields;
• literal, folded, single-quoted, and double-quoted run: values;
• chomping, blank lines, Unicode, and aliases;
• the exact environment strings and executed shell script seen by the job.

The job should fail on any unexpected value and emit a small, non-secret JSON result plus the GitHub run URL. It can initially run on pushes to a dedicated probe branch. If retained, a workflow_dispatch trigger and infrequent schedule on the default branch would detect hosted-parser changes over time.

Expected-rejection cases cannot all live in that workflow. A duplicate key, unsupported merge key, or other parser-level rejection prevents the workflow run from being created, masking every other case. Test each rejecting construct in an isolated workflow or commit, then record whether GitHub created a run, produced an Invalid workflow file annotation, or accepted and executed it.

Store the dated observed results in this issue or a small compatibility fixture document. The corpus used to compare go-yaml or goccy/go-yaml should then be derived from those hosted results, not merely from the YAML specification.