Improved linting & formatting support for developers

[robyngit]

Linting & formatting is implemented in #2412. GitHub actions were added and the CONTRIBUTING docs updated to help developers adopt the code standards, however, there are more improvements we could make in this regard.

Ideas for potential improvements:

• Add instructions on how to integrate prettier & eslint with common IDEs in CONTRIBUTING.md, e.g. from @ianguerin:

  I was able to get the ESLint findings to show up in VSCode by installing the ESLint extension by Microsoft, and adding the following lines to my User Settings JSON file: ... "eslint.options": { "overrideConfigFile": "eslint.config.mjs" }, "eslint.experimental.useFlatConfig": true, ...

• Consider including shareable vscode config in the repo

• Improve GitHub actions to include job summaries and better PR comments *

• Pre-commit hooks (with warnings)

• Correct format automatically with prettier (e.g. use github actions to commit formatting corrections when needed)

---

* I started working on improved GitHub actions during #2412, but opted to keep it simpler for the first release instead. Here is the WIP code in case it can be put to use:

💻 Github actions snippet to create markdown summary & custom PR comment [WIP]

- name: Set env vars for subsequent steps
  env:
    OVERALL_OUTCOME: ${{ job.status }}
    PASS_MD: '✅ PASS'
    FAIL_MD: '❌ FAIL'
    FORMATTING_OUT: ${{ steps.prettier_check.outcome }}
    LINTING_OUT: ${{ steps.eslint_check.outcome }}
    UNIT_OUT: ${{ steps.test.outcome }}
    JSDOC_OUT: ${{ steps.jsdoc-dry-run.outcome }}
  run: |
    echo "OVERALL_OUTCOME=${{ env.OVERALL_OUTCOME }}" >> $GITHUB_ENV
    echo "PASS_MD=${{ env.PASS_MD }}" >> $GITHUB_ENV
    echo "FAIL_MD=${{ env.FAIL_MD }}" >> $GITHUB_ENV
    echo "FORMATTING_OUT=${{ env.FORMATTING_OUT }}" >> $GITHUB_ENV
    echo "LINTING_OUT=${{ env.LINTING_OUT }}" >> $GITHUB_ENV
    echo "UNIT_OUT=${{ env.UNIT_OUT }}" >> $GITHUB_ENV
    echo "JSDOC_OUT=${{ env.JSDOC_OUT }}" >> $GITHUB_ENV
    echo "FORMATTING_OUT_MD=${{ env.FORMATTING_OUT == 'success' && env.PASS_MD || env.FAIL_MD }}" >> $GITHUB_ENV
    echo "LINTING_OUT_MD=${{ env.LINTING_OUT == 'success' && env.PASS_MD || env.FAIL_MD }}" >> $GITHUB_ENV
    echo "UNIT_OUT_MD=${{ env.UNIT_OUT == 'success' && env.PASS_MD || env.FAIL_MD }}" >> $GITHUB_ENV
    echo "JSDOC_OUT_MD=${{ env.JSDOC_OUT == 'success' && env.PASS_MD ||
    env.FAIL_MD }}" >> $GITHUB_ENV
- name: Render workflow summary template
  id: summary-template
  uses: chuhlomin/[email protected]
  with:
    template: .github/WORKFLOW_TEMPLATE/format-test-lint-summary.md
    vars: |
      formatting_out_md: ${{ env.FORMATTING_OUT_MD }}
      linting_out_md: ${{ env.LINTING_OUT_MD }}
      unit_out_md: ${{ env.UNIT_OUT_MD }}
      jsdoc_out_md: ${{ env.JSDOC_OUT_MD }}
- name: Write summary to step summary
  run: echo "${{ steps.summary-template.outputs.result }}" >> $GITHUB_STEP_SUMMARY
- name: Choose PR comment template based on outcome
  id: choose-template
  env:
    GUIDANCE_TEMPLATE: .github/WORKFLOW_TEMPLATE/pr-comment-guidance.md
    CONFIRMATION_TEMPLATE: .github/WORKFLOW_TEMPLATE/pr-comment-confirmation.md
  run: |
    if [ ${{ env.OVERALL_OUTCOME }} == 'success' ]; then
      echo "PR_COMMENT_TEMPLATE=${{ env.CONFIRMATION_TEMPLATE }}" >> $GITHUB_ENV
    else
      echo "PR_COMMENT_TEMPLATE=${{ env.GUIDANCE_TEMPLATE }}" >> $GITHUB_ENV
    fi
- name: Render PR comment template
  id: guidance-template
  uses: chuhlomin/[email protected]
  with:
    template: ${{ env.PR_COMMENT_TEMPLATE }}
    vars: |
      formatting_out_md: ${{ env.FORMATTING_OUT_MD }}
      linting_out_md: ${{ env.LINTING_OUT_MD }}
      unit_out_md: ${{ env.UNIT_OUT_MD }}
      jsdoc_out_md: ${{ env.JSDOC_OUT_MD }}
- name: Create comment
  uses: peter-evans/create-or-update-comment@v4
  with:
    issue-number: ${{ github.event.pull_request.number }}
    body: ${{ steps.guidance-template.outputs.result }}
    token: ${{ secrets.GITHUB_TOKEN }}

WIP Markdown templates referenced by the above GitHub Actions snippet:

• 📄 pr-comment-guidance.md
• 📄 pr-comment-confirmation.md
• 📄 format-test-lint-summary.md