@telorun/analyzer 0.56.1 → 0.58.0

package/src/migrations/provenance.ts

@@ -0,0 +1,167 @@
+/** Path provenance — part of the driver's contract, not an optional extra.
+ *
+ *  `resolveRange` looks a diagnostic's dotted path up in a position index built
+ *  from the RAW file, then falls back to the parent's key or value range. Every
+ *  rewrite that existed before migrations preserved paths; a `rename-key` is
+ *  the first that does not, and without a remap every downstream diagnostic on
+ *  that node degrades to a parent squiggle — with a `DiagnosticFix` over a
+ *  single-line parent value writing a whole value across it.
+ *
+ *  So each rewrite records the legacy path it matched alongside the migrated
+ *  one, and diagnostics are remapped through that record before position
+ *  resolution. This is the generalization of `rewriteSyntheticOrigins`, which
+ *  already rewrites `data.path` so lookups resolve after
+ *  `normalizeInlineResources` has moved a resource. */
+
+import type { AnalysisDiagnostic } from "../types.js";
+import type { LoadedGraph } from "../loaded-types.js";
+import type { MigrationRewrite } from "./types.js";
+
+/** One rewrite, with everything a diagnostic could be routed by.
+ *
+ *  A diagnostic carries at most two routing facts — the file it is in and the
+ *  resource it is about — and it routinely carries only one. So a record keeps
+ *  both, and both indexes below are built over the same records. */
+interface RewriteRecord {
+  readonly source: string;
+  readonly kind?: string;
+  readonly name?: string;
+  readonly rewrite: MigrationRewrite;
+}
+
+/** Records reachable by each routing fact.
+ *
+ *  `byFile` is the general index: every rewrite is in it, so a diagnostic that
+ *  names only its file is still remapped. Indexing by identity ALONE was the
+ *  hole this closes — a diagnostic with no `data.resource` (a module-level one)
+ *  and a rewrite in a document with no `metadata.name` (every `Telo.Import`)
+ *  were both simply unreachable.
+ *
+ *  `byIdentity` is the NARROWING index, not a substitute: `(kind, name)` is not
+ *  an identity across a graph, since resource names are module-scoped and two
+ *  modules routinely declare the same one (`Store`, `Connection`, …). Applying
+ *  one module's record to another's diagnostic is exactly how a squiggle lands
+ *  on an unrelated node — the failure this pass exists to prevent. */
+interface RewriteIndex {
+  readonly byFile: Map<string, RewriteRecord[]>;
+  readonly byIdentity: Map<string, RewriteRecord[]>;
+  readonly size: number;
+}
+
+function identityKey(kind: string, name: string): string {
+  return `${kind}\0${name}`;
+}
+
+function push(index: Map<string, RewriteRecord[]>, key: string, record: RewriteRecord): void {
+  const bucket = index.get(key);
+  if (bucket) bucket.push(record);
+  else index.set(key, [record]);
+}
+
+function buildIndex(graph: LoadedGraph): RewriteIndex {
+  const byFile = new Map<string, RewriteRecord[]>();
+  const byIdentity = new Map<string, RewriteRecord[]>();
+  let size = 0;
+  for (const mod of graph.modules.values()) {
+    for (const file of [mod.owner, ...mod.partials]) {
+      for (const rewrite of file.migrations.rewrites) {
+        const manifest = file.manifests[rewrite.documentIndex];
+        const kind = typeof manifest?.kind === "string" ? manifest.kind : undefined;
+        const name = typeof manifest?.metadata?.name === "string" ? manifest.metadata.name : undefined;
+        const record: RewriteRecord = { source: file.source, kind, name, rewrite };
+        push(byFile, file.source, record);
+        if (kind !== undefined && name !== undefined) {
+          push(byIdentity, identityKey(kind, name), record);
+        }
+        size++;
+      }
+    }
+  }
+  return { byFile, byIdentity, size };
+}
+
+/** The records a diagnostic may be remapped against, narrowed by whichever
+ *  routing facts it carries. `undefined` means "cannot be narrowed to one
+ *  file", the one case where no answer is better than a guess. */
+function candidatesFor(
+  index: RewriteIndex,
+  filePath: string | undefined,
+  kind: string | undefined,
+  name: string | undefined,
+): RewriteRecord[] | undefined {
+  if (kind !== undefined && name !== undefined) {
+    const records = index.byIdentity.get(identityKey(kind, name));
+    if (!records) return undefined;
+    if (filePath !== undefined) return records.filter((r) => r.source === filePath);
+    // Several files declare this identity and the diagnostic names none of
+    // them. Guessing would move a squiggle onto an unrelated node, which is
+    // worse than the parent-squiggle fallback leaving it where it is.
+    return new Set(records.map((r) => r.source)).size > 1 ? undefined : records;
+  }
+  if (filePath !== undefined) return index.byFile.get(filePath);
+  return undefined;
+}
+
+/** `path` with the longest matching migrated prefix swapped back to the legacy
+ *  spelling, or `undefined` when no rewrite touched it. Longest-prefix wins so
+ *  a rewrite nested inside another resolves against the innermost one.
+ *
+ *  Two records covering the same path with DIFFERENT legacy spellings are
+ *  ambiguous — a file-scoped candidate set spans every document in the file,
+ *  and two documents can share a path. Refusing beats picking one. */
+function remapPath(path: string, records: readonly RewriteRecord[]): string | undefined {
+  let best: MigrationRewrite | undefined;
+  let ambiguous = false;
+  for (const { rewrite } of records) {
+    const migrated = rewrite.migratedPath;
+    if (migrated === rewrite.legacyPath) continue;
+    const covers =
+      path === migrated || path.startsWith(`${migrated}.`) || path.startsWith(`${migrated}[`);
+    if (!covers) continue;
+    if (!best || migrated.length > best.migratedPath.length) {
+      best = rewrite;
+      ambiguous = false;
+    } else if (
+      migrated.length === best.migratedPath.length &&
+      rewrite.legacyPath !== best.legacyPath
+    ) {
+      ambiguous = true;
+    }
+  }
+  if (!best || ambiguous) return undefined;
+  return best.legacyPath + path.slice(best.migratedPath.length);
+}
+
+/**
+ * Rewrite every diagnostic's `data.path` from the migrated spelling back to
+ * what the author wrote, so position lookups against the raw file resolve.
+ *
+ * A no-op — and returns the input array — when nothing in the graph was
+ * migrated, which is the overwhelmingly common case.
+ */
+export function remapMigratedPaths(
+  graph: LoadedGraph,
+  diagnostics: readonly AnalysisDiagnostic[],
+): AnalysisDiagnostic[] {
+  const index = buildIndex(graph);
+  if (index.size === 0) return [...diagnostics];
+
+  return diagnostics.map((d) => {
+    const data = d.data as
+      | { resource?: { kind?: string; name?: string }; path?: string; filePath?: string }
+      | undefined;
+    if (typeof data?.path !== "string") return d;
+
+    const records = candidatesFor(
+      index,
+      typeof data.filePath === "string" ? data.filePath : undefined,
+      typeof data.resource?.kind === "string" ? data.resource.kind : undefined,
+      typeof data.resource?.name === "string" ? data.resource.name : undefined,
+    );
+    if (!records || records.length === 0) return d;
+
+    const remapped = remapPath(data.path, records);
+    if (remapped === undefined || remapped === data.path) return d;
+    return { ...d, data: { ...data, path: remapped } };
+  });
+}

package/src/migrations/registry.ts

@@ -0,0 +1,40 @@
+/** The core migration set — entries that ship with the analyzer and may match
+ *  any node.
+ *
+ *  **The set is data, not code.** One JSON file per entry, canonical at
+ *  `analyzer/migrations/`, read as one lexically ordered list: adding a
+ *  migration is one file, and retiring one is deleting it. Nothing here lists
+ *  the entries — TypeScript has no glob import, so the barrel beside the copies
+ *  is emitted from the same directory listing that produced them. A
+ *  hand-maintained list was the one place this mechanism could fail silently:
+ *  add a file, forget the import, and the migration never fires, which looks
+ *  exactly like one that ran.
+ *
+ *  The files live beside the language implementations rather than inside any
+ *  one of them because every kernel must apply the IDENTICAL rewrite — a
+ *  rewrite added to one side would mean one artifact means two things on two
+ *  kernels, invisibly, since a migration that succeeds is silent. Only
+ *  `analyzer/nodejs` reads them today — the Rust reader is planned, and until
+ *  it lands the Rust kernel applies NO migration, so a legacy spelling it
+ *  cannot otherwise interpret fails there rather than being rewritten. When it
+ *  lands it will embed these files with `include_str!`; a Go half would use
+ *  `//go:embed`. JSON rather than YAML for one reason: it is the only format
+ *  all three embed with no generation step, because TypeScript's only native
+ *  embed is `resolveJsonModule`. The copy under `./entries/` is made by the
+ *  analyzer's `prepare` (`scripts/copy-migration-entries.mjs`) — identical
+ *  bytes, so no entry's MEANING is ever derived from anything.
+ *
+ *  **Entries carry no version stamp.** "Can this be deleted?" turns on whether
+ *  any published artifact still carries the legacy spelling, which the
+ *  artifact's own release version cannot answer — the hub can, since it caches
+ *  every tracked module version's `telo.yaml`. A stamp would record when an
+ *  entry was written, which git already does, while looking like an answer to a
+ *  question it does not address. */
+
+import { parseMigrationEntry } from "./entry-data.js";
+import { MIGRATION_ENTRY_FILES } from "./entries/index.js";
+import type { MigrationEntry } from "./types.js";
+
+export const CORE_MIGRATIONS: readonly MigrationEntry[] = MIGRATION_ENTRY_FILES.map(
+  ([file, data]) => parseMigrationEntry(file, data),
+);

package/src/migrations/report.ts

@@ -0,0 +1,169 @@
+/** How a rewrite is REPORTED — the provenance record and the diagnostic.
+ *
+ *  Split from the driver because the two answer different questions: the driver
+ *  owns the guarantees (one pass, a frozen match set, all-or-nothing patches,
+ *  refusal rather than a guess), while everything here is about telling an
+ *  author what happened. Nothing in this file can change what a migration does.
+ *
+ *  **A diagnostic composes in three parts and the entry writes only one.** What
+ *  changed and how to apply it are generated identically for every entry, from
+ *  the matched key and value, the replacement, and the operation verbs. What
+ *  the driver cannot know is *why*, which is the part that makes a deprecation
+ *  actionable rather than mysterious — so an entry supplies `reason`, and never
+ *  a clause of the generated sentence. */
+
+import type { ResourceManifest } from "@telorun/sdk";
+import { isTaggedSentinel } from "@telorun/templating";
+import { formatMigrationPath, type MigrationEffect, type PatchPlan } from "./patch.js";
+import type {
+  MigrationEntry,
+  MigrationOperation,
+  MigrationPath,
+  MigrationRewrite,
+} from "./types.js";
+import type { AnalysisDiagnostic, DiagnosticFix } from "../types.js";
+
+/** One patch that applied, as the reporting side needs to see it. */
+export interface AppliedPatch {
+  readonly entry: MigrationEntry;
+  readonly documentIndex: number;
+  readonly matched: MigrationPath;
+  readonly plan: PatchPlan;
+  readonly ops: readonly MigrationOperation[];
+}
+
+export function toRewrite(applied: AppliedPatch): MigrationRewrite {
+  return {
+    entryId: applied.entry.id,
+    code: applied.entry.code,
+    severity: applied.entry.severity,
+    documentIndex: applied.documentIndex,
+    legacyPath: formatMigrationPath(applied.matched),
+    migratedPath: formatMigrationPath(applied.plan.finalPath),
+    summary: describeChange(applied),
+  };
+}
+
+export function toDiagnostic(
+  applied: AppliedPatch,
+  rewrite: MigrationRewrite,
+  source: string,
+  manifests: ReadonlyArray<ResourceManifest | null>,
+): AnalysisDiagnostic {
+  const fix = deriveFix(applied);
+  const closing = fix
+    ? "Run `telo migrate` to apply it."
+    : `no quick fix (${refusalPhrase(applied.ops)}) — run \`telo migrate\``;
+
+  const manifest = manifests[applied.documentIndex];
+  const kind = manifest?.kind;
+  const name = manifest?.metadata?.name;
+
+  return {
+    severity: applied.entry.severity,
+    code: applied.entry.code,
+    source: "telo-analyzer",
+    message: `${rewrite.summary}\n${applied.entry.reason}\n${closing}`,
+    data: {
+      filePath: source,
+      // The AUTHOR's path, not the post-rewrite one: the position index is
+      // built from the raw file and knows only the spelling that is in it.
+      path: rewrite.legacyPath,
+      ...(typeof kind === "string" && typeof name === "string"
+        ? { resource: { kind, name } }
+        : {}),
+      ...(fix ? { fix } : {}),
+      migration: {
+        id: applied.entry.id,
+        legacyPath: rewrite.legacyPath,
+        migratedPath: rewrite.migratedPath,
+      },
+    },
+  };
+}
+
+/**
+ * Whether a quick fix exists is DERIVED from the operations, never declared.
+ *
+ * `DiagnosticFix` is a whole-value `replacement` written over a value node's
+ * span, and it promises a repair applicable without review. A lone `set-value`
+ * producing a scalar is exactly that. Anything else — a key rename, a tag, a
+ * collection edit, a structured value — has no honest whole-value form, and the
+ * diagnostic says so rather than offering a repair that would corrupt the file.
+ * The derivation is total, so a migration never silently lacks one.
+ */
+function deriveFix(applied: AppliedPatch): DiagnosticFix | undefined {
+  if (applied.ops.length !== 1) return undefined;
+  const only = applied.ops[0]!;
+  if (only.op !== "set-value") return undefined;
+  const value = applied.plan.after;
+  if (typeof value === "string") return { replacement: value };
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    return { replacement: String(value) };
+  }
+  return undefined;
+}
+
+function refusalPhrase(ops: readonly MigrationOperation[]): string {
+  for (const op of ops) {
+    switch (op.op) {
+      case "rename-key":
+        return "renames a key";
+      case "set-tag":
+        return "adds a tag";
+      case "insert-item":
+        return "inserts an item";
+      case "remove-entry":
+        return "removes an entry";
+      default:
+        break;
+    }
+  }
+  return "writes a structured value";
+}
+
+/** Only the items an `insert-item` added, narrowed by the effect's own kind so
+ *  the value is read off a typed field rather than cast out of a union. */
+function insertedValues(effects: readonly MigrationEffect[]): unknown[] | undefined {
+  const values: unknown[] = [];
+  for (const effect of effects) {
+    if (effect.kind !== "insert-item") return undefined;
+    values.push(effect.value);
+  }
+  return values.length > 0 ? values : undefined;
+}
+
+/** The generated "what changed" sentence — the half no entry writes. */
+function describeChange(applied: AppliedPatch): string {
+  const legacyKey = lastSegment(applied.matched);
+  const migratedKey = lastSegment(applied.plan.finalPath);
+  const { before, after, effects } = applied.plan;
+
+  if (after === undefined && effects.some((e) => e.kind === "remove-entry")) {
+    return `\`${legacyKey}\` is no longer used.`;
+  }
+  const inserted = insertedValues(effects);
+  if (inserted) {
+    return `\`${formatMigrationPath(applied.matched)}\` gains \`${inserted
+      .map(renderValue)
+      .join("`, `")}\`.`;
+  }
+  return `\`${legacyKey}: ${renderValue(before)}\` is now written \`${migratedKey}: ${renderValue(after)}\`.`;
+}
+
+function lastSegment(path: MigrationPath): string {
+  const last = path[path.length - 1];
+  return typeof last === "number" ? `[${last}]` : String(last ?? "");
+}
+
+function renderValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (isTaggedSentinel(value)) return `!${value.engine} ${value.source}`;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/migrations/types.ts

@@ -0,0 +1,144 @@
+/** Manifest migrations — the entry vocabulary.
+ *
+ *  A migration is a MATCHER plus a PATCH. The two halves are at different
+ *  maturities and that is deliberate (`plans/manifest-migrations.md`):
+ *
+ *  - The **patch** names what it targets. Every operation has a known YAML edit
+ *    form, which is what makes a migration applicable to a *file* at all and
+ *    what lets the driver derive whether a quick fix exists — read straight off
+ *    the verb, never declared by the author.
+ *  - The **matcher** selects every occurrence of a legacy spelling, which is
+ *    the half a plain patch format has none of (see `match.ts`).
+ *
+ *  BOTH halves are data, and an entry contains no code at all. That is what
+ *  lets one entry file be read by every kernel: a predicate expressed in one
+ *  language would mean one artifact is read two ways, invisibly, since a
+ *  migration that succeeds is silent. A migration that does not fit is a signal
+ *  to extend the vocabulary, never to hand-write a rewrite. */
+
+import type { DiagnosticSeverity } from "../types.js";
+import type { MigrationMatch } from "./match.js";
+
+/** A location inside one manifest document. Segments are mapping keys
+ *  (strings) and sequence indices (numbers) — the same shape `Document.getIn`
+ *  takes, so the tree applier and the YAML applier address a node identically. */
+export type MigrationPath = ReadonlyArray<string | number>;
+
+/** Rename the matched mapping entry's KEY, within its own mapping. Deliberately
+ *  not JSON Patch's `move`, which relocates a value anywhere in a document
+ *  across parents and replaces an occupied destination. This refuses an
+ *  occupied destination instead — silently discarding a value the author wrote
+ *  is exactly what the leave-it-alone invariant exists to prevent. */
+export interface RenameKeyOperation {
+  readonly op: "rename-key";
+  readonly to: string;
+}
+
+/** Replace the value at the matched location.
+ *
+ *  Exactly one of `value` / `qualify` is supplied. `qualify` prefixes the
+ *  existing string — the shape a spelling rewrite that alias-qualifies a bare
+ *  name needs, which a literal `value` cannot express because a patch is static
+ *  data and cannot read the match. */
+export interface SetValueOperation {
+  readonly op: "set-value";
+  readonly value?: unknown;
+  readonly qualify?: string;
+}
+
+/** Put the matched scalar behind a templating tag (`!cel`, `!ref`, …). `tag` is
+ *  the engine name without its `!`. */
+export interface SetTagOperation {
+  readonly op: "set-tag";
+  readonly tag: string;
+}
+
+/** Insert an item into the matched sequence. `at` defaults to the end. */
+export interface InsertItemOperation {
+  readonly op: "insert-item";
+  readonly value: unknown;
+  readonly at?: number;
+}
+
+/** Remove the matched mapping entry or sequence item. */
+export interface RemoveEntryOperation {
+  readonly op: "remove-entry";
+}
+
+/** The closed operation vocabulary. Named for what each TARGETS, so the target
+ *  is never inferred from which parameter happens to be present and the
+ *  quick-fix question reads off the name. */
+export type MigrationOperation =
+  | RenameKeyOperation
+  | SetValueOperation
+  | SetTagOperation
+  | InsertItemOperation
+  | RemoveEntryOperation;
+
+export const MIGRATION_OPS = [
+  "rename-key",
+  "set-value",
+  "set-tag",
+  "insert-item",
+  "remove-entry",
+] as const;
+
+/** One legacy spelling and the edit that replaces it. */
+export interface MigrationRule {
+  /** Which nodes this rule rewrites, resolved against the frozen pre-migration
+   *  tree. Declarative — see `match.ts`. */
+  readonly match: MigrationMatch;
+  /** Applied in order at each match. A patch that cannot apply in full leaves
+   *  the node untouched. */
+  readonly patch: readonly MigrationOperation[];
+}
+
+/** One deprecation story. May carry several rules — the value-type unification
+ *  changed three spellings but tells the author one thing, which is why the
+ *  rationale is entry-level and a mechanical description is not. */
+export interface MigrationEntry {
+  /** Stable identifier. Names which migration fired; docs list them. */
+  readonly id: string;
+  /** Diagnostic code reported for every rewrite this entry makes. */
+  readonly code: string;
+  readonly severity: DiagnosticSeverity;
+  /** A sentence or two of rationale — the one part the driver cannot generate,
+   *  and the part that makes a deprecation actionable rather than mysterious.
+   *  Never a clause of the generated sentence. */
+  readonly reason: string;
+  readonly rules: readonly MigrationRule[];
+}
+
+/** One applied rewrite. Path provenance is part of the driver's contract:
+ *  diagnostics are remapped through `legacyPath` before position resolution,
+ *  and `telo migrate` reads its edit target from the same record — the location
+ *  in the author's file, not the post-rewrite path. */
+export interface MigrationRewrite {
+  readonly entryId: string;
+  readonly code: string;
+  readonly severity: DiagnosticSeverity;
+  readonly documentIndex: number;
+  /** Dotted path (`a.b[0].c`) as the AUTHOR wrote it — the key into a
+   *  position index built from the raw file. */
+  readonly legacyPath: string;
+  /** Dotted path after the rewrite. Equal to `legacyPath` unless a
+   *  `rename-key` moved it. */
+  readonly migratedPath: string;
+  /** Human-readable description of what changed, generated by the driver. */
+  readonly summary: string;
+}
+
+/** Why a matched patch was refused. A migration that cannot rewrite leaves the
+ *  node untouched for the ordinary validator to reject — never guessing, never
+ *  dropping. */
+export type MigrationRefusal =
+  | "path-not-found"
+  | "destination-occupied"
+  | "not-a-mapping-entry"
+  | "not-a-sequence"
+  | "not-a-scalar"
+  | "malformed-value"
+  /** The value is already what the patch would write. A rule should match only
+   *  the legacy spelling, so this means its matcher was too wide — refusing
+   *  keeps that from surfacing as a deprecation the author cannot act on. */
+  | "nothing-to-rewrite";