@happyvertical/smrt-scanner 0.51.32 → 0.51.33

package/AGENTS.md

@@ -306,3 +306,12 @@ place, `toKnowledgeAgentSurface` in `vite-plugin/index.ts`.
   invoking it. Any other expression (a call, a computed reference) yields
   `related: undefined` — writing the raw source through produced a garbage FK
   table name and, once FK columns are indexed, a garbage index (#2379).
+
+
+## Filesystem knowledge
+
+The public `@happyvertical/smrt-scanner/knowledge` entry owns filesystem-only
+package/doc discovery, linked module-doc parsing, and knowledge-graph freshness.
+Core's existing knowledge entrypoints reexport these implementations for
+compatibility. Keep this entry free of ORM, SQL, AI, and configuration runtime
+imports so standalone development tooling remains lightweight.

package/dist/agent-surface.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Agent-surface matcher (#2591).
+ *
+ * The class scanner discovers `@smrt()`-decorated classes by matching
+ * DECORATORS. Neither a view intent (#2588) nor a playbook (#2589) is a class,
+ * so this module adds the second recognizable shape the framework emits from:
+ * a **module-scope call with a single object-literal argument**.
+ *
+ * ```ts
+ * import { defineIntent } from '@happyvertical/smrt-web/intents';
+ * export const nextPage = defineIntent({ id: 'orders.next_page', ... });
+ * ```
+ *
+ * It keeps exactly the discipline the decorator matcher keeps:
+ *
+ * - **structural only** — nothing is evaluated, no import is followed, no
+ *   module is loaded. A value that is not spelled literally in the argument is
+ *   not a value this matcher can read;
+ * - **never a silent drop** — every declaration this matcher recognizes but
+ *   cannot read produces a diagnostic naming `useWebMcpTool`, the documented
+ *   escape hatch for a tool set that genuinely cannot be static. A declaration
+ *   that vanishes from the emitted surface without a word is the failure mode
+ *   this module exists to prevent;
+ * - **binding-aware** — a call is matched only when its callee resolves to an
+ *   import binding from the ONE accepted specifier per helper. A local helper
+ *   that happens to be named `defineIntent` is not a view intent.
+ *
+ * Accepted import specifiers, exactly:
+ *
+ * | Helper | Specifier |
+ * | --- | --- |
+ * | `defineIntent` | `@happyvertical/smrt-web/intents` |
+ * | `definePlaybook` | `@happyvertical/smrt-playbooks` |
+ *
+ * `defineIntent` deliberately ships ONLY from the `/intents` subpath entry, so
+ * an `OrderTable.intents.ts` sidecar never drags the client-data engine into a
+ * page (see `packages/smrt-web/AGENTS.md`). Recognizing the subpath and not the
+ * package root is therefore part of the contract, not an omission.
+ */
+import type { AgentSurface, AgentSurfaceDiagnostic } from './types.js';
+/**
+ * Whether the agent-surface emitter reads this file. **This is the one
+ * authority on that question.**
+ *
+ * Both the scanner's declaration pass and `dev:knowledge-check`'s freshness
+ * re-scan call it, because the two answering differently is not a cosmetic
+ * inconsistency: a file the emitter reads but the checker skips is reported as
+ * "no longer present in source" on every run, and a file the checker reads but
+ * the emitter skips is reported as "missing from smrt-knowledge.json" — both
+ * unclearable by any rebuild. It is a path predicate rather than a glob so the
+ * two sides cannot drift through differing glob semantics either.
+ *
+ * Callers still pass globs to prune the WALK for speed; this decides what
+ * counts.
+ */
+export declare function isAgentSurfaceSourcePath(filePath: string, rootDir?: string): boolean;
+/**
+ * Whether a path lies in a directory declarations are never read from,
+ * measured **relative to the project root**.
+ *
+ * `rootDir` is not optional in spirit. Matching these segments against an
+ * absolute path would disable the entire feature for a checkout that merely
+ * LIVES under one — a container with `WORKDIR /build`, or a clone in
+ * `~/build/…` — and it would do so with no diagnostic at all, because the
+ * freshness check applies the same predicate and would agree that nothing is
+ * declared. That is the silent drop this module exists to prevent, so the same
+ * care `discovery.ts` takes to rewrite globs relative to `cwd` applies here.
+ *
+ * Exported so the `.svelte` pass and `dev:knowledge-check`'s walk prune
+ * identically; a `.svelte` file cannot go through
+ * {@link isAgentSurfaceSourcePath}, which rejects it on extension.
+ */
+export declare function isPrunedAgentSurfacePath(filePath: string, rootDir?: string): boolean;
+export interface ExtractAgentSurfaceOptions {
+    /** Program body from an OXC parse. */
+    body: readonly unknown[];
+    /** Full source text, used for diagnostic line/column. */
+    sourceText: string;
+    /** Path recorded on every emitted entry and diagnostic. */
+    filePath: string;
+}
+/**
+ * Fast pre-check: a file that names neither helper cannot declare either, so
+ * the AST walk is skipped entirely. Callers use it to keep the matcher off the
+ * hot path of a large scan.
+ */
+export declare function sourceMayDeclareAgentSurface(sourceText: string): boolean;
+/**
+ * Match `defineIntent(...)` / `definePlaybook(...)` declarations in one parsed
+ * module.
+ *
+ * @returns Emittable entries plus a diagnostic for every recognized call that
+ *   is not emittable. A recognized call always produces exactly one of the two.
+ */
+export declare function extractAgentSurface(options: ExtractAgentSurfaceOptions): AgentSurface;
+export declare function scanSvelteAgentSurface(filePath: string, sourceText?: string): AgentSurfaceDiagnostic[];
+/**
+ * Merge per-file results into ONE deterministic surface.
+ *
+ * Emission must not depend on the order the file system happened to hand files
+ * to the scanner — a cross-profile parity snapshot that churns on directory
+ * order proves nothing. So identity is total and content-derived:
+ *
+ * - an intent is identified by its `id`, a playbook by its `key`;
+ * - entries sort by that identity, then by the recorded source path;
+ * - when two files declare the same identity, the entry from the
+ *   lexicographically smaller path wins and the other is reported as a
+ *   `duplicate-identity` diagnostic — a rule that gives the same answer for
+ *   every input order, which "first one scanned wins" does not;
+ * - diagnostics sort by path, then line, column, code, and message.
+ *
+ * `relativize` maps an absolute scan path to the stable path recorded in the
+ * artifact; callers pass the package root's relativizer so a checked-in
+ * artifact never carries a machine-specific absolute path.
+ */
+export declare function mergeAgentSurfaces(surfaces: readonly AgentSurface[], relativize?: (filePath: string) => string): AgentSurface;
+/**
+ * One WebMCP tool name the build will register for a generated model action,
+ * supplied by the caller that knows the exposure policy.
+ */
+export 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;
+}
+export 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[];
+}
+/**
+ * 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[];
+/** An empty surface, for callers that skipped the scan. */
+export declare function emptyAgentSurface(): AgentSurface;
+//# sourceMappingURL=agent-surface.d.ts.map

package/dist/agent-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-surface.d.ts","sourceRoot":"","sources":["../src/agent-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,OAAO,KAAK,EACV,YAAY,EAEZ,sBAAsB,EAKvB,MAAM,YAAY,CAAC;AAqKpB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAKT;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAmBT;AAutBD,MAAM,WAAW,0BAA0B;IACzC,sCAAsC;IACtC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IACzB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,YAAY,CA6Kd;AAqED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,sBAAsB,EAAE,CA4B1B;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,UAAU,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAA+B,GAChE,YAAY,CAoHd;AAMD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACvD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,EAAE,CAyE1B;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,IAAI,YAAY,CAEhD"}

package/dist/cli.d.ts

@@ -1 +1,21 @@
-export {}
+#!/usr/bin/env node
+/**
+ * smrt-scan CLI
+ *
+ * High-performance TypeScript scanner for SMRT manifest generation.
+ *
+ * Usage:
+ *   smrt-scan [options] [directory]
+ *
+ * Options:
+ *   -o, --output <file>   Output manifest file (default: stdout)
+ *   -i, --include <glob>  Include patterns (comma-separated)
+ *   -e, --exclude <glob>  Exclude patterns (comma-separated)
+ *   --json                Output as JSON (default)
+ *   --stats               Output scan statistics
+ *   --benchmark           Run performance benchmark
+ *   -h, --help            Show help
+ *   -v, --version         Show version
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/discovery.d.ts

@@ -0,0 +1,15 @@
+export interface SourceDiscoveryOptions {
+    cwd: string;
+    include: string[];
+    exclude: string[];
+    followSymbolicLinks?: boolean;
+}
+/**
+ * Discover authored source files with the bounded policy shared by every
+ * scanner entry point, including ManifestBuilder's preflight (#2275).
+ */
+export declare function discoverSourceFiles(options: SourceDiscoveryOptions): Promise<string[]>;
+/** Preserve relative glob escapes; normalize separators only after rewriting. */
+export declare function relativeGlobToCwd(pattern: string, cwd: string): string;
+export declare function normalizeGlobSeparators(pattern: string, pathSeparator?: "\\" | "/"): string;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAkCtE;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,aAAa,aAAM,GAClB,MAAM,CAIR"}