@astrale-os/sdk 0.4.11 → 0.4.13

package/src/linter/rules/oxlint-ast.js

@@ -0,0 +1,110 @@
+// @ts-check
+
+import { relative, sep } from 'node:path'
+
+/** @typedef {import('./oxlint-rule.js').AstNode} AstNode */
+/** @typedef {import('./oxlint-rule.js').OxlintRuleContext} OxlintRuleContext */
+/** @typedef {{ object: AstNode, property: string }} StaticMember */
+
+/** @param {AstNode | undefined} node @returns {StaticMember | undefined} */
+export function staticMember(node) {
+  if (!node || node.type !== 'MemberExpression' || node.computed) return undefined
+  if (!node.object || node.property?.type !== 'Identifier' || !node.property.name) return undefined
+  return { object: node.object, property: node.property.name }
+}
+
+/** @param {AstNode | undefined} node */
+export function isFunctionNode(node) {
+  return (
+    node?.type === 'ArrowFunctionExpression' ||
+    node?.type === 'FunctionDeclaration' ||
+    node?.type === 'FunctionExpression'
+  )
+}
+
+/** @param {AstNode | undefined} node @returns {AstNode | undefined} */
+export function nearestFunction(node) {
+  let current = node
+  while (current) {
+    if (isFunctionNode(current)) return current
+    current = current.parent
+  }
+  return undefined
+}
+
+/** @param {AstNode} callback @returns {AstNode | undefined} */
+export function callbackCall(callback) {
+  let current = callback
+  while (current.parent && isTransparentWrapper(current.parent)) current = current.parent
+  const parent = current.parent
+  if (parent?.type !== 'CallExpression' || !parent.arguments?.includes(current)) return undefined
+  return parent
+}
+
+/** @param {AstNode} node */
+function isTransparentWrapper(node) {
+  return (
+    node.type === 'ChainExpression' ||
+    node.type === 'ParenthesizedExpression' ||
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSNonNullExpression' ||
+    node.type === 'TSSatisfiesExpression'
+  )
+}
+
+/** @param {AstNode | undefined} call */
+export function isStepRun(call) {
+  if (call?.type !== 'CallExpression') return false
+  const member = staticMember(call.callee)
+  if (!member || member.property !== 'run') return false
+  if (member.object.type === 'Identifier') return member.object.name === 'step'
+  return staticMember(member.object)?.property === 'step'
+}
+
+/** @param {AstNode | undefined} call */
+export function isMutateCall(call) {
+  if (call?.type !== 'CallExpression') return false
+  const member = staticMember(call.callee)
+  if (!member || member.property !== 'mutate') return false
+  if (member.object.type === 'Identifier') return member.object.name === 'kernel'
+  return staticMember(member.object)?.property === 'kernel'
+}
+
+/** @param {OxlintRuleContext} context */
+export function relativeFilename(context) {
+  const path = relative(context.cwd, context.filename)
+  return sep === '/' ? path : path.split(sep).join('/')
+}
+
+/** @param {OxlintRuleContext} context */
+export function isProductionFile(context) {
+  const path = relativeFilename(context)
+  return (
+    !path.split('/').includes('__tests__') &&
+    !/\.(?:test|spec|bench|perf)\.[cm]?[jt]sx?$/.test(path) &&
+    !path.includes('.gen.')
+  )
+}
+
+/** @param {OxlintRuleContext} context */
+export function isProductionCoreFile(context) {
+  const path = relativeFilename(context)
+  return (path === 'core' || path.startsWith('core/')) && isProductionFile(context)
+}
+
+/** @param {OxlintRuleContext} context @param {AstNode} node @param {string} id @param {string} messageId */
+export function reportUnlessSuppressed(context, node, id, messageId) {
+  if (isSuppressed(context, node, id)) return
+  context.report({ node, messageId })
+}
+
+/** @param {OxlintRuleContext} context @param {AstNode} node @param {string} id */
+function isSuppressed(context, node, id) {
+  const line = context.sourceCode.getLoc(node).start.line
+  if (line <= 1) return false
+  const previous = context.sourceCode.text.split(/\r?\n/)[line - 2]
+  const match = previous
+    ? /^\s*\/\/\s*astrale-disable-next-line\s+(.+?)\s+--\s+\S.*$/.exec(previous)
+    : null
+  return match ? match[1].split(/[\s,]+/).includes(id) : false
+}

package/src/linter/rules/oxlint-rule.ts

@@ -0,0 +1,35 @@
+export type AstNode = {
+  type: string
+  parent?: AstNode
+  range?: [number, number]
+  async?: boolean
+  await?: boolean
+  name?: string
+  computed?: boolean
+  object?: AstNode
+  property?: AstNode
+  callee?: AstNode
+  arguments?: AstNode[]
+}
+
+export type OxlintRuleContext = {
+  id: string
+  filename: string
+  cwd: string
+  sourceCode: {
+    text: string
+    getText(node?: AstNode | null): string
+    getLoc(node: AstNode): { start: { line: number; column: number } }
+  }
+  report(diagnostic: { node: AstNode; messageId: string }): void
+}
+
+export type OxlintRule = {
+  meta: {
+    type: 'problem'
+    docs: { description: string; url: string }
+    messages: Record<string, string>
+    schema: readonly []
+  }
+  create(context: OxlintRuleContext): Record<string, ((node: AstNode) => void) | undefined>
+}

package/src/linter/rules/project-rule.ts

@@ -0,0 +1,37 @@
+import type { LintDiagnostic } from '../diagnostic.js'
+import type { DomainProject } from '../project.js'
+import type { SourceFile, SourceToken } from '../source.js'
+
+import { isSuppressed } from '../suppression.js'
+import { ruleCatalog, ruleId, type ImplementedRuleSlug } from './catalog.js'
+
+export type AnalyzerRule = {
+  slug: ImplementedRuleSlug
+  analyze(project: DomainProject): readonly LintDiagnostic[]
+}
+
+export function analyzerDiagnostic(
+  slug: ImplementedRuleSlug,
+  file: SourceFile,
+  token: SourceToken,
+  detail?: string,
+): LintDiagnostic | undefined {
+  const info = ruleCatalog[slug]
+  const id = ruleId(slug)
+  if (isSuppressed(file, token.line, id)) return undefined
+  return {
+    id,
+    severity: 'error',
+    message: detail ? `${info.message} ${detail}` : info.message,
+    help: info.help,
+    url: info.url,
+    owner: info.owner,
+    location: {
+      path: file.relativePath,
+      line: token.line,
+      column: token.column,
+      offset: token.offset,
+      length: token.length,
+    },
+  }
+}

package/src/linter/rules/thin-schema-composition-root.ts

@@ -0,0 +1,26 @@
+import type { LintDiagnostic } from '../diagnostic.js'
+import type { DomainProject } from '../project.js'
+
+import { importedCalls } from '../source.js'
+import { analyzerDiagnostic, type AnalyzerRule } from './project-rule.js'
+
+const schemaModules = new Set(['@astrale-os/kernel-core', '@astrale-os/kernel-dsl'])
+const memberConstructors = new Set([
+  'edgeClass',
+  'edgeInterface',
+  'fn',
+  'func',
+  'nodeClass',
+  'nodeInterface',
+])
+
+export const thinSchemaCompositionRoot: AnalyzerRule = {
+  slug: 'thin-schema-composition-root',
+  analyze(project: DomainProject): readonly LintDiagnostic[] {
+    const root = project.files.find((file) => file.relativePath === 'schema/index.ts')
+    if (!root) return []
+    return importedCalls(root, schemaModules, memberConstructors)
+      .map((token) => analyzerDiagnostic(this.slug, root, token, `Found ${token.value}().`))
+      .filter((diagnostic): diagnostic is LintDiagnostic => diagnostic !== undefined)
+  },
+}

package/src/linter/source.ts

@@ -0,0 +1,323 @@
+export type SourceToken = {
+  kind: 'identifier' | 'string' | 'punctuation'
+  value: string
+  offset: number
+  length: number
+  line: number
+  column: number
+}
+
+export type SourceImport = {
+  specifier: string
+  token: SourceToken
+  bindings: ReadonlyMap<string, string>
+  namespace?: string
+}
+
+export type SourceFile = {
+  path: string
+  relativePath: string
+  text: string
+  tokens: readonly SourceToken[]
+  imports: readonly SourceImport[]
+}
+
+const identifierStart = /[A-Za-z_$]/
+const identifierPart = /[A-Za-z0-9_$]/
+
+export function scanSource(path: string, relativePath: string, text: string): SourceFile {
+  const tokens = tokenize(text)
+  return { path, relativePath, text, tokens, imports: parseImports(tokens) }
+}
+
+function tokenize(text: string): SourceToken[] {
+  const tokens: SourceToken[] = []
+  let offset = 0
+  let line = 1
+  let column = 1
+
+  const advance = (): string => {
+    const char = text[offset++]!
+    if (char === '\n') {
+      line++
+      column = 1
+    } else {
+      column++
+    }
+    return char
+  }
+
+  while (offset < text.length) {
+    const char = text[offset]!
+    if (/\s/.test(char)) {
+      advance()
+      continue
+    }
+
+    if (char === '/' && text[offset + 1] === '/') {
+      advance()
+      advance()
+      while (offset < text.length && text[offset] !== '\n') advance()
+      continue
+    }
+
+    if (char === '/' && text[offset + 1] === '*') {
+      advance()
+      advance()
+      while (offset < text.length) {
+        if (text[offset] === '*' && text[offset + 1] === '/') {
+          advance()
+          advance()
+          break
+        }
+        advance()
+      }
+      continue
+    }
+
+    if (char === "'" || char === '"') {
+      const quote = char
+      const start = offset
+      const startLine = line
+      const startColumn = column
+      advance()
+      let value = ''
+      while (offset < text.length) {
+        const current = advance()
+        if (current === '\\') {
+          if (offset < text.length) value += decodeEscape(advance())
+          continue
+        }
+        if (current === quote) break
+        value += current
+      }
+      tokens.push({
+        kind: 'string',
+        value,
+        offset: start,
+        length: offset - start,
+        line: startLine,
+        column: startColumn,
+      })
+      continue
+    }
+
+    if (char === '`') {
+      advance()
+      while (offset < text.length) {
+        const current = advance()
+        if (current === '\\') {
+          if (offset < text.length) advance()
+          continue
+        }
+        if (current === '`') break
+      }
+      continue
+    }
+
+    if (identifierStart.test(char)) {
+      const start = offset
+      const startLine = line
+      const startColumn = column
+      let value = advance()
+      while (offset < text.length && identifierPart.test(text[offset]!)) value += advance()
+      tokens.push({
+        kind: 'identifier',
+        value,
+        offset: start,
+        length: offset - start,
+        line: startLine,
+        column: startColumn,
+      })
+      continue
+    }
+
+    tokens.push({
+      kind: 'punctuation',
+      value: char,
+      offset,
+      length: 1,
+      line,
+      column,
+    })
+    advance()
+  }
+
+  return tokens
+}
+
+function decodeEscape(char: string): string {
+  switch (char) {
+    case 'n':
+      return '\n'
+    case 'r':
+      return '\r'
+    case 't':
+      return '\t'
+    default:
+      return char
+  }
+}
+
+function parseImports(tokens: readonly SourceToken[]): SourceImport[] {
+  const imports: SourceImport[] = []
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index]!
+    if (token.kind !== 'identifier' || (token.value !== 'import' && token.value !== 'export')) {
+      continue
+    }
+
+    if (token.value === 'import' && tokens[index + 1]?.value === '(') {
+      const specifier = tokens[index + 2]
+      if (specifier?.kind === 'string') {
+        imports.push({ specifier: specifier.value, token, bindings: new Map() })
+      }
+      continue
+    }
+
+    const end = statementEnd(tokens, index + 1)
+    let specifierIndex = -1
+    for (let cursor = index + 1; cursor < end; cursor++) {
+      const candidate = tokens[cursor]!
+      if (candidate.kind === 'string') specifierIndex = cursor
+    }
+    if (specifierIndex < 0) continue
+
+    const specifier = tokens[specifierIndex]!
+    const bindings = new Map<string, string>()
+    let namespace: string | undefined
+    if (token.value === 'import') {
+      const fromIndex = findToken(tokens, index + 1, specifierIndex, 'from')
+      const bindingsEnd = fromIndex >= 0 ? fromIndex : specifierIndex
+      const open = findToken(tokens, index + 1, bindingsEnd, '{')
+      if (open >= 0) {
+        const close = findMatching(tokens, open, '{', '}', bindingsEnd)
+        if (close >= 0) parseNamedBindings(tokens, open + 1, close, bindings)
+      }
+      const star = findToken(tokens, index + 1, bindingsEnd, '*')
+      if (star >= 0 && tokens[star + 1]?.value === 'as') namespace = tokens[star + 2]?.value
+    }
+
+    imports.push({
+      specifier: specifier.value,
+      token,
+      bindings,
+      ...(namespace ? { namespace } : {}),
+    })
+    index = Math.max(index, specifierIndex)
+  }
+  return imports
+}
+
+function statementEnd(tokens: readonly SourceToken[], start: number): number {
+  let depth = 0
+  let sawSpecifier = false
+  for (let index = start; index < tokens.length; index++) {
+    const token = tokens[index]!
+    if (token.value === ';' && depth === 0) return index
+    if (token.value === '{' || token.value === '(' || token.value === '[') depth++
+    if (token.value === '}' || token.value === ')' || token.value === ']') depth--
+    if (token.kind === 'string' && depth === 0) sawSpecifier = true
+    const next = tokens[index + 1]
+    if (sawSpecifier && depth === 0 && next && next.line > token.line) return index + 1
+  }
+  return tokens.length
+}
+
+function findToken(
+  tokens: readonly SourceToken[],
+  start: number,
+  end: number,
+  value: string,
+): number {
+  for (let index = start; index < end; index++) {
+    if (tokens[index]?.value === value) return index
+  }
+  return -1
+}
+
+function findMatching(
+  tokens: readonly SourceToken[],
+  start: number,
+  open: string,
+  close: string,
+  end: number,
+): number {
+  let depth = 0
+  for (let index = start; index < end; index++) {
+    if (tokens[index]?.value === open) depth++
+    if (tokens[index]?.value === close && --depth === 0) return index
+  }
+  return -1
+}
+
+function parseNamedBindings(
+  tokens: readonly SourceToken[],
+  start: number,
+  end: number,
+  bindings: Map<string, string>,
+): void {
+  let index = start
+  while (index < end) {
+    if (tokens[index]?.value === ',' || tokens[index]?.value === 'type') {
+      index++
+      continue
+    }
+    const imported = tokens[index]
+    if (!imported || imported.kind !== 'identifier') {
+      index++
+      continue
+    }
+    if (tokens[index + 1]?.value === 'as' && tokens[index + 2]?.kind === 'identifier') {
+      bindings.set(imported.value, tokens[index + 2]!.value)
+      index += 3
+      continue
+    }
+    bindings.set(imported.value, imported.value)
+    index++
+  }
+}
+
+export function importedCalls(
+  file: SourceFile,
+  modules: ReadonlySet<string>,
+  names: ReadonlySet<string>,
+): SourceToken[] {
+  const locals = new Set<string>()
+  const namespaces = new Set<string>()
+  for (const sourceImport of file.imports) {
+    if (!modules.has(sourceImport.specifier)) continue
+    for (const name of names) {
+      const local = sourceImport.bindings.get(name)
+      if (local) locals.add(local)
+    }
+    if (sourceImport.namespace) namespaces.add(sourceImport.namespace)
+  }
+
+  const calls: SourceToken[] = []
+  for (let index = 0; index < file.tokens.length; index++) {
+    const token = file.tokens[index]!
+    if (token.kind !== 'identifier') continue
+    if (locals.has(token.value) && callFollows(file.tokens, index)) {
+      calls.push(token)
+      continue
+    }
+    if (
+      namespaces.has(token.value) &&
+      file.tokens[index + 1]?.value === '.' &&
+      names.has(file.tokens[index + 2]?.value ?? '') &&
+      callFollows(file.tokens, index + 2)
+    ) {
+      calls.push(file.tokens[index + 2]!)
+    }
+  }
+  return calls
+}
+
+function callFollows(tokens: readonly SourceToken[], index: number): boolean {
+  const next = tokens[index + 1]
+  if (next?.value === '(') return true
+  if (next?.value !== '<') return false
+  const close = findMatching(tokens, index + 1, '<', '>', tokens.length)
+  return close >= 0 && tokens[close + 1]?.value === '('
+}

package/src/linter/suppression.ts

@@ -0,0 +1,11 @@
+import type { SourceFile } from './source.js'
+
+const suppression = /^\s*\/\/\s*astrale-disable-next-line\s+(.+?)\s+--\s+\S.*$/
+
+export function isSuppressed(file: SourceFile, line: number, id: string): boolean {
+  if (line <= 1) return false
+  const previous = file.text.split(/\r?\n/)[line - 2]
+  const match = previous ? suppression.exec(previous) : null
+  if (!match) return false
+  return match[1]!.split(/[\s,]+/).includes(id)
+}

package/src/method/class.ts

@@ -25,9 +25,9 @@ import type {
 } from '@astrale-os/kernel-core/domain'
 import type { ImplementableOwnKeys, Schema } from '@astrale-os/kernel-dsl'
 
-import type { TypedSelf } from '../dispatch/self'
-import type { DomainKernel } from './context'
-import type { MethodImpl, RemoteHandler } from './single'
+import type { TypedSelf } from '../dispatch/self.js'
+import type { DomainKernel } from './context.js'
+import type { MethodImpl, RemoteHandler } from './single.js'
 
 /** Per-class method implementations for a remote domain. */
 export type ClassMethodsImpl<

package/src/method/context.ts

@@ -13,11 +13,11 @@ import type { FnMap, SchemaBoundView } from '@astrale-os/kernel-client'
 import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
 import type { AuthContext } from '@astrale-os/kernel-core'
 import type { Schema } from '@astrale-os/kernel-dsl'
+import type { Defer, Sleep } from '@astrale-os/kernel-server'
 
-import type { FunctionContextApi } from '../auth/function-context'
-import type { DomainAuthority } from '../auth/issuer-mint'
-import type { Defer } from '../defer'
-import type { Step } from '../step'
+import type { FunctionContextApi } from '../auth/function-context.js'
+import type { DomainAuthority } from '../auth/issuer-mint.js'
+import type { Step } from '../step/index.js'
 
 export type { GraphApi } from '@astrale-os/kernel-client/graph'
 
@@ -130,4 +130,6 @@ export interface RemoteContext<
   step: Step
   /** Run independent work without making its completion part of this result. */
   defer: Defer
+  /** Pause execution for a relative duration. Durable hosts may persist the wait. */
+  sleep: Sleep
 }

package/src/method/index.ts

@@ -6,14 +6,14 @@ export type {
   KernelForAuth,
   RemoteAuthorizeContext,
   RemoteContext,
-} from './context'
+} from './context.js'
 export type {
   RemoteHandler,
   AnyRemoteHandler,
   MethodImpl,
   MethodParams,
   MethodResult,
-} from './single'
-export { remoteMethod } from './single'
-export type { ClassMethodsImpl, InterfaceMethodsImpl, SchemaMethodsImpl } from './class'
-export { remoteClassMethods, remoteInterfaceMethods } from './class'
+} from './single.js'
+export { remoteMethod } from './single.js'
+export type { ClassMethodsImpl, InterfaceMethodsImpl, SchemaMethodsImpl } from './class.js'
+export { remoteClassMethods, remoteInterfaceMethods } from './class.js'

package/src/method/single.ts

@@ -9,14 +9,14 @@ import type {
 } from '@astrale-os/kernel-core/domain'
 import type { Schema } from '@astrale-os/kernel-dsl'
 
-import type { TypedSelf } from '../dispatch/self'
+import type { TypedSelf } from '../dispatch/self.js'
 import type {
   DomainKernel,
   Kernel,
   KernelForAuth,
   RemoteAuthorizeContext,
   RemoteContext,
-} from './context'
+} from './context.js'
 
 /**
  * Remote method handler. `execute` is optional only for binding stubs; any

package/src/server/auxiliary-routes.ts

@@ -36,21 +36,25 @@ import {
   type FunctionBinding,
   type AuthPolicy,
 } from '@astrale-os/kernel-api/routed'
-import { buildCorsHeaders, type CorsConfig } from '@astrale-os/kernel-server'
-
-import type { RemoteIdentityConfig } from '../auth/identity'
-import type { AnyRemoteFunctionDef } from '../define/remote-function'
-import type { ViewDef } from '../define/view'
-import type { AuxIdentityMap } from '../dispatch/identity'
-
-import { makeFunctionContext } from '../auth/function-context'
-import { makeDomainAuthority } from '../auth/issuer-mint'
-import { resolveInboundAuth } from '../auth/resolve'
-import { createHandlerLifecycle, executionLifetime } from '../defer'
-import { runAuthorize } from '../dispatch/authorize'
-import { SdkResultValidationError, SdkValidationError } from '../dispatch/errors'
-import { validateParams, validateResult } from '../dispatch/validate'
-import { createInlineStep } from '../step'
+import {
+  buildCorsHeaders,
+  createCapabilityLifecycle,
+  honoCapabilityHost,
+  type CorsConfig,
+} from '@astrale-os/kernel-server'
+
+import type { RemoteIdentityConfig } from '../auth/identity.js'
+import type { AnyRemoteFunctionDef } from '../define/remote-function.js'
+import type { ViewDef } from '../define/view.js'
+import type { AuxIdentityMap } from '../dispatch/identity.js'
+
+import { makeFunctionContext } from '../auth/function-context.js'
+import { makeDomainAuthority } from '../auth/issuer-mint.js'
+import { resolveInboundAuth } from '../auth/resolve.js'
+import { runAuthorize } from '../dispatch/authorize.js'
+import { SdkResultValidationError, SdkValidationError } from '../dispatch/errors.js'
+import { validateParams, validateResult } from '../dispatch/validate.js'
+import { createInlineStep } from '../step/index.js'
 
 export type AuxiliaryRoutesConfig<TDeps> = {
   app: Hono
@@ -172,7 +176,7 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
             }),
           }
           if (def.authorize) await runAuthorize(def.authorize, ctx)
-          const lifecycle = createHandlerLifecycle(executionLifetime(c))
+          const lifecycle = createCapabilityLifecycle(honoCapabilityHost(c))
           const result = await (async () => {
             try {
               return await def.execute({
@@ -180,7 +184,8 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
                 step: createInlineStep({
                   scope: { kind: 'function', ref: `function.${slug}`, slug },
                 }),
-                defer: lifecycle.defer,
+                defer: lifecycle.capabilities.defer,
+                sleep: lifecycle.capabilities.sleep,
               })
             } finally {
               await lifecycle.settle()