@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/marketplace/plugins/command-runner/src/server/detectors/python.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Python, and the one Compose source that shares its file shapes.
+ *
+ * ## Why `pyproject.toml` is read as a TABLE OF TABLES
+ *
+ * Python has no single task convention, so the file that holds them is a
+ * container: `[tool.poe.tasks]`, `[tool.pdm.scripts]`, `[tool.hatch.envs.*.scripts]`
+ * and `[tool.taskipy.tasks]` all declare runnable commands, and each names its own
+ * runner. Reading them is reading four declared sources, not guessing one — and
+ * each row's label says which runner it belongs to, so the four are told apart at
+ * a glance.
+ *
+ * `[project.scripts]` is deliberately NOT read: those are console-script ENTRY
+ * POINTS, installed into an environment, and running one requires the package to
+ * be installed first. A row that fails until you have done something else is
+ * worse than no row.
+ *
+ * ## `manage.py` is evidence, not a declaration
+ *
+ * A Django project's commands are knowable only by running `manage.py`, so the
+ * file's PRESENCE is what is read and the verbs are Django's own stable ones (see
+ * `standardVerbs`). The row's label says `python manage.py migrate`, which is
+ * exactly what runs.
+ *
+ * ## Compose services are the one place a NOUN becomes a row
+ *
+ * A service is not a command, but `docker compose up <svc>` and `logs -f <svc>`
+ * are the two things a reader actually does with one, and the service name is the
+ * only thing that varies. Two rows per service, not four: a list that offers every
+ * verb per service stops being scannable, and `build`/`restart` are one word away
+ * in the terminal.
+ */
+
+import { at, field, keys, cmd, standardVerbs, type Detector } from './types';
+import type { Command } from '../../protocol';
+
+/**
+ * The `pyproject.toml` tables that declare commands, with the runner each one's
+ * commands belong to.
+ *
+ * A flat table rather than a chain of `if`s: a fifth convention is a row.
+ */
+const PYPROJECT_TABLES: ReadonlyArray<{ path: readonly string[]; prefix: readonly string[] }> = [
+  { path: ['tool', 'poe', 'tasks'], prefix: ['poe'] },
+  { path: ['tool', 'pdm', 'scripts'], prefix: ['pdm', 'run'] },
+  { path: ['tool', 'taskipy', 'tasks'], prefix: ['task'] },
+];
+
+/** The Django verbs worth a row: stable, argument-free, and common. */
+const DJANGO_VERBS = [
+  'runserver',
+  'migrate',
+  'makemigrations',
+  'test',
+  'shell',
+  'collectstatic',
+  'createsuperuser',
+  'check',
+] as const;
+
+/** `pyproject.toml`: every declared task table, each with its own runner. */
+function parsePyproject(text: string): Command[] {
+  const parsed = Bun.TOML.parse(text) as unknown;
+  const out: Command[] = [];
+
+  for (const { path, prefix } of PYPROJECT_TABLES) {
+    for (const name of keys(at(parsed, path))) out.push(cmd(name, [...prefix, name]));
+  }
+
+  // `[tool.hatch.envs.<env>.scripts]` — the env is part of the invocation, and
+  // the default env needs no qualifier (`hatch run build`, not
+  // `hatch run default:build`).
+  const envs = at(parsed, ['tool', 'hatch', 'envs']);
+  for (const env of keys(envs)) {
+    for (const name of keys(field(envs, env) === undefined ? undefined : at(field(envs, env), ['scripts']))) {
+      out.push(
+        cmd(
+          env === 'default' ? name : `${env}:${name}`,
+          env === 'default' ? ['hatch', 'run', name] : ['hatch', 'run', `${env}:${name}`],
+        ),
+      );
+    }
+  }
+
+  return out;
+}
+
+/** `Pipfile` scripts: `[scripts]`, run by the pipenv that declares them. */
+function parsePipfile(text: string): Command[] {
+  const parsed = Bun.TOML.parse(text) as unknown;
+  return keys(at(parsed, ['scripts'])).map((name) => cmd(name, ['pipenv', 'run', name]));
+}
+
+/** A Django `manage.py`, whose verbs are Django's own. */
+function parseManage(): Command[] {
+  return standardVerbs(['python', 'manage.py'], DJANGO_VERBS);
+}
+
+/** Compose services: the two things a reader does with one. */
+function parseCompose(text: string): Command[] {
+  const services = field(Bun.YAML.parse(text), 'services');
+  const out: Command[] = [];
+  for (const name of keys(services)) {
+    out.push(cmd(`${name} up`, ['docker', 'compose', 'up', name]));
+    out.push(cmd(`${name} logs`, ['docker', 'compose', 'logs', '-f', name]));
+  }
+  return out;
+}
+
+export const PYTHON_DETECTORS: readonly Detector[] = [
+  { kind: 'python', filenames: ['pyproject.toml'], parse: parsePyproject },
+  { kind: 'pipenv', filenames: ['Pipfile'], parse: parsePipfile },
+  { kind: 'django', filenames: ['manage.py'], parse: parseManage },
+  {
+    kind: 'compose',
+    filenames: ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml'],
+    parse: parseCompose,
+  },
+];

package/marketplace/plugins/command-runner/src/server/detectors/table.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The detector table, assembled from one module per ecosystem family.
+ *
+ * ## Order is the order a walk reports groups in
+ *
+ * Grouped by FAMILY rather than alphabetically, because the families are what a
+ * reader scans for. `package.json` stays FIRST, where it has always been: in this
+ * ecosystem it is the source a reader looks for before any other, and a reorder
+ * would move every existing user's list for no gain. Within a family, a row's
+ * position is its priority for a shared basename — `package.json` before
+ * `deno.json` so the JS answer comes first in a repo that has both.
+ *
+ * ## Adding a source is adding a ROW, and that is now true
+ *
+ * It used to take three coordinated edits — the table, `labelFor`, and `argvFor`
+ * — which is exactly the shape where two of them drift and a row says `npm run
+ * dev` while running something else. The detector now owns its argv and its label
+ * is derived from it (`detectors/types.ts`), so a new source is one row here and
+ * nothing else.
+ */
+
+import type { Detector } from './types';
+import { JS_DETECTORS } from './js';
+import { MAKE_DETECTORS } from './make';
+import { PYTHON_DETECTORS } from './python';
+import { NATIVE_DETECTORS } from './native';
+
+export const DETECTORS: readonly Detector[] = [
+  ...JS_DETECTORS,
+  ...MAKE_DETECTORS,
+  ...PYTHON_DETECTORS,
+  ...NATIVE_DETECTORS,
+];
+
+/**
+ * The detector for a file, or null when no source claims it.
+ *
+ * `repoPath` is the file's path relative to the scanned root, with `/`
+ * separators, and it is what a `paths` row matches on. A row with no `paths` is
+ * matched on the BASENAME alone, which is the common case.
+ */
+export function detectorFor(filename: string, repoPath?: string): Detector | null {
+  for (const detector of DETECTORS) {
+    if (detector.filenames.includes(filename)) return detector;
+  }
+  if (repoPath) {
+    for (const detector of DETECTORS) {
+      if (detector.paths?.some((suffix) => repoPath.endsWith(suffix))) return detector;
+    }
+  }
+  return null;
+}
+
+/** Every filename any source claims, for the panel's "what was looked for" note. */
+export function claimedFilenames(): string[] {
+  return [...new Set(DETECTORS.flatMap((detector) => [...detector.filenames]))].sort();
+}

package/marketplace/plugins/command-runner/src/server/detectors/types.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * What a detector IS, the readers every parser shares, and the one helper that
+ * builds a command.
+ *
+ * ## The detector owns its argv, and the label is DERIVED from it
+ *
+ * A detector knows the tool its file belongs to, so it builds the argv; the label
+ * is `argv.join(' ')` and nothing else. That invariant is the point: the label is
+ * what the row shows and the argv is what runs, so two functions deriving them
+ * from the same `kind` can disagree — and a row that says `npm run dev` while
+ * running `bun run dev` is a lie the reader cannot see. There is now no way to
+ * state one without the other.
+ *
+ * ## Why `parse` takes a context
+ *
+ * Two sources need more than the file's text, and neither is a corner case:
+ *
+ * - **`go.mod`** lists no commands at all — the commands are the `cmd/<name>`
+ *   DIRECTORIES beside it, so the detector has to read the directory.
+ * - **`package.json`** needs the resolved package runner, which is decided by a
+ *   lockfile walk that only `scan.ts` can do.
+ *
+ * Both arrive through `DetectorContext` rather than by widening `parse`'s
+ * arguments one at a time, so a third need is a field rather than a signature
+ * change across every detector.
+ *
+ * ## The readers narrow, they never assert
+ *
+ * Every file this table reads is EXTERNAL data — a JSON, TOML or YAML document
+ * written by somebody else — so a shape is never asserted. `field`/`keys`/`at`
+ * are real runtime reads (`Reflect.get`, `Object.keys`) that answer `undefined`
+ * or `[]` for a shape that is not there, which is what makes a malformed file a
+ * short list rather than a crash.
+ */
+
+import type { Command, CommandKind } from '../../protocol';
+
+/** Everything a detector may read beyond the file's own text. */
+export interface DetectorContext {
+  /** Absolute path of the file being parsed. */
+  file: string;
+  /** The directory the file lives in. */
+  dir: string;
+  /**
+   * Entry names of an absolute directory, or `[]` when it cannot be read.
+   *
+   * Memoized by the caller: a detector that reads `cmd/` twice in one scan must
+   * not pay for two reads.
+   */
+  entries(dir: string): string[];
+  /** Only the DIRECTORIES of an absolute path, or `[]`. Memoized with `entries`. */
+  dirs(dir: string): string[];
+  /**
+   * The resolved package runner, for a detector that declares `needsRunner`.
+   *
+   * `undefined` for every other detector, so a runner that was never resolved
+   * cannot be mistaken for one that was.
+   */
+  runner?: string;
+}
+
+/** One row of the table: a command SOURCE. */
+export interface Detector {
+  kind: CommandKind;
+  /** The filenames this source uses, matched on the BASENAME. */
+  filenames: readonly string[];
+  /**
+   * Paths matched as a SUFFIX of the file's repo-relative path, for a file whose
+   * basename is not distinctive.
+   *
+   * `.cargo/config.toml` is the case this exists for: `config.toml` is a very
+   * common name, and matching it on the basename alone would claim an unrelated
+   * file in every project that happens to have one.
+   */
+  paths?: readonly string[];
+  /**
+   * This source's commands run through the resolved package runner.
+   *
+   * A FLAG rather than a `kind === 'package'` test at the call site: the runner
+   * walk lives in `scan.ts` and would otherwise have to know which kinds want it,
+   * which is the same branch-in-two-places problem the table exists to remove.
+   */
+  needsRunner?: boolean;
+  /**
+   * Read the file into commands.
+   *
+   * Throws for a file that cannot be read as its own format — `scan.ts` turns
+   * that into the group's `error`, because "no commands" and "this file would not
+   * parse" are different answers and a user can only act on the second.
+   */
+  parse(text: string, ctx: DetectorContext): Command[];
+}
+
+/** Read one property of an unknown value, or `undefined`. */
+export function field(value: unknown, key: string): unknown {
+  return typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined;
+}
+
+/** The keys of an unknown object, or `[]` when it is not one. */
+export function keys(value: unknown): string[] {
+  return typeof value === 'object' && value !== null ? Object.keys(value) : [];
+}
+
+/** Follow a path of properties, answering `undefined` at the first gap. */
+export function at(value: unknown, path: readonly string[]): unknown {
+  let node: unknown = value;
+  for (const key of path) {
+    node = field(node, key);
+    if (node === undefined) return undefined;
+  }
+  return node;
+}
+
+/**
+ * One command, with its label derived from its argv.
+ *
+ * `name` is what the command is CALLED in its own source (`dev`, `build`, `web`,
+ * `py311`) — it is the id's tail and the row's identity, and it is deliberately
+ * not always the last argv element (`cargo run --bin foo` runs `foo`).
+ */
+export function cmd(name: string, argv: string[]): Command {
+  return { id: '', name, label: argv.join(' '), argv };
+}
+
+/**
+ * The standard verbs of a toolchain whose command list is only knowable at
+ * runtime.
+ *
+ * `Cargo.toml`, `go.mod`, `artisan` and `manage.py` are all files that PROVE a
+ * toolchain is present while declaring no runnable commands of their own — cargo
+ * and go have no task file, and `artisan`/`manage.py` answer their command list
+ * only when executed. Listing their stable, universal verbs is the useful answer
+ * and the honest one, as long as it is stated: these are the tool's OWN verbs,
+ * not something discovered in the file, and the row's label says exactly what
+ * will run.
+ *
+ * Kept deliberately short. A verb that is not near-universal does not belong
+ * here — a curated list that is wrong is worse than a short one.
+ */
+export function standardVerbs(prefix: readonly string[], verbs: readonly string[]): Command[] {
+  return verbs.map((verb) => cmd(verb, [...prefix, verb]));
+}

package/marketplace/plugins/command-runner/src/server/discovery.test.ts

@@ -0,0 +1,344 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The parsers and the package-manager walk.
+ *
+ * Every case here is a shape that appears in a real file and breaks a naive
+ * implementation, so each test names the shape rather than the regex:
+ *
+ * - a `Makefile` with `.PHONY` (a dot-target is not a command) and with a
+ *   variable assignment CONTAINING a colon (`SRC := a:b`), which a bare
+ *   `^(\w+):` rule lists as a command named `SRC`;
+ * - a pattern rule (`%.o: %.c`), which is a rule rather than something to run;
+ * - a `justfile` with `set shell := …` (an assignment) and `[attributes]`;
+ * - a `package.json` whose `scripts` is absent (a valid file with no commands).
+ *
+ * The runner walk is tested through real directories, because the ORDER of its
+ * three sources is the decision — a declared `packageManager` beats a lockfile,
+ * and the nearest lockfile beats Bun.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { DETECTORS, claimedFilenames, detectorFor } from '../../src/server/detectors/table';
+import type { DetectorContext } from '../../src/server/detectors/types';
+import type { CommandKind } from '../../src/protocol';
+import { runnerForLockfile, runnerForPackageManager } from '../../src/server/package-manager';
+import { resolveRunner, resolveScope, scanScope } from '../../src/server/scan';
+
+describe('runnerForPackageManager', () => {
+  test('reads the name out of a name@version field', () => {
+    expect(runnerForPackageManager('bun@1.4.2')).toBe('bun');
+    expect(runnerForPackageManager('pnpm@9')).toBe('pnpm');
+  });
+
+  test('accepts a bare name', () => {
+    expect(runnerForPackageManager('yarn')).toBe('yarn');
+  });
+
+  test('refuses what it does not know, so the lockfile decides', () => {
+    expect(runnerForPackageManager('corepack@1')).toBeNull();
+    expect(runnerForPackageManager(42)).toBeNull();
+    expect(runnerForPackageManager(undefined)).toBeNull();
+  });
+});
+
+describe('runnerForLockfile', () => {
+  test('maps each lockfile', () => {
+    expect(runnerForLockfile('bun.lock')).toBe('bun');
+    expect(runnerForLockfile('bun.lockb')).toBe('bun');
+    expect(runnerForLockfile('package-lock.json')).toBe('npm');
+    expect(runnerForLockfile('npm-shrinkwrap.json')).toBe('npm');
+    expect(runnerForLockfile('yarn.lock')).toBe('yarn');
+    expect(runnerForLockfile('pnpm-lock.yaml')).toBe('pnpm');
+  });
+
+  test('maps nothing else', () => {
+    expect(runnerForLockfile('bun.lockb.bak')).toBeNull();
+    expect(runnerForLockfile('Cargo.lock')).toBeNull();
+  });
+});
+
+describe('resolveScope', () => {
+  let root = '';
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), 'cr-scope-'));
+    mkdirSync(join(root, 'packages', 'api'), { recursive: true });
+  });
+
+  afterAll(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test('resolves the root itself', () => {
+    expect(resolveScope({ root, repo: '.' })).toBe(root);
+  });
+
+  test('resolves a nested repo', () => {
+    expect(resolveScope({ root, repo: 'packages/api' })).toBe(join(root, 'packages', 'api'));
+  });
+
+  test('refuses a repo that escapes the root', () => {
+    // The check that stops `repo: '../../etc'`.
+    expect(resolveScope({ root, repo: '../../etc' })).toBeNull();
+    expect(resolveScope({ root, repo: 'packages/../../../etc' })).toBeNull();
+  });
+
+  test('refuses a relative root, which would resolve against the server cwd', () => {
+    expect(resolveScope({ root: 'relative/path', repo: '.' })).toBeNull();
+    expect(resolveScope({ root: '', repo: '.' })).toBeNull();
+  });
+
+  test('refuses a path that does not exist, or is a file', () => {
+    expect(resolveScope({ root, repo: 'nope' })).toBeNull();
+    writeFileSync(join(root, 'a-file.txt'), 'x');
+    expect(resolveScope({ root, repo: 'a-file.txt' })).toBeNull();
+  });
+});
+
+describe('resolveRunner', () => {
+  let root = '';
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), 'cr-runner-'));
+    mkdirSync(join(root, 'packages', 'api'), { recursive: true });
+  });
+
+  afterAll(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test('a declared packageManager beats a lockfile', () => {
+    writeFileSync(join(root, 'bun.lock'), '');
+    const file = join(root, 'packages', 'api', 'package.json');
+    expect(resolveRunner(root, file, '{"packageManager":"pnpm@9"}')).toBe('pnpm');
+  });
+
+  test('the nearest lockfile decides, walking up', () => {
+    // No declared field: the root's `bun.lock` is the only one in the tree.
+    const file = join(root, 'packages', 'api', 'package.json');
+    expect(resolveRunner(root, file, '{}')).toBe('bun');
+  });
+
+  test('a nested lockfile beats the one above it', () => {
+    writeFileSync(join(root, 'packages', 'api', 'package-lock.json'), '');
+    const file = join(root, 'packages', 'api', 'package.json');
+    expect(resolveRunner(root, file, '{}')).toBe('npm');
+  });
+
+  test('no lockfile at all falls back to bun', () => {
+    const bare = mkdtempSync(join(tmpdir(), 'cr-bare-'));
+    expect(resolveRunner(bare, join(bare, 'package.json'), '{}')).toBe('bun');
+    rmSync(bare, { recursive: true, force: true });
+  });
+
+  test('an unparseable package.json falls through to the lockfile walk', () => {
+    const file = join(root, 'packages', 'api', 'package.json');
+    expect(resolveRunner(root, file, '{ not json')).toBe('npm');
+  });
+});
+
+describe('scanScope', () => {
+  let root = '';
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), 'cr-scan-'));
+    writeFileSync(join(root, 'package.json'), JSON.stringify({ scripts: { dev: 'x' }, packageManager: 'bun@1.4.2' }));
+    writeFileSync(join(root, 'Makefile'), '.PHONY: build\nbuild:\n\techo');
+    writeFileSync(join(root, 'justfile'), 'lint:\n  echo');
+    // A nested package with its own lockfile, and a node_modules that must NOT
+    // be walked into.
+    mkdirSync(join(root, 'packages', 'web'), { recursive: true });
+    writeFileSync(join(root, 'packages', 'web', 'package.json'), JSON.stringify({ scripts: { build: 'y' } }));
+    writeFileSync(join(root, 'packages', 'web', 'package-lock.json'), '{}');
+    mkdirSync(join(root, 'node_modules', 'dep'), { recursive: true });
+    writeFileSync(join(root, 'node_modules', 'dep', 'package.json'), JSON.stringify({ scripts: { evil: 'z' } }));
+  });
+
+  afterAll(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test('groups by file, one group per command file, in a stable order', () => {
+    const listing = scanScope({ root, repo: '.' });
+    if ('error' in listing) throw new Error(listing.error);
+    expect(listing.groups.map((group) => group.file)).toEqual(['package.json', 'packages/web/package.json', 'Makefile', 'justfile']);
+  });
+
+  test('the node_modules copy is never listed', () => {
+    const listing = scanScope({ root, repo: '.' });
+    if ('error' in listing) throw new Error(listing.error);
+    // The measured failure this pins: Bun.Glob's `ignore` does not exclude it.
+    expect(listing.groups.some((group) => group.file.includes('node_modules'))).toBe(false);
+  });
+
+  test('a command id names its file, kind and name — never a command line', () => {
+    const listing = scanScope({ root, repo: '.' });
+    if ('error' in listing) throw new Error(listing.error);
+    const rootPkg = listing.groups.find((group) => group.file === 'package.json')!;
+    expect(rootPkg.commands[0].id).toBe('package.json#package:dev');
+    expect(rootPkg.runner).toBe('bun');
+    expect(rootPkg.commands[0].label).toBe('bun run dev');
+  });
+
+  test('each package group gets its own runner, from its own lockfile', () => {
+    const listing = scanScope({ root, repo: '.' });
+    if ('error' in listing) throw new Error(listing.error);
+    const web = listing.groups.find((group) => group.file === 'packages/web/package.json')!;
+    expect(web.runner).toBe('npm');
+    expect(web.commands[0].label).toBe('npm run build');
+  });
+
+  test('the cwd is the command file\'s own directory, relative to the scope', () => {
+    const listing = scanScope({ root, repo: '.' });
+    if ('error' in listing) throw new Error(listing.error);
+    // What makes `make build` in `packages/api` a different command from the one
+    // at the root, and what lets a script's relative path resolve.
+    expect(listing.groups.find((group) => group.file === 'Makefile')!.cwd).toBe('.');
+    expect(listing.groups.find((group) => group.file === 'packages/web/package.json')!.cwd).toBe('packages/web');
+  });
+
+  test('a scope that escapes the root is refused, not scanned', () => {
+    const listing = scanScope({ root, repo: '../../etc' });
+    expect('error' in listing).toBe(true);
+  });
+
+  test('a nested repo is scanned on its own', () => {
+    const listing = scanScope({ root, repo: 'packages/web' });
+    if ('error' in listing) throw new Error(listing.error);
+    expect(listing.groups.map((group) => group.file)).toEqual(['package.json']);
+    expect(listing.groups[0].cwd).toBe('.');
+  });
+});
+
+describe('the detector table', () => {
+  test('every detector states an argv, and its label is that argv joined', () => {
+    // The invariant the table exists for: the label is what the row SHOWS and the
+    // argv is what RUNS, so they cannot be two answers. A detector that built a
+    // label of its own could say `npm run dev` while running `bun run dev`.
+    //
+    // Each detector is fed a MINIMAL VALID file, and a detector with no sample
+    // fails by name — a new source has to add one, which is also what stops a
+    // sample from silently covering nothing.
+    for (const detector of DETECTORS) {
+      const key = detector.filenames[0] ?? detector.paths?.[0] ?? detector.kind;
+      const sample = SAMPLES[key];
+      expect(sample, `no sample for ${key}`).toBeDefined();
+      const commands = detector.parse(sample!, stubContext());
+      // A detector that lists nothing from its own sample proves nothing about
+      // the invariant, so an empty answer is a failure too.
+      expect(commands.length, `${key} listed nothing`).toBeGreaterThan(0);
+      for (const command of commands) {
+        expect(command.label).toBe(command.argv.join(' '));
+        expect(command.argv.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  test('no filename is claimed by two detectors', () => {
+    // Two claims would make the walk's answer depend on table order, which is a
+    // silent change the next time a row moves.
+    const seen = new Map<string, string>();
+    for (const detector of DETECTORS) {
+      for (const filename of detector.filenames) {
+        expect(seen.has(filename)).toBe(false);
+        seen.set(filename, detector.kind);
+      }
+    }
+  });
+
+  test('claims the sources it says it does', () => {
+    const cases: Array<[string, CommandKind]> = [
+      ['package.json', 'package'],
+      ['Makefile', 'make'],
+      ['GNUmakefile', 'make'],
+      ['justfile', 'just'],
+      ['Taskfile.yml', 'task'],
+      ['deno.jsonc', 'deno'],
+      ['pyproject.toml', 'python'],
+      ['Pipfile', 'pipenv'],
+      ['manage.py', 'django'],
+      ['compose.yml', 'compose'],
+      ['go.mod', 'go'],
+      ['Cargo.toml', 'rust'],
+      ['composer.json', 'php'],
+      ['artisan', 'php'],
+      ['build.gradle', 'java'],
+      ['build.gradle.kts', 'java'],
+      ['pom.xml', 'java'],
+      ['mix.exs', 'elixir'],
+    ];
+    for (const [filename, kind] of cases) expect(detectorFor(filename)?.kind).toBe(kind);
+  });
+
+  test('a SUFFIX path is claimed, and its bare basename is not', () => {
+    // `.cargo/config.toml` is the reason `paths` exists: `config.toml` alone is
+    // far too common a name to claim, so the basename must resolve to nothing and
+    // the repo-relative path must resolve to the Rust config.
+    expect(detectorFor('config.toml')).toBeNull();
+    expect(detectorFor('config.toml', '.cargo/config.toml')?.kind).toBe('rust');
+    // And a `config.toml` somewhere unrelated is still unclaimed.
+    expect(detectorFor('config.toml', 'app/config.toml')).toBeNull();
+  });
+
+  test('claims nothing else', () => {
+    expect(detectorFor('package.json.bak')).toBeNull();
+    expect(detectorFor('Makefile.am')).toBeNull();
+    expect(detectorFor('README.md')).toBeNull();
+    expect(detectorFor('go.sum')).toBeNull();
+    expect(detectorFor('Cargo.lock')).toBeNull();
+  });
+
+  test('reports every claimed filename, for the panel\'s own note', () => {
+    const names = claimedFilenames();
+    expect(names).toContain('package.json');
+    expect(names).toContain('go.mod');
+    // Sorted and unique, so the note is stable between reads.
+    expect([...names].sort()).toEqual(names);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});
+
+/**
+ * A minimal VALID file per source, keyed by its first filename.
+ *
+ * Keyed that way because a kind is not unique — `php` covers `composer.json` and
+ * `artisan`, `java` covers Gradle and Maven — while a first filename is, and the
+ * test above asserts that no filename is claimed twice.
+ */
+const SAMPLES: Record<string, string> = {
+  'package.json': '{"scripts":{"dev":"x"}}',
+  'deno.jsonc': '{"tasks":{"build":"x"}}',
+  Makefile: 'build:\n\techo',
+  justfile: 'build:\n  echo',
+  'Taskfile.yml': 'tasks:\n  build:\n    cmds: [x]',
+  'pyproject.toml': '[tool.poe.tasks]\nbuild = "x"',
+  Pipfile: '[scripts]\nbuild = "x"',
+  'manage.py': '',
+  'docker-compose.yml': 'services:\n  web:\n    image: x',
+  'go.mod': 'module example.com/app',
+  'Cargo.toml': '[package]\nname = "app"',
+  '.cargo/config.toml': '[alias]\nb = "build"',
+  'composer.json': '{"scripts":{"test":"x"}}',
+  artisan: '',
+  'build.gradle': 'plugins {}',
+  'pom.xml': '<project/>',
+  'mix.exs': 'defp aliases do\n  setup: ["deps.get"]\nend',
+};
+
+/**
+ * A context whose directory reads answer one directory, `app`.
+ *
+ * Non-empty because `go.mod` finds its commands in `cmd/<name>` and would
+ * otherwise list nothing — which the invariant test treats as a failure.
+ */
+function stubContext(): DetectorContext {
+  return { file: '', dir: '', entries: () => ['app'], dirs: () => ['app'] };
+}