@astrale-os/sdk 0.4.11 → 0.4.13

package/src/linter/preflight.ts

@@ -0,0 +1,181 @@
+import { existsSync } from 'node:fs'
+import { readFile, realpath } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { LinterToolError } from './diagnostic.js'
+
+const brandedPackages = [
+  '@astrale-os/kernel-client',
+  '@astrale-os/kernel-core',
+  '@astrale-os/kernel-dsl',
+] as const
+
+const conventionalMembers = ['client', 'frontend', 'schema', 'worker'] as const
+
+type Resolution = {
+  consumer: string
+  path: string
+}
+
+type ConsumerPackageJson = {
+  name?: string
+  dependencies?: Record<string, string>
+  optionalDependencies?: Record<string, string>
+  workspaces?: string[] | { packages?: string[] }
+}
+
+export async function assertSingleTypeUniverse(root: string): Promise<void> {
+  const manifests = await collectConsumerManifests(root)
+  const consumers = [
+    ...manifests.map((path) => ({ label: relative(root, dirname(path)) || '.', path })),
+    { label: '@astrale-os/sdk/linter', path: fileURLPackageJson() },
+  ]
+
+  for (const packageName of brandedPackages) {
+    const resolutions: Resolution[] = []
+    for (const consumer of consumers) {
+      const resolved = await resolvePackageRoot(packageName, consumer.path)
+      if (resolved) resolutions.push({ consumer: consumer.label, path: resolved })
+    }
+    const paths = new Set(resolutions.map((resolution) => resolution.path))
+    if (paths.size <= 1) continue
+    const detail = formatResolutions(resolutions)
+    throw new LinterToolError(
+      `Multiple physical installations of ${packageName} would create incompatible Astrale types.\n` +
+        `${detail}\nReinstall the workspace so every member resolves one compatible package instance.`,
+    )
+  }
+}
+
+function formatResolutions(resolutions: readonly Resolution[]): string {
+  const byPath = new Map<string, string[]>()
+  for (const resolution of resolutions) {
+    const consumers = byPath.get(resolution.path) ?? []
+    consumers.push(resolution.consumer)
+    byPath.set(resolution.path, consumers)
+  }
+  return [...byPath]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([path, consumers]) => {
+      const sorted = [...new Set(consumers)].sort()
+      const shown = sorted.slice(0, 4).join(', ')
+      const omitted = sorted.length > 4 ? ` (+${sorted.length - 4} more)` : ''
+      return `  ${path}\n    from: ${shown}${omitted}`
+    })
+    .join('\n')
+}
+
+async function collectConsumerManifests(root: string): Promise<string[]> {
+  const rootManifest = join(root, 'package.json')
+  if (!existsSync(rootManifest)) return []
+
+  const manifests = new Set([rootManifest])
+  const packageJson = await readPackageJson(rootManifest)
+  const workspaces = Array.isArray(packageJson?.workspaces)
+    ? packageJson.workspaces
+    : packageJson?.workspaces?.packages
+
+  for (const workspace of workspaces ?? []) {
+    if (typeof workspace !== 'string' || hasGlob(workspace)) continue
+    addManifestWithinRoot(manifests, root, workspace)
+  }
+
+  for (const member of conventionalMembers) addManifestWithinRoot(manifests, root, member)
+  await addDomainContractDependencyManifests(manifests)
+  return [...manifests].sort()
+}
+
+async function readPackageJson(manifest: string): Promise<ConsumerPackageJson | undefined> {
+  try {
+    return JSON.parse(await readFile(manifest, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+async function addDomainContractDependencyManifests(manifests: Set<string>): Promise<void> {
+  const pending = [...manifests]
+  for (let index = 0; index < pending.length; index++) {
+    const consumer = pending[index]!
+    const packageJson = await readPackageJson(consumer)
+    const dependencies = {
+      ...packageJson?.optionalDependencies,
+      ...packageJson?.dependencies,
+    }
+    for (const packageName of Object.keys(dependencies).sort()) {
+      if (!isDomainContractPackage(packageName)) continue
+      const manifest = await resolveDependencyManifest(packageName, consumer)
+      if (!manifest || manifests.has(manifest)) continue
+      manifests.add(manifest)
+      pending.push(manifest)
+    }
+  }
+}
+
+async function resolveDependencyManifest(
+  packageName: string,
+  consumerManifest: string,
+): Promise<string | undefined> {
+  const require = createRequire(consumerManifest)
+  try {
+    return await realpath(require.resolve(`${packageName}/package.json`))
+  } catch {
+    try {
+      let directory = dirname(await realpath(require.resolve(packageName)))
+      for (;;) {
+        const manifest = join(directory, 'package.json')
+        if (existsSync(manifest)) {
+          const packageJson = await readPackageJson(manifest)
+          if (packageJson?.name === packageName) return await realpath(manifest)
+        }
+        const parent = dirname(directory)
+        if (parent === directory) return undefined
+        directory = parent
+      }
+    } catch {
+      return undefined
+    }
+  }
+}
+
+function addManifestWithinRoot(manifests: Set<string>, root: string, member: string): void {
+  const manifest = resolve(root, member, 'package.json')
+  const parent = relative(root, manifest)
+  if (parent.startsWith('..') || parent === '') return
+  if (existsSync(manifest)) manifests.add(manifest)
+}
+
+function hasGlob(path: string): boolean {
+  return /[*?[\]{}!]/u.test(path)
+}
+
+function isDomainContractPackage(packageName: string): boolean {
+  return packageName.startsWith('@astrale-domains/')
+}
+
+async function resolvePackageRoot(
+  packageName: (typeof brandedPackages)[number],
+  manifest: string,
+): Promise<string | undefined> {
+  if (!existsSync(manifest)) return undefined
+  try {
+    const resolved = createRequire(manifest).resolve(`${packageName}/package.json`)
+    return await realpath(dirname(resolved))
+  } catch {
+    return undefined
+  }
+}
+
+function fileURLPackageJson(): string {
+  let directory = dirname(fileURLToPath(import.meta.url))
+  for (;;) {
+    const candidate = join(directory, 'package.json')
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(directory)
+    if (parent === directory) break
+    directory = parent
+  }
+  return join(directory, 'package.json')
+}

package/src/linter/project.ts

@@ -0,0 +1,108 @@
+import { readdir, readFile, realpath } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+import { scanSource, type SourceFile } from './source.js'
+
+const ignoredDirectories = new Set([
+  '.astrale',
+  '.dist',
+  '.domain-studio',
+  '.git',
+  '.output',
+  '.turbo',
+  '.wrangler',
+  'coverage',
+  'dist',
+  'dist-client',
+  'node_modules',
+])
+
+const sourceExtensions = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx'])
+
+export type DomainProject = {
+  root: string
+  files: readonly SourceFile[]
+  filesByPath: ReadonlyMap<string, SourceFile>
+}
+
+export async function discoverProject(root: string): Promise<DomainProject> {
+  const projectRoot = await realpath(resolve(root))
+  const paths: string[] = []
+  await collectSourcePaths(projectRoot, paths)
+  paths.sort()
+
+  const files = await Promise.all(
+    paths.map(async (path) => {
+      const text = await readFile(path, 'utf8')
+      return scanSource(path, normalizePath(relative(projectRoot, path)), text)
+    }),
+  )
+  return {
+    root: projectRoot,
+    files,
+    filesByPath: new Map(files.map((file) => [file.path, file])),
+  }
+}
+
+async function collectSourcePaths(directory: string, result: string[]): Promise<void> {
+  const entries = await readdir(directory, { withFileTypes: true })
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (entry.isSymbolicLink()) return
+      const path = join(directory, entry.name)
+      if (entry.isDirectory()) {
+        if (!ignoredDirectories.has(entry.name)) await collectSourcePaths(path, result)
+        return
+      }
+      if (!entry.isFile() || !sourceExtensions.has(extname(entry.name))) return
+      if (entry.name.endsWith('.d.ts') || entry.name.includes('.gen.')) return
+      result.push(path)
+    }),
+  )
+}
+
+export function normalizePath(path: string): string {
+  return sep === '/' ? path : path.split(sep).join('/')
+}
+
+export function isProductionSource(relativePath: string): boolean {
+  const normalized = normalizePath(relativePath)
+  return (
+    !normalized.split('/').includes('__tests__') &&
+    !/\.(?:test|spec|bench|perf)\.[cm]?[jt]sx?$/.test(normalized) &&
+    !normalized.includes('.gen.')
+  )
+}
+
+export function isProductionCore(relativePath: string): boolean {
+  const normalized = normalizePath(relativePath)
+  return (normalized === 'core' || normalized.startsWith('core/')) && isProductionSource(normalized)
+}
+
+export function resolveProjectImport(
+  project: DomainProject,
+  importer: SourceFile,
+  specifier: string,
+): SourceFile | undefined {
+  if (!specifier.startsWith('.')) return undefined
+  const unresolved = resolve(dirname(importer.path), specifier)
+  for (const candidate of importCandidates(unresolved)) {
+    const file = project.filesByPath.get(candidate)
+    if (file) return file
+  }
+  return undefined
+}
+
+function importCandidates(path: string): string[] {
+  const extension = extname(path)
+  const candidates = [path]
+  if (extension === '.js' || extension === '.jsx' || extension === '.mjs' || extension === '.cjs') {
+    const stem = path.slice(0, -extension.length)
+    candidates.push(`${stem}.ts`, `${stem}.tsx`, `${stem}.mts`, `${stem}.cts`)
+  }
+  if (!extension) {
+    candidates.push(`${path}.ts`, `${path}.tsx`, `${path}.mts`, `${path}.cts`)
+    candidates.push(join(path, 'index.ts'), join(path, 'index.tsx'))
+  }
+  return candidates.map((candidate) => (isAbsolute(candidate) ? candidate : resolve(candidate)))
+}

package/src/linter/report.ts

@@ -0,0 +1,25 @@
+import type { LintResult } from './diagnostic.js'
+
+export type LintReportFormat = 'json' | 'stylish'
+
+export function formatLintResult(result: LintResult, format: LintReportFormat = 'stylish'): string {
+  if (format === 'json') return `${JSON.stringify(result, null, 2)}\n`
+  const lines: string[] = []
+  for (const diagnostic of result.diagnostics) {
+    const location = diagnostic.location
+      ? `${diagnostic.location.path}:${diagnostic.location.line}:${diagnostic.location.column}`
+      : result.root
+    lines.push(`${location}  ${diagnostic.severity} ${diagnostic.id}  ${diagnostic.message}`)
+    if (diagnostic.help) lines.push(`  ${diagnostic.help}`)
+  }
+
+  const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === 'error').length
+  const warnings = result.diagnostics.length - errors
+  if (lines.length > 0) lines.push('')
+  lines.push(
+    errors === 0
+      ? `\u2713 ${result.files} files linted in ${result.durationMs}ms${warnings ? ` (${warnings} warnings)` : ''}`
+      : `\u2717 ${errors} ${errors === 1 ? 'error' : 'errors'}, ${warnings} ${warnings === 1 ? 'warning' : 'warnings'} in ${result.durationMs}ms`,
+  )
+  return `${lines.join('\n')}\n`
+}

package/src/linter/rules/catalog.ts

@@ -0,0 +1,67 @@
+export type RuleOwner = 'analyzer' | 'oxlint' | 'sdk'
+
+export type RuleInfo = {
+  slug: string
+  owner: RuleOwner
+  message: string
+  help: string
+  url: string
+}
+
+const ruleDocsUrl = (slug: string) => `https://docs.astrale.ai/linter/rules/${slug}`
+
+export const ruleCatalog = {
+  'thin-schema-composition-root': {
+    slug: 'thin-schema-composition-root',
+    owner: 'analyzer',
+    message: 'The schema composition root defines a schema member inline.',
+    help: 'Move this member definition to its bounded-context module and import it here.',
+    url: ruleDocsUrl('thin-schema-composition-root'),
+  },
+  'one-remote-definition-per-file': {
+    slug: 'one-remote-definition-per-file',
+    owner: 'analyzer',
+    message: 'This file defines more than one Astrale remote callable.',
+    help: 'Keep one remoteMethod or defineRemoteFunction definition per implementation file.',
+    url: ruleDocsUrl('one-remote-definition-per-file'),
+  },
+  'core-is-pure': {
+    slug: 'core-is-pure',
+    owner: 'analyzer',
+    message: 'Pure core code depends on an effectful or runtime-only module.',
+    help: 'Move I/O orchestration to runtime or integrations and pass pure data into core.',
+    url: ruleDocsUrl('core-is-pure'),
+  },
+  'core-has-no-async': {
+    slug: 'core-has-no-async',
+    owner: 'oxlint',
+    message: 'Production core code contains asynchronous syntax.',
+    help: 'Keep core deterministic and synchronous; perform asynchronous work in runtime or integrations.',
+    url: ruleDocsUrl('core-has-no-async'),
+  },
+  'no-nested-steps': {
+    slug: 'no-nested-steps',
+    owner: 'oxlint',
+    message: 'A durable step directly contains another durable step.',
+    help: 'Give each stage one step boundary and call helper-owned steps outside another step callback.',
+    url: ruleDocsUrl('no-nested-steps'),
+  },
+  'no-read-inside-mutate': {
+    slug: 'no-read-inside-mutate',
+    owner: 'oxlint',
+    message: 'A graph mutation builder performs a read or is asynchronous.',
+    help: 'Read before mutate, then keep the mutation callback synchronous and limited to patch construction.',
+    url: ruleDocsUrl('no-read-inside-mutate'),
+  },
+} as const satisfies Record<string, RuleInfo>
+
+export type ImplementedRuleSlug = keyof typeof ruleCatalog
+
+export function ruleId(slug: ImplementedRuleSlug): `astrale/${ImplementedRuleSlug}` {
+  return `astrale/${slug}`
+}
+
+export function ruleInfo(id: string): RuleInfo | undefined {
+  const slug = id.startsWith('astrale/') ? id.slice('astrale/'.length) : id
+  return ruleCatalog[slug as ImplementedRuleSlug]
+}

package/src/linter/rules/core-has-no-async.js

@@ -0,0 +1,43 @@
+// @ts-check
+
+import { isProductionCoreFile, nearestFunction, reportUnlessSuppressed } from './oxlint-ast.js'
+
+const id = 'astrale/core-has-no-async'
+
+/** @type {import('./oxlint-rule.js').OxlintRule} */
+export const coreHasNoAsync = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Production core code contains asynchronous syntax.',
+      url: 'https://docs.astrale.ai/linter/rules/core-has-no-async',
+    },
+    messages: {
+      asyncFunction: 'Production core functions must be synchronous.',
+      topLevelAwait: 'Production core modules must not use top-level await.',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (!isProductionCoreFile(context)) return {}
+    /** @param {import('./oxlint-rule.js').AstNode} node */
+    const reportFunction = (node) => {
+      if (node.async) reportUnlessSuppressed(context, node, id, 'asyncFunction')
+    }
+    return {
+      FunctionDeclaration: reportFunction,
+      FunctionExpression: reportFunction,
+      ArrowFunctionExpression: reportFunction,
+      AwaitExpression(node) {
+        if (!nearestFunction(node.parent)) {
+          reportUnlessSuppressed(context, node, id, 'topLevelAwait')
+        }
+      },
+      ForOfStatement(node) {
+        if (node.await && !nearestFunction(node.parent)) {
+          reportUnlessSuppressed(context, node, id, 'topLevelAwait')
+        }
+      },
+    }
+  },
+}

package/src/linter/rules/core-is-pure.ts

@@ -0,0 +1,103 @@
+import type { LintDiagnostic } from '../diagnostic.js'
+import type { SourceFile, SourceImport } from '../source.js'
+
+import {
+  isProductionCore,
+  isProductionSource,
+  resolveProjectImport,
+  type DomainProject,
+} from '../project.js'
+import { analyzerDiagnostic, type AnalyzerRule } from './project-rule.js'
+
+const forbiddenPackages = new Set([
+  '@astrale-os/adapter-astrale',
+  '@astrale-os/adapter-cloudflare',
+  '@astrale-os/kernel-api',
+  '@astrale-os/kernel-client',
+  '@astrale-os/kernel-server',
+  '@astrale-os/kernel-test',
+  '@astrale-os/sdk',
+  'node:child_process',
+  'node:cluster',
+  'node:dgram',
+  'node:dns',
+  'node:fs',
+  'node:fs/promises',
+  'node:http',
+  'node:http2',
+  'node:https',
+  'node:net',
+  'node:tls',
+  'node:worker_threads',
+])
+
+const forbiddenRoots = new Set(['client', 'functions', 'integrations', 'runtime', 'simulation'])
+const forbiddenRootFiles = new Set(['astrale.config.ts', 'deps.ts', 'domain.ts', 'env.ts'])
+
+export const coreIsPure: AnalyzerRule = {
+  slug: 'core-is-pure',
+  analyze(project: DomainProject): readonly LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = []
+    const visited = new Set<string>()
+    const pending = project.files.filter((file) => isProductionCore(file.relativePath))
+
+    while (pending.length > 0) {
+      const file = pending.pop()!
+      if (visited.has(file.path)) continue
+      visited.add(file.path)
+
+      for (const sourceImport of file.imports) {
+        const forbiddenPackage = forbiddenPackageName(sourceImport.specifier)
+        if (forbiddenPackage) {
+          pushDiagnostic(
+            diagnostics,
+            this.slug,
+            file,
+            sourceImport,
+            `Import ${forbiddenPackage} crosses the pure-core boundary.`,
+          )
+          continue
+        }
+
+        const dependency = resolveProjectImport(project, file, sourceImport.specifier)
+        if (!dependency || !isProductionSource(dependency.relativePath)) continue
+        if (isForbiddenProjectLayer(dependency.relativePath)) {
+          pushDiagnostic(
+            diagnostics,
+            this.slug,
+            file,
+            sourceImport,
+            `Import ${sourceImport.specifier} reaches ${dependency.relativePath}.`,
+          )
+          continue
+        }
+        pending.push(dependency)
+      }
+    }
+    return diagnostics
+  },
+}
+
+function forbiddenPackageName(specifier: string): string | undefined {
+  if (forbiddenPackages.has(specifier)) return specifier
+  for (const name of forbiddenPackages) {
+    if (specifier.startsWith(`${name}/`)) return name
+  }
+  return undefined
+}
+
+function isForbiddenProjectLayer(relativePath: string): boolean {
+  const [root] = relativePath.split('/')
+  return forbiddenRoots.has(root ?? '') || forbiddenRootFiles.has(relativePath)
+}
+
+function pushDiagnostic(
+  diagnostics: LintDiagnostic[],
+  slug: AnalyzerRule['slug'],
+  file: SourceFile,
+  sourceImport: SourceImport,
+  detail: string,
+): void {
+  const diagnostic = analyzerDiagnostic(slug, file, sourceImport.token, detail)
+  if (diagnostic) diagnostics.push(diagnostic)
+}

package/src/linter/rules/no-nested-steps.js

@@ -0,0 +1,37 @@
+// @ts-check
+
+import {
+  callbackCall,
+  isProductionFile,
+  isStepRun,
+  nearestFunction,
+  reportUnlessSuppressed,
+} from './oxlint-ast.js'
+
+const id = 'astrale/no-nested-steps'
+
+/** @type {import('./oxlint-rule.js').OxlintRule} */
+export const noNestedSteps = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'A durable step directly contains another durable step.',
+      url: 'https://docs.astrale.ai/linter/rules/no-nested-steps',
+    },
+    messages: {
+      nested: 'A step.run callback must not directly invoke another step.run.',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (!isProductionFile(context)) return {}
+    return {
+      CallExpression(node) {
+        if (!isStepRun(node)) return
+        const containingFunction = nearestFunction(node.parent)
+        if (!containingFunction || !isStepRun(callbackCall(containingFunction))) return
+        reportUnlessSuppressed(context, node, id, 'nested')
+      },
+    }
+  },
+}

package/src/linter/rules/no-read-inside-mutate.js

@@ -0,0 +1,72 @@
+// @ts-check
+
+import {
+  callbackCall,
+  isFunctionNode,
+  isMutateCall,
+  isProductionFile,
+  nearestFunction,
+  reportUnlessSuppressed,
+  staticMember,
+} from './oxlint-ast.js'
+
+const id = 'astrale/no-read-inside-mutate'
+const readMethods = new Set([
+  'call',
+  'check',
+  'children',
+  'get',
+  'getOrThrow',
+  'neighbors',
+  'query',
+  'refresh',
+  'whoami',
+])
+
+/** @type {import('./oxlint-rule.js').OxlintRule} */
+export const noReadInsideMutate = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'A graph mutation builder performs a read or is asynchronous.',
+      url: 'https://docs.astrale.ai/linter/rules/no-read-inside-mutate',
+    },
+    messages: {
+      asyncCallback: 'A kernel.mutate callback must be synchronous.',
+      read: 'Read graph state before kernel.mutate; its callback only constructs a patch.',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (!isProductionFile(context)) return {}
+    return {
+      CallExpression(node) {
+        if (isMutateCall(node)) {
+          const callback = node.arguments?.find(isFunctionNode)
+          if (callback?.async) {
+            reportUnlessSuppressed(context, callback, id, 'asyncCallback')
+          }
+          return
+        }
+
+        const callback = nearestFunction(node.parent)
+        if (!callback || callback.async) return
+        const mutate = callbackCall(callback)
+        if (!isMutateCall(mutate)) return
+
+        const mutationMember = staticMember(mutate?.callee)
+        const readMember = staticMember(node.callee)
+        if (!mutationMember || !readMember || !readMethods.has(readMember.property)) return
+        if (!sameKernelRoot(context, mutationMember.object, readMember.object)) return
+        reportUnlessSuppressed(context, node, id, 'read')
+      },
+    }
+  },
+}
+
+/** @param {import('./oxlint-rule.js').OxlintRuleContext} context @param {import('./oxlint-rule.js').AstNode} mutationRoot @param {import('./oxlint-rule.js').AstNode} readRoot */
+function sameKernelRoot(context, mutationRoot, readRoot) {
+  const mutationText = context.sourceCode.getText(mutationRoot)
+  const readText = context.sourceCode.getText(readRoot)
+  return readText === mutationText || readText.startsWith(`${mutationText}.`)
+}

package/src/linter/rules/one-remote-definition-per-file.ts

@@ -0,0 +1,29 @@
+import type { LintDiagnostic } from '../diagnostic.js'
+
+import { isProductionSource, type DomainProject } from '../project.js'
+import { importedCalls } from '../source.js'
+import { analyzerDiagnostic, type AnalyzerRule } from './project-rule.js'
+
+const sdkModules = new Set(['@astrale-os/sdk'])
+const remoteDefinitions = new Set(['defineRemoteFunction', 'remoteMethod'])
+
+export const oneRemoteDefinitionPerFile: AnalyzerRule = {
+  slug: 'one-remote-definition-per-file',
+  analyze(project: DomainProject): readonly LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = []
+    for (const file of project.files) {
+      if (!isProductionSource(file.relativePath)) continue
+      const definitions = importedCalls(file, sdkModules, remoteDefinitions)
+      for (const definition of definitions.slice(1)) {
+        const diagnostic = analyzerDiagnostic(
+          this.slug,
+          file,
+          definition,
+          `Found ${definitions.length} definitions.`,
+        )
+        if (diagnostic) diagnostics.push(diagnostic)
+      }
+    }
+    return diagnostics
+  },
+}