@capybara-hq/plugin-tools 0.0.0-stage → 0.1.0-rc.0

package/dist/check/release-metadata.d.ts

@@ -0,0 +1,13 @@
+import type { Finding } from "./source.js";
+/**
+ * Release metadata of the plugins a repository publishes (`plugin-release-metadata`): a plugin that
+ * would be published (not `"private": true`) needs a `description`, a `license`, an https `homepage`
+ * and `"repository": { "type": "git", "url", "directory": <its dir relative to root> }`, where `url`
+ * is the root package.json's `repository.url` (npm provenance rejects a publish whose repository
+ * does not match the repository that built it; core's plugins name `capybara-hq/core.git`, the
+ * plugins repository's `capybara-hq/plugins.git`). A plugin that is the repository root itself
+ * has no `directory`. The `example-*` plugins must be private. The plugin tgz carries these fields
+ * (`METADATA_FIELDS` of the packer); the libraries' half of the rule is core's
+ * `check:release-metadata`.
+ */
+export declare function checkPluginReleaseMetadata(plugins: string[], root: string): Finding[];

package/dist/check/release-metadata.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+const RULE = "plugin-release-metadata";
+const readJson = (file) => JSON.parse(readFileSync(file, "utf8"));
+/** `repository.url` of a package.json (`"repository": "<url>"` or `{ url }`). */
+function repositoryUrl(pkg) {
+    const r = pkg.repository;
+    if (typeof r === "string")
+        return r;
+    if (typeof r === "object" && r !== null && typeof r.url === "string") {
+        return r.url;
+    }
+    return undefined;
+}
+/**
+ * Release metadata of the plugins a repository publishes (`plugin-release-metadata`): a plugin that
+ * would be published (not `"private": true`) needs a `description`, a `license`, an https `homepage`
+ * and `"repository": { "type": "git", "url", "directory": <its dir relative to root> }`, where `url`
+ * is the root package.json's `repository.url` (npm provenance rejects a publish whose repository
+ * does not match the repository that built it; core's plugins name `capybara-hq/core.git`, the
+ * plugins repository's `capybara-hq/plugins.git`). A plugin that is the repository root itself
+ * has no `directory`. The `example-*` plugins must be private. The plugin tgz carries these fields
+ * (`METADATA_FIELDS` of the packer); the libraries' half of the rule is core's
+ * `check:release-metadata`.
+ */
+export function checkPluginReleaseMetadata(plugins, root) {
+    const out = [];
+    const rootFile = join(root, "package.json");
+    const url = existsSync(rootFile) ? repositoryUrl(readJson(rootFile)) : undefined;
+    let rootReported = false;
+    for (const dir of plugins) {
+        const file = join(dir, "package.json");
+        if (!existsSync(file))
+            continue;
+        const pkg = readJson(file);
+        if (pkg.private === true)
+            continue;
+        const rel = relative(root, dir).split("\\").join("/");
+        const label = rel === "" ? String(pkg.name ?? basename(dir)) : rel;
+        const finding = (message) => out.push({ file, line: 1, rule: RULE, message });
+        if (basename(dir).startsWith("example-")) {
+            finding(`${label} must not be published: add "private": true (example plugins stay off npm)`);
+            continue;
+        }
+        if (typeof pkg.description !== "string" || pkg.description.trim() === "") {
+            finding(`${label} is published and needs a "description"`);
+        }
+        if (typeof pkg.license !== "string")
+            finding(`${label} is published and needs a "license"`);
+        if (typeof pkg.homepage !== "string" || !pkg.homepage.startsWith("https://")) {
+            finding(`${label} is published and needs an https "homepage"`);
+        }
+        if (url === undefined) {
+            if (!rootReported) {
+                rootReported = true;
+                out.push({
+                    file: rootFile,
+                    line: 1,
+                    rule: RULE,
+                    message: 'the repository root package.json needs "repository": { "type": "git", "url": … }: ' +
+                        "every published plugin's repository.url must equal it (npm provenance)",
+                });
+            }
+            continue;
+        }
+        const repo = pkg.repository;
+        const ok = typeof repo === "object" &&
+            repo !== null &&
+            repo.type === "git" &&
+            repo.url === url &&
+            (rel === "" ? repo.directory === undefined : repo.directory === rel);
+        if (!ok) {
+            const want = rel === ""
+                ? `{ "type": "git", "url": "${url}" }`
+                : `{ "type": "git", "url": "${url}", "directory": "${rel}" }`;
+            finding(`${label} is published and needs "repository": ${want} (the root package.json's repository; npm provenance requires it)`);
+        }
+    }
+    return out;
+}

package/dist/check/report.d.ts

@@ -0,0 +1,8 @@
+import type { Finding } from "./source.js";
+/** One finding as a line: `<file relative to root>:<line> <rule> <message>`. */
+export declare const formatFinding: (f: Finding, root: string) => string;
+/**
+ * Prints the result of one check: `[name] passed`, or the finding count and one line per finding
+ * (stderr). Returns whether it passed.
+ */
+export declare function printCheck(name: string, findings: Finding[], root: string): boolean;

package/dist/check/report.js

@@ -0,0 +1,17 @@
+import { relative } from "node:path";
+/** One finding as a line: `<file relative to root>:<line> <rule> <message>`. */
+export const formatFinding = (f, root) => `${relative(root, f.file) || f.file}:${f.line} ${f.rule} ${f.message}`;
+/**
+ * Prints the result of one check: `[name] passed`, or the finding count and one line per finding
+ * (stderr). Returns whether it passed.
+ */
+export function printCheck(name, findings, root) {
+    if (findings.length === 0) {
+        console.log(`[${name}] passed`);
+        return true;
+    }
+    console.error(`[${name}] ${findings.length} finding(s)`);
+    for (const f of findings)
+        console.error(`  ${formatFinding(f, root)}`);
+    return false;
+}

package/dist/check/run.d.ts

@@ -0,0 +1,36 @@
+import type { Finding } from "./source.js";
+/** What the plugin-scoped checks scan. */
+export interface PluginCheckScope {
+    /**
+     * The repository root: its package.json's `repository.url` is the one every published plugin
+     * must name (release metadata).
+     */
+    root: string;
+    /**
+     * Plugin directories: every check runs on each (dependency boundary, extension state,
+     * permissions, pack, tool design, test imports, release metadata, and the migrations in
+     * `<plugin>/migrations`).
+     */
+    plugins: string[];
+    /** Package directories held to the SDK's boundary (core: `packages/plugin-sdk`). */
+    sdkDirs?: string[];
+    /** More directories the tool design rules scan (core: the kernel's builtin tools). */
+    toolDesignDirs?: string[];
+    /** More migration directories (core: the kernel's migrations). */
+    migrationDirs?: string[];
+}
+/** A named check: `run` returns its findings. */
+export interface NamedCheck {
+    name: string;
+    run: () => Finding[] | Promise<Finding[]>;
+}
+/**
+ * Every plugin-scoped check over `scope`, in the order `capybara-plugin check` and core's `pnpm
+ * check` run them. `checkAppliedMigrations` is not here: it needs a diff base (PR only).
+ */
+export declare function pluginChecks(scope: PluginCheckScope): NamedCheck[];
+/**
+ * Runs `checks` in order and prints each result ({@link printCheck}, paths relative to `root`); a
+ * check that throws counts as failed. Returns the number of failed checks.
+ */
+export declare function runChecks(checks: NamedCheck[], root: string): Promise<number>;

package/dist/check/run.js

@@ -0,0 +1,60 @@
+import { join } from "node:path";
+import { checkDeps } from "./deps.js";
+import { checkMigrations } from "./migrations.js";
+import { checkPluginPack } from "./plugin-pack.js";
+import { checkPluginPermissions } from "./plugin-permissions.js";
+import { checkPluginState } from "./plugin-state.js";
+import { checkPluginReleaseMetadata } from "./release-metadata.js";
+import { printCheck } from "./report.js";
+import { checkPluginTestImports } from "./test-imports.js";
+import { checkToolDesign } from "./tool-design.js";
+/**
+ * Every plugin-scoped check over `scope`, in the order `capybara-plugin check` and core's `pnpm
+ * check` run them. `checkAppliedMigrations` is not here: it needs a diff base (PR only).
+ */
+export function pluginChecks(scope) {
+    const { plugins } = scope;
+    return [
+        {
+            name: "Migrations",
+            run: () => checkMigrations([
+                ...(scope.migrationDirs ?? []),
+                ...plugins.map((p) => join(p, "migrations")),
+            ]),
+        },
+        { name: "Dependency boundary", run: () => checkDeps(plugins, scope.sdkDirs ?? []) },
+        { name: "Extension state", run: () => checkPluginState(plugins) },
+        { name: "Extension permissions", run: () => checkPluginPermissions(plugins) },
+        { name: "Plugin pack", run: () => checkPluginPack(plugins) },
+        {
+            name: "Tool design",
+            run: () => checkToolDesign([...(scope.toolDesignDirs ?? []), ...plugins]),
+        },
+        { name: "Plugin test imports", run: () => checkPluginTestImports(plugins) },
+        {
+            name: "Plugin release metadata",
+            run: () => checkPluginReleaseMetadata(plugins, scope.root),
+        },
+    ];
+}
+/**
+ * Runs `checks` in order and prints each result ({@link printCheck}, paths relative to `root`); a
+ * check that throws counts as failed. Returns the number of failed checks.
+ */
+export async function runChecks(checks, root) {
+    let failed = 0;
+    for (const c of checks) {
+        let findings;
+        try {
+            findings = await c.run();
+        }
+        catch (e) {
+            console.error(`[${c.name}] check crashed: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`);
+            failed++;
+            continue;
+        }
+        if (!printCheck(c.name, findings, root))
+            failed++;
+    }
+    return failed;
+}

package/dist/check/source.d.ts

@@ -0,0 +1,53 @@
+import { type Comment } from "oxc-parser";
+export type Finding = {
+    file: string;
+    line: number;
+    rule: string;
+    message: string;
+};
+/** ESTree 节点（oxc-parser 的输出）。只声明本检查用到的公共字段。 */
+export interface Node {
+    type: string;
+    start: number;
+    end: number;
+    [key: string]: unknown;
+}
+export interface SourceFile {
+    file: string;
+    /** 测试文件：插件根的 test/ 目录下的文件，或 *.test.* / *.spec.* 文件。 */
+    isTest: boolean;
+}
+/**
+ * 递归列出目录下的源码文件。node_modules 与 packer 的临时目录 `.capybara-pack-*` 在任何深度都跳过；
+ * dist 只在根目录跳过（构建产物），
+ * test / tests / __tests__ 目录只在根目录算测试（标 isTest），更深处同名目录照常当源码扫描，
+ * 否则 `src/test/impl.ts` 再 re-export 就能绕过全部检查。结果有序。
+ */
+export declare function listSourceFiles(dir: string): SourceFile[];
+export interface ParsedFile {
+    file: string;
+    source: string;
+    program: Node;
+    comments: Comment[];
+    /** 偏移量 -> 1 基行号。 */
+    lineOf(offset: number): number;
+    /** 取 1 基行号的原文。 */
+    lineText(line: number): string;
+}
+/** 解析一个文件；语法错误时返回 Finding（rule: parse-error），检查不能因解析失败而静默放过。 */
+export declare function parseFile(file: string): ParsedFile | Finding;
+/** 判断 parseFile 的结果是不是解析失败。 */
+export declare function isParseError(x: ParsedFile | Finding): x is Finding;
+/** 深度优先遍历 AST；visit 收到节点、父节点与它在父节点上的属性名。 */
+export declare function walk(node: unknown, visit: (n: Node, parent: Node | null, key: string) => void, parent?: Node | null, key?: string): void;
+/** 取字符串字面量、无插值模板字符串、或它们的 `+` 拼接的值；其他表达式返回 undefined。 */
+export declare function stringValue(n: unknown): string | undefined;
+export interface ImportRef {
+    spec: string;
+    start: number;
+}
+/**
+ * 收集文件里所有模块引用：import / export … from / export * / import type / 动态 import() /
+ * require() / import x = require() / import("x") 类型。非字面量的动态 import 无法静态判定，被忽略。
+ */
+export declare function collectImports(program: Node): ImportRef[];

package/dist/check/source.js

@@ -0,0 +1,153 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseSync } from "oxc-parser";
+const SOURCE_EXT = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/** 只在插件根目录下才有特殊含义的目录名（更深处同名目录是普通源码目录，必须扫描）。 */
+const ROOT_TEST_DIRS = new Set(["test", "tests", "__tests__"]);
+/**
+ * 递归列出目录下的源码文件。node_modules 与 packer 的临时目录 `.capybara-pack-*` 在任何深度都跳过；
+ * dist 只在根目录跳过（构建产物），
+ * test / tests / __tests__ 目录只在根目录算测试（标 isTest），更深处同名目录照常当源码扫描，
+ * 否则 `src/test/impl.ts` 再 re-export 就能绕过全部检查。结果有序。
+ */
+export function listSourceFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    const visit = (d, depth, inTestRoot) => {
+        for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const p = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === "node_modules")
+                    continue;
+                // packer 的临时目录（旧版本建在插件目录里，崩溃后可能残留）：里面是打包产物，不是插件源码
+                if (e.name.startsWith(".capybara-pack-"))
+                    continue;
+                if (depth === 0 && e.name === "dist")
+                    continue;
+                visit(p, depth + 1, inTestRoot || (depth === 0 && ROOT_TEST_DIRS.has(e.name)));
+            }
+            else if (e.isFile() && SOURCE_EXT.test(e.name)) {
+                out.push({ file: p, isTest: inTestRoot || TEST_FILE.test(e.name) });
+            }
+        }
+    };
+    visit(dir, 0, false);
+    return out;
+}
+/** 解析一个文件；语法错误时返回 Finding（rule: parse-error），检查不能因解析失败而静默放过。 */
+export function parseFile(file) {
+    const source = readFileSync(file, "utf8");
+    const result = parseSync(file, source);
+    const first = result.errors[0];
+    const starts = [0];
+    for (let i = 0; i < source.length; i++)
+        if (source[i] === "\n")
+            starts.push(i + 1);
+    const lineOf = (offset) => {
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (starts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo + 1;
+    };
+    const lines = source.split("\n");
+    if (first) {
+        const label = first.labels?.[0];
+        return {
+            file,
+            line: label ? lineOf(label.start) : 1,
+            rule: "parse-error",
+            message: `无法解析，检查无法进行：${first.message}`,
+        };
+    }
+    return {
+        file,
+        source,
+        program: result.program,
+        comments: result.comments,
+        lineOf,
+        lineText: (n) => lines[n - 1] ?? "",
+    };
+}
+/** 判断 parseFile 的结果是不是解析失败。 */
+export function isParseError(x) {
+    return "rule" in x;
+}
+const isNode = (v) => typeof v === "object" && v !== null && typeof v.type === "string";
+/** 深度优先遍历 AST；visit 收到节点、父节点与它在父节点上的属性名。 */
+export function walk(node, visit, parent = null, key = "") {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walk(item, visit, parent, key);
+        return;
+    }
+    if (!isNode(node))
+        return;
+    visit(node, parent, key);
+    for (const [k, v] of Object.entries(node)) {
+        if (k === "type" || k === "start" || k === "end")
+            continue;
+        if (typeof v === "object" && v !== null)
+            walk(v, visit, node, k);
+    }
+}
+/** 取字符串字面量、无插值模板字符串、或它们的 `+` 拼接的值；其他表达式返回 undefined。 */
+export function stringValue(n) {
+    if (!isNode(n))
+        return undefined;
+    if (n.type === "BinaryExpression" && n.operator === "+") {
+        const l = stringValue(n.left);
+        const r = stringValue(n.right);
+        return l !== undefined && r !== undefined ? l + r : undefined;
+    }
+    if (n.type === "Literal" && typeof n.value === "string")
+        return n.value;
+    if (n.type === "TemplateLiteral") {
+        const quasis = n.quasis;
+        const exprs = n.expressions;
+        if (exprs.length === 0 && quasis.length === 1)
+            return quasis[0]?.value.cooked ?? undefined;
+    }
+    return undefined;
+}
+/**
+ * 收集文件里所有模块引用：import / export … from / export * / import type / 动态 import() /
+ * require() / import x = require() / import("x") 类型。非字面量的动态 import 无法静态判定，被忽略。
+ */
+export function collectImports(program) {
+    const out = [];
+    const add = (n, at) => {
+        const spec = stringValue(n);
+        if (spec !== undefined)
+            out.push({ spec, start: at.start });
+    };
+    walk(program, (n) => {
+        switch (n.type) {
+            case "ImportDeclaration":
+            case "ExportNamedDeclaration":
+            case "ExportAllDeclaration":
+            case "ImportExpression":
+            case "TSImportType":
+                add(n.source, n);
+                break;
+            case "TSExternalModuleReference":
+                add(n.expression, n);
+                break;
+            case "CallExpression": {
+                const callee = n.callee;
+                const args = n.arguments;
+                if (callee.type === "Identifier" && callee.name === "require")
+                    add(args[0], n);
+                break;
+            }
+        }
+    });
+    return out;
+}

package/dist/check/sync-versions-cli.d.ts

@@ -0,0 +1,10 @@
+export declare const SYNC_VERSIONS_USAGE = "capybara-plugin sync-versions [--root <dir>] [--plugins <glob>]";
+/**
+ * `capybara-plugin sync-versions`: copies each plugin's `package.json` version into its
+ * `.capybara-plugin/plugin.json` and its extension manifest (`src/index.ts`, `  version: "x"`),
+ * which the packer requires equal. Run it right after `changeset version` (which bumps only
+ * `package.json`), before anything packs. Plugins are found as by `check` (`<root>/plugins/*`,
+ * `--plugins <glob>`, or the root itself). Relative paths resolve against `cwd`. Returns the exit
+ * code.
+ */
+export declare function syncVersionsCommand(args: string[], cwd: string): Promise<number>;

package/dist/check/sync-versions-cli.js

@@ -0,0 +1,44 @@
+import { relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { discoverPlugins } from "../discover.js";
+import { syncPluginVersions } from "./plugin-versions.js";
+export const SYNC_VERSIONS_USAGE = "capybara-plugin sync-versions [--root <dir>] [--plugins <glob>]";
+/**
+ * `capybara-plugin sync-versions`: copies each plugin's `package.json` version into its
+ * `.capybara-plugin/plugin.json` and its extension manifest (`src/index.ts`, `  version: "x"`),
+ * which the packer requires equal. Run it right after `changeset version` (which bumps only
+ * `package.json`), before anything packs. Plugins are found as by `check` (`<root>/plugins/*`,
+ * `--plugins <glob>`, or the root itself). Relative paths resolve against `cwd`. Returns the exit
+ * code.
+ */
+export async function syncVersionsCommand(args, cwd) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            help: { type: "boolean", short: "h", default: false },
+            root: { type: "string" },
+            plugins: { type: "string" },
+        },
+    });
+    if (values.help) {
+        console.log(`usage: ${SYNC_VERSIONS_USAGE}`);
+        return 0;
+    }
+    const root = resolve(cwd, values.root ?? ".");
+    try {
+        const plugins = discoverPlugins(root, values.plugins);
+        if (plugins.length === 0) {
+            console.error(`${relative(cwd, root) || "."}: no plugin found`);
+            return 1;
+        }
+        const changed = syncPluginVersions(root, plugins);
+        console.log(changed.length === 0
+            ? "plugin versions already match package.json"
+            : `plugin versions synced from package.json: ${changed.join(", ")}`);
+        return 0;
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+}

package/dist/check/test-imports.d.ts

@@ -0,0 +1,20 @@
+import { type Finding } from "./source.js";
+/**
+ * `@capybara-hq/*` packages a plugin test may use besides the plugin itself: the SDK, the test
+ * helpers, and model-fake (the scripted model provider published from core), which a test loads by
+ * package name to drive agent runs.
+ */
+export declare const PLUGIN_TEST_PACKAGES: string[];
+/**
+ * `plugin-test-imports`: a test of a plugin (any file under `<plugin>/test`) reaches nothing outside
+ * the plugin, so it keeps working in a repository of its own (the official plugins live in
+ * `capybara-hq/plugins`; package ecosystem spec §6.2):
+ * - no import of an `@capybara-hq/*` package other than {@link PLUGIN_TEST_PACKAGES} and the plugin
+ *   itself, nor such a package name written as a string (a name in a kernel `extensions` list,
+ *   `require.resolve`);
+ * - no relative import or path string (`../x`) that leaves the plugin directory, and no `join` /
+ *   `resolve` whose bare `..` arguments leave it (taken from the file's directory);
+ * - no repo-root path into `packages/` or `apps/` (core's layout).
+ * A kernel facility a plugin test needs is exported by `@capybara-hq/testing`.
+ */
+export declare function checkPluginTestImports(pluginDirs: string[]): Finding[];

package/dist/check/test-imports.js

@@ -0,0 +1,158 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { collectImports, isParseError, parseFile, stringValue, walk, } from "./source.js";
+/**
+ * `@capybara-hq/*` packages a plugin test may use besides the plugin itself: the SDK, the test
+ * helpers, and model-fake (the scripted model provider published from core), which a test loads by
+ * package name to drive agent runs.
+ */
+export const PLUGIN_TEST_PACKAGES = [
+    "@capybara-hq/plugin-sdk",
+    "@capybara-hq/testing",
+    "@capybara-hq/plugin-model-fake",
+];
+const SOURCE_EXT = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+/** A relative path in a string or template literal (`./x`, `../x`). */
+const RELATIVE_STRING = /(["'`])(\.{1,2}\/[^"'`$]*)/g;
+/** A repo-root path into core: `"packages/…"`, `"apps/…"`, or after an interpolation `${root}/apps/…`. */
+const ROOTED_STRING = /(?:["'`]|\}\/?)((?:packages|apps)\/[a-z0-9][^"'`$]*)/g;
+/** An `@capybara-hq/<name>` package name (with an optional subpath); group 1 is the package. */
+const SCOPED_NAME = /^(@capybara-hq\/[^/\s]+)(?:\/\S*)?$/;
+/** The path functions whose `..` segments are followed: `join`, `resolve`, `path.join`, `posix.resolve`… */
+const PATH_CALL = new Set(["join", "resolve"]);
+const lineAt = (source, offset) => source.slice(0, offset).split("\n").length;
+function listFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.name === "node_modules")
+            continue;
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...listFiles(p));
+        else if (e.isFile() && SOURCE_EXT.test(e.name))
+            out.push(p);
+    }
+    return out;
+}
+const calleeName = (callee) => {
+    if (callee.type === "Identifier")
+        return callee.name;
+    if (callee.type === "MemberExpression" && !callee.computed) {
+        return callee.property.name ?? undefined;
+    }
+    return undefined;
+};
+/**
+ * Where a `join(...)` / `resolve(...)` call whose literal arguments hold a bare `..` segment points,
+ * when that can be told: the first argument is taken as the file's own directory when it is not a
+ * literal (`here`, `__dirname`, `import.meta.dirname`), then the literal arguments are applied in
+ * order until a non-literal one. `undefined` when no literal argument has a `..` segment.
+ */
+function pathCallTarget(call, file) {
+    const args = call.arguments;
+    const values = args.map((a) => stringValue(a));
+    const hasDotDot = values.some((v) => v?.split(/[\\/]/).includes("..") === true);
+    if (!hasDotDot)
+        return undefined;
+    // A first literal argument is relative to the process's directory: a `..` there leaves anything.
+    let at = values[0] === undefined ? dirname(file) : resolve(dirname(file), "/");
+    for (const [i, v] of values.entries()) {
+        if (v === undefined) {
+            if (i === 0)
+                continue;
+            break;
+        }
+        at = resolve(at, v);
+    }
+    return at;
+}
+/**
+ * `plugin-test-imports`: a test of a plugin (any file under `<plugin>/test`) reaches nothing outside
+ * the plugin, so it keeps working in a repository of its own (the official plugins live in
+ * `capybara-hq/plugins`; package ecosystem spec §6.2):
+ * - no import of an `@capybara-hq/*` package other than {@link PLUGIN_TEST_PACKAGES} and the plugin
+ *   itself, nor such a package name written as a string (a name in a kernel `extensions` list,
+ *   `require.resolve`);
+ * - no relative import or path string (`../x`) that leaves the plugin directory, and no `join` /
+ *   `resolve` whose bare `..` arguments leave it (taken from the file's directory);
+ * - no repo-root path into `packages/` or `apps/` (core's layout).
+ * A kernel facility a plugin test needs is exported by `@capybara-hq/testing`.
+ */
+export function checkPluginTestImports(pluginDirs) {
+    const out = [];
+    for (const pluginDir of pluginDirs) {
+        const pkgFile = join(pluginDir, "package.json");
+        const name = existsSync(pkgFile)
+            ? JSON.parse(readFileSync(pkgFile, "utf8")).name
+            : undefined;
+        const own = typeof name === "string" ? name : undefined;
+        const allowed = new Set([...PLUGIN_TEST_PACKAGES, ...(own === undefined ? [] : [own])]);
+        for (const file of listFiles(join(pluginDir, "test"))) {
+            out.push(...fileFindings(file, pluginDir, allowed));
+        }
+    }
+    return out;
+}
+function fileFindings(file, pluginDir, allowed) {
+    const out = [];
+    const source = readFileSync(file, "utf8");
+    const inside = (p) => !relative(pluginDir, p).startsWith("..");
+    const seen = new Set();
+    const add = (offset, what) => {
+        const line = lineAt(source, offset);
+        if (seen.has(line))
+            return;
+        seen.add(line);
+        out.push({
+            file,
+            line,
+            rule: "plugin-test-imports",
+            message: `${what}: a plugin test may use only ${[...allowed].join(", ")} and files inside its ` +
+                "plugin directory (it must keep working in its own repository); export a missing kernel " +
+                "facility from @capybara-hq/testing",
+        });
+    };
+    const parsed = parseFile(file);
+    if (isParseError(parsed)) {
+        out.push(parsed);
+    }
+    else {
+        const imports = new Set();
+        for (const { spec, start } of collectImports(parsed.program)) {
+            imports.add(start);
+            const scoped = SCOPED_NAME.exec(spec)?.[1];
+            if (scoped !== undefined && !allowed.has(scoped))
+                add(start, `imports ${spec}`);
+        }
+        walk(parsed.program, (n) => {
+            if (n.type === "Literal" || n.type === "TemplateLiteral") {
+                const v = stringValue(n);
+                const scoped = v === undefined ? undefined : SCOPED_NAME.exec(v)?.[1];
+                if (scoped !== undefined && !allowed.has(scoped)) {
+                    add(n.start, `names the package ${v}`);
+                }
+            }
+            if (n.type === "CallExpression") {
+                const callee = calleeName(n.callee);
+                if (callee === undefined || !PATH_CALL.has(callee))
+                    return;
+                const target = pathCallTarget(n, file);
+                if (target !== undefined && !inside(target)) {
+                    add(n.start, `the ".." segments of this ${callee}() leave the plugin directory`);
+                }
+            }
+        });
+    }
+    for (const m of source.matchAll(RELATIVE_STRING)) {
+        const p = m[2] ?? "";
+        if (!inside(resolve(dirname(file), p))) {
+            add(m.index ?? 0, `${p} leaves the plugin directory`);
+        }
+    }
+    for (const m of source.matchAll(ROOTED_STRING)) {
+        add(m.index ?? 0, `${m[1] ?? ""} is a path into core`);
+    }
+    return out;
+}