@happyvertical/smrt-scanner 0.47.0 → 0.47.2

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as ManifestAdapter, t as OxcScanner } from "./chunks/scanner-9p-PUN-X.js";
+import { n as ManifestAdapter, t as OxcScanner } from "./chunks/scanner-CxUeI0FI.js";
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/index.d.ts

@@ -13,10 +13,15 @@ export declare interface AgentSurfaceCapability {
 }
 
 /**
- * A recognized declaration that is not emittable.
+ * Something a reader of the emitted surface has to know about a declaration.
  *
- * Never a silent omission: every message names `useWebMcpTool`, the escape
- * hatch for a genuinely computed tool set.
+ * Two kinds, and the difference is whether the entry survived. Every code but
+ * `tool-name-collision` reports a declaration that is NOT emitted — never a
+ * silent omission, so each of those messages names `useWebMcpTool`, the escape
+ * hatch for a genuinely computed tool set. A `tool-name-collision` is
+ * advisory: the declaration IS emitted, and the diagnostic records that its
+ * derived WebMCP tool name is already spoken for by something outside the
+ * declared surface.
  */
 export declare interface AgentSurfaceDiagnostic {
     code: AgentSurfaceDiagnosticCode;
@@ -28,7 +33,7 @@ export declare interface AgentSurfaceDiagnostic {
 }
 
 /** Why a recognized declaration could not be emitted. */
-export declare type AgentSurfaceDiagnosticCode = 'non-literal-argument' | 'not-module-scope' | 'argument-count' | 'incomplete-declaration' | 'invalid-identity' | 'svelte-declaration' | 'duplicate-identity';
+export declare type AgentSurfaceDiagnosticCode = 'non-literal-argument' | 'not-module-scope' | 'argument-count' | 'incomplete-declaration' | 'invalid-identity' | 'svelte-declaration' | 'duplicate-identity' | 'tool-name-collision';
 
 /**
  * Effect classification, mirroring `CapabilityEffect` in
@@ -92,6 +97,41 @@ export declare type AgentSurfacePlaybookStep = {
     id: string;
 };
 
+export declare interface AgentSurfaceToolNameOptions {
+    /**
+     * Generated model tool names for the SAME manifest, already filtered by the
+     * exposure policy.
+     *
+     * Filtered, not enumerated: comparing against every verb a class COULD
+     * expose would report collisions with tools that are never registered.
+     * `buildWebMcpToolDefinitions` in `@happyvertical/smrt-core/vite-plugin` is
+     * the function that emits the runtime definitions, so its output is the only
+     * honest input here.
+     */
+    generatedToolNames?: readonly GeneratedModelToolName[];
+    /**
+     * Prefixes the fixed UI tools are mounted under, defaulting to the
+     * registrar's own `smrt_ui_`.
+     *
+     * Supplied for the same reason `generatedToolNames` is: a name is compared
+     * against tools that will really register. Quantifying over every prefix an
+     * app COULD have configured — deriving the would-be prefix from the name —
+     * looks like more coverage and is the opposite. Under the default it has no
+     * true positive at all, because an id flattening to `smrt_ui_*` is rejected
+     * by {@link intentIdentityProblem} before it can become an entry, so every
+     * diagnostic such a rule emits for a default-configured app is false. A
+     * warning that is always wrong where it fires is worse than silence: it is
+     * persisted into the knowledge artifact, counted by `smrt doctor`, and
+     * clearable only by renaming an intent that was correct.
+     *
+     * There is no build-time source for this today — `ui.prefix` is a runtime
+     * `<Provider webmcp={{ ui: { prefix } }}>` prop — so the default leaves this
+     * half dormant. That is the honest state of it, and the seam is ready for
+     * the caller that can fill it.
+     */
+    uiToolPrefixes?: readonly string[];
+}
+
 declare interface ArrayExpression extends BaseNode {
     type: 'ArrayExpression';
     elements: (Expression | SpreadElement | null)[];
@@ -129,6 +169,57 @@ declare interface CallExpression extends BaseNode {
     typeParameters?: TSTypeParameterInstantiation;
 }
 
+/**
+ * Report an emitted intent whose derived WebMCP tool name is already spoken
+ * for by something OUTSIDE the declared surface (#2725).
+ *
+ * `mergeAgentSurfaces` resolves the collisions it can see on its own —
+ * intent vs intent, where `intentToolName` is not injective. It cannot see the
+ * two sources that live outside the declaration set:
+ *
+ * - **generated model tools**, `${className.toLowerCase()}_${action}`, so
+ *   `defineIntent({ id: 'product.list' })` lands exactly on `Product.list`;
+ * - **the six fixed UI tools** under a CUSTOM `webmcp.ui.prefix`. The default
+ *   `smrt_ui_` is already a hard rejection in {@link intentIdentityProblem},
+ *   mirroring `defineIntent`; a custom prefix is not, because `defineIntent`
+ *   accepts such an id and the intent really does register.
+ *
+ * ### These are warnings, not drops — unlike intent vs intent
+ *
+ * The asymmetry is real and it is the whole reason this is a separate pass.
+ * Two colliding intents are a closed question: `defineIntent` REJECTS the
+ * second declaration, so only one can exist and emitting both would overstate
+ * the surface by an entry that cannot be. Neither collision here is closed:
+ *
+ * - `defineIntent` accepts the intent, so the declaration is real and the
+ *   entry belongs in the artifact. Dropping it would make the emitted surface
+ *   disagree with the source, which is the failure this module exists to
+ *   prevent;
+ * - which registration survives is decided at mount by the document-global
+ *   tool-name lock (#2613), which rejects the second with a
+ *   `WebMcpToolNameCollisionError` naming the owner. That is a runtime answer
+ *   to a question the build can already see coming, and it costs whoever loses
+ *   its tool; the build-time notice is the earlier, cheaper one;
+ * - and whether it happens at all depends on runtime values no artifact
+ *   records: a WebMCP `namespace` moves every generated tool out of the way,
+ *   an `effects` policy can exclude the action, and a page need not mount
+ *   both. A build-time drop would be a guess about all three.
+ *
+ * So the entry stays and the report is advisory. The message names both sides,
+ * the consequence, and — because those runtime values are unknowable here and
+ * a `namespace` genuinely dissolves the collision — the precondition under
+ * which it holds. Without that last part a namespaced app gets a notice that
+ * is always wrong where it fires, recommending the very remedy it already
+ * applied, with renaming a correct intent as the only clearing action. That is
+ * the standard `uiToolPrefixes` exists to meet; the generated half has to meet
+ * it too, and it does so in the message because the caller CAN supply
+ * namespaced names when it knows them.
+ *
+ * @param surface - A MERGED surface; intent-vs-intent losers are already gone.
+ * @returns Diagnostics only. The caller appends them; nothing is removed.
+ */
+export declare function checkAgentSurfaceToolNames(surface: AgentSurface, options?: AgentSurfaceToolNameOptions): AgentSurfaceDiagnostic[];
+
 declare interface ClassBody extends BaseNode {
     type: 'ClassBody';
     body: ClassElement[];
@@ -314,6 +405,28 @@ declare interface FunctionExpression extends BaseNode {
     body: BlockStatement;
 }
 
+/**
+ * One WebMCP tool name the build will register for a generated model action,
+ * supplied by the caller that knows the exposure policy.
+ */
+export declare interface GeneratedModelToolName {
+    /**
+     * The tool name EXACTLY as it will be registered.
+     *
+     * This pass never derives a generated name and never applies a namespace of
+     * its own: it compares the strings it is handed. That is deliberate. The
+     * WebMCP `namespace` is a runtime `<Provider webmcp={{ namespace }}>` value
+     * that no build artifact records, so inventing a build-time declaration of
+     * it here would create a second place to say what the provider already says,
+     * free to disagree with it silently. Taking names instead means a caller
+     * that ever does know the namespace qualifies them itself and nothing in
+     * this module changes.
+     */
+    name: string;
+    /** What owns that name, for the message — e.g. `Product.list`. */
+    declaredBy?: string;
+}
+
 declare interface Identifier extends BaseNode {
     type: 'Identifier';
     name: string;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as sourceMayDeclareAgentSurface, a as parseFile, c as discoverSourceFiles, d as emptyAgentSurface, f as extractAgentSurface, g as scanSvelteAgentSurface, h as mergeAgentSurfaces, i as parseAgentSurfaceFile, l as normalizeGlobSeparators, m as isPrunedAgentSurfacePath, n as ManifestAdapter, o as parseSource, p as isAgentSurfaceSourcePath, r as extractSmrtImports, s as InheritanceResolver, t as OxcScanner, u as relativeGlobToCwd } from "./chunks/scanner-9p-PUN-X.js";
+import { _ as scanSvelteAgentSurface, a as parseFile, c as discoverSourceFiles, d as checkAgentSurfaceToolNames, f as emptyAgentSurface, g as mergeAgentSurfaces, h as isPrunedAgentSurfacePath, i as parseAgentSurfaceFile, l as normalizeGlobSeparators, m as isAgentSurfaceSourcePath, n as ManifestAdapter, o as parseSource, p as extractAgentSurface, r as extractSmrtImports, s as InheritanceResolver, t as OxcScanner, u as relativeGlobToCwd, v as sourceMayDeclareAgentSurface } from "./chunks/scanner-CxUeI0FI.js";
 import "./types.js";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
@@ -272,6 +272,6 @@ async function verifyManifestCompleteness(options) {
 	};
 }
 //#endregion
-export { InheritanceResolver, ManifestAdapter, OxcScanner, classifyNumericFieldName, discoverSourceFiles, emptyAgentSurface, extractAgentSurface, extractSmrtImports, isAgentSurfaceSourcePath, isPrunedAgentSurfacePath, lintNumericPrecision, mergeAgentSurfaces, normalizeGlobSeparators, parseAgentSurfaceFile, parseFile, parseSource, relativeGlobToCwd, scanSvelteAgentSurface, sourceMayContainNumericPrecisionIssue, sourceMayDeclareAgentSurface, splitIdentifierWords, verifyManifestCompleteness };
+export { InheritanceResolver, ManifestAdapter, OxcScanner, checkAgentSurfaceToolNames, classifyNumericFieldName, discoverSourceFiles, emptyAgentSurface, extractAgentSurface, extractSmrtImports, isAgentSurfaceSourcePath, isPrunedAgentSurfacePath, lintNumericPrecision, mergeAgentSurfaces, normalizeGlobSeparators, parseAgentSurfaceFile, parseFile, parseSource, relativeGlobToCwd, scanSvelteAgentSurface, sourceMayContainNumericPrecisionIssue, sourceMayDeclareAgentSurface, splitIdentifierWords, verifyManifestCompleteness };
 
 //# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -13,10 +13,15 @@ export declare interface AgentSurfaceCapability {
 }
 
 /**
- * A recognized declaration that is not emittable.
+ * Something a reader of the emitted surface has to know about a declaration.
  *
- * Never a silent omission: every message names `useWebMcpTool`, the escape
- * hatch for a genuinely computed tool set.
+ * Two kinds, and the difference is whether the entry survived. Every code but
+ * `tool-name-collision` reports a declaration that is NOT emitted — never a
+ * silent omission, so each of those messages names `useWebMcpTool`, the escape
+ * hatch for a genuinely computed tool set. A `tool-name-collision` is
+ * advisory: the declaration IS emitted, and the diagnostic records that its
+ * derived WebMCP tool name is already spoken for by something outside the
+ * declared surface.
  */
 export declare interface AgentSurfaceDiagnostic {
     code: AgentSurfaceDiagnosticCode;
@@ -28,7 +33,7 @@ export declare interface AgentSurfaceDiagnostic {
 }
 
 /** Why a recognized declaration could not be emitted. */
-export declare type AgentSurfaceDiagnosticCode = 'non-literal-argument' | 'not-module-scope' | 'argument-count' | 'incomplete-declaration' | 'invalid-identity' | 'svelte-declaration' | 'duplicate-identity';
+export declare type AgentSurfaceDiagnosticCode = 'non-literal-argument' | 'not-module-scope' | 'argument-count' | 'incomplete-declaration' | 'invalid-identity' | 'svelte-declaration' | 'duplicate-identity' | 'tool-name-collision';
 
 /**
  * Effect classification, mirroring `CapabilityEffect` in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-scanner",
-  "version": "0.47.0",
+  "version": "0.47.2",
   "description": "High-performance TypeScript scanner using OXC for SMRT manifest generation",
   "author": "HappyVertical",
   "type": "module",