@happyvertical/smrt-scanner 0.43.9 → 0.44.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { n as ManifestAdapter, t as OxcScanner } from "./chunks/scanner-CW9g-vyS.js";
-import { dirname, resolve } from "node:path";
+import { n as ManifestAdapter, t as OxcScanner } from "./chunks/scanner-C3VqXyzB.js";
 import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts
 function parseArgs(args) {

package/dist/index.d.ts

@@ -1,3 +1,97 @@
+/** The declared agent-addressable surface found by one scan. */
+export declare interface AgentSurface {
+    intents: AgentSurfaceIntent[];
+    playbooks: AgentSurfacePlaybook[];
+    diagnostics: AgentSurfaceDiagnostic[];
+}
+
+/** A fully resolved classification (#2587's fail-closed rule already applied). */
+export declare interface AgentSurfaceCapability {
+    effect: AgentSurfaceEffect;
+    idempotent: boolean;
+    openWorld: boolean;
+}
+
+/**
+ * A recognized declaration that is not emittable.
+ *
+ * Never a silent omission: every message names `useWebMcpTool`, the escape
+ * hatch for a genuinely computed tool set.
+ */
+export declare interface AgentSurfaceDiagnostic {
+    code: AgentSurfaceDiagnosticCode;
+    helper: AgentSurfaceHelper;
+    message: string;
+    filePath: string;
+    line?: number;
+    column?: number;
+}
+
+/** 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';
+
+/**
+ * Effect classification, mirroring `CapabilityEffect` in
+ * `@happyvertical/smrt-types`. Mirrored rather than imported because this
+ * package carries no `@happyvertical/*` dependency — core depends on it, and
+ * importing back would close the cycle.
+ */
+export declare type AgentSurfaceEffect = 'read' | 'write' | 'destructive';
+
+/** The two module-scope helpers the agent-surface matcher recognizes. */
+export declare type AgentSurfaceHelper = 'defineIntent' | 'definePlaybook';
+
+/** One emitted view intent (#2588). */
+export declare interface AgentSurfaceIntent {
+    kind: 'intent';
+    /** Declared, dot-namespaced identity. This is the entry's stable identity. */
+    id: string;
+    description: string;
+    capability: AgentSurfaceCapability;
+    target: Record<string, unknown>;
+    /** Whether the declaration carried an `inputSchema` object. */
+    hasInputSchema: boolean;
+    /**
+     * Always exactly `['browser']`. An intent moves mounted browser state; a
+     * server-side agent reaches one only through the #2446 command/ack bridge,
+     * which the referencing PLAYBOOK declares. Typed as the literal tuple rather
+     * than the open plane list so the contract cannot be read as wider than it is.
+     */
+    planes: ['browser'];
+    /** Declaring module, relativized by the emitting caller. */
+    filePath: string;
+}
+
+/** Plane a declaration is valid on. */
+export declare type AgentSurfacePlane = 'browser' | 'server';
+
+/** One emitted playbook (#2589). */
+export declare interface AgentSurfacePlaybook {
+    kind: 'playbook';
+    /** Declared registry key. This is the entry's stable identity. */
+    key: string;
+    title: string;
+    description: string;
+    steps: AgentSurfacePlaybookStep[];
+    planes: AgentSurfacePlane[];
+    /** False when `planes` was derived from the step kinds rather than declared. */
+    planesDeclared: boolean;
+    onStepFailure: 'abort' | 'continue';
+    enabled: boolean;
+    /** Declaring module, relativized by the emitting caller. */
+    filePath: string;
+}
+
+/** One step of an emitted playbook (#2589). Playbooks cannot nest. */
+export declare type AgentSurfacePlaybookStep = {
+    kind: 'operation';
+    model: string;
+    action: string;
+} | {
+    kind: 'intent';
+    id: string;
+};
+
 declare interface ArrayExpression extends BaseNode {
     type: 'ArrayExpression';
     elements: (Expression | SpreadElement | null)[];
@@ -73,6 +167,9 @@ declare interface Decorator extends BaseNode {
  */
 export declare function discoverSourceFiles(options: SourceDiscoveryOptions): Promise<string[]>;
 
+/** An empty surface, for callers that skipped the scan. */
+export declare function emptyAgentSurface(): AgentSurface;
+
 declare interface ExportDefaultDeclaration extends BaseNode {
     type: 'ExportDefaultDeclaration';
     declaration: Statement | Expression;
@@ -113,6 +210,24 @@ export declare interface ExternalManifest {
     classes: Map<string, RawClassDefinition>;
 }
 
+/**
+ * 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 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;
+}
+
 /* Excluded from this release type: extractSmrtImports */
 
 declare interface FieldDefinition {
@@ -183,6 +298,12 @@ export declare interface FileScanResult {
     typeAliases: Record<string, string>;
     /** SMRT package imports found in file (package name → Set of imported class names) */
     smrtImports?: Map<string, Set<string>>;
+    /**
+     * Declared view intents and playbooks found in the file, plus a diagnostic
+     * for every recognized declaration that is not statically emittable (#2591).
+     * Omitted when the file declares none.
+     */
+    agentSurface?: AgentSurface;
 }
 
 declare interface FunctionExpression extends BaseNode {
@@ -465,6 +586,41 @@ export declare class InheritanceResolver {
     };
 }
 
+/**
+ * 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;
+
 /**
  * Report every persisted `number` field whose declared precision contradicts
  * its name — money declared decimal, or a rate declared integer.
@@ -678,6 +834,27 @@ declare interface MemberExpression extends BaseNode {
     computed: boolean;
 }
 
+/**
+ * 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;
+
 declare interface MethodDefinition {
     name: string;
     async: boolean;
@@ -945,6 +1122,37 @@ export declare class OxcScanner {
      * or `~/.cache` would then match nothing at all, silently.
      */
     private discoverFiles;
+    /**
+     * Find declarations in files the CLASS scan did not cover.
+     *
+     * The class `include` is routinely narrowed to where models live, but an
+     * intent sidecar lives beside its component. Without this pass those
+     * declarations would be missing from every artifact with no diagnostic — a
+     * silent omission, and in the shipped SvelteKit template's own layout at
+     * that. Files already parsed by the class scan are skipped so a declaration
+     * is never counted twice and cannot collide with itself.
+     *
+     * @param alreadyScanned - Absolute paths the class scan already parsed.
+     */
+    private scanDeclarationsOutsideClassGlob;
+    /**
+     * Search `.svelte` files for declarations the scanner can never read.
+     *
+     * A `.svelte` file is not a TypeScript program and is never parsed here, so
+     * this pass produces diagnostics only — never an emitted entry. It exists
+     * because the alternative is silence: an intent declared inline in a
+     * component simply would not appear anywhere, with nothing to explain why.
+     */
+    private scanSvelteDeclarations;
+    /**
+     * Record a declaring module as a `cwd`-relative POSIX path.
+     *
+     * Emitted entries land in checked-in artifacts, so an absolute path would
+     * make them machine-specific and a Windows separator would make them
+     * platform-specific — either one churns a snapshot that is supposed to prove
+     * two builds agree.
+     */
+    private relativizeSourcePath;
     /**
      * Parse a single file with timing
      */
@@ -987,8 +1195,47 @@ export declare interface OxcScannerOptions {
      * stays on real directories unless a caller explicitly opts back in.
      */
     followSymbolicLinks?: boolean;
+    /**
+     * Match module-scope `defineIntent()` / `definePlaybook()` declarations and
+     * report `.svelte` declarations the scanner can never read (#2591). Defaults
+     * to `true`.
+     */
+    agentSurface?: boolean;
+    /**
+     * Glob patterns searched for `.svelte` declarations the scanner cannot read.
+     * Only used when {@link OxcScannerOptions.agentSurface} is enabled.
+     */
+    svelteInclude?: string[];
+    /**
+     * Glob patterns searched for `defineIntent` / `definePlaybook` declarations,
+     * independently of {@link OxcScannerOptions.include}.
+     *
+     * A model scan is routinely narrowed to where models live, but an intent
+     * sidecar lives beside the component that uses it; binding declaration
+     * discovery to the class glob would silently drop those. Only used when
+     * {@link OxcScannerOptions.agentSurface} is enabled.
+     */
+    agentSurfaceInclude?: string[];
 }
 
+/**
+ * Read one file for agent-surface declarations ONLY (#2591).
+ *
+ * Exists because the agent surface must not be confined to the class scan's
+ * `include` glob: an application that scans `src/lib/objects/**` for its models
+ * — the shipped template does exactly that — would otherwise never see a
+ * `src/lib/agent/Foo.intents.ts` sidecar, and the declaration would vanish from
+ * every artifact with no diagnostic. Silent omission is the one failure this
+ * matcher exists to prevent, so declarations are discovered on their own terms.
+ *
+ * The token pre-filter runs before the parse, so a file that declares nothing
+ * costs one read and one `String.includes`.
+ *
+ * @returns The file's surface, or `undefined` when it declares nothing or
+ *   cannot be read.
+ */
+export declare function parseAgentSurfaceFile(filePath: string): AgentSurface | undefined;
+
 /**
  * Parse a single TypeScript file and extract SMRT class definitions.
  *
@@ -1290,8 +1537,15 @@ export declare interface ScanResults {
     typeAliases: Record<string, string>;
     /** Accumulated SMRT package imports across all files (package name → Set of imported class names) */
     smrtImports?: Map<string, Set<string>>;
+    /**
+     * The project's declared agent-addressable surface, merged across files with
+     * deterministic identity so emission never depends on file order (#2591).
+     */
+    agentSurface: AgentSurface;
 }
 
+export declare function scanSvelteAgentSurface(filePath: string, sourceText?: string): AgentSurfaceDiagnostic[];
+
 declare interface SmartObjectConfig {
     tableStrategy?: 'sti' | 'cti';
     idType?: 'uuid' | 'text';
@@ -1376,6 +1630,13 @@ declare interface SourceLocation {
  */
 export declare function sourceMayContainNumericPrecisionIssue(source: string): boolean;
 
+/**
+ * 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;
+
 /**
  * Split an identifier into lowercase words on camelCase, PascalCase, digits,
  * and underscores. `totalAmountCents` → `['total', 'amount', 'cents']`.

package/dist/index.js

@@ -1,7 +1,7 @@
-import { a as parseSource, c as normalizeGlobSeparators, i as parseFile, l as relativeGlobToCwd, n as ManifestAdapter, o as InheritanceResolver, r as extractSmrtImports, s as discoverSourceFiles, t as OxcScanner } from "./chunks/scanner-CW9g-vyS.js";
+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 "./types.js";
-import { basename, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
 //#region src/numeric-precision-lint.ts
 var MONEY_HEAD_WORDS = /* @__PURE__ */ new Set([
 	"amount",
@@ -272,6 +272,6 @@ async function verifyManifestCompleteness(options) {
 	};
 }
 //#endregion
-export { InheritanceResolver, ManifestAdapter, OxcScanner, classifyNumericFieldName, discoverSourceFiles, extractSmrtImports, lintNumericPrecision, normalizeGlobSeparators, parseFile, parseSource, relativeGlobToCwd, sourceMayContainNumericPrecisionIssue, splitIdentifierWords, verifyManifestCompleteness };
+export { InheritanceResolver, ManifestAdapter, OxcScanner, 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

@@ -1,3 +1,97 @@
+/** The declared agent-addressable surface found by one scan. */
+export declare interface AgentSurface {
+    intents: AgentSurfaceIntent[];
+    playbooks: AgentSurfacePlaybook[];
+    diagnostics: AgentSurfaceDiagnostic[];
+}
+
+/** A fully resolved classification (#2587's fail-closed rule already applied). */
+export declare interface AgentSurfaceCapability {
+    effect: AgentSurfaceEffect;
+    idempotent: boolean;
+    openWorld: boolean;
+}
+
+/**
+ * A recognized declaration that is not emittable.
+ *
+ * Never a silent omission: every message names `useWebMcpTool`, the escape
+ * hatch for a genuinely computed tool set.
+ */
+export declare interface AgentSurfaceDiagnostic {
+    code: AgentSurfaceDiagnosticCode;
+    helper: AgentSurfaceHelper;
+    message: string;
+    filePath: string;
+    line?: number;
+    column?: number;
+}
+
+/** 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';
+
+/**
+ * Effect classification, mirroring `CapabilityEffect` in
+ * `@happyvertical/smrt-types`. Mirrored rather than imported because this
+ * package carries no `@happyvertical/*` dependency — core depends on it, and
+ * importing back would close the cycle.
+ */
+export declare type AgentSurfaceEffect = 'read' | 'write' | 'destructive';
+
+/** The two module-scope helpers the agent-surface matcher recognizes. */
+export declare type AgentSurfaceHelper = 'defineIntent' | 'definePlaybook';
+
+/** One emitted view intent (#2588). */
+export declare interface AgentSurfaceIntent {
+    kind: 'intent';
+    /** Declared, dot-namespaced identity. This is the entry's stable identity. */
+    id: string;
+    description: string;
+    capability: AgentSurfaceCapability;
+    target: Record<string, unknown>;
+    /** Whether the declaration carried an `inputSchema` object. */
+    hasInputSchema: boolean;
+    /**
+     * Always exactly `['browser']`. An intent moves mounted browser state; a
+     * server-side agent reaches one only through the #2446 command/ack bridge,
+     * which the referencing PLAYBOOK declares. Typed as the literal tuple rather
+     * than the open plane list so the contract cannot be read as wider than it is.
+     */
+    planes: ['browser'];
+    /** Declaring module, relativized by the emitting caller. */
+    filePath: string;
+}
+
+/** Plane a declaration is valid on. */
+export declare type AgentSurfacePlane = 'browser' | 'server';
+
+/** One emitted playbook (#2589). */
+export declare interface AgentSurfacePlaybook {
+    kind: 'playbook';
+    /** Declared registry key. This is the entry's stable identity. */
+    key: string;
+    title: string;
+    description: string;
+    steps: AgentSurfacePlaybookStep[];
+    planes: AgentSurfacePlane[];
+    /** False when `planes` was derived from the step kinds rather than declared. */
+    planesDeclared: boolean;
+    onStepFailure: 'abort' | 'continue';
+    enabled: boolean;
+    /** Declaring module, relativized by the emitting caller. */
+    filePath: string;
+}
+
+/** One step of an emitted playbook (#2589). Playbooks cannot nest. */
+export declare type AgentSurfacePlaybookStep = {
+    kind: 'operation';
+    model: string;
+    action: string;
+} | {
+    kind: 'intent';
+    id: string;
+};
+
 /**
  * Describes a pre-loaded manifest from an installed SMRT package, used by
  * {@link InheritanceResolver} to resolve base classes that originate outside
@@ -67,6 +161,12 @@ export declare interface FileScanResult {
     typeAliases: Record<string, string>;
     /** SMRT package imports found in file (package name → Set of imported class names) */
     smrtImports?: Map<string, Set<string>>;
+    /**
+     * Declared view intents and playbooks found in the file, plus a diagnostic
+     * for every recognized declaration that is not statically emittable (#2591).
+     * Omitted when the file declares none.
+     */
+    agentSurface?: AgentSurface;
 }
 
 /**
@@ -127,6 +227,27 @@ export declare interface OxcScannerOptions {
      * stays on real directories unless a caller explicitly opts back in.
      */
     followSymbolicLinks?: boolean;
+    /**
+     * Match module-scope `defineIntent()` / `definePlaybook()` declarations and
+     * report `.svelte` declarations the scanner can never read (#2591). Defaults
+     * to `true`.
+     */
+    agentSurface?: boolean;
+    /**
+     * Glob patterns searched for `.svelte` declarations the scanner cannot read.
+     * Only used when {@link OxcScannerOptions.agentSurface} is enabled.
+     */
+    svelteInclude?: string[];
+    /**
+     * Glob patterns searched for `defineIntent` / `definePlaybook` declarations,
+     * independently of {@link OxcScannerOptions.include}.
+     *
+     * A model scan is routinely narrowed to where models live, but an intent
+     * sidecar lives beside the component that uses it; binding declaration
+     * discovery to the class glob would silently drop those. Only used when
+     * {@link OxcScannerOptions.agentSurface} is enabled.
+     */
+    agentSurfaceInclude?: string[];
 }
 
 /**
@@ -328,6 +449,11 @@ export declare interface ScanResults {
     typeAliases: Record<string, string>;
     /** Accumulated SMRT package imports across all files (package name → Set of imported class names) */
     smrtImports?: Map<string, Set<string>>;
+    /**
+     * The project's declared agent-addressable surface, merged across files with
+     * deterministic identity so emission never depends on file order (#2591).
+     */
+    agentSurface: AgentSurface;
 }
 
 export { }

package/package.json

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