@happyvertical/smrt-scanner 0.46.0 → 0.47.1

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as ManifestAdapter, t as OxcScanner } from "./chunks/scanner-C3VqXyzB.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;
@@ -863,11 +976,19 @@ declare interface MethodDefinition {
         type: string;
         optional: boolean;
         default?: unknown;
+        /** See `RawParameterDefinition.typeUnresolved` (#2686). */
+        typeUnresolved?: boolean;
+        /** See `RawParameterDefinition.memberTypes` (#2686). */
+        memberTypes?: string[];
+        /** See `RawParameterDefinition.unionBranches` (#2686). */
+        unionBranches?: ParameterTypeBranch[];
     }>;
     returnType: string;
     description?: string;
     isStatic: boolean;
     isPublic: boolean;
+    /** Config of an `@method()` decorator on this method (#2686). */
+    decoratorConfig?: Record<string, unknown>;
 }
 
 declare interface MethodDefinition_2 extends BaseNode {
@@ -878,6 +999,7 @@ declare interface MethodDefinition_2 extends BaseNode {
     computed: boolean;
     static: boolean;
     accessibility?: 'public' | 'private' | 'protected';
+    decorators?: Decorator[];
 }
 
 declare interface NewExpression extends BaseNode {
@@ -1218,6 +1340,14 @@ export declare interface OxcScannerOptions {
     agentSurfaceInclude?: string[];
 }
 
+/** One branch of a top-level union parameter type (#2686). */
+export declare interface ParameterTypeBranch {
+    /** The branch's own type name, e.g. `string` or `object`. */
+    type: string;
+    /** Inline object members declared by THIS branch only. */
+    memberTypes?: string[];
+}
+
 /**
  * Read one file for agent-surface declarations ONLY (#2591).
  *
@@ -1456,6 +1586,17 @@ export declare interface RawMethodDefinition {
     returnType: string | null;
     /** JSDoc description if present */
     description: string | null;
+    /**
+     * Config object of an `@method()` decorator on this method, when one is
+     * present. `{}` for a bare `@method()`; `undefined` when the method carries
+     * no `@method()` decorator at all — the two are distinct, because an
+     * explicit bare decorator still marks the method as deliberately reviewed.
+     *
+     * Values are extracted with the same literal-only rules the class-level
+     * `@smrt()` config uses, so an expression the scanner cannot resolve becomes
+     * a scan error rather than a silently dropped `expose: false`.
+     */
+    decoratorConfig?: Record<string, unknown>;
     /** Start line in source */
     line: number;
 }
@@ -1472,6 +1613,45 @@ export declare interface RawParameterDefinition {
     optional: boolean;
     /** Default value as string */
     defaultValue: string | null;
+    /**
+     * True when the parameter carries a type annotation the scanner could not
+     * express as a string — an intersection, tuple, conditional, mapped,
+     * `typeof`, or indexed-access type — or when an inline object literal
+     * contains such a member.
+     *
+     * This is the provenance that separates "the author wrote `any`" from "the
+     * scanner gave up": both previously reached the manifest as the string
+     * `'any'`. Consumers that must fail closed on an uncertain type (the API
+     * wire-ability gate) read this rather than trusting `type`.
+     *
+     * `type: null` with `typeUnresolved` absent means the parameter simply has
+     * no annotation, which is an implicit — and genuinely authored — `any`.
+     */
+    typeUnresolved?: boolean;
+    /**
+     * Resolved member types of an INLINE object-literal annotation
+     * (`{ onDone: () => void; target: Content }` → `['Function', 'Content']`),
+     * flattened across nested literals, arrays, and unions.
+     *
+     * `extractTypeName` collapses every inline literal to the single string
+     * `'object'`, which erases exactly the members a caller needs to judge
+     * whether the bag can cross a wire. NAMED bags (an interface, type alias,
+     * `Partial<>`/`Pick<>`) are deliberately NOT expanded — resolving them needs
+     * cross-file type resolution this AST layer does not do, and they are
+     * accepted heuristically by the consumers that care.
+     */
+    memberTypes?: string[];
+    /**
+     * For a top-level UNION, each branch with the inline members IT declared.
+     *
+     * `memberTypes` above flattens across branches, which lets one branch veto
+     * another: `{ callback: () => void } | string` is wire-able through its
+     * string branch, but the flattened `Function` rejected the whole parameter.
+     * A consumer that understands this field MUST prefer it over `memberTypes`
+     * for unions. Absent on a non-union parameter and on manifests generated
+     * before #2686.
+     */
+    unionBranches?: ParameterTypeBranch[];
 }
 
 /** Preserve relative glob escapes; normalize separators only after rewriting. */
@@ -1659,6 +1839,10 @@ declare interface TSArrayType extends BaseNode {
     elementType: TSType;
 }
 
+declare interface TSBigIntKeyword extends BaseNode {
+    type: 'TSBigIntKeyword';
+}
+
 declare interface TSBooleanKeyword extends BaseNode {
     type: 'TSBooleanKeyword';
 }
@@ -1702,6 +1886,10 @@ declare interface TSMethodSignature extends BaseNode {
     returnType?: TSTypeAnnotation;
 }
 
+declare interface TSNeverKeyword extends BaseNode {
+    type: 'TSNeverKeyword';
+}
+
 declare interface TSNullKeyword extends BaseNode {
     type: 'TSNullKeyword';
 }
@@ -1710,6 +1898,10 @@ declare interface TSNumberKeyword extends BaseNode {
     type: 'TSNumberKeyword';
 }
 
+declare interface TSObjectKeyword extends BaseNode {
+    type: 'TSObjectKeyword';
+}
+
 declare interface TSPropertySignature extends BaseNode {
     type: 'TSPropertySignature';
     key: Expression;
@@ -1728,7 +1920,15 @@ declare interface TSStringKeyword extends BaseNode {
     type: 'TSStringKeyword';
 }
 
-declare type TSType = TSStringKeyword | TSNumberKeyword | TSBooleanKeyword | TSAnyKeyword | TSVoidKeyword | TSNullKeyword | TSUndefinedKeyword | TSTypeReference | TSArrayType | TSUnionType | TSTypeLiteral | TSLiteralType | TSFunctionType;
+declare interface TSSymbolKeyword extends BaseNode {
+    type: 'TSSymbolKeyword';
+}
+
+declare interface TSThisType extends BaseNode {
+    type: 'TSThisType';
+}
+
+declare type TSType = TSStringKeyword | TSNumberKeyword | TSBooleanKeyword | TSAnyKeyword | TSUnknownKeyword | TSNeverKeyword | TSObjectKeyword | TSBigIntKeyword | TSSymbolKeyword | TSVoidKeyword | TSNullKeyword | TSUndefinedKeyword | TSThisType | TSTypeReference | TSArrayType | TSUnionType | TSTypeLiteral | TSLiteralType | TSFunctionType;
 
 declare interface TSTypeAliasDeclaration extends BaseNode {
     type: 'TSTypeAliasDeclaration';
@@ -1769,6 +1969,10 @@ declare interface TSUnionType extends BaseNode {
     types: TSType[];
 }
 
+declare interface TSUnknownKeyword extends BaseNode {
+    type: 'TSUnknownKeyword';
+}
+
 declare interface TSVoidKeyword extends BaseNode {
     type: 'TSVoidKeyword';
 }

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-C3VqXyzB.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
@@ -250,6 +255,14 @@ export declare interface OxcScannerOptions {
     agentSurfaceInclude?: string[];
 }
 
+/** One branch of a top-level union parameter type (#2686). */
+export declare interface ParameterTypeBranch {
+    /** The branch's own type name, e.g. `string` or `object`. */
+    type: string;
+    /** Inline object members declared by THIS branch only. */
+    memberTypes?: string[];
+}
+
 /**
  * Type definitions for OXC-based SMRT scanner
  *
@@ -377,6 +390,17 @@ export declare interface RawMethodDefinition {
     returnType: string | null;
     /** JSDoc description if present */
     description: string | null;
+    /**
+     * Config object of an `@method()` decorator on this method, when one is
+     * present. `{}` for a bare `@method()`; `undefined` when the method carries
+     * no `@method()` decorator at all — the two are distinct, because an
+     * explicit bare decorator still marks the method as deliberately reviewed.
+     *
+     * Values are extracted with the same literal-only rules the class-level
+     * `@smrt()` config uses, so an expression the scanner cannot resolve becomes
+     * a scan error rather than a silently dropped `expose: false`.
+     */
+    decoratorConfig?: Record<string, unknown>;
     /** Start line in source */
     line: number;
 }
@@ -393,6 +417,45 @@ export declare interface RawParameterDefinition {
     optional: boolean;
     /** Default value as string */
     defaultValue: string | null;
+    /**
+     * True when the parameter carries a type annotation the scanner could not
+     * express as a string — an intersection, tuple, conditional, mapped,
+     * `typeof`, or indexed-access type — or when an inline object literal
+     * contains such a member.
+     *
+     * This is the provenance that separates "the author wrote `any`" from "the
+     * scanner gave up": both previously reached the manifest as the string
+     * `'any'`. Consumers that must fail closed on an uncertain type (the API
+     * wire-ability gate) read this rather than trusting `type`.
+     *
+     * `type: null` with `typeUnresolved` absent means the parameter simply has
+     * no annotation, which is an implicit — and genuinely authored — `any`.
+     */
+    typeUnresolved?: boolean;
+    /**
+     * Resolved member types of an INLINE object-literal annotation
+     * (`{ onDone: () => void; target: Content }` → `['Function', 'Content']`),
+     * flattened across nested literals, arrays, and unions.
+     *
+     * `extractTypeName` collapses every inline literal to the single string
+     * `'object'`, which erases exactly the members a caller needs to judge
+     * whether the bag can cross a wire. NAMED bags (an interface, type alias,
+     * `Partial<>`/`Pick<>`) are deliberately NOT expanded — resolving them needs
+     * cross-file type resolution this AST layer does not do, and they are
+     * accepted heuristically by the consumers that care.
+     */
+    memberTypes?: string[];
+    /**
+     * For a top-level UNION, each branch with the inline members IT declared.
+     *
+     * `memberTypes` above flattens across branches, which lets one branch veto
+     * another: `{ callback: () => void } | string` is wire-able through its
+     * string branch, but the flattened `Function` rejected the whole parameter.
+     * A consumer that understands this field MUST prefer it over `memberTypes`
+     * for unions. Absent on a non-union parameter and on manifests generated
+     * before #2686.
+     */
+    unionBranches?: ParameterTypeBranch[];
 }
 
 /**

package/package.json

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