Skip to content

fix(ci): unbreak lint workflow + fix 138 pre-existing violations#2

Open
DimitarTAtanasov wants to merge 3 commits into
lightchain-protocol:mainfrom
DimitarTAtanasov:fix/ci-lint-warnings
Open

fix(ci): unbreak lint workflow + fix 138 pre-existing violations#2
DimitarTAtanasov wants to merge 3 commits into
lightchain-protocol:mainfrom
DimitarTAtanasov:fix/ci-lint-warnings

Conversation

@DimitarTAtanasov

@DimitarTAtanasov DimitarTAtanasov commented May 22, 2026

Copy link
Copy Markdown
Contributor

Summary

The lint workflow has been red on every CI run since the repo was created (verified — first failure was on the initial commit). This PR fixes the root causes and brings CI to green for the first time, end-to-end verified on a fork.

Three commits, three layers of fix:

Commit Layer What it fixes
fix(ci): rename $args to $dockerArgs in common.ps1 Invoke-Worker PowerShell 9 × PSAvoidAssignmentToAutomaticVariable warnings — $args is a reserved PowerShell automatic variable.
fix(ci): extract markdownlint config to a real file so the workflow runs Workflow The config: input to markdownlint-cli2-action@v16 expects a file path, not inline JSON. Move config to .markdownlint-cli2.jsonc (auto-discovered by the action) and drop the broken with: block.
style(docs): fix 137 pre-existing markdownlint violations Docs Once the workflow actually loads its config, it surfaces 137 real violations across 12 doc files. All fixed; no rules disabled.

Markdownlint breakdown (third commit)

Rule Count Fix
MD060 — table-column-style 96 Reformatted every table; pipes now align with header in "aligned" style. Properly handles the wide-character ✅ (East-Asian-Width = W) in README's status table.
MD040 — fenced-code-language 23 Bare triple-backtick blocks got explicit language tags. Most became text (log/error output); installation-linux.md:125 is a systemd unit so it became ini.
MD031 — blanks-around-fences 6 Auto-fixed via markdownlint-cli2 --fix.
MD022 — blanks-around-headings 4 Auto-fixed.
MD032 — blanks-around-lists 4 Auto-fixed.
MD034 — no-bare-urls 2 Auto-fixed (wrapped with <>).
MD051 — link-fragments 1 troubleshooting.md had a broken anchor pointing at #9-windows-host.docker.internal-ipv6-first; GitHub strips the periods from inline-code parts, so the correct anchor is #9-windows-hostdockerinternal-ipv6-first.
MD028 — no-blanks-blockquote 1 Two adjacent blockquotes in security.md joined with a > line in between (preserves the paragraph break visually).
MD027 — no-multiple-space-blockquote 1 README's lead blockquote had > (two spaces). Auto-fixed.
Total 137

Test plan

End-to-end verified on a fork of this repo. After pushing the branch and triggering the workflow on main:

✓ main lint · run 26274291589

✓ shellcheck         in   6s
✓ markdownlint       in   4s   ← config now loads; all 137 violations fixed
✓ PSScriptAnalyzer   in 2m54s  ← rename clears all 9 warnings on Windows runner

First green CI run in the history of this repo.

Out of scope (worth mentioning, not addressing here)

  • actions/checkout@v4 and markdownlint-cli2-action@v16 use Node.js 20, which GitHub Actions runners will remove by September 2026. A follow-up PR could bump them to versions supporting Node 24; intentionally left untouched here to keep scope tight.
  • windows-latest will redirect to windows-2025-vs2026 on June 15, 2026 — informational GitHub-side change, no action needed in the workflow.
  • Markdownlint rule selection — I kept the exact rule set that was in the original inline config (MD013, MD024, MD033, MD041 disabled). No rules added or relaxed; the 137 fixes all happened against the rules the maintainers chose.

PowerShell's $args is an automatic variable that PowerShell auto-populates
with positional arguments passed to a function or script. Assigning to it
inside Invoke-Worker triggered 9 PSAvoidAssignmentToAutomaticVariable
warnings from PSScriptAnalyzer, which the lint workflow treats as errors
and fails the CI run on.

Rename the local docker-args accumulator to $dockerArgs throughout
Invoke-Worker. Behaviour is unchanged (the variable was never read back
through the automatic-variable mechanism); only the symbol name changes.

This matches the convention already used in scripts/powershell/08-run-worker.ps1
where the same accumulator is called $dockerArgs.
The previous workflow inlined the JSON config under markdownlint-cli2-action's
'config:' input, but that input expects a file *path*. The action then tried
to read a file whose entire name was the JSON blob, and every run failed at
config-load time before any lint ran:

  Error: Unable to use configuration file '/home/runner/.../{
    "default": true, ...

Move the same config into .markdownlint-cli2.jsonc at the repo root (an
auto-discovered location for markdownlint-cli2), and drop the broken
'with:' block from the workflow step. The action now picks the config up
on its own.
The markdownlint CI workflow has been broken since the repo was created
(the config-loading bug fixed in the previous commit). With the workflow
now functional, it surfaces 137 real lint violations across 12 doc files
that have accumulated. This commit fixes all of them.

Breakdown by rule:

  * MD060 (96) — table-column-style: pipes did not align with header for
    'aligned' style. Reformatted every table in README.md, all docs/*.md,
    and faq.md so every pipe aligns vertically. Properly accounts for the
    wide-character ✅ (East-Asian-Width = W) used in the README's status
    table.
  * MD040 (23) — fenced-code-language: bare ``` blocks now have an
    explicit language tag. Most became 'text' (log output, error
    messages); installation-linux.md:125 is a systemd unit so it became
    'ini'.
  * MD031 (6) — blanks-around-fences: code fences need blank lines
    around them. Auto-fixed.
  * MD022 (4) — blanks-around-headings: ditto for headings. Auto-fixed.
  * MD032 (4) — blanks-around-lists: ditto for lists. Auto-fixed.
  * MD034 (2) — no-bare-urls: bare URLs in faq.md wrapped with <>. Auto-fixed.
  * MD051 (1) — link-fragments: troubleshooting.md had a broken anchor
    pointing at #9-windows-host.docker.internal-ipv6-first; GitHub strips
    the periods, so the correct anchor is #9-windows-hostdockerinternal-
    ipv6-first.
  * MD028 (1) — no-blanks-blockquote: two adjacent blockquotes in
    security.md joined with a '>' line in between (preserves visual
    paragraph break).
  * MD027 (1) — no-multiple-space-blockquote: README's lead blockquote
    had a double space after '>'. Auto-fixed.

Net result: markdownlint passes with 0 errors. No rules disabled.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant