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

package/studio/shared/schema/identity.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  IR_SCHEMA_REF_KINDS,
+  definitionRefKey,
+  isIrDefinitionRef,
+  isIrInterfaceRef,
+  isIrSchemaRef,
+  parseDefinitionRefKey,
+  parseSchemaRefKey,
+  schemaRefKey,
+  type IrSchemaRef,
+} from './identity'
+
+describe('canonical schema identity', () => {
+  test('round-trips every structural reference kind without short-name aliases', () => {
+    for (const kind of IR_SCHEMA_REF_KINDS) {
+      const ref = {
+        origin: 'directory.example.dev',
+        kind,
+        name: '$Named_member',
+      } satisfies IrSchemaRef
+      expect(parseSchemaRefKey(schemaRefKey(ref))).toEqual(ref)
+    }
+  })
+
+  test('keeps class and interface identities distinct', () => {
+    const classRef = { origin: 'contracts.example.dev', kind: 'class', name: 'Shared' } as const
+    const interfaceRef = {
+      origin: 'contracts.example.dev',
+      kind: 'interface',
+      name: 'Shared',
+    } as const
+
+    expect(definitionRefKey(classRef)).toBe('contracts.example.dev:class.Shared')
+    expect(definitionRefKey(interfaceRef)).toBe('contracts.example.dev:interface.Shared')
+    expect(parseDefinitionRefKey(definitionRefKey(classRef))).toEqual(classRef)
+    expect(parseDefinitionRefKey(definitionRefKey(interfaceRef))).toEqual(interfaceRef)
+  })
+
+  test('guards structural refs without claiming SDK admission', () => {
+    expect(isIrSchemaRef({ origin: 'a.dev', kind: 'policy', name: 'may_read' })).toBe(true)
+    expect(isIrDefinitionRef({ origin: 'a.dev', kind: 'class', name: 'Thing' })).toBe(true)
+    expect(isIrDefinitionRef({ origin: 'a.dev', kind: 'policy', name: 'may_read' })).toBe(false)
+    expect(isIrInterfaceRef({ origin: 'a.dev', kind: 'interface', name: 'Named' })).toBe(true)
+    expect(isIrInterfaceRef({ origin: 'a.dev', kind: 'class', name: 'Named' })).toBe(false)
+    expect(isIrSchemaRef({ origin: 'a.dev', kind: 'unknown', name: 'Thing' })).toBe(false)
+    expect(isIrSchemaRef({ origin: 'a.dev', kind: 'class' })).toBe(false)
+  })
+
+  test('rejects malformed and non-definition keys', () => {
+    expect(parseSchemaRefKey('a.dev:unknown.Thing')).toBeUndefined()
+    expect(parseSchemaRefKey('a.dev:class.')).toBeUndefined()
+    expect(parseSchemaRefKey(':class.Thing')).toBeUndefined()
+    expect(parseSchemaRefKey(null)).toBeUndefined()
+    expect(parseDefinitionRefKey('a.dev:type.Payload')).toBeUndefined()
+  })
+})

package/studio/shared/schema/identity.ts

@@ -0,0 +1,82 @@
+/**
+ * Canonical Studio identity for DomainSchema references.
+ *
+ * These helpers validate and encode only the structural wire coordinate. SDK
+ * admission remains the authority for whether a reference is semantically valid.
+ */
+
+export const IR_SCHEMA_REF_KINDS = [
+  'type',
+  'interface',
+  'class',
+  'function',
+  'policy',
+  'view',
+  'core',
+] as const
+
+export type IrSchemaRefKind = (typeof IR_SCHEMA_REF_KINDS)[number]
+
+/** Exact structural coordinate embedded in a canonical DomainSchema V1 root. */
+export interface IrSchemaRef {
+  origin: string
+  kind: IrSchemaRefKind
+  name: string
+}
+
+/** Canonical DSL key for a schema member: `origin:kind.name`. */
+export type IrSchemaKey = `${string}:${IrSchemaRefKind}.${string}`
+
+export type IrDefinitionRef = Omit<IrSchemaRef, 'kind'> & {
+  kind: 'class' | 'interface'
+}
+
+export type IrDefinitionKey = `${string}:${IrDefinitionRef['kind']}.${string}`
+
+const schemaKinds = new Set<string>(IR_SCHEMA_REF_KINDS)
+const schemaKeyPattern = /^(.+):(type|interface|class|function|policy|view|core)\.(.+)$/
+
+/** Structural guard only; it deliberately does not perform SDK admission. */
+export function isIrSchemaRef(value: unknown): value is IrSchemaRef {
+  if (!value || typeof value !== 'object') return false
+  const ref = value as Partial<IrSchemaRef>
+  return (
+    typeof ref.origin === 'string' &&
+    typeof ref.name === 'string' &&
+    typeof ref.kind === 'string' &&
+    schemaKinds.has(ref.kind)
+  )
+}
+
+export function isIrDefinitionRef(value: unknown): value is IrDefinitionRef {
+  return isIrSchemaRef(value) && (value.kind === 'class' || value.kind === 'interface')
+}
+
+export function isIrInterfaceRef(value: unknown): value is IrDefinitionRef & { kind: 'interface' } {
+  return isIrSchemaRef(value) && value.kind === 'interface'
+}
+
+export function schemaRefKey(ref: IrSchemaRef): IrSchemaKey {
+  return `${ref.origin}:${ref.kind}.${ref.name}`
+}
+
+export function definitionRefKey(ref: IrDefinitionRef): IrDefinitionKey {
+  return `${ref.origin}:${ref.kind}.${ref.name}`
+}
+
+/** Parse a canonical key without asserting that the referenced member exists. */
+export function parseSchemaRefKey(value: unknown): IrSchemaRef | undefined {
+  if (typeof value !== 'string') return undefined
+  const match = schemaKeyPattern.exec(value)
+  if (!match) return undefined
+  return {
+    origin: match[1],
+    kind: match[2] as IrSchemaRefKind,
+    name: match[3],
+  }
+}
+
+export function parseDefinitionRefKey(value: unknown): IrDefinitionRef | undefined {
+  const ref = parseSchemaRefKey(value)
+  return ref && isIrDefinitionRef(ref) ? ref : undefined
+}