@happyvertical/smrt-scanner 0.43.10 → 0.44.1

package/AGENTS.md

@@ -36,10 +36,141 @@ executes the source.
   Driven by `scripts/verify-manifest-completeness.mjs` from `prepack`.
 - `discoverSourceFiles(options)` — shared bounded source-discovery policy used
   by `OxcScanner` and the core manifest preflight.
+- `extractAgentSurface` / `scanSvelteAgentSurface` / `mergeAgentSurfaces` —
+  the agent-surface matcher (#2591). See below.
 - Types (re-exported from `./types`): `RawClassDefinition`,
   `RawFieldDefinition`, `RawMethodDefinition`, `ResolvedClassDefinition`,
   `ScanResults`, `FileScanResult`, `OxcScannerOptions`, `InferredFieldType`,
-  `FieldTypeInference`.
+  `FieldTypeInference`, `AgentSurface`, `AgentSurfaceIntent`,
+  `AgentSurfacePlaybook`, `AgentSurfaceDiagnostic`.
+
+## The agent-surface matcher (#2591)
+
+`@smrt()` classes are found by matching DECORATORS. A view intent (#2588) and a
+playbook (#2589) are not classes, so `agent-surface.ts` adds the second shape
+the framework emits from: a **module-scope call with one object-literal
+argument**. `ScanResults.agentSurface` carries the merged result.
+
+### What it accepts
+
+| Requirement | Why |
+|---|---|
+| A `.ts` / `.tsx` / `.js` / `.jsx` module | the scanner never reads `.svelte` |
+| Callee bound by an import from exactly one specifier — `defineIntent` from `@happyvertical/smrt-web/intents`, `definePlaybook` from `@happyvertical/smrt-playbooks` | a local function of the same name is not a declaration. `defineIntent` ships solely from the `/intents` subpath so a sidecar drags in no client-data engine; matching the package root would invent a specifier |
+| The call directly at module scope — `const x = f({…})`, `export const x = f({…})`, `f({…});`, `export default f({…})`, or an element of a module-scope array initializer | anything deeper is conditional on control flow; an array literal is not |
+| Exactly one argument, an `ObjectExpression` whose values are literals, literal objects, or literal arrays | there is nothing to read otherwise |
+
+Named imports (aliased or not) and namespace imports (`intents.defineIntent`)
+both resolve; a default import does not, since neither package has one.
+
+**Declaration discovery is NOT bound to the class-scan `include` glob.** A model
+scan is routinely narrowed to where models live — the shipped SvelteKit template
+uses `src/lib/objects/**/*.ts` — but an intent sidecar lives beside the component
+that uses it. So `agentSurfaceInclude` (default `**/*.{ts,tsx,js,jsx}`, the
+extensions the Vite plugin's own default accepts) is globbed separately, files
+the class pass already parsed are skipped so nothing is counted twice, and the
+token pre-filter keeps a non-declaring file at one read. Binding the two globs
+together made sidecars vanish from every artifact with no diagnostic at all —
+the exact silent omission this matcher exists to prevent.
+
+**`isAgentSurfaceSourcePath` is the single authority on what counts as a
+declaration source**, and it is a path predicate, not a glob. Both passes here
+and `dev:knowledge-check`'s freshness re-scan call it. That matters because the
+two sides disagreeing is not cosmetic: a file the emitter reads but the checker
+skips reports as "no longer present in source" forever, and the reverse reports
+as "missing from smrt-knowledge.json" forever — neither clearable by a rebuild.
+It rejects `.d.ts`, `*.test.*`, `*.spec.*`, any hidden (dot) segment, and
+anything under `node_modules`, `dist`, `build`, `coverage`, `__tests__`, or
+`__typechecks__` — measured
+**relative to the scan root**, via the companion `isPrunedAgentSurfacePath`
+(which the `.svelte` passes call directly, since a `.svelte` path is rejected on
+extension by the source predicate). Relative matching is load-bearing: against
+an absolute path, a checkout that merely LIVES under `build/` — a container with
+`WORKDIR /build`, a clone in `~/build/…` — would drop every declaration with no
+diagnostic, and the freshness check would apply the same rule and agree, so the
+artifact would ship an empty surface and `smrt doctor` would call it healthy.
+This is the trap `discovery.ts` rewrites globs relative to `cwd` to avoid.
+
+`dist` is not paranoia. A caller's `exclude` REPLACES `DEFAULT_EXCLUDE`, and
+every real caller passes a narrower one (the Vite plugin sends only test globs
+plus `node_modules`), so this whole-project pass would otherwise walk build
+output. A transpiling build — `tsc`, `svelte-package`, vite lib mode with
+`@happyvertical/*` externalized — keeps both the import specifier and the
+module-scope call in its output, so `dist/foo.intents.js` matches this matcher
+exactly; and since `dist` sorts before `src`, it would WIN the duplicate tie and
+become the recorded source of a declaration nobody wrote there.
+
+### What it refuses, always with a diagnostic
+
+Never a silent omission — every message names `useWebMcpTool`, the escape hatch
+for a tool set genuinely derived from computed or fetched data:
+
+| Code | Shape |
+|---|---|
+| `non-literal-argument` | an identifier reference, a spread (in an object or an array), a call, a conditional, a template literal (interpolated **or not**), a computed or shorthand key, a computed unary, or an argument that is not an object literal |
+| `not-module-scope` | declared inside a function, class, conditional, or loop |
+| `argument-count` | not exactly one argument |
+| `incomplete-declaration` | the literal parsed but lacks `id`/`description`/`target` (intent) or `key`/`title`/`description`/`steps` (playbook) |
+| `invalid-identity` | a declaration the runtime helper itself would reject: an intent `id` that is not lowercase and dot-namespaced, over 128 chars, or resolving into the reserved `smrt_ui_` namespace; an unknown declaration, target, or capability key; a malformed `capability` (bad `effect`, non-boolean flag); a `target` outside the closed `control`/`dataSurface` unions or missing a required `controlId`; a playbook with no steps, an empty/non-array/unknown-plane `planes`, an `onStepFailure` outside `abort`/`continue`, a non-boolean `enabled`, or a step whose `model` is not a qualified pair |
+| `svelte-declaration` | written inline in a `.svelte` file |
+| `duplicate-identity` | two modules declare the same `id`/`key`, or two intent ids derive the same WebMCP tool name |
+
+These rules are mirrored from `defineIntent` and `definePlaybook` (this package
+cannot depend on `smrt-web` or `smrt-playbooks`), and keeping them in step is
+load-bearing: the declaration types `id` as `string`, so `id: 'Orders.Bad'`
+type-checks and fails only at page load. An entry the runtime would reject is
+worse than no entry, because the artifact and `smrt doctor` would then advertise
+an operation that can never register. The same applies to the tool name, which
+is `id` with `.`/`-` replaced by `_` and is therefore **not injective** —
+`orders.foo_bar` and `orders.foo.bar` collide, and `defineIntent` rejects the
+second registration.
+
+Invalid values are **rejected, never repaired**. That matters most for a
+playbook's `planes`: `definePlaybook` throws on an empty or unknown-plane list,
+so defaulting it here would emit an entry asserting `server` validity the author
+never declared — the exact fail-open the plane rule exists to prevent. The same
+holds for `capability`: the fail-closed default is for an OMITTED capability,
+not a typo'd one, so `{ effect: 'reed' }` is a diagnostic rather than a silent
+`destructive`. Playbook *keys* get no pattern check, because `definePlaybook`
+imposes none; only uniqueness applies. **If either runtime tightens its rules,
+tighten these too.**
+
+This is deliberately narrower than the decorator-config extractor, which
+RESOLVES spreads against module-scope constants. That one must, because a
+dropped `@smrt({ ...CFG })` key silently reopens an exposure surface. Here the
+requirement runs the other way: an emitted entry has to be exactly what an
+author can see in one object literal, so a partial resolution would be worse
+than a refusal.
+
+The `.svelte` pass is textual, not a Svelte parse: it requires the import
+specifier plus a call, and it exists only to say "move this to a `.ts` sidecar"
+— which is the answer regardless of what the declaration contains. It resolves
+the local names the file's own import binds, so `defineIntent as declare`
+followed by `declare({…})` is caught, and it tolerates whitespace before the
+parenthesis; requiring the literal token `defineIntent(` would let exactly the
+case this pass exists for slip through unremarked. Any `*.svelte` exclude a
+caller passes for the class scan is dropped here, since callers routinely
+exclude Svelte because OXC cannot parse it, and honouring that would silence the
+one thing the pass is for.
+
+### Deterministic identity
+
+`mergeAgentSurfaces` makes emission independent of file order, so a
+cross-profile parity snapshot does not churn on directory order:
+
+- an intent is identified by `id`, a playbook by `key`;
+- entries sort by identity, then by source path;
+- on a duplicate identity the **lexicographically smaller path wins** and the
+  other becomes a `duplicate-identity` diagnostic. "First one scanned wins"
+  would give different answers for different input orders;
+- diagnostics sort by path, line, column, code, message;
+- paths are recorded `cwd`-relative and POSIX-separated, so a checked-in
+  artifact is neither machine- nor platform-specific.
+
+The scanner mirrors the #2587 capability vocabulary structurally instead of
+importing `@happyvertical/smrt-types`: core depends on this package, so the
+reverse edge would close a cycle. Core reconciles the two shapes in exactly one
+place, `toKnowledgeAgentSurface` in `vite-plugin/index.ts`.
 
 ## Discovery boundaries
 
@@ -87,6 +218,11 @@ exhausts the heap when the scanner is pointed at an application root (#2275):
 - `src/manifest-adapter.ts` — `ManifestAdapter`: raw → manifest conversion and
   field-type inference.
 - `src/verify-completeness.ts` — `verifyManifestCompleteness` publish guard.
+- `src/agent-surface.ts` — the `defineIntent` / `definePlaybook` matcher, its
+  diagnostics, and `mergeAgentSurfaces` (#2591).
+- `src/source-location.ts` — `getLineColumn`, split out so `agent-surface.ts`
+  can resolve a diagnostic's position without importing `oxc-parser.ts`, which
+  imports it back.
 - `src/types.ts` — shared raw/resolved/result type definitions.
 - `src/cli.ts` / `bin/smrt-scan.js` — the `smrt-scan` CLI.
 
@@ -128,6 +264,15 @@ exhausts the heap when the scanner is pointed at an application root (#2275):
   but its taint replays into the diagnostics of every decorator that spreads
   it, transitively through constant chains. Without that the silent drop simply
   moves one level up. An unused tainted constant reports nothing.
+- **A non-static `defineIntent`/`definePlaybook` warns, it does not fail the
+  build** — unlike an unresolved `@smrt()` spread, which errors. The asymmetry
+  is deliberate: a dropped decorator spread reopens an exposure surface, while a
+  computed tool set is a legitimate choice with a supported path
+  (`useWebMcpTool`). What is never acceptable is the declaration disappearing
+  unremarked, so it is recorded in `ScanResults.agentSurface.diagnostics`,
+  printed by the Vite plugin, carried into `smrt-knowledge.json`, reported by
+  `smrt doctor`, and surfaced by `dev:knowledge-check` as
+  `agent-surface-not-static`.
 - **Relationship targets are resolved, not copied**: `@foreignKey`,
   `@oneToMany` and `@manyToMany` arguments arrive as raw source text.
   `'Target'`/`Target` pass through and a forward-reference thunk