channel_not_found: a channel name where an ID belongs

"""Check that every Slack channel reference in your configuration is an ID.

Read only, and mostly offline: the shape of a reference settles most of the
finding before a request is sent. One paginated conversations.list resolves the
names that are left. Nothing is written; the replacement config line is printed
for you to paste.
"""
import argparse
import json
import logging
import os
import re
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("slack_channel_reference_form")

API = "https://slack.com/api/"

ID_RE = re.compile(r"^[CG][A-Z0-9]{7,}$")
DM_RE = re.compile(r"^D[A-Z0-9]{7,}$")
USER_RE = re.compile(r"^[UW][A-Z0-9]{7,}$")
NAME_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,79}$")
LINK_RE = re.compile(r"/archives/([CGD][A-Z0-9]{7,})")

# chat.postMessage kept legacy name resolution from before the conversations.*
# family existed. Nothing else did. That split is the whole reason this survives
# code review: the send path works and the read path does not.
TOLERANT = ("chat.postMessage",)
STRICT = ("conversations.info", "conversations.history", "conversations.members",
          "files.completeUploadExternal")
FAMILIES = TOLERANT + STRICT

NEEDS_LOOKUP = ("hash-name", "bare-name")


def reference_form(value):
    """Name the shape of one configured channel reference. Pure, so it is offline.

    Returns (form, detail). Order matters: a permalink contains a valid ID and
    would otherwise fall through to the malformed bucket, and a bare name is only
    a name once every ID pattern has been ruled out.
    """
    text = ("" if value is None else str(value)).strip()
    if not text:
        return ("empty", "no value at all. Something upstream resolved to an empty "
                         "string and the call will fail on every method.")

    link = LINK_RE.search(text)
    if link and not ID_RE.match(text):
        return ("permalink",
                "a channel permalink. The ID is inside it (%s) but no method will "
                "unwrap a URL for you." % link.group(1))
    if ID_RE.match(text):
        return ("channel-id", "a channel ID, which is what every method wants")
    if DM_RE.match(text):
        return ("dm-id",
                "a DM conversation ID. Every method accepts it and none of them "
                "will tell you it reaches one person rather than a channel.")
    if USER_RE.match(text):
        return ("user-id",
                "a user ID in the channel slot. chat.postMessage opens a DM and "
                "delivers to that person, so there is no error to find.")
    if text.startswith("#"):
        body = text[1:]
        if NAME_RE.match(body):
            return ("hash-name",
                    "a channel name with the display hash. The hash is UI syntax; "
                    "no method has ever treated it as part of an identifier.")
        return ("malformed", "starts with # but the rest is not a legal channel name")
    if NAME_RE.match(text):
        return ("bare-name",
                "a channel name. Names are display labels: mutable, reusable, and "
                "accepted by exactly one method family.")
    return ("malformed",
            "not an ID, not a legal channel name, and not a permalink. Whatever "
            "built this string built it wrong.")


def path_outcomes(form):
    """Turn a reference shape into the per-method truth table. Pure.

    Returns (verdict, rows) with rows as [(method, outcome), ...]. The verdict is
    the half worth reading: `split-brain` means this exact string is correct for
    one method family and wrong for another, which is why the failure looks
    intermittent rather than configured.
    """
    if form == "channel-id":
        return ("canonical", [(m, "accepts") for m in FAMILIES])
    if form in NEEDS_LOOKUP:
        return ("split-brain",
                [(m, "accepts") for m in TOLERANT] + [(m, "refuses") for m in STRICT])
    if form == "user-id":
        return ("wrong-entity",
                [(m, "delivers elsewhere") for m in TOLERANT]
                + [(m, "refuses") for m in STRICT])
    if form == "dm-id":
        return ("not-a-channel", [(m, "accepts") for m in FAMILIES])
    if form == "permalink":
        return ("recoverable", [(m, "refuses") for m in FAMILIES])
    return ("unusable", [(m, "refuses") for m in FAMILIES])


def resolve_name(value, channels):
    """Match a configured name against the workspace inventory. Pure.

    Names are unique among live channels, but archiving releases a name for
    reuse, so a sweep that includes archives can return two rows for one string.
    Returns (state, channel, detail) and never picks a winner when the answer is
    genuinely two channels.
    """
    wanted = str(value).lstrip("#").strip().lower()
    hits = [c for c in channels if str(c.get("name") or "").lower() == wanted]
    live = [c for c in hits if not c.get("is_archived")]

    if not hits:
        return ("unresolved", None,
                "no channel in the workspace carries this name. It was renamed, "
                "deleted, or belongs to a workspace this token cannot see.")
    if not live:
        return ("archived-only", hits[0],
                "the only match is archived (%s). The ID resolves and the channel "
                "accepts nothing." % hits[0].get("id"))
    if len(live) > 1:
        return ("ambiguous", None,
                "%d live channels answer to this name, which happens across an "
                "Enterprise Grid org. A name cannot address one of them."
                % len(live))
    if len(hits) > 1:
        return ("resolved-with-archived-twin", live[0],
                "resolves to %s, and an archived channel holds the same name. The "
                "name is already contested." % live[0].get("id"))
    return ("resolved", live[0], "resolves to %s" % live[0].get("id"))


def config_line(key, channel, original):
    """The replacement line, with the old name kept as a comment. Pure."""
    return "%s=%s  # was %s, now #%s" % (key, channel.get("id"), original,
                                         channel.get("name"))


def list_channels(session):
    """Every channel the token can enumerate, archives included. GET only."""
    out, cursor = [], ""
    while True:
        params = {"types": "public_channel,private_channel",
                  "exclude_archived": "false", "limit": 1000}
        if cursor:
            params["cursor"] = cursor
        body = session.get(API + "conversations.list", params=params, timeout=30).json()
        if body.get("ok") is not True:
            raise SystemExit("conversations.list answered 200 with ok: false, "
                             "error=%s" % body.get("error"))
        out.extend(body.get("channels") or [])
        cursor = (body.get("response_metadata") or {}).get("next_cursor") or ""
        if not cursor:
            return out


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--config", required=True,
                    help="JSON object mapping a config key to its channel reference")
    ap.add_argument("--token-env", default="SLACK_BOT_TOKEN",
                    help="environment variable holding the bot token")
    args = ap.parse_args()

    entries = json.loads(open(args.config, encoding="utf-8").read())
    forms = {k: reference_form(v) for k, v in entries.items()}

    channels = []
    if any(f[0] in NEEDS_LOOKUP for f in forms.values()):
        token = os.environ.get(args.token_env)
        if not token:
            log.error("set %s (channels:read and groups:read are enough)", args.token_env)
            return 2
        s = requests.Session()
        s.headers.update({"Authorization": "Bearer " + token})
        channels = list_channels(s)
        log.info("inventory: %d channel(s) the token can enumerate", len(channels))

    bad = 0
    for key in sorted(entries):
        value = entries[key]
        form, detail = forms[key]
        verdict, rows = path_outcomes(form)
        if verdict == "canonical":
            log.info("%-14s %-16s %-12s accepted by every method family",
                     verdict, key, value)
            continue

        bad += 1
        log.warning("%-14s %-16s %-12s %s", verdict, key, value, detail)
        for method, outcome in rows:
            if outcome != "accepts":
                log.warning("  %-30s %s", method, outcome)

        if form == "permalink":
            log.warning("  repair: %s=%s", key, LINK_RE.search(str(value)).group(1))
            continue
        if form not in NEEDS_LOOKUP:
            log.warning("  repair: put a channel ID in %s; copy it from the channel "
                        "details panel in Slack", key)
            continue

        state, channel, why = resolve_name(value, channels)
        log.warning("  lookup: %s -- %s", state, why)
        if channel is not None and state != "archived-only":
            log.warning("  repair: %s", config_line(key, channel, value))
        elif state == "archived-only":
            log.warning("  repair: this name only exists on an archived channel; "
                        "point %s at a live one", key)
        else:
            log.warning("  repair: find the channel in Slack, copy its ID from the "
                        "details panel, and store that in %s", key)

    log.info("%d reference(s) checked, %d that are not channel IDs", len(entries), bad)
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main())

/**
 * Check that every Slack channel reference in your configuration is an ID.
 *
 * Read only, and mostly offline: the shape of a reference settles most of the
 * finding before a request is sent. One paginated conversations.list resolves
 * the names that are left. Nothing is written; the replacement config line is
 * printed for you to paste.
 */
import { readFile } from 'node:fs/promises';

const API = 'https://slack.com/api/';

const ID_RE = /^[CG][A-Z0-9]{7,}$/;
const DM_RE = /^D[A-Z0-9]{7,}$/;
const USER_RE = /^[UW][A-Z0-9]{7,}$/;
const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,79}$/;
const LINK_RE = /\/archives\/([CGD][A-Z0-9]{7,})/;

// chat.postMessage kept legacy name resolution from before the conversations.*
// family existed. Nothing else did. That split is the whole reason this survives
// code review: the send path works and the read path does not.
const TOLERANT = ['chat.postMessage'];
const STRICT = ['conversations.info', 'conversations.history',
  'conversations.members', 'files.completeUploadExternal'];
const FAMILIES = [...TOLERANT, ...STRICT];

const NEEDS_LOOKUP = new Set(['hash-name', 'bare-name']);

/**
 * Name the shape of one configured channel reference. Pure, so it is offline.
 * Order matters: a permalink contains a valid ID and would otherwise fall through
 * to the malformed bucket.
 */
export function referenceForm(value) {
  const text = (value === null || value === undefined ? '' : String(value)).trim();
  if (!text) {
    return ['empty', 'no value at all. Something upstream resolved to an empty ' +
      'string and the call will fail on every method.'];
  }

  const link = LINK_RE.exec(text);
  if (link && !ID_RE.test(text)) {
    return ['permalink',
      `a channel permalink. The ID is inside it (${link[1]}) but no method will ` +
      'unwrap a URL for you.'];
  }
  if (ID_RE.test(text)) return ['channel-id', 'a channel ID, which is what every method wants'];
  if (DM_RE.test(text)) {
    return ['dm-id',
      'a DM conversation ID. Every method accepts it and none of them will tell ' +
      'you it reaches one person rather than a channel.'];
  }
  if (USER_RE.test(text)) {
    return ['user-id',
      'a user ID in the channel slot. chat.postMessage opens a DM and delivers to ' +
      'that person, so there is no error to find.'];
  }
  if (text.startsWith('#')) {
    const body = text.slice(1);
    if (NAME_RE.test(body)) {
      return ['hash-name',
        'a channel name with the display hash. The hash is UI syntax; no method ' +
        'has ever treated it as part of an identifier.'];
    }
    return ['malformed', 'starts with # but the rest is not a legal channel name'];
  }
  if (NAME_RE.test(text)) {
    return ['bare-name',
      'a channel name. Names are display labels: mutable, reusable, and accepted ' +
      'by exactly one method family.'];
  }
  return ['malformed',
    'not an ID, not a legal channel name, and not a permalink. Whatever built ' +
    'this string built it wrong.'];
}

/**
 * Turn a reference shape into the per-method truth table. Pure.
 * `split-brain` means this exact string is correct for one method family and
 * wrong for another, which is why the failure looks intermittent.
 */
export function pathOutcomes(form) {
  if (form === 'channel-id') return ['canonical', FAMILIES.map((m) => [m, 'accepts'])];
  if (NEEDS_LOOKUP.has(form)) {
    return ['split-brain', [
      ...TOLERANT.map((m) => [m, 'accepts']),
      ...STRICT.map((m) => [m, 'refuses']),
    ]];
  }
  if (form === 'user-id') {
    return ['wrong-entity', [
      ...TOLERANT.map((m) => [m, 'delivers elsewhere']),
      ...STRICT.map((m) => [m, 'refuses']),
    ]];
  }
  if (form === 'dm-id') return ['not-a-channel', FAMILIES.map((m) => [m, 'accepts'])];
  if (form === 'permalink') return ['recoverable', FAMILIES.map((m) => [m, 'refuses'])];
  return ['unusable', FAMILIES.map((m) => [m, 'refuses'])];
}

/**
 * Match a configured name against the workspace inventory. Pure.
 * Never picks a winner when the answer is genuinely two channels.
 */
export function resolveName(value, channels) {
  const wanted = String(value).replace(/^#+/, '').trim().toLowerCase();
  const hits = channels.filter((c) => String(c.name ?? '').toLowerCase() === wanted);
  const live = hits.filter((c) => !c.is_archived);

  if (hits.length === 0) {
    return ['unresolved', null,
      'no channel in the workspace carries this name. It was renamed, deleted, or ' +
      'belongs to a workspace this token cannot see.'];
  }
  if (live.length === 0) {
    return ['archived-only', hits[0],
      `the only match is archived (${hits[0].id}). The ID resolves and the channel ` +
      'accepts nothing.'];
  }
  if (live.length > 1) {
    return ['ambiguous', null,
      `${live.length} live channels answer to this name, which happens across an ` +
      'Enterprise Grid org. A name cannot address one of them.'];
  }
  if (hits.length > 1) {
    return ['resolved-with-archived-twin', live[0],
      `resolves to ${live[0].id}, and an archived channel holds the same name. The ` +
      'name is already contested.'];
  }
  return ['resolved', live[0], `resolves to ${live[0].id}`];
}

/** The replacement line, with the old name kept as a comment. Pure. */
export function configLine(key, channel, original) {
  return `${key}=${channel.id}  # was ${original}, now #${channel.name}`;
}

async function listChannels(token) {
  const out = [];
  let cursor = '';
  for (;;) {
    const params = new URLSearchParams({
      types: 'public_channel,private_channel',
      exclude_archived: 'false',
      limit: '1000',
    });
    if (cursor) params.set('cursor', cursor);
    const res = await fetch(`${API}conversations.list?${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const body = await res.json();
    if (body.ok !== true) {
      throw new Error(`conversations.list answered 200 with ok: false, error=${body.error}`);
    }
    out.push(...(body.channels ?? []));
    cursor = body.response_metadata?.next_cursor ?? '';
    if (!cursor) return out;
  }
}

function arg(args, name, fallback = null) {
  const i = args.indexOf(name);
  return i === -1 ? fallback : args[i + 1];
}

async function main() {
  const args = process.argv.slice(2);
  const configPath = arg(args, '--config');
  if (!configPath) {
    console.error('usage: --config channels.json [--token-env SLACK_BOT_TOKEN]');
    process.exitCode = 2;
    return;
  }
  const tokenEnv = arg(args, '--token-env', 'SLACK_BOT_TOKEN');
  const entries = JSON.parse(await readFile(configPath, 'utf8'));
  const forms = new Map(Object.entries(entries).map(([k, v]) => [k, referenceForm(v)]));

  let channels = [];
  if ([...forms.values()].some(([f]) => NEEDS_LOOKUP.has(f))) {
    const token = process.env[tokenEnv];
    if (!token) {
      console.error(`set ${tokenEnv} (channels:read and groups:read are enough)`);
      process.exitCode = 2;
      return;
    }
    channels = await listChannels(token);
    console.log(`inventory: ${channels.length} channel(s) the token can enumerate`);
  }

  let bad = 0;
  for (const key of Object.keys(entries).sort()) {
    const value = entries[key];
    const [form, detail] = forms.get(key);
    const [verdict, rows] = pathOutcomes(form);
    if (verdict === 'canonical') {
      console.log(`${verdict.padEnd(14)} ${key.padEnd(16)} ${String(value).padEnd(12)} ` +
                  'accepted by every method family');
      continue;
    }

    bad += 1;
    console.warn(`${verdict.padEnd(14)} ${key.padEnd(16)} ${String(value).padEnd(12)} ${detail}`);
    for (const [method, outcome] of rows) {
      if (outcome !== 'accepts') console.warn(`  ${method.padEnd(30)} ${outcome}`);
    }

    if (form === 'permalink') {
      console.warn(`  repair: ${key}=${LINK_RE.exec(String(value))[1]}`);
      continue;
    }
    if (!NEEDS_LOOKUP.has(form)) {
      console.warn(`  repair: put a channel ID in ${key}; copy it from the channel ` +
                   'details panel in Slack');
      continue;
    }

    const [state, channel, why] = resolveName(value, channels);
    console.warn(`  lookup: ${state} -- ${why}`);
    if (channel !== null && state !== 'archived-only') {
      console.warn(`  repair: ${configLine(key, channel, value)}`);
    } else if (state === 'archived-only') {
      console.warn('  repair: this name only exists on an archived channel; point ' +
                   `${key} at a live one`);
    } else {
      console.warn('  repair: find the channel in Slack, copy its ID from the details ' +
                   `panel, and store that in ${key}`);
    }
  }

  console.log(`${Object.keys(entries).length} reference(s) checked, ${bad} that are ` +
              'not channel IDs');
  process.exitCode = bad ? 1 : 0;
}

// Only run when invoked directly, so importing this module in the tests does not
// execute main() and fail the file on a missing config.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from slack_channel_reference_form import (config_line, path_outcomes,
                                           reference_form, resolve_name)

LIVE = {"id": "C01ABCDE9", "name": "alerts", "is_archived": False}
DEAD = {"id": "C09OLDONE", "name": "alerts", "is_archived": True}


def test_a_channel_id_is_the_canonical_form():
    form, _ = reference_form("C01ABCDE9")
    assert form == "channel-id"
    assert path_outcomes(form)[0] == "canonical"


def test_a_hash_name_is_accepted_by_one_family_and_refused_by_the_rest():
    form, _ = reference_form("#alerts")
    assert form == "hash-name"
    verdict, rows = path_outcomes(form)
    assert verdict == "split-brain"
    assert dict(rows)["chat.postMessage"] == "accepts"
    assert dict(rows)["conversations.history"] == "refuses"


def test_a_bare_name_lands_in_the_same_bucket_as_a_hash_name():
    assert reference_form("alerts")[0] == "bare-name"
    assert path_outcomes("bare-name")[0] == "split-brain"


def test_a_user_id_is_not_a_name_problem_because_nothing_errors():
    form, detail = reference_form("U024BE7LH")
    assert form == "user-id"
    assert "DM" in detail
    verdict, rows = path_outcomes(form)
    assert verdict == "wrong-entity"
    assert dict(rows)["chat.postMessage"] == "delivers elsewhere"


def test_a_permalink_carries_the_id_it_needs():
    form, detail = reference_form("https://acme.slack.com/archives/C01ABCDE9")
    assert form == "permalink"
    assert "C01ABCDE9" in detail


def test_an_empty_string_is_reported_as_its_own_shape():
    assert reference_form("")[0] == "empty"
    assert reference_form(None)[0] == "empty"
    assert path_outcomes("empty")[0] == "unusable"


def test_a_name_resolves_to_the_live_channel():
    state, channel, _ = resolve_name("#alerts", [LIVE])
    assert state == "resolved"
    assert channel["id"] == "C01ABCDE9"


def test_a_name_held_by_a_live_and_an_archived_channel_is_reported_as_contested():
    state, channel, detail = resolve_name("alerts", [DEAD, LIVE])
    assert state == "resolved-with-archived-twin"
    assert channel["id"] == "C01ABCDE9"
    assert "contested" in detail


def test_a_name_that_only_matches_an_archive_is_not_a_resolution():
    state, _, _ = resolve_name("alerts", [DEAD])
    assert state == "archived-only"


def test_two_live_channels_with_one_name_are_never_silently_picked():
    twin = dict(LIVE, id="C07OTHER1")
    state, channel, _ = resolve_name("alerts", [LIVE, twin])
    assert state == "ambiguous"
    assert channel is None


def test_the_repair_line_keeps_the_old_name_as_a_comment():
    line = config_line("ALERTS_CHANNEL", LIVE, "#alerts")
    assert line.startswith("ALERTS_CHANNEL=C01ABCDE9")
    assert "#alerts" in line

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { configLine, pathOutcomes, referenceForm, resolveName }
  from './slack-channel-reference-form.mjs';

const LIVE = { id: 'C01ABCDE9', name: 'alerts', is_archived: false };
const DEAD = { id: 'C09OLDONE', name: 'alerts', is_archived: true };

test('a channel id is the canonical form', () => {
  const [form] = referenceForm('C01ABCDE9');
  assert.equal(form, 'channel-id');
  assert.equal(pathOutcomes(form)[0], 'canonical');
});

test('a hash name is accepted by one family and refused by the rest', () => {
  const [form] = referenceForm('#alerts');
  assert.equal(form, 'hash-name');
  const [verdict, rows] = pathOutcomes(form);
  assert.equal(verdict, 'split-brain');
  const table = Object.fromEntries(rows);
  assert.equal(table['chat.postMessage'], 'accepts');
  assert.equal(table['conversations.history'], 'refuses');
});

test('a bare name lands in the same bucket as a hash name', () => {
  assert.equal(referenceForm('alerts')[0], 'bare-name');
  assert.equal(pathOutcomes('bare-name')[0], 'split-brain');
});

test('a user id is not a name problem because nothing errors', () => {
  const [form, detail] = referenceForm('U024BE7LH');
  assert.equal(form, 'user-id');
  assert.match(detail, /DM/);
  const [verdict, rows] = pathOutcomes(form);
  assert.equal(verdict, 'wrong-entity');
  assert.equal(Object.fromEntries(rows)['chat.postMessage'], 'delivers elsewhere');
});

test('a permalink carries the id it needs', () => {
  const [form, detail] = referenceForm('https://acme.slack.com/archives/C01ABCDE9');
  assert.equal(form, 'permalink');
  assert.match(detail, /C01ABCDE9/);
});

test('an empty string is reported as its own shape', () => {
  assert.equal(referenceForm('')[0], 'empty');
  assert.equal(referenceForm(null)[0], 'empty');
  assert.equal(pathOutcomes('empty')[0], 'unusable');
});

test('a name resolves to the live channel', () => {
  const [state, channel] = resolveName('#alerts', [LIVE]);
  assert.equal(state, 'resolved');
  assert.equal(channel.id, 'C01ABCDE9');
});

test('a name held by a live and an archived channel is reported as contested', () => {
  const [state, channel, detail] = resolveName('alerts', [DEAD, LIVE]);
  assert.equal(state, 'resolved-with-archived-twin');
  assert.equal(channel.id, 'C01ABCDE9');
  assert.match(detail, /contested/);
});

test('a name that only matches an archive is not a resolution', () => {
  assert.equal(resolveName('alerts', [DEAD])[0], 'archived-only');
});

test('two live channels with one name are never silently picked', () => {
  const twin = { ...LIVE, id: 'C07OTHER1' };
  const [state, channel] = resolveName('alerts', [LIVE, twin]);
  assert.equal(state, 'ambiguous');
  assert.equal(channel, null);
});

test('the repair line keeps the old name as a comment', () => {
  const line = configLine('ALERTS_CHANNEL', LIVE, '#alerts');
  assert.ok(line.startsWith('ALERTS_CHANNEL=C01ABCDE9'));
  assert.match(line, /#alerts/);
});