@sasjs/lint 4.3.2 → 4.4.0

package/.github/workflows/mutation-weekly.yml

@@ -1,92 +0,0 @@
-name: Mutation Watch
-
-# The per-PR mutation gate compares a branch's changed files with a baseline, so
-# the baseline is the thing that has to stay honest: if it is never refreshed,
-# files that improve keep their old count and the gate stops asking for more.
-#
-# This runs the whole source tree weekly, prints the new baseline, and fails when
-# any file carries MORE surviving mutants than the recorded one - which means a
-# PR was merged without the gate seeing it (a push to main, a config change, a
-# file the gate skipped). Failure files an issue, as audit-watch.yml does, and
-# only a genuine regression does so.
-
-on:
-  schedule:
-    - cron: '0 7 * * 1' # Mondays, 07:00 UTC
-  workflow_dispatch:
-
-jobs:
-  watch:
-    runs-on: ubuntu-latest
-    # the whole tree takes ~20-30 minutes; bounded so a hang cannot hold a runner
-    # for the six-hour default
-    timeout-minutes: 90
-    permissions:
-      contents: read
-      issues: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-
-      - name: Install Dependencies
-        run: npm ci
-
-      - name: Mutate the whole source tree
-        id: watch
-        env:
-          MUTATION_WATCH_REPORT: ${{ runner.temp }}/mutation-watch-report.md
-        run: node scripts/mutation-gate.mjs weekly
-
-      - name: Keep the report
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: mutation-watch-report
-          path: |
-            reports/mutation/mutation.json
-            ${{ runner.temp }}/mutation-watch-report.md
-          if-no-files-found: ignore
-
-  report:
-    needs: watch
-    # a failure files an issue; a cancelled run does so only when the schedule
-    # cancelled it (the 90-minute timeout), so cancelling a manual run by hand
-    # does not claim a regression that never happened
-    if: >-
-      always() &&
-      (needs.watch.result == 'failure' ||
-       (needs.watch.result == 'cancelled' && github.event_name == 'schedule'))
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      contents: read
-      issues: write
-
-    steps:
-      - name: File an issue
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          title='Mutation watch: a file carries more surviving mutants than the baseline'
-          existing=$(gh issue list --state open --search "\"$title\" in:title" \
-            --json number --jq '.[0].number // empty')
-
-          if [ -n "$existing" ]; then
-            echo "already tracked in #$existing"
-            exit 0
-          fi
-
-          gh issue create --title "$title" --body \
-            "The weekly mutation run found a file carrying more surviving mutants than mutation-baseline.json records, so behaviour was merged without a test that fails on it.
-
-          The run names the file and each surviving mutant (file:line:column, mutator, replacement), and prints the refreshed baseline:
-
-          $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
-
-          Close this once a spec kills them and mutation-baseline.json is updated from that run."

package/.github/workflows/publish.yml

@@ -1,169 +0,0 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-
-name: SASjs Lint Build and Publish
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-# One release at a time. Both triggers publish, and the push trigger fires on
-# every release commit @semantic-release/git pushes back to main, so a
-# dispatched recovery run can interleave with a push-triggered one. Two
-# semantic-release processes racing the same tag and the same npm publish is a
-# new way to strand a release - the state the retry below exists to recover.
-# `cancel-in-progress: false` queues the second run rather than cancelling the
-# first, because cancelling a run midway through a release is itself a way to
-# leave a tag pushed and the release missing.
-concurrency:
-  group: publish
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      id-token: write       # required for npm provenance (trusted publisher)
-      issues: write         # optional: lets @semantic-release/github comment on issues
-      pull-requests: write  # optional: lets @semantic-release/github comment on PRs
-
-    strategy:
-      matrix:
-        node-version: [22]
-
-    steps:
-      # Mint a short-lived GitHub App token (bypass-capable)
-      - name: Generate token
-        id: app-token
-        uses: actions/create-github-app-token@v1
-        with:
-          app-id: ${{ secrets.APP_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      # Checkout using the app token so the release commit can be pushed
-      - uses: actions/checkout@v4
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-          persist-credentials: true
-          fetch-depth: 0      # semantic-release needs full history + tags
-
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          registry-url: https://registry.npmjs.org
-
-      # Node 22 ships npm 10.x — OIDC trusted publishing needs npm >= 11.5.1
-      - name: Update npm
-        run: npm install -g npm@latest
-
-      - name: Install Dependencies
-        run: npm ci
-
-      - name: Check Code Style
-        run: npm run lint
-
-      - name: Run Unit Tests
-        run: npm test
-
-      - name: Build Project
-        run: npm run build
-
-      - name: Clean up ready for publishing
-        run: npm run publishInit
-
-      - name: Semantic Release
-        # The release toolchain is deliberately not a project dependency: every
-        # @semantic-release plugin declares a `semantic-release` peer, which npm
-        # auto-installs together with the `npm` package semantic-release bundles
-        # - and that bundled npm carries advisories nothing here can fix.
-        # Installing it here, pinned, keeps the dependency tree clean. Keep
-        # these versions in step with `release.plugins` in package.json.
-        #
-        # semantic-release pushes twice: @semantic-release/git pushes the release
-        # commit to the branch, then core pushes the tag in a second, tags-only
-        # push. When that second push is rejected the branch keeps the release
-        # commit - package.json at the new version - with no tag: no GitHub
-        # release, no npm publish, and every later run dying in the exec plugin's
-        # `npm version` with "Version not changed", a state only a hand repair
-        # clears. sasjs/adapter hit exactly that on 2026-10-17.
-        #
-        # The tag push runs after the tag exists locally and after the branch is
-        # updated, so one more attempt has only the tag to push. Retry exactly
-        # that case: a local tag alone does not identify it, because the tag is
-        # also there when the failure came later (the GitHub release), and
-        # retrying that finds the tag restored by semantic-release's own fetch,
-        # decides there is nothing to release, exits 0 and leaves the step green
-        # with the release still missing - so require the tag to be absent from
-        # the remote as well.
-        #
-        # Only a definitive answer counts. `git ls-remote --exit-code` exits 2 for
-        # an absent ref but 128 when the query itself fails (network, auth,
-        # unreachable remote), and treating every non-zero exit as "absent" would
-        # retry on the transient GitHub-side failures that are the very class of
-        # incident this retry repairs. So 2 retries, 0 and anything else fail the
-        # step.
-        run: |
-          run_release() {
-            npx --yes \
-              --package semantic-release@25.0.9 \
-              --package @semantic-release/exec@7.1.0 \
-              --package @semantic-release/git@11.0.1 \
-              semantic-release
-          }
-
-          if run_release; then
-            exit 0
-          fi
-
-          version=$(node -p "require('./package.json').version")
-
-          if ! git rev-parse -q --verify "refs/tags/v$version" >/dev/null; then
-            echo "No local v$version tag, so the failure came before the tag was created - not retrying." >&2
-            exit 1
-          fi
-
-          ls_rc=0
-          git ls-remote --exit-code --tags origin "refs/tags/v$version" >/dev/null 2>&1 || ls_rc=$?
-
-          if [ "$ls_rc" -eq 0 ]; then
-            echo "v$version is already on the remote, so the failure came after the tag push - not retrying." >&2
-            exit 1
-          fi
-
-          if [ "$ls_rc" -ne 2 ]; then
-            echo "Could not establish whether v$version is on the remote (git ls-remote exited $ls_rc) - not retrying." >&2
-            exit 1
-          fi
-
-          echo "Retrying: v$version exists locally but not on the remote, so the tag push is what failed."
-          git tag -d "v$version"
-          run_release
-        env:
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}   # <-- app token, not secrets.GITHUB_TOKEN
-
-      # semantic-release only releases when it finds a releasable commit, and the
-      # angular convention this repo is configured with does not treat `chore:` or
-      # `docs:` as one. This step ran on `if: success()` regardless, so a merge with
-      # no releasable commit published the version already in package.json, which
-      # npm rejects with "You cannot publish over the previously published
-      # versions". Compare against the registry instead, and publish only when
-      # there is something new.
-      - name: Publish to npm with trusted publisher
-        id: publish
-        if: success()
-        run: |
-          local_version=$(node -p "require('./package.json').version")
-          published_version=$(npm view @sasjs/lint version 2>/dev/null || echo "")
-
-          if [ "$local_version" = "$published_version" ]; then
-            echo "released=false" >> "$GITHUB_OUTPUT"
-            echo "Nothing to publish - $local_version is already on npm"
-            exit 0
-          fi
-
-          npm publish --access public
-          echo "released=true" >> "$GITHUB_OUTPUT"

package/.gitpod.yml

@@ -1,8 +0,0 @@
-# This configuration file was automatically generated by Gitpod.
-# Please adjust to your needs (see https://www.gitpod.io/docs/config-gitpod-file)
-# and commit this file to your remote git repository to share the goodness with others.
-
-tasks:
-  - init: npm install && npm run build
-
-

package/.pre-commit-config.yaml

@@ -1,16 +0,0 @@
-# Hooks for the pre-commit framework - https://pre-commit.com
-#
-# The repo also ships native hooks in .git-hooks/, covering the secret scan, a
-# 2MB commit size limit and Conventional Commits. But .npmrc sets
-# ignore-scripts=true, so the `prepare` script that would activate them never
-# runs on `npm i` - a fresh clone commits unchecked until the one-time command
-# in .github/CONTRIBUTING.md is run by hand.
-#
-# This file is the standard route instead: install the framework once with
-# `pre-commit install`, and the secret scan runs on every commit. The hook is
-# pinned to an exact gitleaks release tag.
-repos:
-  - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.30.1
-    hooks:
-      - id: gitleaks

package/.prettierrc

@@ -1,6 +0,0 @@
-{
-  "trailingComma": "none",
-  "tabWidth": 2,
-  "semi": false,
-  "singleQuote": true
-}

package/.sasjslint

@@ -1,13 +0,0 @@
-{
-    "noTrailingSpaces": true,
-    "noEncodedPasswords": true,
-    "hasDoxygenHeader": true,
-    "noSpacesInFileNames": true,
-    "maxLineLength": 80,
-    "lowerCaseFileNames": true,
-    "noTabIndentation": true,
-    "indentationMultiple": 2,
-    "hasMacroNameInMend": true,
-    "noNestedMacros": true,
-    "hasMacroParentheses": true
-}

package/jest.config.js

@@ -1,62 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  // A Stryker run keeps a sandbox under .stryker-tmp with a copy of src/ in it.
-  // Without this, any jest run that overlaps a mutation run collects every spec
-  // twice (measured: 946 tests instead of 464) and reports failures from files
-  // that are being mutated. Anchored to <rootDir> on purpose: inside the sandbox
-  // the whole project IS under .stryker-tmp, and an unanchored pattern would make
-  // Stryker's own dry run collect nothing ("No tests were executed").
-  testPathIgnorePatterns: [
-    '/node_modules/',
-    '<rootDir>/.stryker-tmp/',
-    '<rootDir>/build/'
-  ],
-  coverageThreshold: {
-    global: {
-      branches: 80,
-      functions: 80,
-      lines: 80,
-      statements: -10
-    },
-    // Per-path floors, so a change that hollows out one area cannot hide behind
-    // the aggregate. Every number is the coverage measured when this was written,
-    // rounded down, so the block is a ratchet: raise one when the area improves,
-    // never lower one to get a branch green. `statements` is a PERCENTAGE unless
-    // it is negative, where `-N` reads as "at most N uncovered statements" - so a
-    // plain `0` asserts nothing at all (0% coverage passes), which is why the two
-    // fully-covered areas ask for 100 and the three with known gaps carry a budget
-    // measured from the tree on the day this landed.
-    './src/utils/': {
-      branches: 95,
-      functions: 100,
-      lines: 99,
-      statements: -4
-    },
-    './src/rules/': {
-      branches: 95,
-      functions: 100,
-      lines: 100,
-      statements: 100
-    },
-    './src/lint/': {
-      branches: 85,
-      functions: 100,
-      lines: 100,
-      statements: -2
-    },
-    './src/format/': {
-      branches: 90,
-      functions: 100,
-      lines: 100,
-      statements: 100
-    },
-    './src/types/': {
-      branches: 95,
-      functions: 100,
-      lines: 96,
-      statements: -4
-    }
-  },
-  collectCoverageFrom: ['src/**/{!(index|formatExample|lintExample),}.ts']
-}

package/jest.stryker.config.js

@@ -1,17 +0,0 @@
-/**
- * Jest config for Stryker runs.
- *
- * The only difference from jest.config.js is that coverage is off: Stryker
- * instruments the code itself, and the coverage thresholds would fail a
- * single-mutant run. The suite itself runs in full, so the weekly baseline is
- * built on every test - a skipped spec here would record mutants it covers as
- * legitimate survivors and let them into the baseline permanently.
- */
-const base = require('./jest.config.js')
-
-module.exports = {
-  ...base,
-  collectCoverage: false,
-  coverageThreshold: undefined,
-  collectCoverageFrom: undefined
-}

package/mutation-baseline.json

@@ -1,30 +0,0 @@
-{
-  "_comment": "Surviving-mutant counts per file, used by scripts/mutation-gate.mjs. Refresh from the output of npm run mutation:watch; raise a count only with a reason in the PR that raises it.",
-  "generatedAt": "2026-10-25T20:06:38Z",
-  "files": {
-    "src/rules/file/noUnusedMacros.ts": {
-      "score": 100.0,
-      "survived": 0,
-      "killed": 37,
-      "timeout": 0
-    },
-    "src/utils/getIndicesOf.ts": {
-      "score": 100.0,
-      "survived": 0,
-      "killed": 15,
-      "timeout": 6
-    },
-    "src/utils/isIgnored.ts": {
-      "score": 100.0,
-      "survived": 0,
-      "killed": 25,
-      "timeout": 0
-    },
-    "src/utils/parseMacroCalls.ts": {
-      "score": 92.98,
-      "survived": 25,
-      "killed": 293,
-      "timeout": 38
-    }
-  }
-}

package/scripts/audit-watch.mjs

@@ -1,249 +0,0 @@
-/**
- * Watches the dev-tree audit exemption declared in `.github/workflows/build.yml`.
- *
- * That workflow gates on `npm audit --omit=dev` because the dev tree carries one
- * advisory nothing in this repo can fix: GHSA-hp3w-g68c-fv3c (sprintf-js,
- * reached through @jest/transform -> babel-plugin-istanbul ->
- * @istanbuljs/load-nyc-config -> js-yaml 3 -> argparse). Every package in that
- * chain is at its latest published version and the advisory lists no patched
- * release, so gating on it would mean a permanently red build.
- *
- * An exemption with no expiry is how a scoped gate becomes a permanent one, so
- * this script re-checks it weekly and reports when it is out of date:
- *
- *   - a dev-tree advisory outside EXEMPTIONS appears - the exemption is too narrow
- *   - an EXEMPTIONS advisory no longer appears in the tree - the exemption is dead
- *   - a WATCHED_FOR_RELEASE package publishes a version newer than the one
- *     recorded here - a fix may now exist, so re-evaluate and drop the exemption
- *   - an EXEMPTIONS id is missing from the build.yml comment - the gate and this
- *     script disagree about what is exempt
- *
- * Any of those exits 1, failing the scheduled run and making the workflow file an
- * issue. The known advisory on its own does NOT exit 1: it is expected, and a job
- * that is red every week trains people to ignore red.
- *
- * Run with `node scripts/audit-watch.mjs`.
- */
-import { execFileSync } from 'node:child_process'
-import { appendFileSync, readFileSync, writeFileSync } from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const BUILD_WORKFLOW = path.join('.github', 'workflows', 'build.yml')
-
-/**
- * Advisories the dev-scoped gate in build.yml is allowed to leave unaddressed.
- * Each one must also be named in that workflow's comment - the check below
- * enforces it, so the gate and this list cannot drift apart.
- */
-const EXEMPTIONS = ['GHSA-hp3w-g68c-fv3c']
-
-/**
- * Packages whose published version decides whether an exemption is still
- * justified. `newestKnown` is the newest release at the time the exemption was
- * written; a newer one on the registry means a fix may exist and the exemption
- * deserves a fresh look rather than another year of silence.
- */
-const WATCHED_FOR_RELEASE = [{ name: 'sprintf-js', newestKnown: '1.1.3' }]
-
-/**
- * `npm audit --json` exits 1 whenever it reports anything, so the exit code says
- * nothing about whether the command worked - parse the report instead.
- */
-const runAudit = () => {
-  let stdout
-  try {
-    stdout = execFileSync('npm', ['audit', '--json'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore']
-    })
-  } catch (error) {
-    stdout = error.stdout
-  }
-  if (!stdout || !stdout.trim()) {
-    throw new Error('npm audit produced no JSON - run `npm ci` first')
-  }
-  return JSON.parse(stdout)
-}
-
-/**
- * The advisories the report names, keyed by GHSA id. A `via` entry is a bare
- * package name when the advisory is inherited from a dependency, and an object
- * carrying the GHSA url when it is the root of the chain - only the latter are
- * advisories in their own right.
- */
-const collectAdvisories = (report) => {
-  const advisories = new Map()
-
-  for (const [packageName, info] of Object.entries(report?.vulnerabilities ?? {})) {
-    for (const via of info?.via ?? []) {
-      if (typeof via !== 'object' || via === null) continue
-      const id = String(via.url ?? '').split('/').pop()
-      if (!id?.startsWith('GHSA-')) continue
-
-      const entry = advisories.get(id) ?? {
-        severity: via.severity,
-        title: via.title,
-        packages: []
-      }
-      entry.packages.push(packageName)
-      advisories.set(id, entry)
-    }
-  }
-
-  return advisories
-}
-
-/** The version the registry currently resolves `latest` to, or null if offline. */
-const latestPublished = (name) => {
-  try {
-    return execFileSync('npm', ['view', name, 'version'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore']
-    }).trim()
-  } catch {
-    return null
-  }
-}
-
-/**
- * Numeric dotted comparison, so `1.1.10` sorts above `1.1.9`. A prerelease
- * suffix is dropped from both sides first: `1.1.3-beta.1` is not newer than
- * `1.1.3`, and a prerelease that happens to be tagged `latest` must not raise
- * the alarm by itself.
- */
-const isNewer = (candidate, baseline) => {
-  const a = candidate.split('-')[0].split('.')
-  const b = baseline.split('-')[0].split('.')
-  for (let i = 0; i < Math.max(a.length, b.length); i++) {
-    const left = a[i] ?? '0'
-    const right = b[i] ?? '0'
-    if (left === right) continue
-    const leftNumber = Number(left)
-    const rightNumber = Number(right)
-    if (Number.isNaN(leftNumber) || Number.isNaN(rightNumber)) {
-      return left > right
-    }
-    return leftNumber > rightNumber
-  }
-  return false
-}
-
-/**
- * Write the report to the step summary and to the file the workflow reads.
- * Wrapped so a failure to report cannot mask the failure being reported - and
- * so the workflow's `gh issue create --body-file` always has a file, including
- * on the path below where the watch itself broke.
- */
-const writeReport = (summary) => {
-  try {
-    if (process.env.GITHUB_STEP_SUMMARY) {
-      appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary)
-    }
-    if (process.env.AUDIT_WATCH_REPORT) {
-      writeFileSync(process.env.AUDIT_WATCH_REPORT, summary)
-    }
-  } catch (error) {
-    console.error(`could not write the report: ${error.message}`)
-  }
-}
-
-const main = () => {
-  const report = runAudit()
-  const advisories = collectAdvisories(report)
-  const problems = []
-
-  for (const [id, advisory] of advisories) {
-    if (EXEMPTIONS.includes(id)) continue
-    problems.push(
-      `new dev-tree advisory ${id} (${advisory.severity}): ${advisory.title} - ` +
-        `packages: ${[...new Set(advisory.packages)].sort().join(', ')}. ` +
-        'Fix it, or add it to EXEMPTIONS and name it in the build.yml comment.'
-    )
-  }
-
-  for (const id of EXEMPTIONS) {
-    if (advisories.has(id)) continue
-    problems.push(
-      `exempted advisory ${id} no longer appears in the tree - the exemption is ` +
-        'dead weight. Remove it from EXEMPTIONS and from the build.yml comment, ' +
-        'and restore the full `npm audit` gate.'
-    )
-  }
-
-  for (const { name, newestKnown } of WATCHED_FOR_RELEASE) {
-    const latest = latestPublished(name)
-    if (latest === null) {
-      console.log(`skipped the registry check for ${name} - npm view failed`)
-      continue
-    }
-    if (isNewer(latest, newestKnown)) {
-      problems.push(
-        `${name} has published ${latest}, newer than the ${newestKnown} recorded ` +
-          'with the exemption - a fix may exist. Re-evaluate the exemption, bump ' +
-          'the chain if it clears, and drop the exemption when it does.'
-      )
-    }
-  }
-
-  const buildWorkflow = readFileSync(path.join(ROOT, BUILD_WORKFLOW), 'utf8')
-  for (const id of EXEMPTIONS) {
-    if (buildWorkflow.includes(id)) continue
-    problems.push(
-      `exemption ${id} is not named in ${BUILD_WORKFLOW} - the gate and this ` +
-        'script disagree about what is exempt.'
-    )
-  }
-
-  const { moderate = 0, high = 0, critical = 0, total = 0 } =
-    report?.metadata?.vulnerabilities ?? {}
-
-  const summary = [
-    '## Dev-tree audit watch',
-    '',
-    `Full audit: ${total} advisories (${critical} critical, ${high} high, ${moderate} moderate).`,
-    '',
-    '| advisory | severity | packages | exempt |',
-    '| --- | --- | --- | --- |',
-    ...[...advisories].map(
-      ([id, advisory]) =>
-        `| ${id} | ${advisory.severity} | ${[...new Set(advisory.packages)].sort().join(', ')} | ` +
-        `${EXEMPTIONS.includes(id) ? 'yes' : '**no**'} |`
-    ),
-    '',
-    problems.length
-      ? ['### The exemption needs attention', '', ...problems.map((p) => `- ${p}`), ''].join('\n')
-      : 'The exemption still matches the tree - nothing to do.',
-    ''
-  ].join('\n')
-
-  console.log(summary)
-  writeReport(summary)
-
-  process.exitCode = problems.length ? 1 : 0
-}
-
-try {
-  main()
-} catch (error) {
-  // The watch itself broke, so the exemption went unchecked. Say so in the
-  // report rather than leaving the workflow to fail on a missing file.
-  const summary = [
-    '## Dev-tree audit watch',
-    '',
-    'The watch did not complete, so the dev-tree audit exemption was **not**',
-    'checked against the tree. Nothing is known about the advisories right now.',
-    '',
-    '```',
-    error.message,
-    '```',
-    '',
-    'Investigate the failing step, then re-run the workflow.',
-    ''
-  ].join('\n')
-
-  console.error(`audit watch failed: ${error.message}`)
-  writeReport(summary)
-  process.exit(1)
-}