SK-166: Initial code for SKEL parser

[drmorr0]

Related Links

• https://linear.app/acrl/issue/SK-166/initial-parserinterpreter-for-skel

Description and Rationale

SKEL - The SimKube Expression Language

This is the first PR in a series that enables support for modifying trace files using a domain-specific language called SKEL. This PR just enables support for the remove operation, which allows removing fields from resources in a trace file. Future PRs will support apply, insert, and other operations. SKEL files are interpreted and applied to traces via a new skctl subcommand called transform, e.g.,

skctl transform input.sktrace example.skel -o output.sktrace

The second commit in this stack contains the initial documentation for SKEL which will show up on the SimKube website.

Initial metrics support

We now include the metrics crate for emitting metrics from various parts of the codebase; initially I want this so I could track some telemetry from skctl transform, but I expect/hope that its usage will expand. (The previous pattern that we used here in, say, skctl validate was to use an "annotated" trace that tracks all of the changes locally, but that is an enormous bear and very convoluted code; tracking these things with a global metrics recorder is much nicer).

Minor QOL improvements to the CLI

I wanted a way to show a progress bar and spinner and such for skctl transform, since for larger traces it will probably take a bit of time to run, so I cribbed from skimmer and set up kdam.

How

SKEL

We use pest to define the grammar for our DSL. Pest takes in the grammar definition file (skel/skel.pest) and converts it to a set of Rules as a Rust enum. The skel code then matches over these rules to create an AST (honestly, it's not really a "tree" per se, there's currently no infix operators or precedence rules to worry about, to it's more of an abstract syntax... path, I guess?). This code is in skel/ast.rs

Once the SKEL file is interpreted into a set of commands, the transform command iterates through every event in the trace, determines whether the command should be applied, and then takes the action. This code is all contained in skel/engine.rs.

The reasoning for this is that in our previous solution to this (aka skctl validate check --fix) we made a change for each validation rule, iterated over the entire trace to apply it, and then moved on to the next rule. This is extremely unperformant for large traces. This model is O(n) in the length of the trace, which should be much more efficient at the expense of limiting "some types" of operations. So far I haven't run into anything that seems impossible to do with SKEL so far.

Docs

In addition to the documentation, there is now a sample SKEL file in examples/sanitize.skel that users can reference. This implements 80% of the sanitizations performed by skctl val check --fix; we still need a way to clean up volumes and volumemounts in pods, which will require a slight extension to the SKEL language.

Metrics

We implemented a local (in-memory) metrics recorder which we can access later on to get the results of the various counters/gauges. I can see this in the future expanding or becoming a separate library, but it works well enough for now.

Test Steps

• Tested the docs in a local www instance, made sure they look OK
• In addition to lots of new tests added, we performed some manual tests

Successful transformation:

> skctl transform ~/tmp/test.sktrace examples/sanitize.skel

Applying all transformations from examples/example.skel to /home/drmorr/tmp/test.sktrace...
 ✅ ████████████████████████████████████████████████████████████████████████████████ 2/2

All done!  Transformed trace written to /home/drmorr/tmp/test.sktrace.20260206114652.

Summary of changes:
--------------------------------------------------------------------------------
  Trace events matched: 46
  Trace resources modified: 46
  Total evaluation time: 10s 100ms
--------------------------------------------------------------------------------

Also confirmed using skctl xray that the output trace file is well-formed and contains the modifications we expect.

Parse error

If there's a syntax error in the user's SKEL file, the output looks like this:

Applying all transformations from examples/sanitize.skel to /home/drmorr/tmp/test.sktrace...

Error:  --> 6:1
  |
6 | rmove(spec.template.spec.serviceAccount);
  | ^---
  |
  = expected EOI, apply_cmd, or remove_cmd

Not the most intuitive output, but it at least points to the right line and gives some sort of useful feedback. I think we can clean this up/improve it in the future.

Other Notes

• This will require a number of follow-on PRs to get this fully usable, but (hopefully) now that the structure is in place those are smaller

• Once we support the volume/volumemount modifications in SKEL, I want to rip out and significantly simplify the logic in skctl validate

• I also want to start using these metrics in skctl validate

• I certify that this PR does not contain any code that has been generated with GitHub Copilot or any other AI-based code generation tool, in accordance with this project's policies.

[codecov]

Codecov Report

❌ Patch coverage is 62.14099% with 145 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.41%. Comparing base (12955f5) to head (f93d1d7).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
sk-cli/src/transform.rs	0.00%	56 Missing ⚠️
sk-core/src/metrics.rs	0.00%	31 Missing ⚠️
sk-cli/src/skel/mod.rs	0.00%	29 Missing ⚠️
sk-cli/src/skel/ast.rs	89.31%	14 Missing ⚠️
sk-cli/src/main.rs	0.00%	6 Missing ⚠️
sk-cli/src/skel/engine.rs	95.27%	6 Missing ⚠️
sk-store/src/trace.rs	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #216      +/-   ##
==========================================
- Coverage   75.76%   74.41%   -1.36%     
==========================================
  Files          58       63       +5     
  Lines        3326     3709     +383     
  Branches      167      181      +14     
==========================================
+ Hits         2520     2760     +240     
- Misses        701      844     +143     
  Partials      105      105              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.