@smthrs/plugin 1.0.0-rc.7 → 1.0.0-rc.9

package/docs/installation.md

@@ -7,7 +7,11 @@ sidebar:
 
 ## Install the package
 
-Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+```bash
+npm install @smthrs/plugin@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
 
 Install `effect` explicitly, in the range `^4.0.4`. The kernel depends on it, but your
 plugins import `Effect`, `Layer`, and `Option` directly, so `effect` belongs in

package/docs/quickstart.md

@@ -16,7 +16,8 @@ defines the plugins and runs the host. There are no services to provide.
 ## Prerequisites
 
 - Node.js 26.4.0 or later.
-- A TypeScript project with the package installed. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+- A TypeScript project with the package installed:
+  `npm install @smthrs/plugin@next effect`.
 
 ## Declare the host's hook catalog
 

package/docs/troubleshooting.md

@@ -45,7 +45,8 @@ At startup, `Options.hooks` labelled `config` with a kind other than
 `waterfall`, or `configResolved` with a kind other than `parallel`; the path
 names the entry, such as `$options.hooks.config`. At dispatch, a method was
 called for a hook the catalog declares with a different kind, which only a cast
-around the typed dispatcher can reach. In both cases no handler ran.
+around the typed dispatcher can reach, or for a hook a hand-built `Resolved`
+gave handlers without declaring it in `kinds`. In every case no handler ran.
 
 **What to change.** Make the catalog agree with the hook interface: spread
 `engineHooks` for the shared hooks and write each of your own hooks with the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/plugin",
   "type": "module",
-  "version": "1.0.0-rc.7",
+  "version": "1.0.0-rc.9",
   "license": "MIT",
   "smthrs": {
     "group": "agent"
@@ -145,8 +145,8 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/canonical": "1.0.0-rc.7",
-    "@smthrs/flow": "1.0.0-rc.7"
+    "@smthrs/canonical": "1.0.0-rc.9",
+    "@smthrs/flow": "1.0.0-rc.9"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",
@@ -171,7 +171,7 @@
     "effect": "^4.0.4"
   },
   "scripts": {
-    "lint": "eslint src --max-warnings=0 && dprint check",
+    "lint": "eslint src examples --max-warnings=0 && dprint check",
     "format": "dprint fmt",
     "build": "node scripts/build.mjs",
     "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",

package/src/Plugins.ts

@@ -32,8 +32,23 @@ const empty: ReadonlyArray<HandlerRecord> = Object.freeze([])
 // The typed catalog and the runtime catalog can only drift when a host casts
 // around `KeysOfKind`; refuse before any handler runs rather than execute a
 // hook under semantics its declaration never promised.
-const kindMismatch = (resolved: Resolved<unknown>, hook: string, kind: HookKind): PluginError | undefined => {
-  if (!Object.hasOwn(resolved.kinds, hook)) return undefined
+// A hook the catalog does not declare dispatches as empty, unless a
+// hand-built resolution registered handlers for it: those have no declared
+// kind to honor, so they are refused too.
+const kindMismatch = (
+  resolved: Resolved<unknown>,
+  hook: string,
+  kind: HookKind,
+  handlers: ReadonlyArray<HandlerRecord>
+): PluginError | undefined => {
+  if (!Object.hasOwn(resolved.kinds, hook)) {
+    if (handlers.length === 0) return undefined
+    return new PluginError({
+      code: "hook_kind_mismatch",
+      message: `hook "${hook}" has handlers but is not declared in the runtime catalog`,
+      hook
+    })
+  }
   const declared = resolved.kinds[hook]
   if (declared === kind) return undefined
   return new PluginError({
@@ -125,7 +140,7 @@ export const make = <H = FlowsHooks>(resolved: Resolved<H>): Service<H> => {
 
   const sequential = ((hook: string, ...args: Array<unknown>) =>
     Effect.gen(function*() {
-      const mismatch = kindMismatch(resolved, hook, "sequential")
+      const mismatch = kindMismatch(resolved, hook, "sequential", handlers(hook))
       if (mismatch !== undefined) return yield* Effect.fail(mismatch)
       const results: Array<unknown> = []
       for (const record of handlers(hook)) {
@@ -135,7 +150,7 @@ export const make = <H = FlowsHooks>(resolved: Resolved<H>): Service<H> => {
     })) as Service<H>["sequential"]
 
   const parallel = ((hook: string, ...args: Array<unknown>) => {
-    const mismatch = kindMismatch(resolved, hook, "parallel")
+    const mismatch = kindMismatch(resolved, hook, "parallel", handlers(hook))
     if (mismatch !== undefined) return Effect.succeed([mismatch])
     return Effect.forEach(
       handlers(hook),
@@ -149,7 +164,7 @@ export const make = <H = FlowsHooks>(resolved: Resolved<H>): Service<H> => {
 
   const first = ((hook: string, ...args: Array<unknown>) =>
     Effect.gen(function*() {
-      const mismatch = kindMismatch(resolved, hook, "first")
+      const mismatch = kindMismatch(resolved, hook, "first", handlers(hook))
       if (mismatch !== undefined) return yield* Effect.fail(mismatch)
       for (const record of handlers(hook)) {
         const result = yield* runHandler(record, args)
@@ -171,7 +186,7 @@ export const make = <H = FlowsHooks>(resolved: Resolved<H>): Service<H> => {
   const waterfall =
     ((hook: string, initial: unknown, merge: (previous: unknown, patch: unknown) => unknown) =>
       Effect.gen(function*() {
-        const mismatch = kindMismatch(resolved, hook, "waterfall")
+        const mismatch = kindMismatch(resolved, hook, "waterfall", handlers(hook))
         if (mismatch !== undefined) return yield* Effect.fail(mismatch)
         let value = initial
         for (const record of handlers(hook)) {
@@ -186,13 +201,15 @@ export const make = <H = FlowsHooks>(resolved: Resolved<H>): Service<H> => {
                     message: cause.message,
                     plugin: record.plugin,
                     hook: record.hook,
-                    path: cause.path
+                    path: cause.path,
+                    cause
                   })
                   : new PluginError({
                     code: "config_invalid",
                     message: `waterfall hook "${record.hook}" in plugin "${record.plugin}" returned an invalid patch`,
                     plugin: record.plugin,
-                    hook: record.hook
+                    hook: record.hook,
+                    cause
                   })
             })
           }

package/src/Resolve.ts

@@ -161,22 +161,25 @@ const childPath = (path: string, key: string): string => {
 const ownData = (
   input: unknown,
   path: string,
-  allowed?: ReadonlySet<string>
+  allowed?: ReadonlySet<string>,
+  fields: { readonly plugin?: string; readonly hook?: string } = {}
 ): Readonly<Record<string, unknown>> => {
   if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    throw invalidPlugin(path, "must be an ordinary record")
+    throw invalidPlugin(path, "must be an ordinary record", fields)
   }
   const prototype = Object.getPrototypeOf(input)
-  if (prototype !== Object.prototype && prototype !== null) throw invalidPlugin(path, "must be an ordinary record")
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw invalidPlugin(path, "must be an ordinary record", fields)
+  }
   const output: Record<string, unknown> = {}
   for (const key of Reflect.ownKeys(input)) {
-    if (typeof key !== "string") throw invalidPlugin(path, "must not contain symbol keys")
+    if (typeof key !== "string") throw invalidPlugin(path, "must not contain symbol keys", fields)
     if (allowed !== undefined && !allowed.has(key)) {
-      throw invalidPlugin(childPath(path, key), "contains an unknown property")
+      throw invalidPlugin(childPath(path, key), "contains an unknown property", fields)
     }
     const descriptor = Object.getOwnPropertyDescriptor(input, key)
     if (descriptor === undefined || !("value" in descriptor) || !descriptor.enumerable) {
-      throw invalidPlugin(childPath(path, key), "must be an enumerable data property")
+      throw invalidPlugin(childPath(path, key), "must be an enumerable data property", fields)
     }
     Object.defineProperty(output, key, { value: descriptor.value, enumerable: true })
   }
@@ -249,7 +252,7 @@ const snapshotHook = (
   if (entry === undefined) {
     throw invalidPlugin(path, "must be a function or a hook object", { plugin, hook })
   }
-  const values = ownData(entry, path, new Set(["order", "handler"]))
+  const values = ownData(entry, path, new Set(["order", "handler"]), { plugin, hook })
   if (typeof values.handler !== "function") {
     throw invalidPlugin(`${path}.handler`, "must be a function", { plugin, hook })
   }
@@ -285,11 +288,11 @@ const snapshotPlugin = <H>(
 
   let hooks: Readonly<Record<string, unknown>> | undefined
   if (values.hooks !== undefined) {
-    const rawHooks = ownData(values.hooks, `${path}.hooks`)
+    const rawHooks = ownData(values.hooks, `${path}.hooks`, undefined, { plugin: name })
     const snapshot: Record<string, unknown> = Object.create(null)
     for (const [index, hook] of Object.keys(rawHooks).entries()) {
       if (!validName(hook)) {
-        throw invalidPlugin(`${path}.hooks[${index}]`, "contains an invalid hook name")
+        throw invalidPlugin(`${path}.hooks[${index}]`, "contains an invalid hook name", { plugin: name })
       }
       const entry = rawHooks[hook]
       Object.defineProperty(snapshot, hook, {
@@ -360,7 +363,7 @@ const flatten = <H>(input: unknown): ReadonlyArray<AdmittedPlugin<H>> => {
 }
 
 const included = <H>(
-  plugin: FlowsPlugin<H>,
+  { path, plugin }: AdmittedPlugin<H>,
   config: FlowsConfig,
   target: "engine" | "harness"
 ): Effect.Effect<boolean, PluginError> => {
@@ -370,14 +373,14 @@ const included = <H>(
   return Effect.try({
     try: () => apply(config),
     catch: () =>
-      failure("apply_failed", `plugin "${plugin.name}" apply predicate failed`, "$.apply", {
+      failure("apply_failed", `plugin "${plugin.name}" apply predicate failed`, `${path}.apply`, {
         plugin: plugin.name
       })
   }).pipe(
     Effect.flatMap((result) =>
       typeof result === "boolean"
         ? Effect.succeed(result)
-        : Effect.fail(invalidPlugin("$.apply", "predicate must return a boolean", { plugin: plugin.name }))
+        : Effect.fail(invalidPlugin(`${path}.apply`, "predicate must return a boolean", { plugin: plugin.name }))
     )
   )
 }
@@ -443,7 +446,7 @@ export const resolve = <H = FlowsHooks>(
           : invalidPlugin("$", "could not be inspected without executing user code")
     })
     const target = raw.target ?? "engine"
-    const selected = yield* Effect.filter(admitted, ({ plugin }) => included(plugin, config, target))
+    const selected = yield* Effect.filter(admitted, (entry) => included(entry, config, target))
 
     let handlerCount = 0
     for (const { path, plugin } of selected) {
@@ -470,24 +473,25 @@ export const resolve = <H = FlowsHooks>(
     }
 
     const seen = new Set<string>()
-    for (const { plugin } of selected) {
+    for (const { path, plugin } of selected) {
       if (seen.has(plugin.name)) {
         return yield* Effect.fail(failure(
           "duplicate_name",
           `duplicate plugin name "${plugin.name}"`,
-          "$.name",
+          `${path}.name`,
           { plugin: plugin.name }
         ))
       }
       seen.add(plugin.name)
     }
 
-    const plugins = Object.freeze(
-      selected
-        .map(({ plugin }, index) => ({ plugin, index }))
-        .sort((left, right) => rank(left.plugin.enforce) - rank(right.plugin.enforce) || left.index - right.index)
-        .map(({ plugin }) => plugin)
-    )
+    const orderedEntries = selected
+      .map((entry, index) => ({ entry, index }))
+      .sort((left, right) =>
+        rank(left.entry.plugin.enforce) - rank(right.entry.plugin.enforce) || left.index - right.index
+      )
+      .map(({ entry }) => entry)
+    const plugins = Object.freeze(orderedEntries.map(({ plugin }) => plugin))
     const entries: Array<readonly [string, ReadonlyArray<HandlerRecord>]> = []
     for (const hook of Object.keys(known)) {
       const records: Array<{
@@ -514,7 +518,7 @@ export const resolve = <H = FlowsHooks>(
         .map(({ record }) => record)
       if (ordered.length > 0) entries.push([hook, Object.freeze(ordered)])
     }
-    const cacheEnvironment = yield* snapshotCacheEnvironment(raw.cacheEnvironment, plugins)
+    const cacheEnvironment = yield* snapshotCacheEnvironment(raw.cacheEnvironment, orderedEntries)
     return Object.freeze({
       plugins,
       handlers: ImmutableMap.make(entries),

package/src/internal/snapshotCacheEnvironment.ts

@@ -18,24 +18,25 @@ const escapePluginIdentityPart = (value: string): string =>
 
 /**
  * Admits a caller cache environment and prepends one escaped `name@version`
- * identity per plugin, in resolved order. An absent input stays absent.
+ * identity per plugin, in resolved order. An absent input stays absent. A
+ * versionless plugin is refused at the dollar-path it was admitted from.
  *
  * @private
  * @since 1.0.0-rc.0
  */
 export const snapshotCacheEnvironment = <H>(
   input: unknown,
-  plugins: ReadonlyArray<FlowsPlugin<H>>
+  plugins: ReadonlyArray<{ readonly plugin: FlowsPlugin<H>; readonly path: string }>
 ): Effect.Effect<Action.CacheEnvironment | undefined, PluginError> => {
   if (input === undefined) return Effect.succeed(undefined)
   const pluginIdentities: Array<string> = []
-  for (const plugin of plugins) {
+  for (const { path, plugin } of plugins) {
     if (plugin.version === undefined) {
       return Effect.fail(
         new PluginError({
           code: "cache_environment_invalid",
           message: `cache environment requires a version for plugin "${plugin.name}"`,
-          path: "$.version",
+          path: `${path}.version`,
           plugin: plugin.name
         })
       )