@capybara-hq/plugin-tools 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/check/report.js

@@ -1,16 +1,26 @@
 import { relative } from "node:path";
+import { errorsOf } from "./source.js";
 /** 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.
+ * Prints the result of one check: `[name] passed` (`passed with N warning(s)` and one line per
+ * warning when it has only warnings), or the finding count and one line per finding (stderr).
+ * Returns whether it passed (warnings do not fail it).
  */
 export function printCheck(name, findings, root) {
+    const errors = errorsOf(findings);
     if (findings.length === 0) {
         console.log(`[${name}] passed`);
         return true;
     }
-    console.error(`[${name}] ${findings.length} finding(s)`);
+    if (errors.length === 0) {
+        console.error(`[${name}] passed with ${findings.length} warning(s)`);
+        for (const f of findings)
+            console.error(`  ${formatFinding(f, root)}`);
+        return true;
+    }
+    const warnings = findings.length - errors.length;
+    console.error(`[${name}] ${errors.length} finding(s)${warnings > 0 ? ` and ${warnings} warning(s)` : ""}`);
     for (const f of findings)
         console.error(`  ${formatFinding(f, root)}`);
     return false;

package/dist/check/run.d.ts

@@ -8,7 +8,7 @@ export interface PluginCheckScope {
     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
+     * permissions, pack, config forms, tool design, test imports, release metadata, and the migrations in
      * `<plugin>/migrations`).
      */
     plugins: string[];

package/dist/check/run.js

@@ -1,6 +1,8 @@
 import { join } from "node:path";
+import { checkConfigForms } from "./config-forms.js";
 import { checkDeps } from "./deps.js";
 import { checkMigrations } from "./migrations.js";
+import { checkOrgOverride } from "./org-override.js";
 import { checkPluginPack } from "./plugin-pack.js";
 import { checkPluginPermissions } from "./plugin-permissions.js";
 import { checkPluginState } from "./plugin-state.js";
@@ -27,6 +29,8 @@ export function pluginChecks(scope) {
         { name: "Extension state", run: () => checkPluginState(plugins) },
         { name: "Extension permissions", run: () => checkPluginPermissions(plugins) },
         { name: "Plugin pack", run: () => checkPluginPack(plugins) },
+        { name: "Config forms", run: () => checkConfigForms(plugins) },
+        { name: "Org override", run: () => checkOrgOverride(plugins) },
         {
             name: "Tool design",
             run: () => checkToolDesign([...(scope.toolDesignDirs ?? []), ...plugins]),

package/dist/check/source.d.ts

@@ -1,10 +1,17 @@
 import { type Comment } from "oxc-parser";
+/**
+ * One finding of a check. `severity: "warning"` is printed but does not fail the check (only a
+ * few rules warn, e.g. `release-description-zh`); without it the finding is an error.
+ */
 export type Finding = {
     file: string;
     line: number;
     rule: string;
     message: string;
+    severity?: "warning";
 };
+/** The findings that fail a check (every finding that is not a warning). */
+export declare const errorsOf: (findings: Finding[]) => Finding[];
 /** ESTree 节点（oxc-parser 的输出）。只声明本检查用到的公共字段。 */
 export interface Node {
     type: string;

package/dist/check/source.js

@@ -1,6 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseSync } from "oxc-parser";
+/** The findings that fail a check (every finding that is not a warning). */
+export const errorsOf = (findings) => findings.filter((f) => f.severity !== "warning");
 const SOURCE_EXT = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
 const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
 /** 只在插件根目录下才有特殊含义的目录名（更深处同名目录是普通源码目录，必须扫描）。 */

package/dist/marketplace/cli.d.ts

@@ -1,20 +1,22 @@
 export declare const MARKETPLACE_USAGE: string;
 /**
  * `capybara-plugin marketplace`: writes (`--write`) or checks (`--check`) the repository's
- * marketplace manifest against reproducible packs of its public plugins ({@link syncMarketplace}).
+ * marketplace manifest, one entry per public plugin at its current version, against reproducible
+ * packs of its public plugins ({@link syncMarketplace}).
  *
  * - `--root <dir>`: the repository (default: the current directory);
  * - `--file <path>`: the manifest, relative to the root (default `.capybara-plugin/marketplace.json`);
  * - `--plugins <glob>`: the plugin directories, relative to the root (default `plugins/*`, or the
  *   root itself when it is a plugin).
  *
- * - `--base <rev>` (with `--check`, on pull requests): the entries the file had at `<rev>` must be
- *   unchanged and first, in order (`marketplace-append-only`), and the entries added since must
- *   match the tree's packs (`marketplace-integrity`).
+ * - `--base <rev>` (with `--check`, on pull requests): an entry's version may only increase over the
+ *   versions `<rev>` lists (`marketplace-version-decrease`), a version `<rev>` lists keeps its
+ *   integrity, and the entries added since must match the tree's packs (`marketplace-integrity`).
  *
- * `--check` exits 1 on any finding (`marketplace-missing`, `marketplace-integrity`,
- * `marketplace-append-only`, `marketplace-invalid`); `--write` appends the missing entries and
- * exits 1 only on `marketplace-invalid`.
+ * `--check` exits 1 on any finding that is not a warning (`marketplace-missing`,
+ * `marketplace-display-stale`, `marketplace-integrity`, `marketplace-version-decrease`,
+ * `marketplace-invalid`); `--write` writes each plugin's entry (replacing its other versions,
+ * refreshing a listed entry's summary and displayName) and exits 1 only on `marketplace-invalid`.
  * Relative paths resolve against `cwd`. Returns the exit code.
  */
 export declare function marketplaceCommand(args: string[], cwd: string): Promise<number>;

package/dist/marketplace/cli.js

@@ -1,25 +1,28 @@
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { formatFinding } from "../check/report.js";
+import { errorsOf } from "../check/source.js";
 import { MARKETPLACE_FILE, syncMarketplace } from "./marketplace.js";
 export const MARKETPLACE_USAGE = "capybara-plugin marketplace --write|--check [--base <rev>] [--root <dir>] [--file <path>]\n" +
     "                            [--plugins <glob>]";
 /**
  * `capybara-plugin marketplace`: writes (`--write`) or checks (`--check`) the repository's
- * marketplace manifest against reproducible packs of its public plugins ({@link syncMarketplace}).
+ * marketplace manifest, one entry per public plugin at its current version, against reproducible
+ * packs of its public plugins ({@link syncMarketplace}).
  *
  * - `--root <dir>`: the repository (default: the current directory);
  * - `--file <path>`: the manifest, relative to the root (default `.capybara-plugin/marketplace.json`);
  * - `--plugins <glob>`: the plugin directories, relative to the root (default `plugins/*`, or the
  *   root itself when it is a plugin).
  *
- * - `--base <rev>` (with `--check`, on pull requests): the entries the file had at `<rev>` must be
- *   unchanged and first, in order (`marketplace-append-only`), and the entries added since must
- *   match the tree's packs (`marketplace-integrity`).
+ * - `--base <rev>` (with `--check`, on pull requests): an entry's version may only increase over the
+ *   versions `<rev>` lists (`marketplace-version-decrease`), a version `<rev>` lists keeps its
+ *   integrity, and the entries added since must match the tree's packs (`marketplace-integrity`).
  *
- * `--check` exits 1 on any finding (`marketplace-missing`, `marketplace-integrity`,
- * `marketplace-append-only`, `marketplace-invalid`); `--write` appends the missing entries and
- * exits 1 only on `marketplace-invalid`.
+ * `--check` exits 1 on any finding that is not a warning (`marketplace-missing`,
+ * `marketplace-display-stale`, `marketplace-integrity`, `marketplace-version-decrease`,
+ * `marketplace-invalid`); `--write` writes each plugin's entry (replacing its other versions,
+ * refreshing a listed entry's summary and displayName) and exits 1 only on `marketplace-invalid`.
  * Relative paths resolve against `cwd`. Returns the exit code.
  */
 export async function marketplaceCommand(args, cwd) {
@@ -59,14 +62,20 @@ export async function marketplaceCommand(args, cwd) {
         });
         for (const f of r.findings)
             console.error(formatFinding(f, root));
-        if (r.findings.length > 0) {
-            console.error(`\n${r.findings.length} marketplace finding(s)`);
+        const errors = errorsOf(r.findings);
+        if (errors.length > 0) {
+            console.error(`\n${errors.length} marketplace finding(s)`);
             return 1;
         }
         if (values.write) {
             for (const e of r.added)
                 console.log(`added ${e.name}@${e.version}`);
-            console.log(r.added.length === 0 ? "marketplace is up to date" : `wrote ${file}`);
+            for (const k of r.removed)
+                console.log(`removed ${k}`);
+            for (const k of r.refreshed)
+                console.log(`refreshed ${k}`);
+            const changed = r.added.length + r.removed.length + r.refreshed.length > 0;
+            console.log(changed ? `wrote ${file}` : "marketplace is up to date");
         }
         else {
             console.log("marketplace is up to date");

package/dist/marketplace/marketplace.d.ts

@@ -9,44 +9,58 @@ export interface SyncMarketplaceOptions {
     file: string;
     /** Plugin directories relative to `root` (`*` within one segment); default as `discoverPlugins`. */
     plugins?: string;
-    /** Append the missing entries to `file` (`--write`); otherwise only report them (`--check`). */
+    /** Write the plugins' entries into `file` (`--write`); otherwise only report them (`--check`). */
     write: boolean;
     /**
      * A git revision (`--check --base <rev>`, pull requests): the entries the file had there are
-     * published and must still be there, unchanged and in the same order (only appending is
-     * allowed; `marketplace-append-only`), and every entry added since must match the tree's pack
-     * (`marketplace-integrity`). A file the base does not have constrains nothing.
+     * published. An entry of a version the base lists must keep its source and integrity
+     * (`marketplace-integrity`); an entry of a version the base does not list must be newer than
+     * every version the base lists for that plugin (`marketplace-version-decrease`) and, when it is
+     * the tree's version, match the tree's pack (`marketplace-integrity`). A file the base does not
+     * have constrains nothing.
      */
     base?: string;
 }
 /** The result of {@link syncMarketplace}. */
 export interface SyncMarketplaceResult {
-    /** Entries for `(name, version)` pairs the file does not list yet (appended with `write`). */
+    /** New entries: plugins not listed at their current version (written with `write`). */
     added: MarketplaceEntry[];
+    /** `name@version` of the other entries of the tree's plugins (dropped with `write`). */
+    removed: string[];
     /**
-     * `marketplace-invalid` (the file does not parse, or would not after appending),
-     * `marketplace-integrity` (with a base: an entry added since names another package or integrity
-     * than the tree's pack), `marketplace-append-only` (with a base: a published entry changed, moved
-     * or went away) and, without `write`, `marketplace-missing` (one per added entry).
+     * `name@version` of listed entries whose `summary` / `displayName` differ from plugin.json
+     * (rewritten with `write`; source and integrity never change).
+     */
+    refreshed: string[];
+    /**
+     * `marketplace-invalid` (the file does not parse, or would not after writing),
+     * `marketplace-integrity` and `marketplace-version-decrease` (with a base, see
+     * {@link SyncMarketplaceOptions.base}) and, without `write`, `marketplace-missing` (one per
+     * plugin whose current version is not listed, or not as its only entry) and
+     * `marketplace-display-stale` (a listed entry's summary / displayName differ from plugin.json).
      */
     findings: Finding[];
 }
 /**
- * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing every
- * published version of its public plugins (package ecosystem spec §5.2; one entry per
- * `(name, version)`, Decision 7 of phase A3b). Each public plugin (not `"private": true`) is packed
- * reproducibly with {@link packPlugin}; when the file has no entry for its name and version, an
- * entry `{ name, version, summary, homepage?, permissions, source: { npm: { package, version,
- * integrity } } }` is added (`integrity` the pack's sha512, which the release then publishes
- * byte for byte; `permissions` display only). A version already listed is not packed or compared:
- * once published, its bytes are the release gate's business (`release --marketplace`), so a later
- * source or toolchain change at the same version is not a finding. With `base`, published entries
- * must be unchanged and first in order, and entries added since must match the tree's packs.
- * Entries of versions no longer in the tree are kept, so a pinned commit lists what it pins and
- * older versions stay importable. The file is written formatted as Biome formats it
- * ({@link formatMarketplaceJson}).
- * With `write`, the new entries are appended in plugin order (nothing is written when there is any
- * other finding).
+ * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing one entry
+ * per public plugin, its current version (plugin component management spec §13.2, replacing the
+ * one-entry-per-version rule of the package ecosystem spec §5.2). Each public plugin (not
+ * `"private": true`) not listed at its version is packed reproducibly with {@link packPlugin} and
+ * gets an entry `{ name, version, summary, displayName?, homepage?, permissions, source: { npm: {
+ * package, version, integrity } } }` (`summary` from the plugin.json `description`, a string being
+ * `en`; `displayName` copied from plugin.json; `integrity` the pack's sha512, which the release
+ * then publishes byte for byte; `permissions` display only). The new entry takes the place of the
+ * plugin's first entry (a version that moved), the plugin's other entries are dropped (also those
+ * of a file written in the older one-entry-per-version form), and a plugin not listed yet is
+ * appended. Entries of plugins not in the tree are kept. A version already listed is not packed or
+ * compared: once published, its bytes are the release gate's business (`release --marketplace`),
+ * so a later source or toolchain change at the same version is not a finding; only its display
+ * fields (`summary`, `displayName`) are refreshed from the source plugin.json. Every other field
+ * of a kept entry stays as written, among them `deprecated`, which the maintainer sets by hand on
+ * a published version's entry (not in plugin.json: that would change the packed bytes); a new
+ * version's entry has none, and no rule compares it with the base. With `base`, see
+ * {@link SyncMarketplaceOptions.base}. The file is written formatted as Biome formats it
+ * ({@link formatMarketplaceJson}); nothing is written when there is any other finding.
  */
 export declare function syncMarketplace(opts: SyncMarketplaceOptions): Promise<SyncMarketplaceResult>;
 /**