@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.2

package/studio/server/introspect/source-overlay/kernel-calls.ts

@@ -0,0 +1,49 @@
+/**
+ * Kernel-operation token scan for resolved handler source files.
+ */
+import { readFileSync } from 'node:fs'
+
+type KernelToken = { token: string; label?: string }
+
+/** Kernel-op idioms surfaced as `kernelCalls`; entries are longest-first. */
+const KERNEL_TOKENS: KernelToken[] = [
+  { token: 'graph.createEdge' },
+  { token: 'graph.removeEdge' },
+  { token: 'function.mutate' },
+  { token: 'graph.children' },
+  { token: 'function.get' },
+  { token: 'graph.create' },
+  { token: 'graph.update' },
+  { token: 'graph.remove' },
+  { token: 'graph.mutate' },
+  { token: 'auth.revoke' },
+  { token: 'graph.links' },
+  { token: 'auth.grant' },
+  { token: 'auth.check' },
+  { token: 'graph.tree' },
+  { token: 'graph.node' },
+  { token: 'revokePerm', label: 'revokePerm (legacy)' },
+  { token: 'checkPerm', label: 'checkPerm (legacy)' },
+  { token: 'graph.get' },
+  { token: 'grantPerm', label: 'grantPerm (legacy)' },
+]
+
+/** Scan handler file text for kernel-op tokens. */
+export function scanKernelCalls(file: string): string[] {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return []
+  }
+  const found: string[] = []
+  let work = text
+  for (const entry of KERNEL_TOKENS) {
+    if (work.includes(entry.token)) {
+      found.push(entry.label ?? entry.token)
+      // Blank out matches so `::getLinks` doesn't also count as `::getLink`.
+      work = work.split(entry.token).join(' '.repeat(entry.token.length))
+    }
+  }
+  return found
+}

package/studio/server/introspect/source-overlay/project.ts

@@ -0,0 +1,248 @@
+/**
+ * Tolerant ts-morph project construction and authored-source resolution.
+ *
+ * This module owns syntax/value lookup only. It does not interpret handlers or
+ * schema members.
+ */
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve as resolvePath } from 'node:path'
+import { Node, Project, SyntaxKind, type CallExpression, type SourceFile } from 'ts-morph'
+
+/** A fresh, in-memory-ish ts-morph project: no tsconfig, tolerant of errors. */
+export function newProject(): Project {
+  return new Project({
+    useInMemoryFileSystem: false,
+    skipFileDependencyResolution: true,
+    skipLoadingLibFiles: true,
+    compilerOptions: {
+      allowJs: true,
+      // `allowImportingTsExtensions` keeps `.ts`-suffixed imports from blowing up.
+      allowImportingTsExtensions: true,
+    },
+  })
+}
+
+/** Add a file to the project if it exists; returns undefined otherwise. */
+export function tryAddFile(project: Project, file: string): SourceFile | undefined {
+  try {
+    if (!existsSync(file)) return undefined
+    return project.getSourceFile(file) ?? project.addSourceFileAtPath(file)
+  } catch {
+    return undefined
+  }
+}
+
+/** Path relative to `root`, POSIX-style ('schema/monitor.ts'), never absolute. */
+export function relToRoot(root: string, file: string): string {
+  const abs = isAbsolute(file) ? file : resolvePath(root, file)
+  const canonical = (value: string) => {
+    try {
+      return realpathSync(value)
+    } catch {
+      return value
+    }
+  }
+  return relative(canonical(root), canonical(abs)).split('\\').join('/')
+}
+
+/** The call's callee identifier name, e.g. `method` / `classMethods` / `todo`. */
+export function calleeName(call: CallExpression): string | undefined {
+  const expr = call.getExpression()
+  if (Node.isIdentifier(expr)) return expr.getText()
+  if (Node.isPropertyAccessExpression(expr)) return expr.getName()
+  return undefined
+}
+
+/** Remove syntax-only wrappers around a runtime value. */
+export function unwrapExpression(node: Node): Node {
+  let current = node
+  while (
+    Node.isParenthesizedExpression(current) ||
+    Node.isAsExpression(current) ||
+    Node.isSatisfiesExpression(current) ||
+    Node.isTypeAssertion(current)
+  ) {
+    current = current.getExpression()
+  }
+  return current
+}
+
+/** Resolve a local or relatively imported identifier to its runtime value. */
+export function valueOfIdentifier(id: Node): Node | undefined {
+  if (!Node.isIdentifier(id)) return undefined
+  const decl = firstValueDeclaration(id)
+  if (decl && Node.isVariableDeclaration(decl)) return decl.getInitializer()
+  return resolveImportedValue(id)
+}
+
+/** Follow a named relative import to the exported value that defines it. */
+function resolveImportedValue(id: Node): Node | undefined {
+  if (!Node.isIdentifier(id)) return undefined
+  const localName = id.getText()
+  const sourceFile = id.getSourceFile()
+
+  for (const imp of sourceFile.getImportDeclarations()) {
+    for (const named of imp.getNamedImports()) {
+      const local = named.getAliasNode()?.getText() ?? named.getName()
+      if (local !== localName) continue
+      const target = resolveModuleFile(sourceFile, imp.getModuleSpecifierValue())
+      if (!target) return undefined
+      return findExportedValue(id.getProject(), target, named.getName(), new Set<string>())
+    }
+  }
+  return undefined
+}
+
+/** Find an exported variable/function value, following local and barrel exports. */
+function findExportedValue(
+  project: Project,
+  file: string,
+  exportName: string,
+  seen: Set<string>,
+): Node | undefined {
+  const key = `${file}:${exportName}`
+  if (seen.has(key)) return undefined
+  seen.add(key)
+  const sf = tryAddFile(project, file)
+  if (!sf) return undefined
+
+  const localValue = (name: string, exportedOnly: boolean): Node | undefined => {
+    const variable = sf
+      .getVariableDeclarations()
+      .find(
+        (candidate) => candidate.getName() === name && (!exportedOnly || candidate.isExported()),
+      )
+    if (variable) return variable.getInitializer()
+    return sf
+      .getFunctions()
+      .find(
+        (candidate) => candidate.getName() === name && (!exportedOnly || candidate.isExported()),
+      )
+  }
+
+  const direct = localValue(exportName, true)
+  if (direct) return direct
+
+  for (const ex of sf.getExportDeclarations()) {
+    const modSpec = ex.getModuleSpecifierValue()
+    const target = modSpec ? resolveModuleFile(sf, modSpec) : undefined
+    const named = ex.getNamedExports()
+    if (named.length > 0) {
+      for (const specifier of named) {
+        const exposed = specifier.getAliasNode()?.getText() ?? specifier.getName()
+        if (exposed !== exportName) continue
+        const original = specifier.getName()
+        if (target) return findExportedValue(project, target, original, seen)
+        return localValue(original, false)
+      }
+    } else if (target) {
+      const found = findExportedValue(project, target, exportName, seen)
+      if (found) return found
+    }
+  }
+  return undefined
+}
+
+/** Get the value node of an object-literal property (handles shorthand). */
+export function getProp(obj: Node, name: string): Node | undefined {
+  if (!Node.isObjectLiteralExpression(obj)) return undefined
+  const prop = obj.getProperty(name)
+  if (!prop) return undefined
+  if (Node.isPropertyAssignment(prop)) return prop.getInitializer()
+  if (Node.isShorthandPropertyAssignment(prop)) return prop.getNameNode()
+  if (Node.isMethodDeclaration(prop)) return prop
+  return prop
+}
+
+/** First value/declaration node a name resolves to (definition, not reference). */
+export function firstValueDeclaration(node: Node): Node | undefined {
+  const idNode = Node.isIdentifier(node)
+    ? node
+    : node.getFirstDescendantByKind(SyntaxKind.Identifier)
+  if (!idNode || !Node.isIdentifier(idNode)) return undefined
+  const symbol = idNode.getSymbol()
+  if (!symbol) return undefined
+  const decls = symbol.getDeclarations()
+  return decls[0]
+}
+
+/** Resolve a relative module specifier to a concrete .ts file path on disk. */
+export function resolveModuleFile(from: SourceFile, spec: string): string | undefined {
+  if (!spec.startsWith('.')) {
+    // Current SDK projects use package `imports` aliases such as
+    // `#actions/risk`. Resolve them from the authored file's directory through
+    // Bun so the overlay follows the same project-local map as runtime imports.
+    if (!spec.startsWith('#')) return undefined
+    try {
+      const resolved = Bun.resolveSync(spec, dirname(from.getFilePath()))
+      if (existsSync(resolved)) return resolved
+    } catch {
+      return undefined
+    }
+    return undefined
+  }
+  const baseDir = dirname(from.getFilePath())
+  const base = resolvePath(baseDir, spec)
+  const sourceBase = base.replace(/\.(?:[cm]?js|jsx)$/, '')
+  const candidates = [
+    base,
+    sourceBase.endsWith('.ts') ? sourceBase : `${sourceBase}.ts`,
+    sourceBase.endsWith('.tsx') ? sourceBase : `${sourceBase}.tsx`,
+    `${base}/index.ts`,
+    `${base}/index.tsx`,
+  ]
+  for (const c of candidates) if (existsSync(c)) return c
+  return undefined
+}
+
+/** Resolve a value to an object literal, following local/imported identifiers. */
+export function resolveObjectLiteral(
+  node: Node,
+  seen = new Set<string>(),
+): import('ts-morph').ObjectLiteralExpression | undefined {
+  const value = unwrapExpression(node)
+  const key = `${value.getSourceFile().getFilePath()}:${value.getStart()}`
+  if (seen.has(key)) return undefined
+  seen.add(key)
+  if (Node.isObjectLiteralExpression(value)) return value
+  if (Node.isIdentifier(value)) {
+    const resolved = valueOfIdentifier(value)
+    if (resolved) return resolveObjectLiteral(resolved, seen)
+  }
+  return undefined
+}
+
+/** Value carried by an object-literal property, including shorthand/method syntax. */
+export function objectPropertyValue(prop: Node): Node | undefined {
+  if (Node.isPropertyAssignment(prop)) return prop.getInitializer()
+  if (Node.isShorthandPropertyAssignment(prop)) return prop.getNameNode()
+  if (Node.isMethodDeclaration(prop)) return prop
+  return undefined
+}
+
+/** A string-literal property value, e.g. `as: 'page'` → 'page'. */
+export function stringLiteralOfProp(obj: Node, name: string): string | undefined {
+  if (!Node.isObjectLiteralExpression(obj)) return undefined
+  const prop = obj.getProperty(name)
+  if (!prop || !Node.isPropertyAssignment(prop)) return undefined
+  const v = prop.getInitializer()
+  if (v && (Node.isStringLiteral(v) || Node.isNoSubstitutionTemplateLiteral(v)))
+    return v.getLiteralText()
+  return undefined
+}
+
+/** The key name of an object-literal property (assignment / shorthand / method). */
+export function propertyKey(prop: Node): string | undefined {
+  if (
+    Node.isPropertyAssignment(prop) ||
+    Node.isShorthandPropertyAssignment(prop) ||
+    Node.isMethodDeclaration(prop)
+  ) {
+    const nameNode = prop.getNameNode()
+    if (Node.isStringLiteral(nameNode)) return nameNode.getLiteralText()
+    if (Node.isComputedPropertyName(nameNode)) return undefined // skip `[expr]: …`
+    return nameNode.getText()
+  }
+  // Spread (`...knobs`) — no single key.
+  return undefined
+}

package/studio/server/introspect/source-overlay/spans.ts

@@ -0,0 +1,360 @@
+/**
+ * Source coordinates and leading documentation for authored schema members.
+ */
+import { existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { Node, SyntaxKind, type CallExpression, type SourceFile } from 'ts-morph'
+
+import type { SchemaIR, SourceSpan } from '../../../shared/types'
+
+import {
+  calleeName,
+  newProject,
+  objectPropertyValue,
+  propertyKey,
+  relToRoot,
+  resolveObjectLiteral,
+  stringLiteralOfProp,
+  unwrapExpression,
+  valueOfIdentifier,
+} from './project'
+
+/**
+ * Harvest the leading JSDoc / line-comment block immediately above `node`,
+ * stripped of comment markers, collapsed to a single trimmed string.
+ */
+function leadingDoc(node: Node): string | undefined {
+  // Prefer real JSDoc nodes when present (ts-morph exposes them on many decls).
+  const anyNode = node as unknown as { getJsDocs?: () => Array<{ getText: () => string }> }
+  if (typeof anyNode.getJsDocs === 'function') {
+    const docs = anyNode.getJsDocs()
+    if (docs.length > 0) {
+      const text = docs.map((d) => d.getText()).join('\n')
+      const cleaned = cleanComment(text)
+      if (cleaned) return cleaned
+    }
+  }
+  // Fall back to raw leading comment ranges (covers `//` line comments too).
+  const ranges = node.getLeadingCommentRanges()
+  if (ranges.length === 0) return undefined
+  const raw = ranges.map((r) => r.getText()).join('\n')
+  const cleaned = cleanComment(raw)
+  return cleaned || undefined
+}
+
+/** Strip `/** *​/`, `//`, leading `*` gutters; collapse to a tidy single line. */
+function cleanComment(raw: string): string {
+  const lines = raw
+    .replace(/\/\*\*?/g, '')
+    .replace(/\*\//g, '')
+    .split('\n')
+    .map((l) =>
+      l
+        .replace(/^\s*\*\s?/, '')
+        .replace(/^\s*\/\/\s?/, '')
+        .trim(),
+    )
+    .filter((l) => l.length > 0)
+  return lines.join(' ').replace(/\s+/g, ' ').trim()
+}
+
+const DECL_HELPERS: Record<string, 'node' | 'interface' | 'edge' | 'function'> = {
+  nodeClass: 'node',
+  nodeInterface: 'interface',
+  edgeClass: 'edge',
+  fn: 'function',
+}
+
+/** Recognize both legacy `edgeClass(...)` and current
+ * `edgeClass.directed/undirected({...})` authoring forms. */
+function declarationHelper(
+  call: CallExpression,
+): 'node' | 'interface' | 'edge' | 'function' | undefined {
+  const direct = calleeName(call)
+  if (direct && direct in DECL_HELPERS) return DECL_HELPERS[direct]
+  const expression = call.getExpression()
+  if (
+    Node.isPropertyAccessExpression(expression) &&
+    (expression.getName() === 'directed' || expression.getName() === 'undirected') &&
+    expression.getExpression().getText() === 'edgeClass'
+  ) {
+    return 'edge'
+  }
+  return undefined
+}
+
+/**
+ * A schema member's true NAME + section, resolved from the `defineSchema` map.
+ * The declaration helpers (nodeClass/nodeInterface/edgeClass) carry no name — a
+ * member is named by the KEY it is registered under, not by its variable — and a
+ * domain may register a class and an interface under the SAME name (the
+ * intentional same-name pattern: the `iUser` interface alongside the `User`
+ * class). So the map is the sole authority for both the anchor name and the
+ * interface-vs-class distinction; the variable identifier alone tells us neither.
+ */
+interface MemberName {
+  schemaName: string
+  section: 'interface' | 'class' | 'function' // the `classes` map also holds edge classes
+}
+
+interface MemberNameMap {
+  /** Exact declaration initializer, robust to imported/local aliases. */
+  byValue: Map<string, MemberName>
+  /** Legacy fallback when a symbol cannot be resolved. */
+  byIdentifier: Map<string, MemberName>
+}
+
+/** Stable source coordinate for the value behind a local/imported alias. */
+function memberValueKey(node: Node, seen = new Set<string>()): string | undefined {
+  const value = unwrapExpression(node)
+  const key = `${value.getSourceFile().getFilePath()}:${value.getStart()}`
+  if (seen.has(key)) return undefined
+  seen.add(key)
+  if (Node.isIdentifier(value)) {
+    const resolved = valueOfIdentifier(value)
+    if (resolved) return memberValueKey(resolved, seen)
+  }
+  return key
+}
+
+/** Map each registered member VARIABLE (as referenced in `defineSchema`) to its
+ *  schema name + section, from the domain's own schema files — never node_modules
+ *  (a dependency's `defineSchema` is not this domain's). */
+function buildMemberNameMap(files: SourceFile[]): MemberNameMap {
+  const map: MemberNameMap = {
+    byValue: new Map<string, MemberName>(),
+    byIdentifier: new Map<string, MemberName>(),
+  }
+  for (const sf of files) {
+    if (sf.getFilePath().includes('/node_modules/')) continue
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      if (calleeName(call) !== 'defineSchema') continue
+      const input = call.getArguments()[1]
+      const cfg = input ? resolveObjectLiteral(input) : undefined
+      if (!cfg) continue
+      collectSchemaSection(map, cfg, 'interfaces', 'interface')
+      collectSchemaSection(map, cfg, 'classes', 'class')
+      collectSchemaSection(map, cfg, 'functions', 'function')
+    }
+  }
+  return map
+}
+
+/** Record `variable → { schemaName, section }` for one `defineSchema` section,
+ *  handling both `Key: alias` and shorthand `Key`. */
+function collectSchemaSection(
+  map: MemberNameMap,
+  cfg: Node,
+  prop: 'interfaces' | 'classes' | 'functions',
+  section: 'interface' | 'class' | 'function',
+): void {
+  const obj = getObjectProp(cfg, prop)
+  if (!obj) return
+  for (const p of obj.getProperties()) {
+    const schemaName = propertyKey(p)
+    const memberValue = objectPropertyValue(p)
+    if (!schemaName || !memberValue) continue
+    const member = { schemaName, section } satisfies MemberName
+    const valueKey = memberValueKey(memberValue)
+    if (valueKey) map.byValue.set(valueKey, member)
+    const unwrapped = unwrapExpression(memberValue)
+    if (Node.isIdentifier(unwrapped)) map.byIdentifier.set(unwrapped.getText(), member)
+  }
+}
+
+/**
+ * The anchor namespace ('class' | 'interface' | 'edge') for a declared member.
+ * The `defineSchema` SECTION is authoritative for interface-vs-class — a
+ * `nodeClass` whose name collides with a same-named interface must still anchor
+ * as a class. Within the class section, an `edgeClass` (or an IR edge type)
+ * anchors as 'edge'. Falls back to the declaration helper when the member isn't
+ * in a parseable `defineSchema` map (e.g. an imported kernel member).
+ */
+function resolveMemberKind(
+  ir: SchemaIR | null,
+  name: string,
+  section: 'interface' | 'class' | 'function' | undefined,
+  helperKind: 'node' | 'interface' | 'edge' | 'function',
+): 'class' | 'interface' | 'edge' | 'function' {
+  if (section === 'function' || helperKind === 'function') return 'function'
+  if (section === 'interface') return 'interface'
+  const isEdge = helperKind === 'edge' || ir?.classes?.[name]?.type === 'edge'
+  if (section === 'class') return isEdge ? 'edge' : 'class'
+  if (helperKind === 'interface') return 'interface'
+  return isEdge ? 'edge' : 'class'
+}
+
+export function buildSourceSpans(args: {
+  ir: SchemaIR | null
+  schemaDir: string
+}): Record<string, SourceSpan> {
+  const { ir, schemaDir } = args
+  if (!schemaDir || !existsSync(schemaDir)) return {}
+
+  // The domain root is the parent of the schema dir (spans are relative to it).
+  const domainRoot = dirname(schemaDir.replace(/\/$/, ''))
+
+  const project = newProject()
+  let files: string[] = []
+  try {
+    const added = project.addSourceFilesAtPaths(`${schemaDir.replace(/\/$/, '')}/**/*.ts`)
+    files = added.map((f) => f.getFilePath())
+  } catch {
+    return {}
+  }
+
+  const spans: Record<string, SourceSpan> = {}
+
+  const sourceFiles = files.map((f) => project.getSourceFile(f)).filter((f): f is SourceFile => !!f)
+  // The domain's `defineSchema` map is authoritative for each member's name +
+  // interface-vs-class kind, so an aliased interface (`iUser`→`User`) and a class
+  // sharing its name (`User`) each anchor correctly instead of colliding.
+  const memberNames = buildMemberNameMap(sourceFiles)
+
+  for (const sf of sourceFiles) {
+    const fileRel = relToRoot(domainRoot, sf.getFilePath())
+
+    for (const v of sf.getVariableDeclarations()) {
+      if (!v.isExported()) continue
+      const init = v.getInitializer()
+      if (!init || !Node.isCallExpression(init)) continue
+      const helperKind = declarationHelper(init)
+      if (!helperKind) continue
+      const valueKey = memberValueKey(init)
+      const member =
+        (valueKey ? memberNames.byValue.get(valueKey) : undefined) ??
+        memberNames.byIdentifier.get(v.getName())
+      const name = member?.schemaName ?? v.getName()
+      const ns = resolveMemberKind(ir, name, member?.section, helperKind)
+
+      const stmt = v.getVariableStatement() ?? v
+      spans[`${ns}.${name}`] = makeSpan(domainRoot, fileRel, stmt, v)
+
+      // The single object-literal argument: nodeClass({ properties, methods })
+      // and current edgeClass.directed({ source, target, properties }).
+      const cfgArg = init.getArguments()[0]
+      if (ns !== 'function' && cfgArg && Node.isObjectLiteralExpression(cfgArg)) {
+        collectPropsAndMethods(spans, ns, name, cfgArg, domainRoot, fileRel)
+      }
+
+      // Edges: endpoints are the first two args; props live in the third.
+      if (ns === 'edge') {
+        collectEdge(spans, name, init, domainRoot, fileRel)
+      }
+    }
+  }
+
+  return spans
+}
+
+/** Build a SourceSpan, harvesting leading doc from the declaration `docNode`. */
+function makeSpan(domainRoot: string, fileRel: string, spanNode: Node, docNode: Node): SourceSpan {
+  const span: SourceSpan = {
+    file: fileRel,
+    startLine: spanNode.getStartLineNumber(),
+    endLine: spanNode.getEndLineNumber(),
+  }
+  const doc = leadingDoc(docNode) ?? leadingDoc(spanNode)
+  if (doc) span.doc = doc
+  return span
+}
+
+/** Record `<ns>.<Name>.property.<p>` and `.method.<m>` from a config object. */
+function collectPropsAndMethods(
+  spans: Record<string, SourceSpan>,
+  ns: string,
+  name: string,
+  cfg: Node,
+  domainRoot: string,
+  fileRel: string,
+): void {
+  if (!Node.isObjectLiteralExpression(cfg)) return
+  const propsObj = getObjectProp(cfg, 'properties') ?? getObjectProp(cfg, 'props')
+  if (propsObj) {
+    for (const p of propsObj.getProperties()) {
+      const pName = propertyKey(p)
+      if (!pName) continue
+      spans[`${ns}.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
+    }
+  }
+  const methodsObj = getObjectProp(cfg, 'methods')
+  if (methodsObj) {
+    for (const m of methodsObj.getProperties()) {
+      const mName = propertyKey(m)
+      if (!mName) continue
+      spans[`${ns}.${name}.method.${mName}`] = makeSpan(domainRoot, fileRel, m, m)
+    }
+  }
+}
+
+/** Record edge endpoint spans `edge.<Name>.endpoint.<role>` from the two args. */
+function collectEdge(
+  spans: Record<string, SourceSpan>,
+  name: string,
+  init: CallExpression,
+  domainRoot: string,
+  fileRel: string,
+): void {
+  const argsList = init.getArguments()
+  const expression = init.getExpression()
+  const currentObjectForm =
+    Node.isPropertyAccessExpression(expression) &&
+    (expression.getName() === 'directed' || expression.getName() === 'undirected') &&
+    argsList[0] &&
+    Node.isObjectLiteralExpression(argsList[0])
+
+  if (currentObjectForm) {
+    const config = argsList[0]
+    if (Node.isObjectLiteralExpression(config)) {
+      for (const endpointName of ['source', 'target'] as const) {
+        const ep = getObjectProp(config, endpointName)
+        if (!ep) continue
+        const role = stringLiteralOfProp(ep, 'as') ?? stringLiteralOfProp(ep, 'role')
+        if (role) spans[`edge.${name}.endpoint.${role}`] = makeSpan(domainRoot, fileRel, ep, ep)
+      }
+      const properties = getObjectProp(config, 'properties') ?? getObjectProp(config, 'props')
+      if (properties) {
+        for (const p of properties.getProperties()) {
+          const pName = propertyKey(p)
+          if (!pName) continue
+          spans[`edge.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
+        }
+      }
+    }
+    return
+  }
+
+  for (let i = 0; i < Math.min(2, argsList.length); i++) {
+    const ep = argsList[i]
+    if (!Node.isObjectLiteralExpression(ep)) continue
+    const role = stringLiteralOfProp(ep, 'as')
+    if (!role) continue
+    spans[`edge.${name}.endpoint.${role}`] = makeSpan(domainRoot, fileRel, ep, ep)
+  }
+  // Legacy edge props live in the third (config) arg.
+  const cfgArg = argsList[2]
+  if (cfgArg && Node.isObjectLiteralExpression(cfgArg)) {
+    const propsObj = getObjectProp(cfgArg, 'properties') ?? getObjectProp(cfgArg, 'props')
+    if (propsObj) {
+      for (const p of propsObj.getProperties()) {
+        const pName = propertyKey(p)
+        if (!pName) continue
+        spans[`edge.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
+      }
+    }
+  }
+}
+
+/** The object-literal value of a named property, if it is itself an object. */
+function getObjectProp(
+  obj: Node,
+  name: string,
+): import('ts-morph').ObjectLiteralExpression | undefined {
+  if (!Node.isObjectLiteralExpression(obj)) return undefined
+  const prop = obj.getProperty(name)
+  if (!prop) return undefined
+  let value: Node | undefined
+  if (Node.isPropertyAssignment(prop)) value = prop.getInitializer()
+  else if (Node.isShorthandPropertyAssignment(prop)) value = prop.getNameNode()
+  return value ? resolveObjectLiteral(value) : undefined
+}