@telorun/ide-support 0.7.9 → 0.8.0

package/dist/diagnostics/range-resolver.d.ts

@@ -12,5 +12,5 @@ import type { DiagnosticContext } from "../types.js";
  *       instead of spreading across every line of the surrounding map.
  *    4. Whole-line span at `sourceLine` when known.
  *    5. `(0,0)-(0,0)` as a last resort. Never undefined. */
-export declare function resolveRange(d: AnalysisDiagnostic, ctx: DiagnosticContext): Range;
+export declare function resolveRange(d: AnalysisDiagnostic, ctx: Pick<DiagnosticContext, "positionIndex" | "sourceLine">): Range;
 //# sourceMappingURL=range-resolver.d.ts.map

package/dist/diagnostics/range-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"range-resolver.d.ts","sourceRoot":"","sources":["../../src/diagnostics/range-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAOrD;;;;;;;;;;;4DAW4D;AAC5D,wBAAgB,YAAY,CAAC,CAAC,EAAE,kBAAkB,EAAE,GAAG,EAAE,iBAAiB,GAAG,KAAK,CAuBjF"}
+{"version":3,"file":"range-resolver.d.ts","sourceRoot":"","sources":["../../src/diagnostics/range-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAOrD;;;;;;;;;;;4DAW4D;AAC5D,wBAAgB,YAAY,CAC1B,CAAC,EAAE,kBAAkB,EAIrB,GAAG,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,YAAY,CAAC,GAC3D,KAAK,CAuBP"}

package/dist/diagnostics/range-resolver.js

@@ -14,7 +14,11 @@ const ZERO_RANGE = {
  *       instead of spreading across every line of the surrounding map.
  *    4. Whole-line span at `sourceLine` when known.
  *    5. `(0,0)-(0,0)` as a last resort. Never undefined. */
-export function resolveRange(d, ctx) {
+export function resolveRange(d, 
+// Only the position half of a `DiagnosticContext` — a full one still
+// satisfies this, and a caller holding just a located file (the CLI) does not
+// have to invent a registry to reuse the one resolution rule.
+ctx) {
     if (d.range)
         return d.range;
     const fieldPath = d.data?.path;

package/dist/import-upgrades/build-import-upgrades.d.ts

@@ -0,0 +1,78 @@
+import { type AstDocument, type Range } from "@telorun/analyzer";
+/** Version enumeration for one version-independent base ref, newest first.
+ *
+ *  Narrower than the full `IdeEnvironmentAdapter` on purpose. It is the only
+ *  environment capability an upgrade check needs, and a host that caches or
+ *  throttles hub traffic wraps just this — a CodeLens re-resolves far more
+ *  often than a completion popup opens, so the refresh cadence is the host's
+ *  policy, not this module's. A host backed by the hub passes
+ *  `adapter.listVersionsForRef`. */
+export type ModuleVersionLookup = (baseRef: string) => Promise<string[]>;
+/** A source edit a host applies verbatim to upgrade an import. Ranges never
+ *  overlap, within an upgrade or across a batch, so a host may apply the whole
+ *  set in one pass without ordering them. */
+export interface ImportUpgradeEdit {
+    range: Range;
+    newText: string;
+}
+/** One import that has a newer version available. */
+export interface ImportUpgrade {
+    alias: string;
+    /** The source as written, with any object-form `integrity:` folded in. */
+    source: string;
+    currentVersion: string;
+    latestVersion: string;
+    /** The source that replaces it: re-pointed at `latestVersion` with the
+     *  integrity pin dropped. */
+    newSource: string;
+    /** True when the replaced import carried a pin. A host that cannot recompute
+     *  the hash should say so — the pin covers the version being replaced, and
+     *  `telo upgrade` re-pins either shape. */
+    wasPinned: boolean;
+    /** Span of the alias key — where a per-entry affordance anchors. */
+    keyRange: Range;
+    /** Apply all of these to upgrade this one import. */
+    edits: ImportUpgradeEdit[];
+}
+/** An import that IS behind but that this module declines to rewrite. Carries
+ *  the same anchor and versions an {@link ImportUpgrade} does, so a host can
+ *  render it in place of the upgrade affordance rather than leaving the author
+ *  wondering why a stale import shows nothing at all. */
+export interface ImportUpgradeSkip {
+    alias: string;
+    currentVersion: string;
+    latestVersion: string;
+    /** Span of the alias key — where a per-entry affordance anchors. */
+    keyRange: Range;
+    /** Author-facing sentence: what was not done, and what to run instead. */
+    reason: string;
+}
+export interface ImportUpgradeSet {
+    /** Span of the `imports:` key — where a summary affordance anchors. */
+    importsKeyRange: Range;
+    upgrades: ImportUpgrade[];
+    skipped: ImportUpgradeSkip[];
+    /** Base refs whose version lookup failed. Never thrown: one unreachable ref
+     *  must not blank the affordances for every other import in the file. The
+     *  host decides whether to log or surface these. */
+    failures: Array<{
+        baseRef: string;
+        message: string;
+    }>;
+}
+/**
+ * Find every `imports:` entry of a module document that names a version older
+ * than the newest one `listVersions` reports, and produce the source edits that
+ * re-point it.
+ *
+ * Skips what carries no upgradeable version: local path imports, bare URLs,
+ * untagged refs, and pins that are not SemVer (an OCI digest, a moving tag like
+ * `latest`) — `parseVersionedRef` and `isNewerModuleVersion` both decline to
+ * guess, so those simply produce no upgrade.
+ *
+ * Pure apart from `listVersions`: no filesystem, no direct network, no host
+ * API. Returns `undefined` when the file declares no module document or the
+ * module declares no `imports:`.
+ */
+export declare function buildImportUpgrades(text: string, listVersions: ModuleVersionLookup, docs?: AstDocument[]): Promise<ImportUpgradeSet | undefined>;
+//# sourceMappingURL=build-import-upgrades.d.ts.map

package/dist/import-upgrades/build-import-upgrades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-import-upgrades.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/build-import-upgrades.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,KAAK,EACX,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;oCAOoC;AACpC,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAEzE;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB;iCAC6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB;;+CAE2C;IAC3C,SAAS,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED;;;yDAGyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,eAAe,EAAE,KAAK,CAAC;IACvB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;wDAEoD;IACpD,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,mBAAmB,EACjC,IAAI,CAAC,EAAE,WAAW,EAAE,GACnB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAmDvC"}

package/dist/import-upgrades/build-import-upgrades.js

@@ -0,0 +1,95 @@
+import { buildLineOffsets, isLocalPathSource, isNewerModuleVersion, newestModuleVersion, parseToAst, parseVersionedRef, withRefVersion, } from "@telorun/analyzer";
+import { findImportEntries } from "./find-import-entries.js";
+/**
+ * Find every `imports:` entry of a module document that names a version older
+ * than the newest one `listVersions` reports, and produce the source edits that
+ * re-point it.
+ *
+ * Skips what carries no upgradeable version: local path imports, bare URLs,
+ * untagged refs, and pins that are not SemVer (an OCI digest, a moving tag like
+ * `latest`) — `parseVersionedRef` and `isNewerModuleVersion` both decline to
+ * guess, so those simply produce no upgrade.
+ *
+ * Pure apart from `listVersions`: no filesystem, no direct network, no host
+ * API. Returns `undefined` when the file declares no module document or the
+ * module declares no `imports:`.
+ */
+export async function buildImportUpgrades(text, listVersions, docs) {
+    const lineOffsets = buildLineOffsets(text);
+    const block = findImportEntries(text, docs ?? parseToAst(text), lineOffsets);
+    if (!block)
+        return undefined;
+    const candidates = block.entries.flatMap((entry) => {
+        if (isLocalPathSource(entry.source))
+            return [];
+        const ref = parseVersionedRef(entry.source);
+        return ref ? [{ entry, ref }] : [];
+    });
+    const failures = [];
+    const latest = await resolveLatest([...new Set(candidates.map((c) => c.ref.baseRef))], listVersions, failures);
+    const upgrades = [];
+    const skipped = [];
+    for (const { entry, ref } of candidates) {
+        const newest = latest.get(ref.baseRef);
+        if (!newest || !isNewerModuleVersion(newest, ref.version))
+            continue;
+        if (entry.integrityInline) {
+            skipped.push({
+                alias: entry.alias,
+                currentVersion: ref.version,
+                latestVersion: newest,
+                keyRange: entry.keyRange,
+                reason: `'${entry.alias}' carries an inline 'integrity:' that shares a line with other ` +
+                    `fields, so the stale pin cannot be removed by a line edit. Run \`telo upgrade\`.`,
+            });
+            continue;
+        }
+        upgrades.push({
+            alias: entry.alias,
+            source: entry.source,
+            currentVersion: ref.version,
+            latestVersion: newest,
+            newSource: withRefVersion(entry.source, newest),
+            wasPinned: ref.integrity != null,
+            keyRange: entry.keyRange,
+            edits: buildEdits(entry, withRefVersion(entry.source, newest)),
+        });
+    }
+    return { importsKeyRange: block.keyRange, upgrades, skipped, failures };
+}
+/** Re-point the source scalar, and delete a now-stale object-form `integrity:`
+ *  line. `withRefVersion` already strips an inline `#sha256-…` fragment, so the
+ *  scalar shorthand needs no second edit. Dropping the pin is not optional: it
+ *  hashes the `telo.yaml` of the version being replaced, so carrying it onto a
+ *  different version turns the next install into a tamper error. */
+function buildEdits(entry, newSource) {
+    const edits = [{ range: entry.sourceRange, newText: newSource }];
+    if (entry.integrityLineRange) {
+        edits.push({ range: entry.integrityLineRange, newText: "" });
+    }
+    return edits;
+}
+/** Newest version per base ref, fetched once each. A ref whose lookup rejects
+ *  is recorded in `failures` and left out of the map, so it yields no upgrade
+ *  rather than a wrong one. */
+async function resolveLatest(baseRefs, listVersions, failures) {
+    const results = await Promise.all(baseRefs.map(async (baseRef) => {
+        try {
+            const versions = await listVersions(baseRef);
+            return { baseRef, newest: newestModuleVersion(versions) };
+        }
+        catch (err) {
+            failures.push({
+                baseRef,
+                message: err instanceof Error ? err.message : String(err),
+            });
+            return { baseRef, newest: undefined };
+        }
+    }));
+    const map = new Map();
+    for (const { baseRef, newest } of results) {
+        if (newest)
+            map.set(baseRef, newest);
+    }
+    return map;
+}

package/dist/import-upgrades/find-import-entries.d.ts

@@ -0,0 +1,45 @@
+import { type AstDocument, type Range } from "@telorun/analyzer";
+/** One `imports:` map entry, located in the source text.
+ *
+ *  `source` is the *folded* form — an object-form `integrity:` sibling is
+ *  folded into the source string as a `#sha256-…` fragment, exactly as
+ *  `inlineImportManifests` does, so callers reason about a single
+ *  representation regardless of which shape the author wrote. */
+export interface ImportEntry {
+    alias: string;
+    /** The source with any `integrity:` sibling folded in as a fragment. */
+    source: string;
+    /** Span of the alias key — where a per-entry affordance anchors. */
+    keyRange: Range;
+    /** Span of the source scalar's value: the entry value itself for the scalar
+     *  shorthand, the `source:` value for the object form. Replacing this span
+     *  re-points the import. */
+    sourceRange: Range;
+    /** Whole-line span of an object-form `integrity:` entry, including its
+     *  trailing newline, so a caller can delete the line. Absent for the scalar
+     *  shorthand (where the pin rides inside `sourceRange`) and for an entry that
+     *  declares no `integrity:`. */
+    integrityLineRange?: Range;
+    /** Set when the entry carries an `integrity:` sibling that does NOT occupy
+     *  whole lines of its own (a flow-style `{source: …, integrity: …}` map).
+     *  Deleting it would need a structural rewrite rather than a line splice, so
+     *  a caller that cannot leave the pin behind must skip this entry rather
+     *  than re-point it and strand a hash for the version it replaced. */
+    integrityInline?: boolean;
+}
+/** Where the `imports:` map lives in a module document. */
+export interface ImportsBlock {
+    /** Span of the `imports:` key — where a summary affordance anchors. */
+    keyRange: Range;
+    entries: ImportEntry[];
+}
+/** Locate the `imports:` map of the file's module document (`Telo.Application`
+ *  / `Telo.Library`). Returns `undefined` when the file declares no module doc
+ *  or the doc has no `imports:` map — a partial file, or a module with no
+ *  dependencies.
+ *
+ *  Reads the AST rather than the analyzer's flattened manifests because the
+ *  affordances built on top of this write back to the source: the exact span of
+ *  each source scalar is the deliverable, not the resolved value. */
+export declare function findImportEntries(text: string, docs: AstDocument[], lineOffsets: number[]): ImportsBlock | undefined;
+//# sourceMappingURL=find-import-entries.d.ts.map

package/dist/import-upgrades/find-import-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-import-entries.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/find-import-entries.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,WAAW,EAGhB,KAAK,KAAK,EACX,MAAM,mBAAmB,CAAC;AAE3B;;;;;iEAKiE;AACjE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB;;gCAE4B;IAC5B,WAAW,EAAE,KAAK,CAAC;IACnB;;;oCAGgC;IAChC,kBAAkB,CAAC,EAAE,KAAK,CAAC;IAC3B;;;;0EAIsE;IACtE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,KAAK,CAAC;IAChB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED;;;;;;;qEAOqE;AACrE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EAAE,EACnB,WAAW,EAAE,MAAM,EAAE,GACpB,YAAY,GAAG,SAAS,CAsB1B"}

package/dist/import-upgrades/find-import-entries.js

@@ -0,0 +1,102 @@
+import { foldIntegrity, isModuleKind, offsetToPosition, } from "@telorun/analyzer";
+/** Locate the `imports:` map of the file's module document (`Telo.Application`
+ *  / `Telo.Library`). Returns `undefined` when the file declares no module doc
+ *  or the doc has no `imports:` map — a partial file, or a module with no
+ *  dependencies.
+ *
+ *  Reads the AST rather than the analyzer's flattened manifests because the
+ *  affordances built on top of this write back to the source: the exact span of
+ *  each source scalar is the deliverable, not the resolved value. */
+export function findImportEntries(text, docs, lineOffsets) {
+    for (const doc of docs) {
+        const root = doc.root;
+        if (!root || root.kind !== "map")
+            continue;
+        if (!isModuleKind(scalarString(mapGet(root, "kind"))))
+            continue;
+        const importsPair = root.entries.find((p) => p.key.kind === "scalar" && p.key.value === "imports");
+        if (!importsPair?.value || importsPair.value.kind !== "map")
+            return undefined;
+        return {
+            keyRange: toRange(importsPair.key, lineOffsets),
+            entries: importsPair.value.entries.flatMap((pair) => {
+                const alias = scalarString(pair.key);
+                if (alias === undefined || !pair.value)
+                    return [];
+                const entry = readEntry(alias, pair.key, pair.value, text, lineOffsets);
+                return entry ? [entry] : [];
+            }),
+        };
+    }
+    return undefined;
+}
+/** Read one entry in either authored shape. Returns `undefined` for a malformed
+ *  entry (an object with no string `source:`) — the module document's own
+ *  schema validation already reports those against `imports.<Alias>.source`. */
+function readEntry(alias, keyNode, valueNode, text, lineOffsets) {
+    const keyRange = toRange(keyNode, lineOffsets);
+    if (valueNode.kind === "scalar") {
+        const source = scalarString(valueNode);
+        if (source === undefined)
+            return undefined;
+        return { alias, source, keyRange, sourceRange: toRange(valueNode, lineOffsets) };
+    }
+    if (valueNode.kind !== "map")
+        return undefined;
+    const sourceNode = mapGet(valueNode, "source");
+    const source = scalarString(sourceNode);
+    if (sourceNode === undefined || source === undefined)
+        return undefined;
+    const integrityPair = valueNode.entries.find((p) => p.key.kind === "scalar" && p.key.value === "integrity");
+    const integrity = scalarString(integrityPair?.value);
+    const entry = {
+        alias,
+        source: foldIntegrity(source, integrity),
+        keyRange,
+        sourceRange: toRange(sourceNode, lineOffsets),
+    };
+    if (integrityPair?.value && integrity !== undefined) {
+        const lineSpan = wholeLineSpan(integrityPair.key.range[0], integrityPair.value.range[1], text, lineOffsets);
+        if (lineSpan)
+            entry.integrityLineRange = lineSpan;
+        else
+            entry.integrityInline = true;
+    }
+    return entry;
+}
+/** The whole-lines span covering `[start, end)` plus its trailing newline, or
+ *  `undefined` when the span shares a line with other content — only leading
+ *  indentation may precede it and nothing but spacing may follow. A flow-style
+ *  map (`{source: …, integrity: …}`) fails this test, which is what keeps a
+ *  line splice from eating a sibling field. */
+function wholeLineSpan(start, end, text, lineOffsets) {
+    const lineStart = lineOffsets[offsetToPosition(start, lineOffsets).line];
+    if (text.slice(lineStart, start).trim() !== "")
+        return undefined;
+    const nextNewline = text.indexOf("\n", end);
+    const lineEnd = nextNewline === -1 ? text.length : nextNewline + 1;
+    if (text.slice(end, nextNewline === -1 ? text.length : nextNewline).trim() !== "") {
+        return undefined;
+    }
+    return {
+        start: offsetToPosition(lineStart, lineOffsets),
+        end: offsetToPosition(lineEnd, lineOffsets),
+    };
+}
+function toRange(node, lineOffsets) {
+    return {
+        start: offsetToPosition(node.range[0], lineOffsets),
+        end: offsetToPosition(node.range[1], lineOffsets),
+    };
+}
+function mapGet(node, key) {
+    return node.entries.find((p) => p.key.kind === "scalar" && p.key.value === key)?.value;
+}
+/** The node's value when it is a plain (untagged) string scalar. A `!cel` /
+ *  `!ref` scalar resolves to a sentinel object, not a string, so it falls out
+ *  here — an import source is never an expression. */
+function scalarString(node) {
+    if (!node || node.kind !== "scalar")
+        return undefined;
+    return typeof node.value === "string" ? node.value : undefined;
+}

package/dist/import-upgrades/index.d.ts

@@ -0,0 +1,5 @@
+export { buildImportUpgrades } from "./build-import-upgrades.js";
+export type { ImportUpgrade, ImportUpgradeEdit, ImportUpgradeSet, ImportUpgradeSkip, ModuleVersionLookup, } from "./build-import-upgrades.js";
+export { findImportEntries } from "./find-import-entries.js";
+export type { ImportEntry, ImportsBlock } from "./find-import-entries.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/import-upgrades/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/import-upgrades/index.js

@@ -0,0 +1,2 @@
+export { buildImportUpgrades } from "./build-import-upgrades.js";
+export { findImportEntries } from "./find-import-entries.js";

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export * from "./diagnostics/index.js";
 export * from "./hover/index.js";
 export * from "./semantic-tokens/index.js";
 export * from "./definition/index.js";
+export * from "./import-upgrades/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./diagnostics/index.js";
 export * from "./hover/index.js";
 export * from "./semantic-tokens/index.js";
 export * from "./definition/index.js";
+export * from "./import-upgrades/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/ide-support",
-  "version": "0.7.9",
+  "version": "0.8.0",
   "description": "Editor-host-agnostic IDE support (completions, diagnostic normalization) for Telo manifests.",
   "keywords": [
     "telo",
@@ -36,7 +36,7 @@
     "src/**"
   ],
   "dependencies": {
-    "@telorun/analyzer": "0.49.0"
+    "@telorun/analyzer": "0.50.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/diagnostics/range-resolver.ts

@@ -18,7 +18,13 @@ const ZERO_RANGE: Range = {
  *       instead of spreading across every line of the surrounding map.
  *    4. Whole-line span at `sourceLine` when known.
  *    5. `(0,0)-(0,0)` as a last resort. Never undefined. */
-export function resolveRange(d: AnalysisDiagnostic, ctx: DiagnosticContext): Range {
+export function resolveRange(
+  d: AnalysisDiagnostic,
+  // Only the position half of a `DiagnosticContext` — a full one still
+  // satisfies this, and a caller holding just a located file (the CLI) does not
+  // have to invent a registry to reuse the one resolution rule.
+  ctx: Pick<DiagnosticContext, "positionIndex" | "sourceLine">,
+): Range {
   if (d.range) return d.range;
 
   const fieldPath = (d.data as { path?: string } | undefined)?.path;

package/src/import-upgrades/build-import-upgrades.ts

@@ -0,0 +1,190 @@
+import {
+  buildLineOffsets,
+  isLocalPathSource,
+  isNewerModuleVersion,
+  newestModuleVersion,
+  parseToAst,
+  parseVersionedRef,
+  withRefVersion,
+  type AstDocument,
+  type Range,
+} from "@telorun/analyzer";
+import { findImportEntries, type ImportEntry } from "./find-import-entries.js";
+
+/** Version enumeration for one version-independent base ref, newest first.
+ *
+ *  Narrower than the full `IdeEnvironmentAdapter` on purpose. It is the only
+ *  environment capability an upgrade check needs, and a host that caches or
+ *  throttles hub traffic wraps just this — a CodeLens re-resolves far more
+ *  often than a completion popup opens, so the refresh cadence is the host's
+ *  policy, not this module's. A host backed by the hub passes
+ *  `adapter.listVersionsForRef`. */
+export type ModuleVersionLookup = (baseRef: string) => Promise<string[]>;
+
+/** A source edit a host applies verbatim to upgrade an import. Ranges never
+ *  overlap, within an upgrade or across a batch, so a host may apply the whole
+ *  set in one pass without ordering them. */
+export interface ImportUpgradeEdit {
+  range: Range;
+  newText: string;
+}
+
+/** One import that has a newer version available. */
+export interface ImportUpgrade {
+  alias: string;
+  /** The source as written, with any object-form `integrity:` folded in. */
+  source: string;
+  currentVersion: string;
+  latestVersion: string;
+  /** The source that replaces it: re-pointed at `latestVersion` with the
+   *  integrity pin dropped. */
+  newSource: string;
+  /** True when the replaced import carried a pin. A host that cannot recompute
+   *  the hash should say so — the pin covers the version being replaced, and
+   *  `telo upgrade` re-pins either shape. */
+  wasPinned: boolean;
+  /** Span of the alias key — where a per-entry affordance anchors. */
+  keyRange: Range;
+  /** Apply all of these to upgrade this one import. */
+  edits: ImportUpgradeEdit[];
+}
+
+/** An import that IS behind but that this module declines to rewrite. Carries
+ *  the same anchor and versions an {@link ImportUpgrade} does, so a host can
+ *  render it in place of the upgrade affordance rather than leaving the author
+ *  wondering why a stale import shows nothing at all. */
+export interface ImportUpgradeSkip {
+  alias: string;
+  currentVersion: string;
+  latestVersion: string;
+  /** Span of the alias key — where a per-entry affordance anchors. */
+  keyRange: Range;
+  /** Author-facing sentence: what was not done, and what to run instead. */
+  reason: string;
+}
+
+export interface ImportUpgradeSet {
+  /** Span of the `imports:` key — where a summary affordance anchors. */
+  importsKeyRange: Range;
+  upgrades: ImportUpgrade[];
+  skipped: ImportUpgradeSkip[];
+  /** Base refs whose version lookup failed. Never thrown: one unreachable ref
+   *  must not blank the affordances for every other import in the file. The
+   *  host decides whether to log or surface these. */
+  failures: Array<{ baseRef: string; message: string }>;
+}
+
+/**
+ * Find every `imports:` entry of a module document that names a version older
+ * than the newest one `listVersions` reports, and produce the source edits that
+ * re-point it.
+ *
+ * Skips what carries no upgradeable version: local path imports, bare URLs,
+ * untagged refs, and pins that are not SemVer (an OCI digest, a moving tag like
+ * `latest`) — `parseVersionedRef` and `isNewerModuleVersion` both decline to
+ * guess, so those simply produce no upgrade.
+ *
+ * Pure apart from `listVersions`: no filesystem, no direct network, no host
+ * API. Returns `undefined` when the file declares no module document or the
+ * module declares no `imports:`.
+ */
+export async function buildImportUpgrades(
+  text: string,
+  listVersions: ModuleVersionLookup,
+  docs?: AstDocument[],
+): Promise<ImportUpgradeSet | undefined> {
+  const lineOffsets = buildLineOffsets(text);
+  const block = findImportEntries(text, docs ?? parseToAst(text), lineOffsets);
+  if (!block) return undefined;
+
+  const candidates = block.entries.flatMap((entry) => {
+    if (isLocalPathSource(entry.source)) return [];
+    const ref = parseVersionedRef(entry.source);
+    return ref ? [{ entry, ref }] : [];
+  });
+
+  const failures: Array<{ baseRef: string; message: string }> = [];
+  const latest = await resolveLatest(
+    [...new Set(candidates.map((c) => c.ref.baseRef))],
+    listVersions,
+    failures,
+  );
+
+  const upgrades: ImportUpgrade[] = [];
+  const skipped: ImportUpgradeSkip[] = [];
+
+  for (const { entry, ref } of candidates) {
+    const newest = latest.get(ref.baseRef);
+    if (!newest || !isNewerModuleVersion(newest, ref.version)) continue;
+
+    if (entry.integrityInline) {
+      skipped.push({
+        alias: entry.alias,
+        currentVersion: ref.version,
+        latestVersion: newest,
+        keyRange: entry.keyRange,
+        reason:
+          `'${entry.alias}' carries an inline 'integrity:' that shares a line with other ` +
+          `fields, so the stale pin cannot be removed by a line edit. Run \`telo upgrade\`.`,
+      });
+      continue;
+    }
+
+    upgrades.push({
+      alias: entry.alias,
+      source: entry.source,
+      currentVersion: ref.version,
+      latestVersion: newest,
+      newSource: withRefVersion(entry.source, newest),
+      wasPinned: ref.integrity != null,
+      keyRange: entry.keyRange,
+      edits: buildEdits(entry, withRefVersion(entry.source, newest)),
+    });
+  }
+
+  return { importsKeyRange: block.keyRange, upgrades, skipped, failures };
+}
+
+/** Re-point the source scalar, and delete a now-stale object-form `integrity:`
+ *  line. `withRefVersion` already strips an inline `#sha256-…` fragment, so the
+ *  scalar shorthand needs no second edit. Dropping the pin is not optional: it
+ *  hashes the `telo.yaml` of the version being replaced, so carrying it onto a
+ *  different version turns the next install into a tamper error. */
+function buildEdits(entry: ImportEntry, newSource: string): ImportUpgradeEdit[] {
+  const edits: ImportUpgradeEdit[] = [{ range: entry.sourceRange, newText: newSource }];
+  if (entry.integrityLineRange) {
+    edits.push({ range: entry.integrityLineRange, newText: "" });
+  }
+  return edits;
+}
+
+/** Newest version per base ref, fetched once each. A ref whose lookup rejects
+ *  is recorded in `failures` and left out of the map, so it yields no upgrade
+ *  rather than a wrong one. */
+async function resolveLatest(
+  baseRefs: string[],
+  listVersions: ModuleVersionLookup,
+  failures: Array<{ baseRef: string; message: string }>,
+): Promise<Map<string, string>> {
+  const results = await Promise.all(
+    baseRefs.map(async (baseRef) => {
+      try {
+        const versions = await listVersions(baseRef);
+        return { baseRef, newest: newestModuleVersion(versions) };
+      } catch (err) {
+        failures.push({
+          baseRef,
+          message: err instanceof Error ? err.message : String(err),
+        });
+        return { baseRef, newest: undefined };
+      }
+    }),
+  );
+
+  const map = new Map<string, string>();
+  for (const { baseRef, newest } of results) {
+    if (newest) map.set(baseRef, newest);
+  }
+  return map;
+}
+

package/src/import-upgrades/find-import-entries.ts

@@ -0,0 +1,175 @@
+import {
+  foldIntegrity,
+  isModuleKind,
+  offsetToPosition,
+  type AstDocument,
+  type AstMap,
+  type AstNode,
+  type Range,
+} from "@telorun/analyzer";
+
+/** One `imports:` map entry, located in the source text.
+ *
+ *  `source` is the *folded* form — an object-form `integrity:` sibling is
+ *  folded into the source string as a `#sha256-…` fragment, exactly as
+ *  `inlineImportManifests` does, so callers reason about a single
+ *  representation regardless of which shape the author wrote. */
+export interface ImportEntry {
+  alias: string;
+  /** The source with any `integrity:` sibling folded in as a fragment. */
+  source: string;
+  /** Span of the alias key — where a per-entry affordance anchors. */
+  keyRange: Range;
+  /** Span of the source scalar's value: the entry value itself for the scalar
+   *  shorthand, the `source:` value for the object form. Replacing this span
+   *  re-points the import. */
+  sourceRange: Range;
+  /** Whole-line span of an object-form `integrity:` entry, including its
+   *  trailing newline, so a caller can delete the line. Absent for the scalar
+   *  shorthand (where the pin rides inside `sourceRange`) and for an entry that
+   *  declares no `integrity:`. */
+  integrityLineRange?: Range;
+  /** Set when the entry carries an `integrity:` sibling that does NOT occupy
+   *  whole lines of its own (a flow-style `{source: …, integrity: …}` map).
+   *  Deleting it would need a structural rewrite rather than a line splice, so
+   *  a caller that cannot leave the pin behind must skip this entry rather
+   *  than re-point it and strand a hash for the version it replaced. */
+  integrityInline?: boolean;
+}
+
+/** Where the `imports:` map lives in a module document. */
+export interface ImportsBlock {
+  /** Span of the `imports:` key — where a summary affordance anchors. */
+  keyRange: Range;
+  entries: ImportEntry[];
+}
+
+/** Locate the `imports:` map of the file's module document (`Telo.Application`
+ *  / `Telo.Library`). Returns `undefined` when the file declares no module doc
+ *  or the doc has no `imports:` map — a partial file, or a module with no
+ *  dependencies.
+ *
+ *  Reads the AST rather than the analyzer's flattened manifests because the
+ *  affordances built on top of this write back to the source: the exact span of
+ *  each source scalar is the deliverable, not the resolved value. */
+export function findImportEntries(
+  text: string,
+  docs: AstDocument[],
+  lineOffsets: number[],
+): ImportsBlock | undefined {
+  for (const doc of docs) {
+    const root = doc.root;
+    if (!root || root.kind !== "map") continue;
+    if (!isModuleKind(scalarString(mapGet(root, "kind")))) continue;
+
+    const importsPair = root.entries.find(
+      (p) => p.key.kind === "scalar" && p.key.value === "imports",
+    );
+    if (!importsPair?.value || importsPair.value.kind !== "map") return undefined;
+
+    return {
+      keyRange: toRange(importsPair.key, lineOffsets),
+      entries: importsPair.value.entries.flatMap((pair) => {
+        const alias = scalarString(pair.key);
+        if (alias === undefined || !pair.value) return [];
+        const entry = readEntry(alias, pair.key, pair.value, text, lineOffsets);
+        return entry ? [entry] : [];
+      }),
+    };
+  }
+  return undefined;
+}
+
+/** Read one entry in either authored shape. Returns `undefined` for a malformed
+ *  entry (an object with no string `source:`) — the module document's own
+ *  schema validation already reports those against `imports.<Alias>.source`. */
+function readEntry(
+  alias: string,
+  keyNode: AstNode,
+  valueNode: AstNode,
+  text: string,
+  lineOffsets: number[],
+): ImportEntry | undefined {
+  const keyRange = toRange(keyNode, lineOffsets);
+
+  if (valueNode.kind === "scalar") {
+    const source = scalarString(valueNode);
+    if (source === undefined) return undefined;
+    return { alias, source, keyRange, sourceRange: toRange(valueNode, lineOffsets) };
+  }
+
+  if (valueNode.kind !== "map") return undefined;
+  const sourceNode = mapGet(valueNode, "source");
+  const source = scalarString(sourceNode);
+  if (sourceNode === undefined || source === undefined) return undefined;
+
+  const integrityPair = valueNode.entries.find(
+    (p) => p.key.kind === "scalar" && p.key.value === "integrity",
+  );
+  const integrity = scalarString(integrityPair?.value);
+
+  const entry: ImportEntry = {
+    alias,
+    source: foldIntegrity(source, integrity),
+    keyRange,
+    sourceRange: toRange(sourceNode, lineOffsets),
+  };
+
+  if (integrityPair?.value && integrity !== undefined) {
+    const lineSpan = wholeLineSpan(
+      integrityPair.key.range[0],
+      integrityPair.value.range[1],
+      text,
+      lineOffsets,
+    );
+    if (lineSpan) entry.integrityLineRange = lineSpan;
+    else entry.integrityInline = true;
+  }
+
+  return entry;
+}
+
+/** The whole-lines span covering `[start, end)` plus its trailing newline, or
+ *  `undefined` when the span shares a line with other content — only leading
+ *  indentation may precede it and nothing but spacing may follow. A flow-style
+ *  map (`{source: …, integrity: …}`) fails this test, which is what keeps a
+ *  line splice from eating a sibling field. */
+function wholeLineSpan(
+  start: number,
+  end: number,
+  text: string,
+  lineOffsets: number[],
+): Range | undefined {
+  const lineStart = lineOffsets[offsetToPosition(start, lineOffsets).line];
+  if (text.slice(lineStart, start).trim() !== "") return undefined;
+
+  const nextNewline = text.indexOf("\n", end);
+  const lineEnd = nextNewline === -1 ? text.length : nextNewline + 1;
+  if (text.slice(end, nextNewline === -1 ? text.length : nextNewline).trim() !== "") {
+    return undefined;
+  }
+
+  return {
+    start: offsetToPosition(lineStart, lineOffsets),
+    end: offsetToPosition(lineEnd, lineOffsets),
+  };
+}
+
+function toRange(node: AstNode, lineOffsets: number[]): Range {
+  return {
+    start: offsetToPosition(node.range[0], lineOffsets),
+    end: offsetToPosition(node.range[1], lineOffsets),
+  };
+}
+
+function mapGet(node: AstMap, key: string): AstNode | undefined {
+  return node.entries.find((p) => p.key.kind === "scalar" && p.key.value === key)?.value;
+}
+
+/** The node's value when it is a plain (untagged) string scalar. A `!cel` /
+ *  `!ref` scalar resolves to a sentinel object, not a string, so it falls out
+ *  here — an import source is never an expression. */
+function scalarString(node: AstNode | undefined): string | undefined {
+  if (!node || node.kind !== "scalar") return undefined;
+  return typeof node.value === "string" ? node.value : undefined;
+}

package/src/import-upgrades/index.ts

@@ -0,0 +1,10 @@
+export { buildImportUpgrades } from "./build-import-upgrades.js";
+export type {
+  ImportUpgrade,
+  ImportUpgradeEdit,
+  ImportUpgradeSet,
+  ImportUpgradeSkip,
+  ModuleVersionLookup,
+} from "./build-import-upgrades.js";
+export { findImportEntries } from "./find-import-entries.js";
+export type { ImportEntry, ImportsBlock } from "./find-import-entries.js";

package/src/index.ts

@@ -4,3 +4,4 @@ export * from "./diagnostics/index.js";
 export * from "./hover/index.js";
 export * from "./semantic-tokens/index.js";
 export * from "./definition/index.js";
+export * from "./import-upgrades/index.js";