holocron/plugins/kyberforge/.apm/skills/agent-audit/tests/validate-provenance.bats

#!/usr/bin/env bats

setup() {
    REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../../" && pwd)"
    load "$REPO_ROOT/tests/test_helper/bats-support/load"
    load "$REPO_ROOT/tests/test_helper/bats-assert/load"

    SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-provenance.sh"
    TMPDIR="$(mktemp -d)"

    # Helper: create an APM package root at <root> (apm.yml with a top-level
    # type: line — a real package manifest, not marketplace-only) plus a
    # single vendor-neutral agent file at <root>/.apm/agents/<name>.agent.md.
    make_package() {
        local root="$1"
        mkdir -p "$root/.apm/agents"
        cat > "$root/apm.yml" <<EOF
name: test-package
version: 0.1.0
type: skill
EOF
    }

    # Helper: create a clean agent file (no source_keys)
    make_clean_agent() {
        local root="$1"
        local name="${2:-my-agent}"
        cat > "$root/.apm/agents/${name}.agent.md" <<EOF
---
name: ${name}
description: A valid agent description.
---

You are a test agent.
EOF
    }

    # Helper: create an agent file with source_keys
    make_agent_with_source_keys() {
        local root="$1"
        local name="${2:-my-agent}"
        local slug="${3:-my-source}"
        cat > "$root/.apm/agents/${name}.agent.md" <<EOF
---
name: ${name}
description: A valid agent description.
source_keys:
  - ${slug}
---

You are a test agent.
EOF
    }

    # Helper: create a valid sources.md with one entry
    make_sources_md() {
        local root="$1"
        local slug="${2:-my-source}"
        local contrib="${3:-.apm/agents/my-agent.agent.md}"
        local research="${4:-(none)}"
        cat > "$root/sources.md" <<EOF
# Sources

## ${slug}

- **URL:** https://example.com/${slug}
- **Description:** A test source.
- **Contributing files:** ${contrib}
- **Research doc:** ${research}
- **Status:** \`extracted\`
EOF
    }
}

teardown() {
    rm -rf "$TMPDIR"
}

# ---------------------------------------------------------------------------
# --help
# ---------------------------------------------------------------------------

@test "--help exits 0" {
    run bash "$SCRIPT" --help
    assert_success
    assert_output --partial "Usage:"
}

# ---------------------------------------------------------------------------
# Non-plugin/APM scope → exit 0 silently
# ---------------------------------------------------------------------------

@test "non-plugin scope: no apm.yml in tree → exit 0, no output" {
    local dir="$TMPDIR/no-package"
    mkdir -p "$dir/.apm/agents"
    cat > "$dir/.apm/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - my-source
---

You are a test agent.
EOF
    run bash "$SCRIPT" "$dir/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output ""
}

@test "non-plugin scope: apm.yml present but type:-less (marketplace-only) → exit 0, no output" {
    local dir="$TMPDIR/marketplace-only"
    mkdir -p "$dir/.apm/agents"
    cat > "$dir/apm.yml" <<EOF
name: root-marketplace
marketplace:
  owner: someone
  packages:
    - ./packages/plugin-a
EOF
    cat > "$dir/.apm/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - my-source
---

You are a test agent.
EOF
    run bash "$SCRIPT" "$dir/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output ""
}

@test "non-plugin scope: bare plugin.json (no apm.yml) is no longer a scope signal → exit 0, no output" {
    local dir="$TMPDIR/old-plugin-json-only"
    mkdir -p "$dir/agents"
    echo '{"name":"test-plugin","version":"0.1.0"}' > "$dir/plugin.json"
    cat > "$dir/agents/my-agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - my-source
---

You are a test agent.
EOF
    run bash "$SCRIPT" "$dir/agents/my-agent.md"
    assert_success
    assert_output ""
}

@test "non-plugin scope: walk-up stops at .git boundary before reaching an ancestor apm.yml" {
    local dir="$TMPDIR/repo"
    mkdir -p "$dir/.git" "$dir/.apm/agents"
    cat > "$dir/apm.yml" <<EOF
name: test-package
version: 0.1.0
type: skill
EOF
    mkdir -p "$dir/sub/.apm/agents"
    cat > "$dir/sub/.apm/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - my-source
---

You are a test agent.
EOF
    # sub/ has no .git and no apm.yml of its own; the real package apm.yml
    # lives at $dir, but $dir/.git means the walk from sub/ should stop at
    # sub/ itself only if sub/ had a .git — here .git is at $dir, ABOVE
    # sub/, so the walk from sub/ reaches $dir/apm.yml before any .git.
    # This test instead verifies the walk finds that package root correctly
    # (a positive case) — see the dedicated .git-stops-first test below for
    # the negative case.
    run bash "$SCRIPT" "$dir/sub/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

@test "non-plugin scope: \$HOME boundary stops the walk before reaching an ancestor apm.yml above \$HOME" {
    # A type-bearing apm.yml sits ABOVE the fake $HOME — if find_plugin_root
    # didn't stop at $HOME, it would walk past it and misclassify this
    # user/project-scope file as plugin scope, which would then FAIL on
    # Check 0 (source_keys declared but sources.md absent) since sources.md
    # doesn't exist at that ancestor apm.yml's location either.
    local dir="$TMPDIR/anc"
    mkdir -p "$dir"
    cat > "$dir/apm.yml" <<EOF
name: outer-package
version: 0.1.0
type: skill
EOF
    local fake_home="$dir/fakehome"
    mkdir -p "$fake_home/.apm/agents"
    cat > "$fake_home/.apm/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - my-source
---

You are a test agent.
EOF
    run env HOME="$fake_home" bash "$SCRIPT" "$fake_home/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output ""
}

@test "non-plugin scope: .git between the agent file and an ancestor apm.yml stops the walk first" {
    local dir="$TMPDIR/repo2"
    mkdir -p "$dir/.apm/agents"
    cat > "$dir/apm.yml" <<EOF
name: test-package
version: 0.1.0
type: skill
EOF
    mkdir -p "$dir/sub/.git" "$dir/sub/.apm/agents"
    cat > "$dir/sub/.apm/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - my-source
---

You are a test agent.
EOF
    run bash "$SCRIPT" "$dir/sub/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output ""
}

# ---------------------------------------------------------------------------
# Early exit: no sources.md, no source_keys → exit 0, no output
# ---------------------------------------------------------------------------

@test "clean pass: no sources.md and no source_keys → exit 0, no output" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_clean_agent "$root"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output ""
}

# ---------------------------------------------------------------------------
# Check 0: source_keys present but sources.md absent → FAIL
# ---------------------------------------------------------------------------

@test "FAIL: source_keys in agent file but sources.md absent" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

# ---------------------------------------------------------------------------
# Check 1: FILL IN: placeholder in sources.md → FAIL
# ---------------------------------------------------------------------------

@test "FAIL: FILL IN: placeholder in sources.md" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** FILL IN: add url
- **Description:** A test source.
- **Contributing files:** .apm/agents/my-agent.agent.md
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

@test "FILL IN: inside backticks in sources.md does not fail" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    make_sources_md "$root"
    echo "Use \`FILL IN: value\` as example." >> "$root/sources.md"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
}

# ---------------------------------------------------------------------------
# Check 2: source_keys slug missing from sources.md → FAIL
# ---------------------------------------------------------------------------

@test "FAIL: source_keys slug in agent file not present as H2 in sources.md" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root" "my-agent" "my-source"
    make_sources_md "$root" "different-source" "(none)" "(none)"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

# ---------------------------------------------------------------------------
# Check 3: Contributing file path doesn't exist → FAIL
# ---------------------------------------------------------------------------

@test "FAIL: Contributing file listed in sources.md does not exist" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    make_sources_md "$root" "my-source" ".apm/agents/nonexistent.agent.md"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

@test "pass: (none) in Contributing files is skipped" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    make_sources_md "$root" "my-source" "(none — not used directly)"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
}

# ---------------------------------------------------------------------------
# Check 5: Research doc field missing or placeholder → FAIL
# ---------------------------------------------------------------------------

@test "FAIL: Research doc field missing from sources.md entry" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Contributing files:** .apm/agents/my-agent.agent.md
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

@test "FAIL: Research doc field is FILL IN: placeholder" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Contributing files:** .apm/agents/my-agent.agent.md
- **Research doc:** FILL IN: path to research doc
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

# ---------------------------------------------------------------------------
# Check 4: Bidirectional — contributing file missing slug in source_keys → FAIL
# ---------------------------------------------------------------------------

@test "FAIL: Contributing file exists but does not list parent slug in source_keys" {
    local root="$TMPDIR/package"
    make_package "$root"
    # agent file has source_keys: other-source (not my-source)
    cat > "$root/.apm/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - other-source
---

You are a test agent.
EOF
    # sources.md says my-agent.agent.md contributed to my-source, but
    # my-agent.agent.md doesn't list my-source
    cat > "$root/sources.md" <<EOF
# Sources

## other-source

- **URL:** https://example.com/other-source
- **Description:** A test source.
- **Contributing files:** .apm/agents/my-agent.agent.md
- **Research doc:** (none)
- **Status:** \`extracted\`

## my-source

- **URL:** https://example.com/my-source
- **Description:** Another source.
- **Contributing files:** .apm/agents/my-agent.agent.md
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
}

# ---------------------------------------------------------------------------
# Clean full pass
# ---------------------------------------------------------------------------

@test "clean full pass: all checks satisfied" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    make_sources_md "$root"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
}

# ---------------------------------------------------------------------------
# Checks 3 and 4: None ("could not parse") is NOT [] ("explicitly (none)")
#
# parse_contributing_files returns three distinguishable answers and checks 3
# and 4 have to honour all three. `[]` is the author writing "(none)" — the
# skip is correct and silent. None is a Contributing files block the parser
# cannot read, and skipping THAT silently disables both checks on the one entry
# least likely to be right, which is the failure mode the parser's own
# docstring warns about. The assertions below are therefore about the INFO
# appearing; a silent exit 0 is exactly the bug.
# ---------------------------------------------------------------------------

@test "INFO: an unparsable Contributing files block names the slug instead of skipping checks 3 and 4 silently" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Research doc:** (none)
**Contributing files:**
* .apm/agents/ghost.agent.md (asterisk bullets are not the bullet form)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output --partial "INFO"
    assert_output --partial "Contributing-file checks skipped for 'my-source' — the Contributing files block could not be parsed"
}

@test "INFO: an entry with no Contributing files field at all is reported, not skipped silently" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output --partial "INFO"
    assert_output --partial "Contributing-file checks skipped for 'my-source' — the Contributing files block could not be parsed"
}

@test "checks 3 and 4 skipped silently: an explicit '(none)' emits no INFO" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    make_sources_md "$root" "my-source" "(none — not used directly)"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output ""
}

@test "checks 3 and 4 still run: a parseable Contributing files list is not diverted to the INFO" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    make_sources_md "$root" "my-source" ".apm/agents/nonexistent.agent.md"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL"
    assert_output --partial "Contributing file '.apm/agents/nonexistent.agent.md' does not exist"
    refute_output --partial "could not be parsed"
}

# ---------------------------------------------------------------------------
# The INFO tier itself: kind-aware printing and a kind-aware exit code
#
# INFO is new here — before it, findings was a 5-tuple and print_findings
# stamped every entry FAIL. The two cases below pin the tier rather than any
# one check: an INFO must print under the INFO prefix and leave the exit code
# at 0, and a real FAIL must keep printing under the FAIL prefix and still exit
# non-zero even when an INFO is sitting in the same findings list.
# ---------------------------------------------------------------------------

@test "INFO tier: an INFO alone prints as INFO with a Note and does not set a failing exit code" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output --partial "INFO  Contributing-file checks skipped for 'my-source'"
    assert_output --partial "Note:"
    refute_output --partial "FAIL"
}

@test "FAIL tier: a genuine FAIL alongside an INFO still prints as FAIL and exits non-zero" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Contributing files:** .apm/agents/nonexistent.agent.md
- **Research doc:** (none)
- **Status:** \`extracted\`

## ghost-source

- **URL:** https://example.com/ghost-source
- **Description:** Another test source.
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL  Contributing file '.apm/agents/nonexistent.agent.md' does not exist"
    assert_output --partial "Why:"
    assert_output --partial "INFO  Contributing-file checks skipped for 'ghost-source'"
    assert_output --partial "Note:"
}

# ---------------------------------------------------------------------------
# The exit-2 tier, and its boundary with the silent exit 0
#
# Ported from the skill-audit sibling, which had already split usage and
# environment errors (exit 2) away from findings (exit 1). SKILL.md tells the
# auditor to surface a non-zero exit, so a usage error leaving exit 1 with
# nothing on stdout was indistinguishable from a clean-but-failing run.
#
# The reconciliation this script needs and the sibling does not: "the walk-up
# found no type:-bearing apm.yml" is NOT bad input. It is a verdict about a
# real, readable agent file — user or project scope, where plugin-scope
# provenance does not apply — and scripts/check-scope-walkup-sync.sh fixture 6
# pins it as exit 0 with empty output. Every exit-2 gate is therefore decided
# from the ARGUMENT ALONE, before the walk-up runs, so the two can never
# collide. The two tests at the end of this block assert both halves.
# ---------------------------------------------------------------------------

@test "exit 2: no arguments is a usage error, not a finding" {
    run bash "$SCRIPT"
    [ "$status" -eq 2 ]
    assert_output --partial "agent-file is required"
}

@test "exit 2: a second positional argument is rejected instead of silently dropped" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_clean_agent "$root"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md" --some-typo
    [ "$status" -eq 2 ]
    assert_output --partial "expected exactly one argument"
}

@test "exit 2: a nonexistent path is an error, not a silent pass" {
    run bash "$SCRIPT" "$TMPDIR/no-such-agent.agent.md"
    [ "$status" -eq 2 ]
    assert_output --partial "no such file"
}

@test "exit 2: a directory is not an agent file" {
    local root="$TMPDIR/package"
    make_package "$root"
    run bash "$SCRIPT" "$root/.apm/agents"
    [ "$status" -eq 2 ]
    assert_output --partial "not a regular file"
}

@test "exit 2: an unrecognized extension is rejected before the walk-up runs" {
    local root="$TMPDIR/package"
    make_package "$root"
    echo "not an agent" > "$root/.apm/agents/my-agent.txt"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.txt"
    [ "$status" -eq 2 ]
    assert_output --partial "unrecognized extension"
}

@test "exit 2: a PATH with no python3 names the missing dependency instead of exiting 127" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_clean_agent "$root"
    local emptybin="$TMPDIR/emptybin"
    mkdir -p "$emptybin"
    local bash_bin
    bash_bin="$(command -v bash)"
    run env -i PATH="$emptybin" HOME="$HOME" "$bash_bin" "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    [ "$status" -eq 2 ]
    # The needle is the DIAGNOSTIC, not the bare word: with no preflight, bash's
    # own "python3: command not found" would satisfy a bare-word match.
    assert_output --partial "python3 is required"
}

@test "reconciliation: a REAL agent file at non-plugin scope still exits 0 silently, never 2" {
    # scripts/check-scope-walkup-sync.sh fixture 6 in miniature. The exit-2 tier
    # must not widen to cover "find_plugin_root returned None": the file exists,
    # is readable and is correctly named — it is simply user/project scope.
    local dir="$TMPDIR/anc"
    mkdir -p "$dir"
    cat > "$dir/apm.yml" <<EOF
name: outer-package
version: 0.1.0
type: skill
EOF
    local fake_home="$dir/fakehome"
    mkdir -p "$fake_home/.apm/agents"
    cat > "$fake_home/.apm/agents/my-agent.agent.md" <<EOF
---
name: my-agent
description: A valid agent description.
source_keys:
  - my-source
---

You are a test agent.
EOF
    run env HOME="$fake_home" bash "$SCRIPT" "$fake_home/.apm/agents/my-agent.agent.md"
    [ "$status" -eq 0 ]
    assert_output ""
}

@test "reconciliation: a nonexistent path inside a non-plugin-scope tree exits 2, not the old silent 0" {
    # The other half. Before the exit-2 tier, a typo'd path anywhere outside a
    # package took the not-plugin-scope exit and reported a silent pass, so the
    # typo and a clean agent produced identical output and identical status.
    local fake_home="$TMPDIR/plainhome"
    mkdir -p "$fake_home/.apm/agents"
    run env HOME="$fake_home" bash "$SCRIPT" "$fake_home/.apm/agents/typo.agent.md"
    [ "$status" -eq 2 ]
    assert_output --partial "no such file"
}

# ---------------------------------------------------------------------------
# PLACEHOLDER_RE: the trailing character class was CONSUMING
#
# `(?<!\`)FILL IN:[^\`\n]` required a character after the colon, so a `FILL IN:`
# at end of line matched nothing and escaped checks 1 and 5 entirely — and
# `- **Description:** FILL IN:` is the most likely spelling of a half-written
# entry. The lookahead states the same exclusion without eating a character.
# ---------------------------------------------------------------------------

@test "FAIL: a FILL IN: placeholder at end of line is caught, not skipped" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** FILL IN:
- **Contributing files:** .apm/agents/my-agent.agent.md
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "Unfilled FILL IN: placeholder"
}

@test "FAIL: a Research doc value that is a bare end-of-line FILL IN: is caught" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Contributing files:** .apm/agents/my-agent.agent.md
- **Research doc:** FILL IN:
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "Research doc field is empty or placeholder"
}

# ---------------------------------------------------------------------------
# Encoding, read side: read_text() pins UTF-8 and strips a BOM
#
# The old code used bare open() calls inheriting locale.getpreferredencoding(),
# which is ASCII under LC_ALL=C, and wrapped exactly one of them in
# `except Exception: return []` — so an unreadable agent file was reported as
# having no source_keys and therefore as CLEAN. The other call sites had no
# handler at all and died with a traceback.
# ---------------------------------------------------------------------------

@test "FAIL: an undecodable agent file is reported, not swallowed into a clean pass" {
    local root="$TMPDIR/package"
    make_package "$root"
    printf '\xff\xfe---\nname: my-agent\n---\n' > "$root/.apm/agents/my-agent.agent.md"
    make_sources_md "$root" "my-source" "(none)"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "not valid UTF-8"
    refute_output --partial "Traceback"
}

@test "FAIL: an undecodable contributing file is reported, not a traceback" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    printf '\xff\xfe---\nname: other\n---\n' > "$root/.apm/agents/other.agent.md"
    make_sources_md "$root" "my-source" ".apm/agents/other.agent.md"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "not valid UTF-8"
    refute_output --partial "Traceback"
}

@test "exit 2: an undecodable apm.yml names the file instead of dying mid walk-up" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_clean_agent "$root"
    printf 'name: t\nversion: 0.1.0\ntype: skill\n# \xff\xfe\n' > "$root/apm.yml"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    [ "$status" -eq 2 ]
    assert_output --partial "not valid UTF-8"
    refute_output --partial "Traceback"
}

@test "a BOM-prefixed agent file still has its source_keys read (check 2 runs)" {
    # A leading BOM defeats parse_frontmatter()'s ^--- anchor, so no frontmatter
    # parsed means no source_keys parsed means nothing to validate — check 2
    # went silently missing on exactly the file it was pointed at.
    local root="$TMPDIR/package"
    make_package "$root"
    printf '\xef\xbb\xbf---\nname: my-agent\ndescription: A valid agent description.\nsource_keys:\n  - ghost-source\n---\n\nYou are a test agent.\n' \
      > "$root/.apm/agents/my-agent.agent.md"
    make_sources_md "$root" "my-source" "(none)"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "source_keys slug 'ghost-source' not found in sources.md"
}

@test "under LC_ALL=C a sources.md carrying an em dash is read, not a UnicodeDecodeError" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source — with an em dash.
- **Contributing files:** .apm/agents/ghost.agent.md
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run env LC_ALL=C PYTHONUTF8=0 bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "Contributing file '.apm/agents/ghost.agent.md' does not exist"
    refute_output --partial "Traceback"
}

# ---------------------------------------------------------------------------
# Encoding, write side: sys.stdout/stderr.reconfigure(encoding='utf-8')
#
# Pinning only the reads moved the crash from the read to the WRITE. Every
# finding this script prints contains an em dash, so under LC_ALL=C
# print_findings() died with UnicodeEncodeError after every check had already
# run — losing the whole report at the last step.
# ---------------------------------------------------------------------------

@test "under LC_ALL=C the findings report is printed, not lost to a UnicodeEncodeError" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    make_sources_md "$root" "my-source" ".apm/agents/ghost.agent.md"
    run env LC_ALL=C PYTHONUTF8=0 bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    assert_output --partial "FAIL  Contributing file '.apm/agents/ghost.agent.md' does not exist"
    assert_output --partial "Why:"
    refute_output --partial "UnicodeEncodeError"
}

# ---------------------------------------------------------------------------
# Half-validated entries announced instead of passing silently
# ---------------------------------------------------------------------------

@test "INFO: a duplicated '## slug' says only the first block was checked" {
    # Every per-slug parser locates its block with pattern.search(), so a slug
    # written twice resolves to the FIRST block every time: the second block's
    # fields are never validated, and the entry looked fully checked.
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Contributing files:** (none)
- **Research doc:** (none)
- **Status:** \`extracted\`

## my-source

- **URL:** https://example.com/dup
- **Description:** A duplicate entry.
- **Contributing files:** .apm/agents/ghost.agent.md
- **Research doc:** (none)
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output --partial "Duplicate '## my-source' entry in sources.md"
    # The second block's ghost contributing file is genuinely never checked —
    # the INFO is what makes that visible rather than a silent half-pass.
    refute_output --partial "does not exist"
}

@test "INFO: a second '- **Research doc:**' line in one entry is announced, not ignored" {
    local root="$TMPDIR/package"
    make_package "$root"
    make_agent_with_source_keys "$root"
    cat > "$root/sources.md" <<EOF
# Sources

## my-source

- **URL:** https://example.com/my-source
- **Description:** A test source.
- **Contributing files:** (none)
- **Research doc:** (none)
- **Research doc:** docs/research/added-later.md
- **Status:** \`extracted\`
EOF
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_success
    assert_output --partial "Multiple '- **Research doc:**' lines for 'my-source'"
}

# ---------------------------------------------------------------------------
# Finding dedup
#
# The agent file is read once for its own source_keys and again as a
# contributing file, so an unreadable one produced the identical finding twice.
# Distinct findings about the same file still both appear.
# ---------------------------------------------------------------------------

@test "the same unreadable file reached by two checks is reported once, not twice" {
    local root="$TMPDIR/package"
    make_package "$root"
    printf '\xff\xfe---\nname: my-agent\n---\n' > "$root/.apm/agents/my-agent.agent.md"
    make_sources_md "$root" "my-source" ".apm/agents/my-agent.agent.md"
    run bash "$SCRIPT" "$root/.apm/agents/my-agent.agent.md"
    assert_failure
    local count
    count="$(printf '%s\n' "$output" | grep -c "^FAIL  File is not valid UTF-8" || true)"
    [ "$count" -eq 1 ]
}