@telorun/analyzer 0.56.1 → 0.57.0

package/dist/module-file-claims.js

@@ -0,0 +1,106 @@
+import { defaultCustomTags, defaultRegistry, walkCelExpressions, } from "@telorun/templating";
+import { PackageURL } from "packageurl-js";
+import { parseAllDocuments } from "yaml";
+import { selectorFromQualifiers, selectorKey } from "./artifact-selector.js";
+/** `pkg:telo/local/<format>?path=…` — the bundled-controller delivery mode.
+ *  Anything else (`pkg:npm`, `pkg:cargo`) fetches from its own ecosystem and
+ *  contributes no layer. */
+const BUNDLED_TYPE = "telo";
+const BUNDLED_NAMESPACE = "local";
+/** Qualifier naming extra files that belong in a controller's layer — what an
+ *  entry point loads but the manifest cannot otherwise see (a `.wasm` beside its
+ *  glue, a native library opened at runtime). */
+const SIBLINGS_QUALIFIER = "siblings";
+/** Normalize a `path=` / sibling value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value) {
+    return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+/** Bundled-controller claims from one document's `controllers:` list. */
+function controllerClaims(json) {
+    const candidates = json?.controllers;
+    if (!Array.isArray(candidates))
+        return [];
+    const claims = [];
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string")
+            continue;
+        let parsed;
+        try {
+            parsed = PackageURL.fromString(candidate);
+        }
+        catch {
+            // Not a parseable PURL — claim collection is not the place to reject it;
+            // the analyzer's own validation and the controller loader both report it
+            // with better context.
+            continue;
+        }
+        if (parsed.type !== BUNDLED_TYPE || parsed.namespace !== BUNDLED_NAMESPACE)
+            continue;
+        const entry = parsed.qualifiers?.path;
+        if (typeof entry !== "string" || entry === "")
+            continue;
+        claims.push({
+            role: "controller",
+            path: normalizeRelative(entry),
+            selector: selectorFromQualifiers(parsed.name, parsed.qualifiers, `controller "${candidate}"`),
+            siblings: String(parsed.qualifiers?.[SIBLINGS_QUALIFIER] ?? "")
+                .split(",")
+                .map((p) => p.trim())
+                .filter((p) => p !== ""),
+            origin: candidate,
+        });
+    }
+    return claims;
+}
+/** Claims contributed by tagged values, asked of the engine that owns each tag.
+ *  The walk reaches every tagged scalar in the document, so an engine that
+ *  embeds files is discovered wherever its tag was written.
+ *
+ *  The layer role is assigned HERE, not by the engine: an engine reports what it
+ *  embeds, and which layer that belongs in is this module's vocabulary. A file a
+ *  tag embeds is read only when the resource holding it is created, so `assets`
+ *  — the lazily-fetched layer — is what it is. */
+function taggedClaims(json, registry) {
+    const claims = [];
+    walkCelExpressions(json, "", (source, path, engineName) => {
+        const engine = registry.get(engineName);
+        for (const claim of engine?.fileClaims?.(source) ?? []) {
+            claims.push({ role: "assets", path: claim.path, origin: `!${engineName} at '${path}'` });
+        }
+    });
+    return claims;
+}
+/** Identity of a claim for de-duplication: the same file claimed twice by two
+ *  resources is one file in one layer. Role and selector are part of it because
+ *  a file two controller candidates both claim is genuinely copied into each of
+ *  their layers — dropping one would leave a platform's layer short a file it
+ *  declared it needs. */
+function claimKey(claim) {
+    const selector = claim.role === "controller" ? selectorKey(claim.selector) : "";
+    return `${claim.role}\0${selector}\0${claim.path}`;
+}
+/**
+ * Every module-relative file the manifest names, from every syntax that can name
+ * one.
+ *
+ * `manifestText` is one module's `telo.yaml`. Publish passes the text it is
+ * about to ship — i.e. after `include:` partials have been inlined — but the
+ * answer does not depend on that: claims are root-relative, so collecting them
+ * before or after inlining gives the same set.
+ */
+export function collectModuleFileClaims(manifestText, registry = defaultRegistry()) {
+    const seen = new Set();
+    const claims = [];
+    for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
+        const json = doc.toJSON();
+        for (const claim of [...controllerClaims(json), ...taggedClaims(json, registry)]) {
+            const key = claimKey(claim);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            claims.push(claim);
+        }
+    }
+    return claims;
+}

package/dist/schema-compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAKA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAWpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAaD,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CA2B/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAyBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiChG;AAkED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CA0C/E;AAqBD,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAyDD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwBlF;AAED;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;AAChC;;;;;;;;6DAQ6D;AAC7D,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EACrC,IAAI,SAAK,GACR,OAAO,CAgDT"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAYA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAWpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAaD,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CA2B/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAyBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiChG;AAkED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CA0C/E;AAqBD,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAyDD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwBlF;AAED;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;AAChC;;;;;;;;6DAQ6D;AAC7D,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EACrC,IAAI,SAAK,GACR,OAAO,CA2DT"}

package/dist/schema-compat.js

@@ -1,6 +1,6 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
+import { INCLUDE_BYTES_ENGINE, INCLUDE_ENGINE_NAMES, isRefSentinel, isTaggedSentinel, ManifestRootSchema, normalizeRefSlots, } from "@telorun/templating";
 import { binaryKeyword, isBinarySlot } from "./binary-slot.js";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
@@ -537,6 +537,17 @@ onSubstitute, path = "") {
     if (isRefSentinel(data)) {
         return data;
     }
+    // A file embed's type is a CONSTANT of the tag, not a function of the slot:
+    // `!include-text` always produces a string and `!include-bytes` always
+    // produces bytes. Collapsing them to a slot-shaped placeholder like a CEL
+    // expression would make every slot accept both, so a byte embed at a
+    // `type: string` field passed `telo check` and failed at resource creation —
+    // and the reverse (text at an `x-telo-binary` slot) did too. Substituting the
+    // real type lets AJV and the `x-telo-binary` keyword reject both directions
+    // statically, with no new diagnostic code.
+    if (isTaggedSentinel(data) && INCLUDE_ENGINE_NAMES.has(data.engine)) {
+        return data.engine === INCLUDE_BYTES_ENGINE ? new Uint8Array() : "";
+    }
     if (isTaggedSentinel(data)) {
         mark();
         return celPlaceholderForSchema(resolved);

package/dist/types.d.ts

@@ -26,6 +26,37 @@ export interface Range {
 export type PositionIndex = Map<string, Range>;
 /** LSP-compatible Diagnostic shape. range is optional because parsed YAML may not carry
  *  position info when only the parsed object (not raw text) is available. */
+/** A mechanically applicable repair, carried unchanged from whatever produced
+ *  it (a templating engine, a kind-name suggestion) to every consumer: CLI
+ *  JSON, IDE CodeActions, an agent applying it without re-deriving it from
+ *  prose.
+ *
+ *  `replacement` is the **whole** value at the diagnostic's `path`, corrected —
+ *  never a fragment — so applying it needs no knowledge of the language inside.
+ *  There is deliberately no sub-range: carrying one beside a whole-value
+ *  replacement gives the field two readings, and the minimal-edit reading
+ *  (splice `replacement` at `range`) produces garbage because the two measure
+ *  different strings.
+ *
+ *  One shape rather than one per producer: a `fix` field beside a
+ *  `suggestedKind` field beside a CEL-specific one would leave every host
+ *  wiring a separate action path for what is the same gesture. */
+export interface DiagnosticFix {
+    readonly replacement: string;
+}
+/** The `data` stamp diagnostics carry. Loose by design — passes bolt their own
+ *  keys on — but the fields every consumer reads are declared. */
+export interface DiagnosticData {
+    resource?: {
+        kind: string;
+        name: string;
+    };
+    filePath?: string;
+    /** Dotted path of the offending value within its resource. */
+    path?: string;
+    fix?: DiagnosticFix;
+    [key: string]: unknown;
+}
 export interface AnalysisDiagnostic {
     range?: Range;
     severity?: DiagnosticSeverity;
@@ -36,6 +67,9 @@ export interface AnalysisDiagnostic {
     /** Telo-specific extras such as { resource: { kind, name }, path } */
     data?: unknown;
 }
+/** Single reader for a diagnostic's fix, so no consumer re-derives the shape
+ *  by hand-casting `data`. */
+export declare function diagnosticFix(d: AnalysisDiagnostic): DiagnosticFix | undefined;
 export interface ManifestSource {
     supports(url: string): boolean;
     read(url: string): Promise<{

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;qEAEiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjE;;qEAEiE;IACjE,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;mEAO+D;IAC/D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC;6FACyF;IACzF,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;oCAKgC;IAChC,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC;;;;;;;;;;sDAUkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;IACpE;;;;+EAI2E;IAC3E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAAC;CAC5E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -8,3 +8,9 @@ export const DiagnosticSeverity = {
 };
 /** Default entry-point filename when a directory is given instead of a file. */
 export const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
+/** Single reader for a diagnostic's fix, so no consumer re-derives the shape
+ *  by hand-casting `data`. */
+export function diagnosticFix(d) {
+    const fix = d.data?.fix;
+    return fix && typeof fix.replacement === "string" ? fix : undefined;
+}

package/dist/validate-include-placement.d.ts

@@ -0,0 +1,26 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * An `!include-text` / `!include-bytes` in a doc that is never instantiated is
+ * never read.
+ *
+ * The two tags resolve when the resource owning them is created — deferred so
+ * that loading a manifest does not pull payload layers, which is the property
+ * the artifact spec protects by giving `telo.yaml` a layer of its own. The cost
+ * of that choice is this dead spot: a doc with no `create()` has no moment at
+ * which the file would be read, so the value stays an unresolved marker and
+ * whatever reads it sees a sentinel object instead of the file's contents.
+ *
+ * Nothing else would report it. There is no controller to validate against a
+ * schema and no runtime consumer to fail, so the manifest ships looking correct
+ * — exactly the silent-no-op failure mode that makes a descriptive field worth
+ * checking. Hence an error at the one place that can see it.
+ *
+ * Deliberately narrow: it reports only where the argument is complete ("this
+ * doc is never instantiated"). A JSON-Schema region *inside* a definition —
+ * `schema:`, `inputType:` — is equally unreadable, but that is a general
+ * question about tags in schema metadata rather than one about these two, and
+ * no pass answers it for any tag today.
+ */
+export declare function validateIncludePlacement(manifests: ResourceManifest[]): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-include-placement.d.ts.map

package/dist/validate-include-placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-include-placement.d.ts","sourceRoot":"","sources":["../src/validate-include-placement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAmBzE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CA0B5F"}

package/dist/validate-include-placement.js

@@ -0,0 +1,67 @@
+import { INCLUDE_ENGINE_NAMES, walkCelExpressions } from "@telorun/templating";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Docs that are never instantiated as resources.
+ *
+ * `Telo.Application` / `Telo.Library` are module declarations, and `Telo.Import`
+ * is a dependency edge — none of the three reaches a controller's `create()`.
+ * `Telo.Definition` and `Telo.Abstract` are deliberately absent: a definition's
+ * template body (`resources:` / `invoke:` / `run:` / `provide:`) DOES become
+ * resources, so an embed there resolves normally.
+ */
+const NEVER_INSTANTIATED = new Set([
+    "Telo.Application",
+    "Telo.Library",
+    "Telo.Import",
+]);
+/**
+ * An `!include-text` / `!include-bytes` in a doc that is never instantiated is
+ * never read.
+ *
+ * The two tags resolve when the resource owning them is created — deferred so
+ * that loading a manifest does not pull payload layers, which is the property
+ * the artifact spec protects by giving `telo.yaml` a layer of its own. The cost
+ * of that choice is this dead spot: a doc with no `create()` has no moment at
+ * which the file would be read, so the value stays an unresolved marker and
+ * whatever reads it sees a sentinel object instead of the file's contents.
+ *
+ * Nothing else would report it. There is no controller to validate against a
+ * schema and no runtime consumer to fail, so the manifest ships looking correct
+ * — exactly the silent-no-op failure mode that makes a descriptive field worth
+ * checking. Hence an error at the one place that can see it.
+ *
+ * Deliberately narrow: it reports only where the argument is complete ("this
+ * doc is never instantiated"). A JSON-Schema region *inside* a definition —
+ * `schema:`, `inputType:` — is equally unreadable, but that is a general
+ * question about tags in schema metadata rather than one about these two, and
+ * no pass answers it for any tag today.
+ */
+export function validateIncludePlacement(manifests) {
+    const out = [];
+    for (const manifest of manifests) {
+        if (!NEVER_INSTANTIATED.has(manifest.kind))
+            continue;
+        const name = manifest.metadata?.name;
+        const filePath = manifest.metadata?.source;
+        walkCelExpressions(manifest, "", (source, path, engineName) => {
+            if (!INCLUDE_ENGINE_NAMES.has(engineName))
+                return;
+            out.push({
+                severity: DiagnosticSeverity.Error,
+                code: "INCLUDE_OUTSIDE_RESOURCE",
+                source: SOURCE,
+                message: `${manifest.kind}${name ? `/${name}` : ""}: \`!${engineName} ${source}\` at '${path}' is ` +
+                    `never read — a ${manifest.kind} doc is not instantiated, and a file embed is resolved ` +
+                    `when the resource holding it is created. Move it onto the resource that needs the ` +
+                    `file, or read the file at runtime with Fs.File.`,
+                data: {
+                    resource: { kind: manifest.kind, name: name ?? "" },
+                    filePath,
+                    path,
+                },
+            });
+        });
+    }
+    return out;
+}

package/dist/validate-throws-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-throws-coverage.d.ts","sourceRoot":"","sources":["../src/validate-throws-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAOnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA0ezE,oDAAoD;AACpD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,WAAW,EAChB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,GACnC,kBAAkB,EAAE,CAkDtB"}
+{"version":3,"file":"validate-throws-coverage.d.ts","sourceRoot":"","sources":["../src/validate-throws-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAOnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA+ezE,oDAAoD;AACpD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,WAAW,EAChB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,GACnC,kBAAkB,EAAE,CAkDtB"}

package/dist/validate-throws-coverage.js

@@ -171,7 +171,7 @@ function checkCatchAllPlacement(entries, resource, channel, filePath, arrayPath)
  *  in coverage-proving `when:` clauses. Phase 2 accepts inherit/passthrough
  *  handler unions too — when the resolved union is unbounded, a catch-all is
  *  required (rule 4 extension). */
-function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env) {
+function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env, handler) {
     const diagnostics = [];
     const declaredCodes = new Set(union.codes.keys());
     const covered = new Set();
@@ -221,16 +221,19 @@ function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env
         });
     }
     if (!hasCatchAll) {
-        for (const code of declaredCodes) {
-            if (!covered.has(code)) {
-                diagnostics.push({
-                    severity: DiagnosticSeverity.Error,
-                    code: "UNCOVERED_THROW_CODE",
-                    source: SOURCE,
-                    message: `Code '${code}' is declared by the handler but not covered by any catches: entry (no matching \`when:\` and no catch-all).`,
-                    data: { resource, filePath, path: arrayPath },
-                });
-            }
+        // One diagnostic per block, not per code: every uncovered code sits at the
+        // same `catches:` array, and one catch-all answers all of them at once. A
+        // diagnostic each repeated the same location and the same fix N times.
+        const uncovered = [...declaredCodes].filter((c) => !covered.has(c)).sort();
+        if (uncovered.length > 0) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "UNCOVERED_THROW_CODE",
+                source: SOURCE,
+                message: `handler ${handler?.name ? `\`!ref ${handler.name}\`` : `\`${handler?.kind ?? "?"}\``} can throw ${uncovered.length} code${uncovered.length === 1 ? "" : "s"} that no catches: entry handles: ${uncovered.map((c) => `'${c}'`).join(", ")}. ` +
+                    `Give each a matching \`when:\` (e.g. \`when: !cel "error.code == '${uncovered[0]}'"\`), or add a catch-all entry — one with no \`when:\`, placed last.`,
+                data: { resource, filePath, path: arrayPath, uncovered },
+            });
         }
     }
     return diagnostics;
@@ -447,7 +450,7 @@ export function validateThrowsCoverage(manifests, defs, aliases, env, aliasesByM
             diagnostics.push(...checkCatchAllPlacement(entries, resource, "catches", filePath, arrayPath));
             const handlerRef = resolveHandlerRef(siblingData[catchesFor]);
             const union = handlerRefUnion(handlerRef, manifests, resolveCtx, scopeResolver);
-            diagnostics.push(...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env));
+            diagnostics.push(...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env, handlerRef));
             diagnostics.push(...checkTypedErrorData(entries, union, resource, filePath, arrayPath, env));
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.56.1",
+  "version": "0.57.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -41,14 +41,15 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
+    "packageurl-js": "^2.0.1",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.12.0"
+    "@telorun/templating": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.70.0"
+    "@telorun/sdk": "0.72.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"