@fairfox/polly 0.40.0 → 0.47.0

package/dist/tools/quality/src/plugins/core-checks.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Additional checks bundled into `pollyCorePlugin`.
+ *
+ * Each check here is a port of an existing `scripts/check-*.ts` script
+ * from polly's repo into the plugin contract. The original scripts
+ * remain on disk for back-compat with the existing pre-commit
+ * orchestrator (`scripts/check.ts`); the plugin path is the new way
+ * for downstream consumers (lingua, fairfox, warehouse-experiments)
+ * who do not want to copy the script verbatim.
+ *
+ * Out of scope for this release:
+ *   - `polly:boundaries` issue text describes a workspace-dependency
+ *     model (each package may only import from packages it lists in
+ *     its `dependencies`). Polly itself is a single-package repo and
+ *     uses directional zone bans (`src/` cannot import `tools/`,
+ *     etc.); that model is what ships here. The workspace-dep model
+ *     can be layered on as an additional configuration mode later.
+ */
+import type { Check } from "../types";
+export declare const additionalCoreChecks: Check<unknown>[];

package/dist/tools/quality/src/plugins/core.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `pollyCorePlugin` — the polly-provided core plugin.
+ *
+ * Wraps the four checks polly already ships in `@fairfox/polly/quality`
+ * into the new `Check` contract. The wrapping is purely adaptive: each
+ * underlying function (`checkNoAsCasting`, `checkNoRequire`,
+ * `checkSecrets`, `checkGitignoreCoversAllowlist`) keeps its existing
+ * exports unchanged, so consumers wiring those up by hand continue to
+ * work. The plugin path is the new way; the function path stays the
+ * same.
+ *
+ * The CSS family and shared-components live in a separate `polly-ui`
+ * plugin (#92–#94) because they belong to the styled-component
+ * contract polly-ui owns. Issue #98's scope is the four core checks.
+ */
+import type { QualityPlugin } from "../types";
+export declare const POLLY_CORE_VERSION = "0.45.0";
+export declare const pollyCorePlugin: QualityPlugin;

package/dist/tools/quality/src/plugins/extra-checks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Three more checks bundled into `pollyCorePlugin`:
+ *
+ *   - polly:forbidden-deps     — import-graph ban list (#87)
+ *   - polly:no-state-hooks     — ban useState/useReducer/useSignal (#99)
+ *   - polly:typographic-quotes — opt-in straight-vs-curly enforcement (#88)
+ *
+ * Each check is parameterised: defaults match polly's own pre-commit
+ * surface; consumers override via `polly.config.ts`. Test files are
+ * excluded by default for the import-walking checks since mocks and
+ * fixtures legitimately reference banned packages.
+ */
+import type { Check } from "../types";
+export declare const extraCoreChecks: Check<unknown>[];

package/dist/tools/quality/src/plugins/import-checks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Import-graph checks for `pollyCorePlugin`:
+ *
+ *   - polly:relative-imports — ban `../` imports beyond a depth threshold (#84)
+ *   - polly:tsconfig-paths   — ban `compilerOptions.paths` aliases (#84)
+ *   - polly:no-raw-http      — force HTTP through a canonical client (#86)
+ *   - polly:types            — multi-package tsc --noEmit orchestrator (#85)
+ *
+ * All four are parameterised. Defaults are silent or zero-impact unless a
+ * consumer opts in via `polly.config.ts`. Polly's own pre-commit pipeline
+ * does not currently run these — they exist primarily for downstream
+ * consumers (lingua, fairfox, warehouse-experiments) and ship under the
+ * core plugin namespace so adoption is one config-block change away.
+ */
+import type { Check } from "../types";
+export declare const importCoreChecks: Check<unknown>[];

package/dist/tools/quality/src/plugins/polly-ui.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `pollyUiPlugin` — the polly-ui-provided plugin (#89, #90, #91–#94).
+ *
+ * Re-homes the CSS conformance family and shared-components ban under a
+ * dedicated `polly-ui` namespace, and adds a new `no-inline-handlers`
+ * check for JSX event handlers. Every wrap reuses the underlying
+ * function from `tools/quality/src/css/*` and
+ * `tools/quality/src/check-shared-components.ts` so behaviour is
+ * identical to the pre-host invocation; only the integration surface
+ * changes.
+ *
+ * Out of scope for this release:
+ *   - The data-action dispatcher *runtime* described in #90. The check
+ *     ships here so a project can ban inline handlers today; the
+ *     dispatcher needs a real Preact implementation that mounts near
+ *     <OverlayRoot> and registers a delegated event listener, and that
+ *     work belongs in `src/polly-ui/actions.tsx` rather than under the
+ *     quality plugin host. The check on its own is useful — it forces
+ *     the consumer to pick an alternative — and the runtime can land
+ *     in a follow-up release without changing the check's id.
+ *   - Registry-driven CSS validation. The four CSS checks currently
+ *     parse polly-ui's CSS at scan time. The new
+ *     `@fairfox/polly/ui/registry` (introduced alongside this plugin)
+ *     exposes the canonical token + component lists as data, and a
+ *     follow-up can swap the parse-time discovery for a registry
+ *     lookup. The shape of the wraps does not change when that
+ *     happens; only the inner implementation does.
+ */
+import type { QualityPlugin } from "../types";
+export declare const POLLY_UI_PLUGIN_VERSION = "0.46.0";
+export declare const pollyUiPlugin: QualityPlugin;

package/dist/tools/quality/src/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Plugin-host contract for `@fairfox/polly/quality`.
+ *
+ * A `QualityPlugin` bundles a set of `Check`s under a namespace. The host
+ * loads one or more plugins from `polly.config.ts`, validates that each
+ * check's id is unique, and runs the requested set in parallel. A check
+ * declares the inputs it reads so the cache layer (see `cache.ts`) can
+ * compute a content-hash and skip re-execution when nothing has changed.
+ *
+ * Plugin and check ids are namespaced as `<plugin>:<name>`. Polly's own
+ * plugin uses the `polly` prefix; polly-ui will use `polly-ui`; consumer
+ * plugins use whatever prefix matches their package name.
+ */
+/**
+ * Outcome of running a single check. The host aggregates these into a
+ * `RunReport` for the CLI. `cached` is true when the result came back from
+ * the on-disk cache without re-running the check body.
+ */
+export type CheckRunResult = {
+    id: string;
+    ok: boolean;
+    durationMs: number;
+    cached: boolean;
+    /** Human-readable summary line (one violation per element, or status). */
+    messages: string[];
+    /** Raw error if the check threw; surfaces in CLI output. */
+    error?: string;
+};
+/**
+ * Context passed to a check at run time. The host fills in `rootDir`
+ * and `signal` (for cancellation) before invoking `run`.
+ */
+export type CheckContext<TConfig = unknown> = {
+    /** Repository root the consumer is checking. */
+    rootDir: string;
+    /** Resolved configuration for this check (already validated). */
+    config: TConfig;
+    /** Aborted when the run is cancelled (CLI Ctrl-C, watch reload, etc.). */
+    signal?: AbortSignal;
+};
+/**
+ * A single check. The host calls `validate(config)` once at load time
+ * and `run(ctx)` once per execution. `filesRead(config)` is consulted by
+ * the cache before `run` — return the absolute paths whose content must
+ * invalidate a cached result.
+ */
+export type Check<TConfig = unknown> = {
+    /** Namespaced id, e.g. `polly:no-as-casting`. */
+    id: string;
+    /** One-line description for `polly quality list`. */
+    description: string;
+    /**
+     * Validate user-supplied config. Return `null` for valid input or a
+     * non-empty array of error messages for invalid input. Errors are
+     * surfaced at load time, not at run time.
+     */
+    validate?: (config: unknown) => string[] | null;
+    /**
+     * Files whose content affects the result of this check. Returned as
+     * absolute paths (or paths relative to `rootDir`; the cache normalises).
+     * The host hashes these and skips `run` on cache hit.
+     */
+    filesRead?: (config: TConfig, rootDir: string) => Promise<string[]> | string[];
+    /**
+     * Environment variables and tool versions that contribute to the
+     * cache key alongside file content. Use this when the check's behaviour
+     * depends on something not captured by `filesRead` (e.g. a binary's
+     * version, an env var that flips a code path).
+     */
+    cacheKeyExtras?: (config: TConfig) => Record<string, string>;
+    /** Run the check. Throws are caught by the host and reported as failures. */
+    run: (ctx: CheckContext<TConfig>) => Promise<CheckOutcome>;
+};
+/**
+ * The body of a check returns either pass or fail with messages. The host
+ * adds id, duration, and cache status to produce a `CheckRunResult`.
+ */
+export type CheckOutcome = {
+    ok: boolean;
+    messages: string[];
+};
+/**
+ * A plugin contributes a namespaced bundle of checks.
+ */
+export type QualityPlugin = {
+    /** Namespace used as the prefix on every check id. */
+    name: string;
+    version: string;
+    checks: Check<unknown>[];
+};
+/**
+ * Per-check configuration map keyed by check id. The host pulls the
+ * matching entry out of `qualityConfig` and passes it as `ctx.config`.
+ */
+export type QualityRunConfig = {
+    plugins: QualityPlugin[];
+    /** Per-check config keyed by check id (e.g. `"polly:no-as-casting"`). */
+    checks?: Record<string, unknown>;
+};
+export type RunReport = {
+    ok: boolean;
+    results: CheckRunResult[];
+    totalDurationMs: number;
+};