@telorun/analyzer 0.25.0 → 0.27.0

package/README.md

@@ -23,7 +23,7 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api.yaml
+$ telo ./examples/hello-api
 
 {"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
 ```

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAud/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA2hB/C,CAAC"}

package/dist/builtins.js

@@ -59,12 +59,28 @@ export const KERNEL_BUILTINS = [
                     items: {
                         type: "object",
                         additionalProperties: true,
+                        // Resource bodies are `self`-only for config: per-call `inputs` is
+                        // NOT in scope here. Each entry is a persistent child created once at
+                        // init() and reused, so its config cannot depend on call-time data —
+                        // that flows through the top-level `inputs:` sibling into the dispatch
+                        // target's invoke().
+                        //
+                        // The exception is CEL the child's OWN controller evaluates later
+                        // against a runtime context it owns (e.g. an Http.Api evaluating route
+                        // CEL per request). Those `request` / `result` / `steps` / `error`
+                        // variables are deferred — the template controller preserves them
+                        // untouched (see resource-template-controller.ts) — so they are
+                        // exposed here permissively. Their deep shape is the child kind's
+                        // concern, not the template's, so they type as open values.
                         "x-telo-context": {
                             type: "object",
                             additionalProperties: false,
                             properties: {
                                 self: { "x-telo-context-from-root": "schema" },
-                                inputs: { "x-telo-context-from-root": "inputType" },
+                                request: {},
+                                result: {},
+                                steps: {},
+                                error: {},
                             },
                         },
                     },
@@ -127,6 +143,41 @@ export const KERNEL_BUILTINS = [
                         },
                     },
                 },
+                // Mount dispatch: names the `resources:` entry (a Telo.Mount, e.g. an
+                // Http.Api) whose `register()` this definition delegates to. Same
+                // string / { kind, name } grammar as `invoke:`. The named child stays
+                // persistent so the produced mount's routes can `!ref` its siblings.
+                mount: {
+                    oneOf: [
+                        {
+                            type: "string",
+                            "x-telo-context": {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    self: { "x-telo-context-from-root": "schema" },
+                                },
+                            },
+                        },
+                        {
+                            type: "object",
+                            additionalProperties: true,
+                            properties: {
+                                kind: { type: "string" },
+                                name: {
+                                    type: "string",
+                                    "x-telo-context": {
+                                        type: "object",
+                                        additionalProperties: false,
+                                        properties: {
+                                            self: { "x-telo-context-from-root": "schema" },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    ],
+                },
                 inputs: {
                     type: "object",
                     additionalProperties: true,
@@ -298,6 +349,16 @@ export const KERNEL_BUILTINS = [
                     type: "array",
                     items: { type: "string" },
                 },
+                // Files bundled alongside `telo.yaml` into the module's registry
+                // artifact (`module.tar.gz`) — static assets served by Http.Static,
+                // templates, etc. Ordered `.gitignore`-style patterns resolved against
+                // the manifest dir at publish time. Analyzer-only role: accept the
+                // field (the schema is additionalProperties:false); the analyzer never
+                // reads the assets. See kernel/nodejs/plans/bundle-controllers.md.
+                files: {
+                    type: "array",
+                    items: { type: "string" },
+                },
                 // Inline imports — name-keyed map sugar for separate `Telo.Import`
                 // documents. The key is the PascalCase alias (the import's
                 // `metadata.name`). Each value is either a bare source string
@@ -422,6 +483,13 @@ export const KERNEL_BUILTINS = [
                     type: "array",
                     items: { type: "string" },
                 },
+                // Files bundled into the module's registry artifact — same semantics as
+                // the Telo.Application `files` field above (a library may ship bundled
+                // templates, migrations, seed data).
+                files: {
+                    type: "array",
+                    items: { type: "string" },
+                },
                 // Inline imports — same name-keyed map sugar as Telo.Application; the
                 // loader desugars each entry into a synthetic Telo.Import. See the
                 // Application schema above and analyzer/nodejs/src/inline-imports.ts.

package/dist/validate-provider-coherence.d.ts

@@ -18,6 +18,14 @@ import { type AnalysisDiagnostic } from "./types.js";
  *    kind is registered but not a `Telo.Invocable`.
  *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
  *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
+ *    not `Telo.Mount`.
+ *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
+ *    entry-point (`invoke:` / `run:` / `provide:`).
+ *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
+ *    is registered but not a `Telo.Mount`.
  */
 export declare function validateProviderCoherence(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
 //# sourceMappingURL=validate-provider-coherence.d.ts.map

package/dist/validate-provider-coherence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-provider-coherence.d.ts","sourceRoot":"","sources":["../src/validate-provider-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CAyItB"}
+{"version":3,"file":"validate-provider-coherence.d.ts","sourceRoot":"","sources":["../src/validate-provider-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CAsNtB"}

package/dist/validate-provider-coherence.js

@@ -16,6 +16,14 @@ const SOURCE = "telo-analyzer";
  *    kind is registered but not a `Telo.Invocable`.
  *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
  *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
+ *    not `Telo.Mount`.
+ *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
+ *    entry-point (`invoke:` / `run:` / `provide:`).
+ *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
+ *    is registered but not a `Telo.Mount`.
  */
 export function validateProviderCoherence(manifests, registry, aliases) {
     const diagnostics = [];
@@ -45,11 +53,13 @@ export function validateProviderCoherence(manifests, registry, aliases) {
         const provide = md.provide;
         const invoke = md.invoke;
         const run = md.run;
+        const mount = md.mount;
         const controllers = md.controllers;
         const resources = md.resources;
         const hasProvide = provide !== undefined && provide !== null;
         const hasInvoke = invoke !== undefined && invoke !== null;
         const hasRun = run !== undefined && run !== null;
+        const hasMount = mount !== undefined && mount !== null;
         const hasControllers = Array.isArray(controllers) && controllers.length > 0;
         if (hasProvide && capability !== "Telo.Provider") {
             diagnostics.push({
@@ -133,6 +143,77 @@ export function validateProviderCoherence(manifests, registry, aliases) {
                 }
             }
         }
+        if (hasMount && capability !== "Telo.Mount") {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "MOUNT_ON_NON_MOUNT",
+                source: SOURCE,
+                message: `${label}: 'mount:' is only valid on definitions with 'capability: Telo.Mount' ` +
+                    `(found '${capability ?? "<unset>"}'). Use 'invoke:' / 'run:' / 'provide:' for other capabilities.`,
+                data: { resource, filePath, path: "mount" },
+            });
+        }
+        if (hasMount && (hasInvoke || hasRun || hasProvide)) {
+            const conflict = hasInvoke ? "invoke" : hasRun ? "run" : "provide";
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "MOUNT_DISPATCHER_CONFLICT",
+                source: SOURCE,
+                message: `${label}: 'mount:' cannot co-exist with '${conflict}:'. ` +
+                    `A definition declares exactly one dispatch entry-point.`,
+                data: { resource, filePath, path: "mount" },
+            });
+        }
+        if (hasMount) {
+            // Resolve the target's name from either form: the bare string (the
+            // primary, documented form — `mount: api`) or the object's `name`. A CEL
+            // target (`${{ … }}`) can only be checked at runtime, so skip those.
+            let mountedName;
+            if (typeof mount === "string") {
+                if (!mount.includes("${{"))
+                    mountedName = mount;
+            }
+            else if (typeof mount === "object" && !Array.isArray(mount)) {
+                const mountObj = mount;
+                if (typeof mountObj.name === "string" && !mountObj.name.includes("${{")) {
+                    mountedName = mountObj.name;
+                }
+            }
+            const mountPath = typeof mount === "string" ? "mount" : "mount.name";
+            if (mountedName && Array.isArray(resources)) {
+                const match = resources.find((r) => {
+                    const meta = r?.metadata;
+                    return typeof meta?.name === "string" && meta.name === mountedName;
+                });
+                if (!match) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "MOUNT_TARGET_UNKNOWN",
+                        source: SOURCE,
+                        message: `${label}: '${mountPath}: ${mountedName}' does not match any entry's ` +
+                            `metadata.name in 'resources:'.`,
+                        data: { resource, filePath, path: mountPath },
+                    });
+                }
+                else if (typeof match.kind === "string") {
+                    const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
+                    const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
+                    if (targetDef && targetDef.kind === "Telo.Definition") {
+                        const targetCap = targetDef.capability;
+                        if (typeof targetCap === "string" && targetCap !== "Telo.Mount") {
+                            diagnostics.push({
+                                severity: DiagnosticSeverity.Error,
+                                code: "MOUNT_TARGET_NOT_MOUNTABLE",
+                                source: SOURCE,
+                                message: `${label}: '${mountPath}: ${mountedName}' resolves to a ${match.kind} ` +
+                                    `(capability '${targetCap}'); 'mount:' requires a Telo.Mount target.`,
+                                data: { resource, filePath, path: mountPath },
+                            });
+                        }
+                    }
+                }
+            }
+        }
         if (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
             diagnostics.push({
                 severity: DiagnosticSeverity.Error,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -48,7 +48,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.34.0"
+    "@telorun/sdk": "0.36.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/builtins.ts

@@ -61,12 +61,28 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           items: {
             type: "object",
             additionalProperties: true,
+            // Resource bodies are `self`-only for config: per-call `inputs` is
+            // NOT in scope here. Each entry is a persistent child created once at
+            // init() and reused, so its config cannot depend on call-time data —
+            // that flows through the top-level `inputs:` sibling into the dispatch
+            // target's invoke().
+            //
+            // The exception is CEL the child's OWN controller evaluates later
+            // against a runtime context it owns (e.g. an Http.Api evaluating route
+            // CEL per request). Those `request` / `result` / `steps` / `error`
+            // variables are deferred — the template controller preserves them
+            // untouched (see resource-template-controller.ts) — so they are
+            // exposed here permissively. Their deep shape is the child kind's
+            // concern, not the template's, so they type as open values.
             "x-telo-context": {
               type: "object",
               additionalProperties: false,
               properties: {
                 self: { "x-telo-context-from-root": "schema" },
-                inputs: { "x-telo-context-from-root": "inputType" },
+                request: {},
+                result: {},
+                steps: {},
+                error: {},
               },
             },
           },
@@ -129,6 +145,41 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             },
           },
         },
+        // Mount dispatch: names the `resources:` entry (a Telo.Mount, e.g. an
+        // Http.Api) whose `register()` this definition delegates to. Same
+        // string / { kind, name } grammar as `invoke:`. The named child stays
+        // persistent so the produced mount's routes can `!ref` its siblings.
+        mount: {
+          oneOf: [
+            {
+              type: "string",
+              "x-telo-context": {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  self: { "x-telo-context-from-root": "schema" },
+                },
+              },
+            },
+            {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                kind: { type: "string" },
+                name: {
+                  type: "string",
+                  "x-telo-context": {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      self: { "x-telo-context-from-root": "schema" },
+                    },
+                  },
+                },
+              },
+            },
+          ],
+        },
         inputs: {
           type: "object",
           additionalProperties: true,
@@ -300,6 +351,16 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
+        // Files bundled alongside `telo.yaml` into the module's registry
+        // artifact (`module.tar.gz`) — static assets served by Http.Static,
+        // templates, etc. Ordered `.gitignore`-style patterns resolved against
+        // the manifest dir at publish time. Analyzer-only role: accept the
+        // field (the schema is additionalProperties:false); the analyzer never
+        // reads the assets. See kernel/nodejs/plans/bundle-controllers.md.
+        files: {
+          type: "array",
+          items: { type: "string" },
+        },
         // Inline imports — name-keyed map sugar for separate `Telo.Import`
         // documents. The key is the PascalCase alias (the import's
         // `metadata.name`). Each value is either a bare source string
@@ -424,6 +485,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
+        // Files bundled into the module's registry artifact — same semantics as
+        // the Telo.Application `files` field above (a library may ship bundled
+        // templates, migrations, seed data).
+        files: {
+          type: "array",
+          items: { type: "string" },
+        },
         // Inline imports — same name-keyed map sugar as Telo.Application; the
         // loader desugars each entry into a synthetic Telo.Import. See the
         // Application schema above and analyzer/nodejs/src/inline-imports.ts.

package/src/validate-provider-coherence.ts

@@ -21,6 +21,14 @@ const SOURCE = "telo-analyzer";
  *    kind is registered but not a `Telo.Invocable`.
  *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
  *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
+ *    not `Telo.Mount`.
+ *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
+ *    entry-point (`invoke:` / `run:` / `provide:`).
+ *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
+ *    is registered but not a `Telo.Mount`.
  */
 export function validateProviderCoherence(
   manifests: ResourceManifest[],
@@ -52,12 +60,14 @@ export function validateProviderCoherence(
     const provide = md.provide;
     const invoke = md.invoke;
     const run = md.run;
+    const mount = md.mount;
     const controllers = md.controllers;
     const resources = md.resources;
 
     const hasProvide = provide !== undefined && provide !== null;
     const hasInvoke = invoke !== undefined && invoke !== null;
     const hasRun = run !== undefined && run !== null;
+    const hasMount = mount !== undefined && mount !== null;
     const hasControllers = Array.isArray(controllers) && controllers.length > 0;
 
     if (hasProvide && capability !== "Telo.Provider") {
@@ -149,6 +159,81 @@ export function validateProviderCoherence(
       }
     }
 
+    if (hasMount && capability !== "Telo.Mount") {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "MOUNT_ON_NON_MOUNT",
+        source: SOURCE,
+        message:
+          `${label}: 'mount:' is only valid on definitions with 'capability: Telo.Mount' ` +
+          `(found '${capability ?? "<unset>"}'). Use 'invoke:' / 'run:' / 'provide:' for other capabilities.`,
+        data: { resource, filePath, path: "mount" },
+      });
+    }
+
+    if (hasMount && (hasInvoke || hasRun || hasProvide)) {
+      const conflict = hasInvoke ? "invoke" : hasRun ? "run" : "provide";
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "MOUNT_DISPATCHER_CONFLICT",
+        source: SOURCE,
+        message:
+          `${label}: 'mount:' cannot co-exist with '${conflict}:'. ` +
+          `A definition declares exactly one dispatch entry-point.`,
+        data: { resource, filePath, path: "mount" },
+      });
+    }
+
+    if (hasMount) {
+      // Resolve the target's name from either form: the bare string (the
+      // primary, documented form — `mount: api`) or the object's `name`. A CEL
+      // target (`${{ … }}`) can only be checked at runtime, so skip those.
+      let mountedName: string | undefined;
+      if (typeof mount === "string") {
+        if (!mount.includes("${{")) mountedName = mount;
+      } else if (typeof mount === "object" && !Array.isArray(mount)) {
+        const mountObj = mount as { name?: unknown };
+        if (typeof mountObj.name === "string" && !mountObj.name.includes("${{")) {
+          mountedName = mountObj.name;
+        }
+      }
+      const mountPath = typeof mount === "string" ? "mount" : "mount.name";
+      if (mountedName && Array.isArray(resources)) {
+        const match = resources.find((r) => {
+          const meta = (r as { metadata?: { name?: unknown } })?.metadata;
+          return typeof meta?.name === "string" && meta.name === mountedName;
+        }) as { kind?: unknown } | undefined;
+        if (!match) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "MOUNT_TARGET_UNKNOWN",
+            source: SOURCE,
+            message:
+              `${label}: '${mountPath}: ${mountedName}' does not match any entry's ` +
+              `metadata.name in 'resources:'.`,
+            data: { resource, filePath, path: mountPath },
+          });
+        } else if (typeof match.kind === "string") {
+          const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
+          const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
+          if (targetDef && targetDef.kind === "Telo.Definition") {
+            const targetCap = (targetDef as { capability?: unknown }).capability;
+            if (typeof targetCap === "string" && targetCap !== "Telo.Mount") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "MOUNT_TARGET_NOT_MOUNTABLE",
+                source: SOURCE,
+                message:
+                  `${label}: '${mountPath}: ${mountedName}' resolves to a ${match.kind} ` +
+                  `(capability '${targetCap}'); 'mount:' requires a Telo.Mount target.`,
+                data: { resource, filePath, path: mountPath },
+              });
+            }
+          }
+        }
+      }
+    }
+
     if (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
       diagnostics.push({
         severity: DiagnosticSeverity.Error,