@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/core/registry/registry.js

@@ -0,0 +1,351 @@
+"use strict";
+// =============================================================================
+// Generic typed registry primitive (issue #675, PP-1.3)
+// =============================================================================
+//
+// One implementation of "an additive, typed, string-keyed list", so every closed
+// list the platform turns into a registry shares ONE duplicate rule, ONE
+// ordering rule and ONE set of error codes. Those three things are the
+// "registry behaviour: ordering, duplicate-id handling, error cases" that
+// docs/specs/platform-packages.md promises apps can rely on; registry.spec.ts
+// pins them.
+//
+// ⚠ FRAMEWORK-FREE ON PURPOSE. This file imports nothing: no `@nestjs/*`, no
+// Prisma, no application code. Static registries are read where no Nest
+// container exists: `prisma/seed.ts` under `ts-node --transpile-only`, the
+// standalone `storage-purge.main.ts`, and DTO classes that `createZodDto()`
+// builds while their module is evaluated (and that `npm run openapi:dump` reads
+// in preview mode, where no provider is instantiated and no hook runs).
+// registry.spec.ts reads this file and fails on any import.
+//
+// Two kinds of registry share it (README.md next to this file has the recipe):
+//
+//   - STATIC: `defineRegistry(...)` at module scope, filled at import time by
+//     the registry's manifest, frozen by `RegistryFreezeService` once the Nest
+//     application has bootstrapped. Never filled from `onModuleInit`: several
+//     Nest applications share one module graph in a Jest worker, and the second
+//     one would hit a frozen registry.
+//   - INSTANCE: `new Registry(...)` held by an `@Injectable()`, filled from each
+//     contributor's `onModuleInit` (`register(this)`), optionally frozen by its
+//     owner in `onApplicationBootstrap` (see doctor/doctor-check.registry.ts).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Registry = exports.RegistryError = exports.REGISTRY_ID_MAX_LENGTH = exports.DEFAULT_REGISTRY_ID_PATTERN = void 0;
+exports.defineRegistry = defineRegistry;
+exports.listDefinedRegistries = listDefinedRegistries;
+exports.freezeDefinedRegistries = freezeDefinedRegistries;
+/**
+ * The default pattern every registry id must match: a letter or digit first,
+ * then letters, digits and `. _ : / @ -`.
+ *
+ * It admits every id shape the codebase already uses (`db.connection`,
+ * `jobs:read`, `auth.initial-admin`, `coach/weekly-review`) and rejects whitespace and a
+ * leading separator. Override it per registry with {@link RegistryOptions.idPattern}.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_REGISTRY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/@-]*$/;
+/**
+ * The longest id any registry accepts, in UTF-16 code units.
+ *
+ * @stability stable
+ */
+exports.REGISTRY_ID_MAX_LENGTH = 128;
+/**
+ * The single error type every registry operation throws.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   permissions.register(entry);
+ * } catch (err) {
+ *   if (err instanceof RegistryError && err.code === 'DUPLICATE_ID') { ... }
+ * }
+ * ```
+ *
+ * @stability stable
+ */
+class RegistryError extends Error {
+    /** Machine-readable reason; see {@link RegistryErrorCode}. */
+    code;
+    /** The `name` of the registry that refused the operation. */
+    registry;
+    /** The entry id involved, when there is one. */
+    id;
+    /**
+     * @param code - why the operation was refused.
+     * @param registry - the refusing registry's name.
+     * @param message - human-readable explanation.
+     * @param details - the id involved and, for `INVALID_ENTRY`, the original error as `cause`.
+     */
+    constructor(code, registry, message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = 'RegistryError';
+        this.code = code;
+        this.registry = registry;
+        if (details.id !== undefined)
+            this.id = details.id;
+    }
+}
+exports.RegistryError = RegistryError;
+function compareCodeUnits(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * An additive, typed, string-keyed list with a duplicate policy, deterministic
+ * order and an optional freeze.
+ *
+ * Entries are stored as given (never cloned); {@link list} and {@link ids}
+ * return fresh arrays, so mutating them never changes the registry. Because the
+ * registry holds references, entries should be `as const` or `Object.freeze`d
+ * data.
+ *
+ * @typeParam T - the entry type.
+ *
+ * @example
+ * ```ts
+ * const colours = new Registry<{ id: string; hex: string }>({
+ *   name: 'colours',
+ *   idOf: (c) => c.id,
+ *   validate: (c) => {
+ *     if (!/^#[0-9a-f]{6}$/i.test(c.hex)) throw new Error(`bad hex ${c.hex}`);
+ *   },
+ * });
+ * colours.register({ id: 'brand', hex: '#3366ff' });
+ * colours.require('brand').hex; // '#3366ff'
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability stable
+ */
+class Registry {
+    options;
+    /** The registry's name, as given in {@link RegistryOptions.name}. */
+    name;
+    entries = new Map();
+    isFrozen = false;
+    idPattern;
+    /**
+     * @param options - see {@link RegistryOptions}.
+     * @throws RegistryError `INVALID_ID` when `options.name` is empty.
+     */
+    constructor(options) {
+        this.options = options;
+        if (typeof options.name !== 'string' || options.name.trim() === '') {
+            throw new RegistryError('INVALID_ID', String(options.name), 'A registry name must be a non-empty string.');
+        }
+        this.name = options.name;
+        const pattern = options.idPattern ?? exports.DEFAULT_REGISTRY_ID_PATTERN;
+        this.idPattern = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''));
+    }
+    /**
+     * Adds one entry.
+     *
+     * @throws RegistryError `FROZEN`, `INVALID_ID`, `INVALID_ENTRY` or
+     * `DUPLICATE_ID` (see {@link RegistryErrorCode}); the registry is unchanged
+     * when it throws.
+     */
+    register(entry) {
+        this.registerAll([entry]);
+    }
+    /**
+     * Adds every entry, all or nothing: each entry is checked (id, `validate`,
+     * duplicates against the registry AND earlier entries of the same batch)
+     * before any is added, so one bad entry rejects the whole batch and leaves the
+     * registry unchanged.
+     *
+     * @throws RegistryError as {@link register}; the first failing entry wins.
+     */
+    registerAll(entries) {
+        this.assertWritable();
+        const staged = new Map(this.entries);
+        const replacements = [];
+        for (const entry of entries) {
+            const id = this.checkedId(entry);
+            if (this.options.validate) {
+                try {
+                    this.options.validate(entry, this);
+                }
+                catch (err) {
+                    throw new RegistryError('INVALID_ENTRY', this.name, `Invalid entry "${id}" in registry "${this.name}": ${messageOf(err)}`, { id, cause: err });
+                }
+            }
+            if (staged.has(id)) {
+                const existing = staged.get(id);
+                if ((this.options.onDuplicate ?? 'throw') === 'throw') {
+                    const message = this.options.describeDuplicate
+                        ? this.options.describeDuplicate(existing, entry)
+                        : `Duplicate id "${id}" in registry "${this.name}".`;
+                    throw new RegistryError('DUPLICATE_ID', this.name, message, { id });
+                }
+                replacements.push([existing, entry]);
+            }
+            // Map#set on an existing key keeps its insertion position: exactly the
+            // "replace keeps the new entry at the OLD position" rule.
+            staged.set(id, entry);
+        }
+        this.entries = staged;
+        for (const [previous, next] of replacements) {
+            this.options.onReplace?.(previous, next);
+        }
+    }
+    /** The entry registered under `id`, or `undefined`. */
+    get(id) {
+        return this.entries.get(id);
+    }
+    /**
+     * The entry registered under `id`.
+     *
+     * @throws RegistryError `UNKNOWN_ID` when there is none.
+     */
+    require(id) {
+        const entry = this.entries.get(id);
+        if (entry === undefined && !this.entries.has(id)) {
+            const known = this.ids();
+            const shown = known.length > 20 ? `${known.slice(0, 20).join(', ')}, ...` : known.join(', ');
+            throw new RegistryError('UNKNOWN_ID', this.name, `Unknown id "${id}" in registry "${this.name}". Known ids: ${shown || '(none)'}.`, { id });
+        }
+        return entry;
+    }
+    /** Whether an entry is registered under `id`. */
+    has(id) {
+        return this.entries.has(id);
+    }
+    /** Every id, as a fresh array, in {@link list} order. */
+    ids() {
+        return this.sortedEntries().map(([id]) => id);
+    }
+    /** Every entry, as a fresh array, in the order {@link RegistryOptions.order} names. */
+    list() {
+        return this.sortedEntries().map(([, entry]) => entry);
+    }
+    /** How many entries are registered. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Refuses every later write with `FROZEN`. Reads keep working. Idempotent. */
+    freeze() {
+        this.isFrozen = true;
+    }
+    /** Whether {@link freeze} has been called. */
+    get frozen() {
+        return this.isFrozen;
+    }
+    /** Name, frozen state and ids, for logs, diagnostics and snapshot tests. */
+    snapshot() {
+        return { name: this.name, frozen: this.isFrozen, ids: this.ids() };
+    }
+    /**
+     * Saves the entries and frozen state. For `testing.ts` only.
+     * @internal
+     */
+    _captureState() {
+        return { entries: new Map(this.entries), frozen: this.isFrozen };
+    }
+    /**
+     * Restores a state saved by {@link _captureState}. For `testing.ts` only.
+     * @internal
+     */
+    _restoreState(state) {
+        this.entries = new Map(state.entries);
+        this.isFrozen = state.frozen;
+    }
+    /**
+     * Allows writes again. For `testing.ts` only.
+     * @internal
+     */
+    _unfreeze() {
+        this.isFrozen = false;
+    }
+    assertWritable() {
+        if (this.isFrozen) {
+            throw new RegistryError('FROZEN', this.name, `Registry "${this.name}" is frozen: entries are registered before the application bootstraps.`);
+        }
+    }
+    checkedId(entry) {
+        const id = this.options.idOf(entry);
+        const fail = (why) => {
+            throw new RegistryError('INVALID_ID', this.name, `Invalid id ${JSON.stringify(id)} in registry "${this.name}": ${why}.`, {
+                id: typeof id === 'string' ? id : undefined,
+            });
+        };
+        if (typeof id !== 'string')
+            return fail('an id must be a string');
+        if (id.length === 0)
+            return fail('an id must not be empty');
+        if (id.length > exports.REGISTRY_ID_MAX_LENGTH)
+            return fail(`an id must be at most ${exports.REGISTRY_ID_MAX_LENGTH} characters`);
+        if (!this.idPattern.test(id))
+            return fail(`an id must match ${this.idPattern}`);
+        return id;
+    }
+    sortedEntries() {
+        const pairs = [...this.entries];
+        const order = this.options.order ?? 'registration';
+        if (order === 'id') {
+            pairs.sort(([a], [b]) => compareCodeUnits(a, b));
+        }
+        else if (typeof order === 'function') {
+            pairs.sort(([, a], [, b]) => order(a, b));
+        }
+        return pairs;
+    }
+}
+exports.Registry = Registry;
+// -----------------------------------------------------------------------------
+// The catalogue of static (module-level) registries
+// -----------------------------------------------------------------------------
+const definedRegistries = new Map();
+/**
+ * Creates a module-level ("static") registry and records it in the catalogue,
+ * so {@link freezeDefinedRegistries} (called by `RegistryFreezeService` after
+ * bootstrap) freezes it and {@link listDefinedRegistries} reports it.
+ *
+ * Call it once, at module scope, in the registry's own file; fill it from the
+ * registry's manifest (see README.md next to this file).
+ *
+ * @param options - see {@link RegistryOptions}.
+ * @returns the new registry.
+ * @throws RegistryError `DUPLICATE_REGISTRY` when a defined registry already has that name.
+ *
+ * @example
+ * ```ts
+ * // packages/platform-api/src/core/permissions/permission.registry.ts
+ * export const permissionRegistry = defineRegistry<PermissionDefinition>({
+ *   name: 'permissions',
+ *   idOf: (p) => p.id,
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability stable
+ */
+function defineRegistry(options) {
+    if (definedRegistries.has(options.name)) {
+        throw new RegistryError('DUPLICATE_REGISTRY', options.name, `A registry named "${options.name}" is already defined. Registry names must be unique.`);
+    }
+    const registry = new Registry(options);
+    definedRegistries.set(registry.name, registry);
+    return registry;
+}
+/**
+ * Every registry created with {@link defineRegistry}, in definition order.
+ *
+ * @stability stable
+ */
+function listDefinedRegistries() {
+    return [...definedRegistries.values()];
+}
+/**
+ * Freezes every registry created with {@link defineRegistry}. Idempotent.
+ *
+ * @stability stable
+ */
+function freezeDefinedRegistries() {
+    for (const registry of definedRegistries.values())
+        registry.freeze();
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/registry/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/core/registry/registry.ts"],"names":[],"mappings":"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"}

package/dist/core/registry/testing.d.ts

@@ -0,0 +1,29 @@
+import { Registry } from './registry';
+/**
+ * Adds `entries` to `registry` for the duration of `fn`, then restores the
+ * registry's previous entries and frozen state, even if `fn` throws.
+ *
+ * A frozen registry is unfrozen for the duration and frozen again afterwards.
+ * Restoring is a full rollback: an entry `fn` itself registers is removed too,
+ * and an entry a temporary one replaced (under `onDuplicate: 'replace'`) comes
+ * back at its old position. Nested calls restore in LIFO order, so they compose.
+ *
+ * @param registry - the registry to extend.
+ * @param entries - the temporary entries; registered with `registerAll`, so the
+ *   registry's usual id, validation and duplicate rules apply.
+ * @param fn - the code that needs the entries. May be async.
+ * @returns whatever `fn` returns.
+ * @throws Error when called outside Jest or Vitest (`JEST_WORKER_ID` / `VITEST` unset).
+ * @throws RegistryError when an entry is refused; the registry is unchanged.
+ *
+ * @example
+ * ```ts
+ * await withTemporaryEntries(permissionRegistry, [{ id: 'test:read' }], async () => {
+ *   expect(permissionRegistry.has('test:read')).toBe(true);
+ * });
+ * ```
+ *
+ * @stability stable
+ */
+export declare function withTemporaryEntries<T, R>(registry: Registry<T>, entries: readonly T[], fn: () => R | Promise<R>): Promise<R>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/core/registry/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../src/core/registry/testing.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAOtC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAC7C,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/core/registry/testing.js

@@ -0,0 +1,63 @@
+"use strict";
+// =============================================================================
+// Registry test helper (issue #675, PP-1.3)
+// =============================================================================
+//
+// Static registries are frozen once a Nest application has bootstrapped, and
+// a Jest worker shares one module graph across every `it`. A test that needs an
+// extra entry (a fake permission, a throwaway settings namespace) therefore
+// cannot just call `register()`: it would hit `FROZEN`, or leak the entry into
+// the next test. `withTemporaryEntries` adds the entries, runs the callback and
+// puts the registry back exactly as it found it.
+//
+// Framework-free like registry.ts, and refused outside a test runner so no
+// production path can unfreeze a registry.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTemporaryEntries = withTemporaryEntries;
+/** Whether this process is a Jest worker or a Vitest run. */
+function insideTestRunner() {
+    return Boolean(process.env.JEST_WORKER_ID || process.env.VITEST);
+}
+/**
+ * Adds `entries` to `registry` for the duration of `fn`, then restores the
+ * registry's previous entries and frozen state, even if `fn` throws.
+ *
+ * A frozen registry is unfrozen for the duration and frozen again afterwards.
+ * Restoring is a full rollback: an entry `fn` itself registers is removed too,
+ * and an entry a temporary one replaced (under `onDuplicate: 'replace'`) comes
+ * back at its old position. Nested calls restore in LIFO order, so they compose.
+ *
+ * @param registry - the registry to extend.
+ * @param entries - the temporary entries; registered with `registerAll`, so the
+ *   registry's usual id, validation and duplicate rules apply.
+ * @param fn - the code that needs the entries. May be async.
+ * @returns whatever `fn` returns.
+ * @throws Error when called outside Jest or Vitest (`JEST_WORKER_ID` / `VITEST` unset).
+ * @throws RegistryError when an entry is refused; the registry is unchanged.
+ *
+ * @example
+ * ```ts
+ * await withTemporaryEntries(permissionRegistry, [{ id: 'test:read' }], async () => {
+ *   expect(permissionRegistry.has('test:read')).toBe(true);
+ * });
+ * ```
+ *
+ * @stability stable
+ */
+async function withTemporaryEntries(registry, entries, fn) {
+    if (!insideTestRunner()) {
+        throw new Error(`withTemporaryEntries(${registry.name}) is a test helper: it runs only under Jest or Vitest ` +
+            '(JEST_WORKER_ID or VITEST must be set).');
+    }
+    const saved = registry._captureState();
+    registry._unfreeze();
+    try {
+        registry.registerAll(entries);
+        return await fn();
+    }
+    finally {
+        registry._restoreState(saved);
+    }
+}
+//# sourceMappingURL=testing.js.map

package/dist/core/registry/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../../src/core/registry/testing.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,4CAA4C;AAC5C,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,iDAAiD;AACjD,EAAE;AACF,2EAA2E;AAC3E,2CAA2C;AAC3C,gFAAgF;;AAmChF,oDAqBC;AApDD,6DAA6D;AAC7D,SAAS,gBAAgB;IACvB,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACI,KAAK,UAAU,oBAAoB,CACxC,QAAqB,EACrB,OAAqB,EACrB,EAAwB;IAExB,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,wBAAwB,QAAQ,CAAC,IAAI,wDAAwD;YAC3F,yCAAyC,CAC5C,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,CAAC;IAErB,IAAI,CAAC;QACH,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;AACH,CAAC"}

package/dist/core/testing/index.d.ts

@@ -0,0 +1,5 @@
+export { SECRET_LIKE_FIELD_PATTERN, describePluggableKindConformance } from './pluggable-conformance';
+export type { PluggableConformanceHarness, PluggableConformanceOptions } from './pluggable-conformance';
+export { describeVocabularyConformance } from './vocabulary-conformance';
+export type { VocabularyConformanceOptions } from './vocabulary-conformance';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/testing/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AACtG,YAAY,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAGxG,OAAO,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AACzE,YAAY,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/testing/index.js

@@ -0,0 +1,13 @@
+"use strict";
+// `@marinoscar/platform-api/core/testing`: kits for the core primitives
+// (PP-14.5, issue #923). Never import it from production code. Documented in
+// ../README.md ("Pluggable kinds").
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeVocabularyConformance = exports.describePluggableKindConformance = exports.SECRET_LIKE_FIELD_PATTERN = void 0;
+var pluggable_conformance_1 = require("./pluggable-conformance");
+Object.defineProperty(exports, "SECRET_LIKE_FIELD_PATTERN", { enumerable: true, get: function () { return pluggable_conformance_1.SECRET_LIKE_FIELD_PATTERN; } });
+Object.defineProperty(exports, "describePluggableKindConformance", { enumerable: true, get: function () { return pluggable_conformance_1.describePluggableKindConformance; } });
+// The open-vocabulary kit (PP-14.14): access reasons, credential kinds, error codes.
+var vocabulary_conformance_1 = require("./vocabulary-conformance");
+Object.defineProperty(exports, "describeVocabularyConformance", { enumerable: true, get: function () { return vocabulary_conformance_1.describeVocabularyConformance; } });
+//# sourceMappingURL=index.js.map

package/dist/core/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/testing/index.ts"],"names":[],"mappings":";AAAA,wEAAwE;AACxE,6EAA6E;AAC7E,oCAAoC;;;AAEpC,iEAAsG;AAA7F,kIAAA,yBAAyB,OAAA;AAAE,yIAAA,gCAAgC,OAAA;AAGpE,qFAAqF;AACrF,mEAAyE;AAAhE,uIAAA,6BAA6B,OAAA"}

package/dist/core/testing/pluggable-conformance.d.ts

@@ -0,0 +1,56 @@
+import type { PluggableKind } from '../pluggable/pluggable-kind';
+/**
+ * The test runner's own globals, passed in.
+ *
+ * @stability experimental
+ */
+export interface PluggableConformanceHarness {
+    /** The runner's `describe`. */
+    describe: (name: string, fn: () => void) => unknown;
+    /** The runner's `it`. Every case body the kit passes is a synchronous function. */
+    it: (name: string, fn: () => void) => unknown;
+    /** The runner's `expect`. */
+    expect: (actual: unknown) => any;
+}
+/**
+ * Options of {@link describePluggableKindConformance}.
+ *
+ * @stability experimental
+ */
+export interface PluggableConformanceOptions {
+    /**
+     * Settings field names that look like a secret but are not (an S3 `keyPrefix`,
+     * a `tokenLimit`). Matched exactly. Use sparingly: a real secret belongs in
+     * the implementation's `secrets`.
+     */
+    allowSecretLikeFields?: readonly string[];
+}
+/**
+ * The names the kit treats as secrets when they appear in a `settingsSchema`.
+ *
+ * @stability experimental
+ */
+export declare const SECRET_LIKE_FIELD_PATTERN: RegExp;
+/**
+ * Runs the conformance kit on every implementation currently registered in
+ * `kind`. Call it at the top level of a spec, after importing the file that
+ * registers the implementations, so they are registered when the cases are
+ * declared.
+ *
+ * @param kind - the kind under test.
+ * @param harness - the runner's `describe`, `it` and `expect`.
+ * @param options - see {@link PluggableConformanceOptions}.
+ *
+ * @example
+ * ```ts
+ * import '../../../src/app-registrations/core';
+ * import { describePluggableKindConformance } from '@marinoscar/platform-api/core/testing';
+ *
+ * describePluggableKindConformance(greeterKind, { describe, it, expect });
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function describePluggableKindConformance(kind: PluggableKind<any, any>, harness: PluggableConformanceHarness, options?: PluggableConformanceOptions): void;
+//# sourceMappingURL=pluggable-conformance.d.ts.map

package/dist/core/testing/pluggable-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluggable-conformance.d.ts","sourceRoot":"","sources":["../../../src/core/testing/pluggable-conformance.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+BAA+B;IAC/B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;IACpD,mFAAmF;IACnF,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;IAC9C,6BAA6B;IAC7B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,GAAG,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAA+B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,EAC7B,OAAO,EAAE,2BAA2B,EACpC,OAAO,GAAE,2BAAgC,GACxC,IAAI,CA+DN"}