# How-to: reproduce PR #22423's 864 markdownlint findings locally

## When to use

You want to confirm `analyze-local.sh` matches what Codacy CI reported on a known fixture. PR #22423 is the canonical fixture for this skill: its first CI run reported **864 markdownlint findings**; commit `3a54c9afbc` cleared them by adding `.agents/**` and `docs/netdata-ai/skills/**` to `.codacy.yml`.

This how-to walks through reproducing those 864 findings on the pre-exclusion state, then confirming the post-exclusion state shows zero on the affected files.

## Prerequisite

- `docker` available (or `codacy-analysis-cli` installed locally).
- `<repo>/.env` need NOT contain `CODACY_TOKEN` -- `analyze-local.sh` runs the CLI anonymously.

## Step 1 -- check out the pre-exclusion state

PR #22423 introduced the exclusion in commit `3a54c9afbc`. The parent commit `d7791e6838` is the "before" state.

```bash
git checkout d7791e6838 -- .codacy.yml      # restore the pre-exclusion .codacy.yml
# (do NOT switch branches; just stage the older .codacy.yml)
```

## Step 2 -- run analyze-local on markdownlint only

```bash
.agents/skills/codacy-audit/scripts/analyze-local.sh --tool markdownlint
```

Expected: a JSON dump under `<repo>/.local/audits/codacy/local-markdownlint-<ts>.json`. The CLI returns non-zero when findings exist (this is normal; the script tolerates it).

## Step 3 -- count findings

```bash
DUMP="$(ls -1t .local/audits/codacy/local-markdownlint-*.json | head -1)"
jq '
    if type=="array" then length
    elif type=="object" and has("issues") then (.issues | length)
    elif type=="object" and has("results") then (.results | length)
    else 0 end
' "$DUMP"
```

Expected: a count close to 864 (within ~10% tolerance for tool-version drift between the CLI bundle and Codacy Cloud).

## Step 4 -- restore the exclusion

```bash
git checkout HEAD -- .codacy.yml
```

## Step 5 -- re-run and confirm zero on excluded paths

```bash
.agents/skills/codacy-audit/scripts/analyze-local.sh --tool markdownlint
DUMP="$(ls -1t .local/audits/codacy/local-markdownlint-*.json | head -1)"
jq '[ ... | select(.filePath | startswith(".agents/") or startswith("docs/netdata-ai/skills/")) ] | length' "$DUMP"
```

(The exact jq filter depends on the dump shape -- consult the dump structure first via `jq 'keys' "$DUMP"`.)

Expected: zero rows in the excluded trees.

## What this validates

- `analyze-local.sh` runs end-to-end against the configured runner (docker or local binary).
- The CLI honours `.codacy.yml` exclude_paths (or, if it doesn't, we have empirical evidence to handle that gap in a GitHub issue or branch-local SOW).
- The bundled markdownlint version produces a count consistent with what Codacy CI reports.

## Troubleshooting

- **Docker pull is slow on first run**: `codacy/codacy-analysis-cli:latest` is a few hundred MB. Subsequent runs use the warm cache.
- **Different count than 864**: tool-version drift between the bundled `codacy-analysis-cli` and Codacy Cloud is normal. ~10% tolerance is fine. Anything wider warrants checking the CLI version vs Cloud's reported version.
- **CLI exits with non-zero**: that's expected when findings are present. The script suppresses this; the JSON dump is still valid.
