meridian/.github/workflows/markdown.yml at develop · meridianhub/meridian · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
name: Markdown

on:
  push:
    branches: [develop, main]
    paths:
      - '**.md'
      - '.markdownlint-cli2.jsonc'
      - 'package.json'
      - 'package-lock.json'
      - '.github/workflows/markdown.yml'
  pull_request:
    branches: [develop, main]
    paths:
      - '**.md'
      - '.markdownlint-cli2.jsonc'
      - 'package.json'
      - 'package-lock.json'
      - '.github/workflows/markdown.yml'

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  markdown-lint:
    name: Markdown Lint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run markdownlint
        run: npm run lint:md
        id: markdown-lint

      - name: Comment on PR if linting fails
        if: steps.markdown-lint.outcome == 'failure' && github.event_name == 'pull_request'
        uses: actions/github-script@v9
        with:
          script: |
            const marker = '<!-- markdown-lint-comment -->';
            const body = `${marker}\n❌ **Markdown Linting Failed**\n\nThis PR must resolve markdown formatting issues before merging:\n\n- Run \`npm run lint:md\` locally to see all issues\n- Run \`npm run lint:md:fix\` to automatically fix some issues\n- Check \`.markdownlint-cli2.jsonc\` for configured rules\n\nCommon issues:\n- Missing blank lines around headings\n- Missing blank lines around lists\n- Missing blank lines around code fences\n- Line length exceeds 120 characters\n\nSee [markdownlint rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) for details.`;

            const { data: comments } = await github.rest.issues.listComments({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
            });

            const existingComment = comments.find(c => c.body.includes(marker));

            if (existingComment) {
              await github.rest.issues.updateComment({
                comment_id: existingComment.id,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: body
              });
            } else {
              await github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: body
              });
            }

  link-integrity:
    name: Link Integrity
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Check internal markdown links resolve
        run: |
          rm -f /tmp/broken_links

          # Escape %, newline, CR for GitHub Actions workflow commands
          escape_annotation() {
            local s="$1"
            s="${s//'%'/'%25'}"
            s="${s//$'\n'/'%0A'}"
            s="${s//$'\r'/'%0D'}"
            printf '%s' "$s"
          }

          while IFS= read -r file; do
            dir=$(dirname "$file")

            # Extract markdown links [text](path.md) or [text](path.md#anchor)
            grep -oE '\[[^]]*\]\([^)]+\.md(#[^)]*)?\)' "$file" 2>/dev/null \
              | grep -oE '\([^)]+\.md' \
              | sed 's/^(//' \
              | sed 's/#.*//' \
              | while IFS= read -r link; do

              # Skip URLs
              case "$link" in http://*|https://*) continue ;; esac

              # Resolve relative path
              resolved=$(cd "$dir" && realpath -q "$link" 2>/dev/null || echo "")
              if [ -z "$resolved" ] || [ ! -f "$resolved" ]; then
                safe_file="$(escape_annotation "$file")"
                safe_link="$(escape_annotation "$link")"
                echo "::error file=${safe_file}::Broken link: ${safe_link} (target not found)"
                echo "$file -> $link" >> /tmp/broken_links
              fi
            done
          done < <(find . -name '*.md' \
            -not -path '*/node_modules/*' \
            -not -path './.git/*' \
            -not -path './.taskmaster/*' \
            -not -path './.claude/*')

          if [ -f /tmp/broken_links ]; then
            count=$(wc -l < /tmp/broken_links)
            echo ""
            echo "Found $count broken link(s):"
            cat /tmp/broken_links
            exit 1
          else
            echo "All internal markdown links resolve."
          fi