@telorun/analyzer 0.52.0 → 0.54.0

package/dist/resolve-zone-requirements.js

@@ -0,0 +1,541 @@
+import { isRefSentinel } from "@telorun/templating";
+import { buildCallGraph, } from "./call-graph.js";
+import { enclosingOf, propertySchemas, resolveLocalRef, } from "./manifest-navigation.js";
+import { readProvidesZone, readRequiresZone } from "./zone-slot.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/** Resolve a possibly alias-form kind to its definition in the DECLARING
+ *  module's scope — the same layering `AnalysisRegistry.resolveDefinitionIn`
+ *  uses. */
+function definitionResolver(defs, aliases, aliasesByModule) {
+    return (kind, module) => {
+        const scope = (module ? aliasesByModule.get(module) : undefined) ?? aliases;
+        const canonical = scope.resolveKind(kind);
+        return defs.resolve(kind) ?? (canonical ? defs.resolve(canonical) : undefined);
+    };
+}
+const canonicalOf = (def) => `${def.metadata.module}.${def.metadata.name}`;
+/**
+ * Correlation identity — the resolved DECLARATION SITE, mirroring runtime
+ * instance identity exactly. A named module-level resource is
+ * `(declaring file, name)` — the file, not the owning module name, because a
+ * re-exported instance is forwarded once per re-exporting module under that
+ * module's name while its declaration site survives the copy. A
+ * `with:`-scoped resource is its scope site plus name (one instance per scope
+ * run); an inline declaration is its own generated node.
+ */
+function correlationIdOf(node) {
+    if (node.scoped)
+        return `${node.scopeOwner}\0${node.scopeSite}\0${node.name}`;
+    const source = node.manifest.metadata?.source ?? "";
+    return `${source}\0${node.name}`;
+}
+const labelOf = (node) => `${node.kind} '${node.name}'`;
+/** The schema node at a field-map path (`steps`, `routes[].handler`), following
+ *  `[]` into `items`, `{}` into `additionalProperties` and local `$defs` refs —
+ *  where a slot's zone annotations live. */
+function schemaNodeAt(rootSchema, slotPath) {
+    if (!rootSchema)
+        return undefined;
+    let current = rootSchema;
+    for (const segment of slotPath.split(".")) {
+        if (!current)
+            return undefined;
+        const bare = segment.replace(/(\[\]|\{\})+$/g, "");
+        let next = propertySchemas(current).find(([k]) => k === bare)?.[1];
+        for (const marker of segment.slice(bare.length).match(/\[\]|\{\}/g) ?? []) {
+            next = resolveLocalRef(marker === "[]"
+                ? next?.items
+                : next?.additionalProperties, rootSchema);
+            if (!next || typeof next !== "object")
+                return undefined;
+        }
+        current = resolveLocalRef(next, rootSchema);
+    }
+    return current;
+}
+/**
+ * The LOCAL name a correlation-key hop resolves to, or undefined when the value
+ * is not a reference or does not name something local.
+ *
+ * **A cross-module reference is undefined, deliberately**, matching the kernel's
+ * `referencedName` exactly: `!ref Alias.name` names an instance in another
+ * module's scope, and the only index available here is flat and
+ * module-unscoped, so taking the bare name would bind to whatever local
+ * resource happens to share it. Correlation is an identity comparison — binding
+ * it to the wrong resource is worse than leaving it uncorrelated, which is the
+ * under-approximating direction the whole pass leans on. `Self.` is a local
+ * name written the long way and does resolve.
+ *
+ * This deliberately differs from `call-graph`'s `refTargetName`, which answers a
+ * different question (what an EDGE points at, cross-module included, for a graph
+ * whose consumers tolerate an unresolved target) — hence two functions rather
+ * than one shared helper.
+ */
+function refName(value) {
+    if (isRefSentinel(value)) {
+        const source = value.source;
+        const dot = source.indexOf(".");
+        if (dot <= 0)
+            return source;
+        return source.slice(0, dot) === "Self" ? source.slice(dot + 1) : undefined;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const v = value;
+    const pure = typeof v.kind === "string" &&
+        typeof v.name === "string" &&
+        Object.keys(v).every((k) => k === "kind" || k === "name" || k === "alias" || k === "__ref");
+    if (!pure)
+        return undefined;
+    const alias = v.alias;
+    if (typeof alias === "string" && alias !== "Self")
+        return undefined;
+    return v.name;
+}
+/**
+ * Resolve an ordered correlation-key pointer list against a resource's
+ * manifest, first hit winning — the static counterpart of the kernel's walk.
+ * A pointer may traverse a `!ref` into the referenced resource's own manifest
+ * (read field → resolve reference → read field); traversal is mechanical, so
+ * no kind is named here. Returns undefined when nothing resolves — the
+ * requirement then discharges uncorrelated, the under-approximating side.
+ */
+function resolveStaticKey(start, pointers, resolveName) {
+    for (const pointer of pointers) {
+        if (!pointer.startsWith("/"))
+            continue;
+        let manifest = start.manifest;
+        let context = start;
+        let value = undefined;
+        let failed = false;
+        const segments = pointer.slice(1).split("/");
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i].replace(/~1/g, "/").replace(/~0/g, "~");
+            if (i > 0) {
+                // Traverse the previous hop's reference into its declaration.
+                const name = refName(value);
+                const target = name ? resolveName(name, context) : undefined;
+                if (!target) {
+                    failed = true;
+                    break;
+                }
+                manifest = target.manifest;
+                context = target;
+            }
+            value = manifest?.[segment];
+            if (value === undefined || value === null) {
+                failed = true;
+                break;
+            }
+        }
+        if (failed)
+            continue;
+        const terminalName = refName(value);
+        const target = terminalName ? resolveName(terminalName, context) : undefined;
+        if (target)
+            return target;
+    }
+    return undefined;
+}
+/** Anchor a provider-side single pointer at the object enclosing the slot,
+ *  then resolve exactly like a requirer key. */
+function resolveProviderKey(provider, edge, pointer, resolveName) {
+    const enclosing = enclosingOf(provider.manifest, edge.path);
+    if (enclosing === provider.manifest || enclosing === undefined) {
+        return resolveStaticKey(provider, [pointer], resolveName);
+    }
+    // Slot inside an array item: resolve the first hop off the item, further
+    // hops through references as usual.
+    const synthetic = { ...provider, manifest: enclosing };
+    return resolveStaticKey(synthetic, [pointer], resolveName);
+}
+/** Run the projection over one graph. */
+export function projectZoneRequirements(args) {
+    const { graph, defs, aliases, aliasesByModule, reportModules, seeds, exportOf } = args;
+    const resolveDef = definitionResolver(defs, aliases, aliasesByModule);
+    const diagnostics = [];
+    const openExports = new Map();
+    const reported = new Set();
+    // Scope-local name index, so a scoped resource's pointers resolve against its
+    // scope siblings first — the order `ScopeContext` and `!ref` agree on.
+    const scopeLocal = new Map();
+    for (const node of graph.nodes.values()) {
+        if (node.type !== "resource" || !node.scoped)
+            continue;
+        const key = `${node.scopeOwner}\0${node.scopeSite}`;
+        let bucket = scopeLocal.get(key);
+        if (!bucket)
+            scopeLocal.set(key, (bucket = new Map()));
+        bucket.set(node.name, node);
+    }
+    const resolveName = (name, from) => {
+        if (from.scoped) {
+            const local = scopeLocal.get(`${from.scopeOwner}\0${from.scopeSite}`)?.get(name);
+            if (local)
+                return local;
+        }
+        return graph.resourceByName(name);
+    };
+    const acceptedFor = (zone) => {
+        const out = new Set([zone]);
+        for (const def of defs.getByExtends(zone)) {
+            const module = def.metadata?.module;
+            if (module && def.metadata?.name)
+                out.add(`${module}.${def.metadata.name}`);
+        }
+        return out;
+    };
+    const moduleOf = (node) => node.manifest.metadata?.module;
+    const reportable = (node) => {
+        const module = moduleOf(node);
+        return module === undefined || reportModules.has(module);
+    };
+    const emit = (severity, code, edge, caller, req, via, why) => {
+        if (!reportable(caller))
+            return;
+        const dedupe = `${code}\0${edge.from}\0${edge.path}\0${req.key}`;
+        if (reported.has(dedupe))
+            return;
+        reported.add(dedupe);
+        const wanted = req.correlationLabel
+            ? `a ${req.zone} zone on ${req.correlationLabel}`
+            : `a ${req.zone} zone`;
+        const path = [...via, `${caller.name}.${edge.path}`].join(" → ");
+        const reason = req.reason ? ` ${req.reason}.` : "";
+        diagnostics.push({
+            severity,
+            code,
+            source: SOURCE,
+            message: `${req.origin} requires ${wanted}, and the path ${path} ${why}.${reason}`,
+            data: {
+                resource: { kind: caller.kind, name: caller.name },
+                filePath: caller.manifest.metadata?.source,
+                path: edge.path,
+            },
+        });
+    };
+    const visited = new Set();
+    const propagate = (node, req, via) => {
+        const visitKey = `${node.id}\0${req.key}`;
+        if (visited.has(visitKey))
+            return;
+        visited.add(visitKey);
+        // A requirement reaching an exported instance is part of that export's
+        // contract — recorded, and propagation continues (the export may also be
+        // reached internally, where an enclosing provider can discharge it).
+        const exportName = exportOf?.(node);
+        if (exportName !== undefined) {
+            let bucket = openExports.get(exportName);
+            if (!bucket)
+                openExports.set(exportName, (bucket = []));
+            if (!bucket.some((r) => `${r.zone}\0${r.correlation ?? ""}` === req.key)) {
+                bucket.push({
+                    zone: req.zone,
+                    correlation: req.correlation,
+                    correlationLabel: req.correlationLabel,
+                    correlationName: req.correlationName,
+                    reason: req.reason,
+                    origin: req.origin,
+                    via: [...via],
+                });
+            }
+        }
+        for (const edge of graph.edgesTo(node.id)) {
+            const from = graph.nodes.get(edge.from);
+            if (!from)
+                continue;
+            const caller = from.type === "step"
+                ? graph.nodes.get(from.owner)
+                : from;
+            if (!caller || caller.type !== "resource")
+                continue;
+            // Discharge: the slot provides a zone whose kind satisfies the
+            // requirement and whose correlation payload is the same declaration
+            // site. Checked BEFORE termination, so a terminating provider slot
+            // (a detached durable body) still discharges its own zone.
+            const callerDef = resolveDef(caller.kind, moduleOf(caller));
+            const slotSchema = schemaNodeAt(callerDef?.schema, edge.slot);
+            const provides = readProvidesZone(slotSchema);
+            if (provides && callerDef && req.accepted.has(canonicalOf(callerDef))) {
+                const providerKey = provides.key
+                    ? resolveProviderKey(caller, edge, provides.key, resolveName)
+                    : undefined;
+                const discharged = req.correlation === undefined ||
+                    (providerKey !== undefined && correlationIdOf(providerKey) === req.correlation);
+                if (discharged)
+                    continue;
+            }
+            // A dynamic selector is already a hard diagnostic (validate-ref-slots);
+            // zones do not re-report it — and must not propagate through a use they
+            // cannot read.
+            if (edge.unresolvedReason === "dynamic")
+                continue;
+            if (edge.use.length === 0) {
+                emit(DiagnosticSeverity.Warning, "ZONE_REQUIREMENT_DEFERRED", edge, caller, req, via, "reaches a slot that declares no use, so whether the zone survives it cannot be decided statically; the runtime check remains the enforcement");
+                continue;
+            }
+            if (edge.unresolved) {
+                emit(DiagnosticSeverity.Warning, "ZONE_REQUIREMENT_DEFERRED", edge, caller, req, via, `reaches a slot whose use selector could not be resolved (${edge.unresolvedReason}), so whether the zone survives it cannot be decided statically; the runtime check remains the enforcement`);
+                continue;
+            }
+            if (edge.use.every((u) => u === "dependency" || u === "schema"))
+                continue;
+            if (edge.use.length > 1) {
+                // The zone's lifetime extends through the edge only if EVERY member is
+                // `call` — a set says several relations hold at once, not that one of
+                // them might.
+                if (edge.use.every((u) => u === "call")) {
+                    continueUp(caller, edge, req, via);
+                    continue;
+                }
+                // A member the runtime guarantees is cleared makes the set decidably
+                // wrong, not undecidable: the detached dispatch is NEVER inside the
+                // caller's zone, so the requirement — a universal claim — is violated
+                // on that path. What stays unknown is only how often that path is
+                // taken, and "sometimes throws" is not a working manifest.
+                //
+                // This is the one place the plan's original rule was inverted, and
+                // deliberately. That rule existed to stop `Cache.View`'s UNCONDITIONAL
+                // `[call, detached]` from hard-erroring every cached transactional call
+                // under the default `revalidate: sync`, where the controller never
+                // detaches — but the same change that added this pass re-annotated that
+                // slot as a case map, so a set now appears only where its detach really
+                // happens. The justification went with the annotation.
+                const guaranteedCleared = edge.use.filter((u) => u === "detached" || u === "trigger.inbound");
+                if (guaranteedCleared.length > 0) {
+                    emit(DiagnosticSeverity.Error, "ZONE_REQUIREMENT_UNSATISFIED", edge, caller, req, via, `reaches a slot that dispatches its target several ways in one invocation ([${edge.use.join(", ")}]), and the ${guaranteedCleared.join(" / ")} dispatch is guaranteed a fresh context — so on that path the zone is gone`);
+                    continue;
+                }
+                // Everything else in a set is undecidable rather than wrong — a
+                // `trigger.consumer` member means a drain site MIGHT be inside the
+                // zone, which no static reading can settle.
+                emit(DiagnosticSeverity.Warning, "ZONE_REQUIREMENT_DEFERRED", edge, caller, req, via, `reaches a slot whose declared use is the set [${edge.use.join(", ")}]; whether the zone survives depends on where the consumer drains it, so it cannot be decided statically and the runtime check remains the enforcement`);
+                continue;
+            }
+            switch (edge.use[0]) {
+                case "call":
+                    continueUp(caller, edge, req, via);
+                    break;
+                case "detached":
+                    emit(DiagnosticSeverity.Error, "ZONE_REQUIREMENT_UNSATISFIED", edge, caller, req, via, "detaches there — the runtime guarantees the detached work a fresh context, outside every zone its caller was in");
+                    break;
+                case "trigger.inbound":
+                    emit(DiagnosticSeverity.Error, "ZONE_REQUIREMENT_UNSATISFIED", edge, caller, req, via, "is an inbound trigger registration — the handler runs on a fresh context driven by a request or timer, outside every zone");
+                    break;
+                case "trigger.consumer":
+                    emit(DiagnosticSeverity.Warning, "ZONE_REQUIREMENT_DEFERRED", edge, caller, req, via, "is dispatched when a returned value is drained, so where it runs is the drain site's choice; the runtime check remains the enforcement");
+                    break;
+                // dependency / schema singletons were filtered above.
+            }
+        }
+    };
+    const continueUp = (caller, edge, req, via) => {
+        // Nothing encloses an Application's boot targets: an open requirement
+        // arriving there surfaces at boot.
+        if (caller.kind === "Telo.Application") {
+            emit(DiagnosticSeverity.Error, "ZONE_REQUIREMENT_UNSATISFIED", edge, caller, req, via, "reaches the application's boot targets, which nothing encloses");
+            return;
+        }
+        propagate(caller, req, [...via, caller.name]);
+    };
+    // ── Origins: instances of the entry graph whose annotated field is present.
+    for (const node of graph.nodes.values()) {
+        if (node.type !== "resource")
+            continue;
+        const meta = node.manifest.metadata;
+        // A forwarded export's requirements are derived by ITS library's own stage
+        // (with the internal graph in hand) and seeded below — deriving them here
+        // against the flattened view would resolve correlation against a graph
+        // that no longer holds the library's internals.
+        if (meta?.forwardedExport)
+            continue;
+        const def = resolveDef(node.kind, meta?.module);
+        const schema = def?.schema;
+        if (!def || !schema?.properties)
+            continue;
+        for (const [field, propSchema] of Object.entries(schema.properties)) {
+            const requires = readRequiresZone(propSchema);
+            if (!requires)
+                continue;
+            if (node.manifest[field] === undefined)
+                continue;
+            const zoneDef = resolveDef(requires.zone, def.metadata.module);
+            if (!zoneDef)
+                continue; // ZONE_PROVIDER_UNRESOLVED is reported at registration
+            const zone = canonicalOf(zoneDef);
+            const target = resolveStaticKey(node, requires.key, resolveName);
+            const req = {
+                zone,
+                accepted: acceptedFor(zone),
+                correlation: target ? correlationIdOf(target) : undefined,
+                correlationLabel: target ? labelOf(target) : undefined,
+                correlationName: target?.name,
+                reason: requires.reason,
+                origin: labelOf(node),
+                key: "",
+            };
+            req.key = `${req.zone}\0${req.correlation ?? ""}`;
+            propagate(node, req, [node.name]);
+        }
+    }
+    // ── Seeds: imported libraries' derived export contracts, attached at the
+    // forwarded nodes the importer's graph actually holds.
+    if (seeds && seeds.size > 0) {
+        for (const node of graph.nodes.values()) {
+            if (node.type !== "resource")
+                continue;
+            const meta = node.manifest.metadata;
+            if (!meta?.forwardedExport || !meta.module)
+                continue;
+            const specs = seeds.get(`${meta.module}\0${node.name}`);
+            if (!specs)
+                continue;
+            for (const spec of specs) {
+                const zoneDef = defs.resolve(spec.zone);
+                const req = {
+                    zone: spec.zone,
+                    accepted: zoneDef ? acceptedFor(spec.zone) : new Set([spec.zone]),
+                    correlation: spec.correlation,
+                    correlationLabel: spec.correlationLabel,
+                    correlationName: spec.correlationName,
+                    reason: spec.reason,
+                    origin: spec.origin,
+                    key: `${spec.zone}\0${spec.correlation ?? ""}`,
+                };
+                propagate(node, req, [...spec.via, node.name]);
+            }
+        }
+    }
+    return { diagnostics, openExports };
+}
+/** Content signature over a library's loaded documents — what makes a
+ *  workspace library invalidate on the keystroke that changed it while a
+ *  published library (immutable bytes) hits every time. FNV-1a over the JSON
+ *  projection; collisions only stale a warning-level derivation, and the
+ *  projection is cheap relative to the graph build it guards. */
+export function zoneDocumentsSignature(manifests) {
+    let hash = 0x811c9dc5;
+    const mix = (text) => {
+        for (let i = 0; i < text.length; i++) {
+            hash ^= text.charCodeAt(i);
+            hash = Math.imul(hash, 0x01000193);
+        }
+    };
+    for (const m of manifests)
+        mix(JSON.stringify(m) ?? "");
+    return (hash >>> 0).toString(16);
+}
+/**
+ * Derive one library's export contracts: build the library-scoped graph from
+ * its full documents (which the flattened analysis view no longer holds), run
+ * the projection derive-only, and keep what reaches an exported instance.
+ */
+export function deriveLibraryExportRequirements(docs, defs, aliases, aliasesByModule, cache) {
+    const signature = docs.signature ?? zoneDocumentsSignature(docs.manifests);
+    const cached = cache?.get(docs.sourceId);
+    if (cached && cached.signature === signature)
+        return cached.exports;
+    const exported = new Set(docs.exportedNames);
+    const graph = buildCallGraph(docs.manifests, defs, { aliases, aliasesByModule });
+    const { openExports } = projectZoneRequirements({
+        graph,
+        defs,
+        aliases,
+        aliasesByModule,
+        reportModules: new Set(),
+        exportOf: (node) => !node.scoped && exported.has(node.name) ? node.name : undefined,
+    });
+    cache?.set(docs.sourceId, { signature, exports: openExports });
+    return openExports;
+}
+/**
+ * The zone stage of `analyze()`: per-library export derivation (cached), the
+ * entry projection with those contracts seeded, and — when the entry is a
+ * library — the export-satisfiability check, at the one desk where it is
+ * fixable.
+ */
+export function runZoneAnalysis(args) {
+    const { manifests, graph, defs, aliases, aliasesByModule, rootModules } = args;
+    // Per-library export contracts, derived over each library's own documents.
+    const seeds = new Map();
+    for (const docs of args.moduleDocuments ?? []) {
+        const contracts = deriveLibraryExportRequirements(docs, defs, aliases, aliasesByModule, args.cache);
+        for (const [exportName, specs] of contracts) {
+            if (specs.length > 0)
+                seeds.set(`${docs.module}\0${exportName}`, specs);
+        }
+    }
+    // The entry library's own export surface, for the satisfiability check.
+    const rootLibraries = [];
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Library")
+            continue;
+        const name = m.metadata?.name;
+        if (!name || !rootModules.has(name))
+            continue;
+        const exportedNames = new Set();
+        for (const entry of m.exports?.resources ?? []) {
+            if (typeof entry !== "string")
+                continue;
+            const dot = entry.indexOf(".");
+            exportedNames.add(dot > 0 ? entry.slice(dot + 1) : entry);
+        }
+        if (exportedNames.size > 0)
+            rootLibraries.push({ module: name, exportedNames, doc: m });
+    }
+    const exportOf = rootLibraries.length > 0
+        ? (node) => {
+            if (node.scoped)
+                return undefined;
+            const module = node.manifest.metadata?.module;
+            const lib = rootLibraries.find((l) => l.module === module);
+            return lib?.exportedNames.has(node.name) ? node.name : undefined;
+        }
+        : undefined;
+    const { diagnostics, openExports } = projectZoneRequirements({
+        graph,
+        defs,
+        aliases,
+        aliasesByModule,
+        reportModules: rootModules,
+        seeds: seeds.size > 0 ? seeds : undefined,
+        exportOf,
+    });
+    // An export whose requirement correlates on a resource importers cannot
+    // reach is unsatisfiable by construction — raised HERE, at the exporting
+    // library, never by an importer against a file it does not own.
+    for (const lib of rootLibraries) {
+        for (const [exportName, specs] of openExports) {
+            if (!lib.exportedNames.has(exportName))
+                continue;
+            const node = graph.resourceByName(exportName);
+            if (!node || node.manifest.metadata?.module !== lib.module) {
+                continue;
+            }
+            for (const spec of specs) {
+                if (spec.correlationName === undefined)
+                    continue; // uncorrelated — satisfiable by any zone
+                if (lib.exportedNames.has(spec.correlationName))
+                    continue; // importers can reach it
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "ZONE_EXPORT_UNSATISFIABLE",
+                    source: SOURCE,
+                    message: `exported resource '${exportName}' carries an open requirement: ${spec.origin} requires ` +
+                        `a ${spec.zone} zone on ${spec.correlationLabel}, which this library does not export — ` +
+                        `no importer can satisfy it. Export '${spec.correlationName}' too (importers wrap ` +
+                        `'${exportName}' in their own zone on it), or export a resource that goes through the ` +
+                        `provider instead of '${exportName}' directly.` +
+                        (spec.reason ? ` ${spec.reason}.` : ""),
+                    data: {
+                        resource: { kind: node.kind, name: node.name },
+                        filePath: node.manifest.metadata?.source,
+                        path: "",
+                    },
+                });
+            }
+        }
+    }
+    return diagnostics;
+}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { ZoneModuleDocuments } from "./zone-module-documents.js";
 /** Matches LSP DiagnosticSeverity values exactly.
  *  https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticSeverity */
 export declare const DiagnosticSeverity: {
@@ -74,6 +75,13 @@ export interface LoaderInitOptions {
 }
 export interface AnalysisOptions {
     strictContexts?: boolean;
+    /** Imported libraries' FULL document sets, for the zone stage's per-library
+     *  export derivation — the flattened analysis view forwards only each
+     *  library's export surface, never its internal dispatch chain. Collected
+     *  from a LoadedGraph via `collectZoneModuleDocuments`. Omitting it skips
+     *  the derivation (the under-approximating direction — the runtime check
+     *  remains the enforcement). */
+    moduleDocuments?: ZoneModuleDocuments[];
     /** When true, `analyze()` runs the state-mutating setup (module identity /
      *  alias / definition registration plus `normalizeInlineResources`) but
      *  skips every diagnostic-producing pass — per-resource validation, the

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;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;;;;;;;;;;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":"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"}

package/dist/validate-module-metadata.d.ts

@@ -0,0 +1,38 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * Static validation of the `metadata:` block on module docs (`Telo.Application` /
+ * `Telo.Library`) and of `metadata.deprecated` wherever it appears.
+ *
+ * These fields are descriptive — nothing in the kernel branches on them — but they
+ * are the module's public face: a hub indexes them, and a consumer reads them
+ * before deciding to import. That is exactly why they need checking. A field the
+ * runtime ignores has no failure mode that would ever surface it, so a mistyped
+ * `licence:` or `deprecatd:` is invisible forever, and the module ships claiming
+ * nothing while its author believes otherwise.
+ *
+ * The vocabulary stays **open** — `metadata` accepts any key, because a publisher
+ * may carry their own — so an unknown key is only reported when it is a near-miss
+ * of a known one. That catches the typo without closing the set.
+ *
+ * **Everything here is a WARNING, and fatal only at `telo publish`** (see
+ * {@link PUBLISH_BLOCKING_CODES}). Refusing to *run* a manifest over a field no
+ * runtime reads gets the cost backwards: `version: 1.0` is a YAML float rather
+ * than a string, which is a real mistake worth reporting, but stopping the app
+ * from starting over it is worse than the mistake. Publication is the moment
+ * these fields become consequential — they are projected onto the artifact's
+ * annotations and indexed by the hub — so that is where they block.
+ */
+/**
+ * Codes that must not block running a manifest but MUST block publishing one.
+ *
+ * Kept as a set rather than a severity because the two audiences differ: a
+ * developer running a manifest wants to know, a publisher must be stopped. If a
+ * later check earns the same treatment, add its code here rather than inventing
+ * a third severity level.
+ */
+export declare const PUBLISH_BLOCKING_CODES: ReadonlySet<string>;
+export declare function validateModuleMetadata(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-module-metadata.d.ts.map

package/dist/validate-module-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-module-metadata.d.ts","sourceRoot":"","sources":["../src/validate-module-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAiDH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CA8CtB"}