@telorun/analyzer 0.62.0 → 0.63.0

package/src/index.ts

@@ -110,6 +110,8 @@ export {
   transfersControl,
 } from "./ref-slot.js";
 export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
+export { isStepSlot, readStepSlot, STEP_FRAGMENT } from "./step-slot.js";
+export type { StepSlot } from "./step-slot.js";
 export {
   ANNOTATION_KEYWORDS,
   registerTeloKeywords,
@@ -131,6 +133,8 @@ export type {
   RequiresIssue,
   RequiresVerdict,
 } from "./requires-block.js";
+export { manifestCompatibility } from "./module-compatibility.js";
+export type { ModuleCompatibility } from "./module-compatibility.js";
 export { TELO_SURFACE_VERSION } from "./telo-version.js";
 export { validateRequires } from "./validate-requires.js";
 export type { ValidateRequiresOptions } from "./validate-requires.js";
@@ -150,8 +154,10 @@ export type {
 export {
   hasProvidesZone,
   hasRequiresZone,
+  providedZoneAttributes,
   readProvidesZone,
   readRequiresZone,
+  readViolatesZone,
   rewriteRequiresZoneKind,
 } from "./zone-slot.js";
 export type { ProvidesZoneSlot, RequiresZoneSlot } from "./zone-slot.js";
@@ -169,6 +175,73 @@ export type {
 } from "./resolve-zone-requirements.js";
 export type { ZoneModuleDocuments } from "./zone-module-documents.js";
 export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
+export {
+  RESOURCE_RULES_ANNOTATION,
+  readResourceRules,
+  readRawResourceRules,
+  resolveRuleSubjects,
+  findDynamicLeaf,
+  type ResourceRule,
+  type ResourceRuleSeverity,
+  type RuleSubject,
+} from "./resource-rule.js";
+export {
+  validateResourceRuleDeclarations,
+  evaluateResourceRules,
+  ruleExercised,
+  RESOURCE_RULE_BUDGET_MS,
+  type ResourceRuleIssue,
+  type ResourceRuleFinding,
+} from "./validate-resource-rules.js";
+export {
+  REFERRER_RULES_ANNOTATION,
+  readReferrerRules,
+  readRawReferrerRules,
+  hasReferrerRules,
+  rewriteReferrerRuleKinds,
+  type ReferrerRule,
+} from "./referrer-rule.js";
+export {
+  validateReferrerRuleDeclarations,
+  evaluateReferrerRules,
+  referrerRuleExercised,
+  reportReferrerRules,
+  reportUnexercisedReferrerRule,
+  type Referrer,
+  type ReferrerRuleIssue,
+  type ReferrerRuleFinding,
+  type ReferrerRuleDiagnostic,
+} from "./validate-referrer-rules.js";
+export { RULE_BUDGET_MS } from "./rule-condition.js";
+export {
+  readSchemaProjection,
+  readSchemaMap,
+  readProjectionFrom,
+  readProjectionRef,
+  manifestListScope,
+  projectionKeyMap,
+  projectEntries,
+  resolveSchemaProjections,
+  describeProjectionFailure,
+  type SchemaProjection,
+  type SchemaMap,
+  type ProjectionRef,
+  type ProjectionLookup,
+  type ProjectionScope,
+  type ProjectionFailure,
+} from "./schema-projection.js";
+export { validateSchemaProjection, type SchemaProjectionIssue } from "./validate-schema-projection.js";
+export { validateDurableRegions } from "./validate-durable-regions.js";
+export { validateZoneViolations } from "./validate-zone-violations.js";
+export {
+  containmentIndex,
+  findZoneRegions,
+  regionManifests,
+  type ContainedNode,
+  type DefinitionLookup,
+  type RegionBoundary,
+  type ZoneRegion,
+} from "./resolve-zone-containment.js";
 export type { ZoneSlotIssue } from "./validate-zone-slots.js";
 export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validate-ref-slots.js";
 export type { RefSlotIssue } from "./validate-ref-slots.js";

package/src/invocation-contract.ts

@@ -6,6 +6,11 @@ import {
   effectiveContractField,
 } from "./extends-resolution.js";
 import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+import {
+  manifestListScope,
+  resolveSchemaProjections,
+  type ProjectionFailure,
+} from "./schema-projection.js";
 
 export type { ContractDirection };
 
@@ -80,11 +85,20 @@ export function resolveContract(
   manifest: Record<string, any> | undefined,
   definition: ResourceDefinition | undefined,
   scope: ContractScope,
+  /** Collects declaration-derived slots that could not be projected. Omitted by
+   *  every caller that only wants the schema; the one pass that REPORTS them
+   *  passes an array. */
+  projectionFailures?: ProjectionFailure[],
 ): ResolvedContract | undefined {
   const own = manifest?.[direction];
   if (own !== undefined && own !== null) {
     const schema = resolveTypeFieldToSchema(own, scope.typeManifestsFor(definition));
-    if (schema) return { schema, origin: "instance" };
+    if (schema) {
+      return {
+        schema: projectionResolved(schema, manifest, scope, definition, projectionFailures),
+        origin: "instance",
+      };
+    }
   }
 
   const declared = effectiveContractField(definition, scope.resolveDefinition, direction);
@@ -92,7 +106,36 @@ export function resolveContract(
   const declarer = contractDeclarer(definition, scope.resolveDefinition, direction);
   const schema = resolveTypeFieldToSchema(declared, scope.typeManifestsFor(declarer));
   if (!schema) return undefined;
-  return { schema, origin: "kind", declaredBy: declarer };
+  return {
+    schema: projectionResolved(schema, manifest, scope, declarer, projectionFailures),
+    origin: "kind",
+    declaredBy: declarer,
+  };
+}
+
+/**
+ * A contract may be DECLARATION-derived: a kind whose `outputType` projects the
+ * declaration of a resource it references (a repository typing its rows from
+ * the table it reads). The manifest is in hand here and nowhere later, so this
+ * is where the projection is resolved — and it is resolved for a kind-declared
+ * contract and an instance-declared one alike, since either may carry one.
+ */
+function projectionResolved(
+  schema: Record<string, any>,
+  manifest: Record<string, any> | undefined,
+  scope: ContractScope,
+  declarer: ResourceDefinition | undefined,
+  failures?: ProjectionFailure[],
+): Record<string, any> {
+  return resolveSchemaProjections(
+    schema,
+    manifest,
+    manifestListScope(
+      scope.typeManifestsFor(declarer),
+      (kind) => scope.resolveDefinition(kind) as Record<string, any> | undefined,
+    ),
+    failures,
+  ) as Record<string, any>;
 }
 
 /** {@link resolveContract}, falling back to {@link PERMISSIVE_CONTRACT}. For

package/src/loaded-types.ts

@@ -70,9 +70,11 @@ export interface ImportEdge {
    *  this (minus its version), since it names the module's location
    *  independently of what the module declares about itself. */
   targetRef: string;
-  /** Target library's `metadata.name`, or `null` when the target had no
-   *  Telo.Library doc (an error case captured in `LoadedGraph.errors`). */
-  targetModuleName: string | null;
+  /** Target library's `metadata.name`. Never absent: an import whose target
+   *  names no library identity registers no edge at all and is reported in
+   *  `LoadedGraph.errors`, so an edge that exists is one every consumer can
+   *  resolve a kind through. */
+  targetModuleName: string;
   /** DEPRECATED. Target library's `metadata.namespace`, or `null` when it
    *  declares none. Feeds only the legacy `<namespace>/<module>#<Kind>` form
    *  of `x-telo-ref`; nothing else reads it. */
@@ -137,5 +139,12 @@ export interface GraphLoadError {
   alias?: string;
   /** Line of the `Telo.Import` doc in `fromSource`, for position fallback. */
   sourceLine?: number;
+  /** Why this import is unusable. `"unresolved"` (the default) means the target
+   *  was never obtained — an unreachable or unrecognizable source, which the
+   *  author fixes in their own file. `"unusable-target"` means it WAS obtained
+   *  and is not an importable library, which is a defect in the target module.
+   *  Kept apart because the two call for different actions; consumers phrase
+   *  them differently rather than asserting one cause for both. */
+  reason?: "unresolved" | "unusable-target";
   error: Error;
 }

package/src/manifest-loader.ts

@@ -57,6 +57,62 @@ function collectMigrationDiagnostics(entry: LoadedModule): AnalysisDiagnostic[]
   return diagnostics;
 }
 
+/** The identity an import target contributes to its importer, or the reason it
+ *  contributes none.
+ *
+ *  Every way an import can be unusable answers here, in one place and without
+ *  throwing: the target is an application, it carries no library document at
+ *  all, or it carries one that never names itself. A name is not decoration —
+ *  it is the kind prefix every `Alias.Kind` in the importer resolves through —
+ *  so a target that has none is as unusable as one that was never fetched, and
+ *  is reported the same way rather than left to surface later as an invented
+ *  module nobody declared. */
+type ImportTargetIdentity =
+  | { name: string; namespace: string | null }
+  | { unusable: string };
+
+function importTargetIdentity(target: LoadedModule, importSource: string): ImportTargetIdentity {
+  const library = target.owner.manifests.find((m) => m?.kind === "Telo.Library");
+  const application = target.owner.manifests.find((m) => m?.kind === "Telo.Application");
+
+  if (!library && application) {
+    return {
+      unusable:
+        `Telo.Import target '${importSource}' is a Telo.Application. ` +
+        `Only Telo.Library modules may be imported. Applications are run directly, not imported. ` +
+        `Point this import at a library, or drop it and run that application on its own.`,
+    };
+  }
+
+  if (!library) {
+    const kinds = target.owner.manifests
+      .map((m) => m?.kind)
+      .filter((k): k is string => typeof k === "string");
+    const detail = kinds.length
+      ? `Fetched ${target.owner.manifests.length} document(s) with kinds [${kinds.join(", ")}].`
+      : `Fetched manifest contained no recognizable Telo documents — check that the source ` +
+        `serves a Telo.Library manifest and not an upstream error page.`;
+    return {
+      unusable:
+        `Telo.Import target '${importSource}' did not resolve to a Telo.Library. ` +
+        `Fetched from: ${target.owner.source}. ${detail}`,
+    };
+  }
+
+  const name = library.metadata?.name;
+  if (typeof name !== "string" || name === "") {
+    return {
+      unusable:
+        `Telo.Import target '${importSource}' resolved to a Telo.Library that declares no ` +
+        `'metadata.name'. Fetched from: ${target.owner.source}. A library's name is the kind ` +
+        `prefix its importers reference, so it cannot be imported until the target declares one.`,
+    };
+  }
+
+  const namespace = (library.metadata as { namespace?: string | null } | undefined)?.namespace;
+  return { name, namespace: typeof namespace === "string" ? namespace : null };
+}
+
 const SYSTEM_KINDS = new Set([
   "Telo.Application",
   "Telo.Library",
@@ -320,10 +376,10 @@ export class Loader {
           // Resolve the file we'll fetch through the source chain to get the
           // canonical `source` URL — same identity used as the modules-map key.
           let targetCanonical: string;
-          let targetModule: LoadedModule | undefined;
+          let targetModule: LoadedModule;
           if (modules.has(resolvedTarget)) {
             targetCanonical = resolvedTarget;
-            targetModule = modules.get(resolvedTarget);
+            targetModule = modules.get(resolvedTarget)!;
           } else {
             try {
               const loaded = await this.loadModule(resolvedTarget, options);
@@ -332,7 +388,7 @@ export class Loader {
                 modules.set(targetCanonical, loaded);
                 targetModule = loaded;
               } else {
-                targetModule = modules.get(targetCanonical);
+                targetModule = modules.get(targetCanonical)!;
               }
             } catch (err) {
               const e = err instanceof Error ? err : new Error(String(err));
@@ -349,32 +405,42 @@ export class Loader {
             }
           }
 
-          // Resolve target identity from its Telo.Library doc and stamp it
-          // on the edge — flattenForAnalyzer reads from the edge directly,
-          // never re-deriving from manifest.metadata.
-          let targetModuleName: string | null = null;
-          let targetNamespace: string | null = null;
-          if (targetModule) {
-            const lib = targetModule.owner.manifests.find(
-              (d) => d?.kind === "Telo.Library",
-            );
-            const libName = lib?.metadata?.name;
-            if (typeof libName === "string") targetModuleName = libName;
-            const libNs = (lib?.metadata as { namespace?: string | null } | undefined)
-              ?.namespace;
-            if (typeof libNs === "string") targetNamespace = libNs;
+          // Resolve target identity from its Telo.Library doc and stamp it on
+          // the edge — flattenForAnalyzer reads from the edge directly, never
+          // re-deriving from manifest.metadata.
+          //
+          // Checked per IMPORT rather than per distinct target: an import
+          // pointing at a module something else already reached (the entry
+          // application above all) would otherwise skip the check entirely and
+          // register a nameless edge. An unusable target is recorded exactly
+          // like an unfetchable one — an error against this import, no edge,
+          // and the rest of the graph still loads — so no consumer has to know
+          // the difference between the two ways an import can fail.
+          const identity = importTargetIdentity(targetModule, importSource);
+          if ("unusable" in identity) {
+            const e = new Error(identity.unusable);
+            (e as { sourceLine?: number }).sourceLine = sourceLine;
+            errors.push({
+              url: targetCanonical,
+              source: importSource,
+              fromSource: file.source,
+              alias,
+              sourceLine,
+              reason: "unusable-target",
+              error: e,
+            });
+            continue;
           }
 
           aliases.set(alias, {
             targetSource: targetCanonical,
             targetRef: importSource,
-            targetModuleName,
-            targetNamespace,
+            targetModuleName: identity.name,
+            targetNamespace: identity.namespace,
           });
 
-          if (targetModule && !visited.has(targetCanonical)) {
+          if (!visited.has(targetCanonical)) {
             visited.add(targetCanonical);
-            this.assertImportTargetIsLibrary(targetModule, importSource, sourceLine);
             queue.push(targetModule);
           }
         }
@@ -444,40 +510,6 @@ export class Loader {
     }
   }
 
-  private assertImportTargetIsLibrary(
-    target: LoadedModule,
-    importSource: string,
-    sourceLine: number,
-  ): void {
-    const importedLibrary = target.owner.manifests.find((m) => m?.kind === "Telo.Library");
-    const importedApplication = target.owner.manifests.find(
-      (m) => m?.kind === "Telo.Application",
-    );
-    if (importedApplication) {
-      const e = new Error(
-        `Telo.Import target '${importSource}' is a Telo.Application. ` +
-          `Only Telo.Library modules may be imported. Applications are run directly, not imported.`,
-      );
-      (e as { sourceLine?: number }).sourceLine = sourceLine;
-      throw e;
-    }
-    if (!importedLibrary) {
-      const kinds = target.owner.manifests
-        .map((m) => m?.kind)
-        .filter((k): k is string => typeof k === "string");
-      const detail = kinds.length
-        ? `Fetched ${target.owner.manifests.length} document(s) with kinds [${kinds.join(", ")}].`
-        : `Fetched manifest contained no recognizable Telo documents — check that the source ` +
-          `serves a Telo.Library manifest and not an upstream error page.`;
-      const e = new Error(
-        `Telo.Import target '${importSource}' did not resolve to a Telo.Library. ` +
-          `Fetched from: ${target.owner.source}. ${detail}`,
-      );
-      (e as { sourceLine?: number }).sourceLine = sourceLine;
-      throw e;
-    }
-  }
-
   private async resolveIncludes(
     ownerSource: string,
     patterns: string[],