@astrale-os/sdk 0.4.12 → 0.4.13

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
+  },
+}

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)
+  },
+}