@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.30

package/studio/server/introspect/schema-ir-json.ts

@@ -1,8 +1,9 @@
 /** Structural admission for persisted Studio render IR. SDK admission is separate. */
 
 import type {
+  IrClass,
+  IrClassRef,
   IrFunction,
-  IrInterface,
   IrMethod,
   IrSchemaRef,
   JsonSchema,
@@ -11,10 +12,6 @@ import type {
 
 import { asJsonRecord, asStringArray } from '../json'
 
-function optional<T>(value: unknown, guard: (candidate: unknown) => candidate is T): boolean {
-  return value === undefined || guard(value)
-}
-
 function recordOf(value: unknown, guard: (candidate: unknown) => boolean): boolean {
   const record = asJsonRecord(value)
   return !!record && Object.values(record).every(guard)
@@ -29,14 +26,12 @@ function isSchemaRef(value: unknown): value is IrSchemaRef {
   return (
     typeof record?.origin === 'string' &&
     typeof record.name === 'string' &&
-    ['type', 'interface', 'class', 'function', 'policy', 'view', 'core'].includes(
-      String(record.kind),
-    )
+    ['class', 'function', 'policy', 'view', 'core'].includes(String(record.kind))
   )
 }
 
-function isSchemaRefArray(value: unknown): value is IrSchemaRef[] {
-  return Array.isArray(value) && value.every(isSchemaRef)
+function isClassRef(value: unknown): value is IrClassRef {
+  return isSchemaRef(value) && value.kind === 'class'
 }
 
 function isOutput(value: unknown): boolean {
@@ -52,20 +47,22 @@ function isMethod(value: unknown): value is IrMethod {
   const record = asJsonRecord(value)
   return (
     typeof record?.name === 'string' &&
-    recordOf(record.params, isJsonSchema) &&
-    isJsonSchema(record.returns) &&
+    isJsonSchema(record.input) &&
+    isOutput(record.output) &&
     typeof record.static === 'boolean' &&
-    ['default', 'abstract', 'sealed'].includes(String(record.inheritance)) &&
-    optional(record.input, isJsonSchema) &&
-    (record.requiredParams === undefined || asStringArray(record.requiredParams) !== undefined) &&
-    (record.output === undefined || isOutput(record.output))
+    ['default', 'abstract', 'sealed'].includes(String(record.inheritance))
   )
 }
 
 function isEndpoint(value: unknown): boolean {
   const record = asJsonRecord(value)
   if (!record || typeof record.name !== 'string' || !asStringArray(record.types)) return false
-  if (record.refs !== undefined && !isSchemaRefArray(record.refs)) return false
+  if (
+    record.refs !== undefined &&
+    (!Array.isArray(record.refs) || !record.refs.every(isSchemaRef))
+  ) {
+    return false
+  }
   if (record.cardinality !== undefined) {
     const cardinality = asJsonRecord(record.cardinality)
     if (
@@ -81,31 +78,19 @@ function isEndpoint(value: unknown): boolean {
   return true
 }
 
-function isInterface(value: unknown): value is IrInterface {
-  const record = asJsonRecord(value)
-  return (
-    record?.type === 'interface' &&
-    typeof record.name === 'string' &&
-    recordOf(record.properties, isJsonSchema) &&
-    recordOf(record.methods, isMethod) &&
-    (record.required === undefined || asStringArray(record.required) !== undefined) &&
-    (record.extends === undefined || asStringArray(record.extends) !== undefined) &&
-    (record.extendsRefs === undefined || isSchemaRefArray(record.extendsRefs)) &&
-    (record.endpoints === undefined ||
-      (Array.isArray(record.endpoints) && record.endpoints.every(isEndpoint)))
-  )
-}
-
-function isClass(value: unknown): boolean {
+function isClass(value: unknown): value is IrClass {
   const record = asJsonRecord(value)
   return (
     (record?.type === 'node' || record?.type === 'edge') &&
     typeof record.name === 'string' &&
+    typeof record.origin === 'string' &&
+    isClassRef(record.ref) &&
     recordOf(record.properties, isJsonSchema) &&
     recordOf(record.methods, isMethod) &&
     (record.required === undefined || asStringArray(record.required) !== undefined) &&
-    (record.implements === undefined || asStringArray(record.implements) !== undefined) &&
-    (record.implementsRefs === undefined || isSchemaRefArray(record.implementsRefs)) &&
+    (record.extends === undefined || asStringArray(record.extends) !== undefined) &&
+    (record.extendsRefs === undefined ||
+      (Array.isArray(record.extendsRefs) && record.extendsRefs.every(isClassRef))) &&
     (record.endpoints === undefined ||
       (Array.isArray(record.endpoints) && record.endpoints.every(isEndpoint)))
   )
@@ -113,24 +98,16 @@ function isClass(value: unknown): boolean {
 
 function isFunction(value: unknown): value is IrFunction {
   const record = asJsonRecord(value)
-  return (
-    typeof record?.name === 'string' &&
-    isJsonSchema(record.input) &&
-    recordOf(record.params, isJsonSchema) &&
-    (record.requiredParams === undefined || asStringArray(record.requiredParams) !== undefined) &&
-    isOutput(record.output) &&
-    isJsonSchema(record.returns) &&
-    record.static === true &&
-    record.inheritance === 'default'
-  )
+  return typeof record?.name === 'string' && isJsonSchema(record.input) && isOutput(record.output)
 }
 
 function isImport(value: unknown): boolean {
   const record = asJsonRecord(value)
   return (
     typeof record?.origin === 'string' &&
-    (record.definition === 'class' || record.definition === 'interface') &&
-    optional(record.ref, isSchemaRef)
+    isClassRef(record.ref) &&
+    typeof record.key === 'string' &&
+    record.key === `${record.ref.origin}:class.${record.ref.name}`
   )
 }
 
@@ -139,10 +116,12 @@ function isView(value: unknown): boolean {
   const target = asJsonRecord(record?.target)
   return (
     typeof record?.name === 'string' &&
-    ['required', 'optional', 'public'].includes(String(record.auth)) &&
+    record.auth === undefined &&
     !!target &&
     (target.kind === 'domain' ||
-      (target.kind === 'definition' && isSchemaRefArray(target.definitions)))
+      (target.kind === 'definition' &&
+        Array.isArray(target.definitions) &&
+        target.definitions.every(isSchemaRef)))
   )
 }
 
@@ -150,32 +129,23 @@ export function decodeSchemaIR(value: unknown): SchemaIR | undefined {
   const record = asJsonRecord(value)
   if (
     !record ||
+    record.format !== 'astrale.dsl' ||
     typeof record.version !== 'string' ||
     typeof record.domain !== 'string' ||
-    !recordOf(record.types, isJsonSchema) ||
-    !recordOf(record.interfaces, isInterface) ||
     !recordOf(record.classes, isClass) ||
-    !recordOf(record.imports, isImport) ||
     !recordOf(record.functions, isFunction) ||
-    (record.importsByKey !== undefined && !recordOf(record.importsByKey, isImport)) ||
-    (record.importedInterfacesByKey !== undefined &&
-      !recordOf(record.importedInterfacesByKey, isInterface)) ||
-    (record.views !== undefined && !recordOf(record.views, isView)) ||
-    (record.policies !== undefined && !asJsonRecord(record.policies)) ||
-    (record.dependencies !== undefined &&
-      (!Array.isArray(record.dependencies) ||
-        !record.dependencies.every((dependency) => {
-          const item = asJsonRecord(dependency)
-          return typeof item?.origin === 'string' && typeof item.revision === 'string'
-        })))
+    !recordOf(record.importsByKey, isImport) ||
+    !recordOf(record.importedClassesByKey, isClass) ||
+    !recordOf(record.views, isView) ||
+    !asJsonRecord(record.policies) ||
+    !Array.isArray(record.dependencies) ||
+    !record.dependencies.every((dependency) => {
+      const item = asJsonRecord(dependency)
+      return typeof item?.origin === 'string' && typeof item.revision === 'string'
+    }) ||
+    !('core' in record)
   ) {
     return undefined
   }
   return record as unknown as SchemaIR
 }
-
-export function decodeIrInterfaceRecord(value: unknown): Record<string, IrInterface> | undefined {
-  const record = asJsonRecord(value)
-  if (!record || !Object.values(record).every(isInterface)) return undefined
-  return record as unknown as Record<string, IrInterface>
-}

package/studio/server/introspect/schema-refs.test.ts

@@ -1,100 +1,55 @@
-import { describe, expect, test } from 'bun:test'
+import { expect, test } from 'bun:test'
 
-import type { IrInterface, StudioSchemaBundle } from '../../shared/types'
+import type { StudioSchemaBundle } from '../../shared/types'
 
 import { schemaRefs } from './schema-refs'
 
-function importedInterface(
-  name: string,
-  origin: string,
-  properties: string[] = [],
-  methods: string[] = [],
-): IrInterface {
-  return {
-    type: 'interface',
-    name,
-    origin,
-    ref: { origin, kind: 'interface', name },
-    properties: Object.fromEntries(properties.map((property) => [property, { type: 'string' }])),
-    methods: Object.fromEntries(
-      methods.map((method) => [
-        method,
-        {
-          name: method,
-          params: {},
-          returns: {},
-          static: false,
-          inheritance: 'default',
-        },
-      ]),
-    ),
+test('enumerates local and exact imported Class anchors without collapsing homonyms', () => {
+  const method = {
+    name: 'rename',
+    params: {},
+    returns: {},
+    static: false,
+    inheritance: 'default' as const,
   }
-}
-
-function bundleWithImports(
-  exact: NonNullable<StudioSchemaBundle['ir']>['importedInterfacesByKey'],
-  legacy: Record<string, IrInterface>,
-): StudioSchemaBundle {
-  return {
+  const bundle = {
     ir: {
+      version: 'v1',
       domain: 'root.example.dev',
-      interfaces: {},
-      classes: {},
+      classes: {
+        Document: {
+          type: 'node',
+          name: 'Document',
+          properties: { title: { type: 'string' } },
+          methods: { rename: method },
+        },
+      },
       functions: {},
-      ...(exact === undefined ? {} : { importedInterfacesByKey: exact }),
-    },
-    importedInterfaces: legacy,
-  } as unknown as StudioSchemaBundle
-}
-
-describe('schema refs for imported interfaces', () => {
-  test('enumerates every exact homonym without selecting a name-keyed winner', () => {
-    const refs = schemaRefs(
-      bundleWithImports(
-        {
-          'directory.example.dev:interface.Named': importedInterface(
-            'Named',
-            'directory.example.dev',
-            ['directoryName'],
-          ),
-          'people.example.dev:interface.Named': importedInterface(
-            'Named',
-            'people.example.dev',
-            [],
-            ['rename'],
-          ),
+      importsByKey: {},
+      importedClassesByKey: {
+        'directory.example.dev:class.Named': {
+          type: 'node',
+          name: 'Named',
+          properties: { directoryName: { type: 'string' } },
+          methods: {},
         },
-        {
-          Named: importedInterface('Named', 'legacy.invalid', ['legacyOnly']),
+        'people.example.dev:class.Named': {
+          type: 'node',
+          name: 'Named',
+          properties: {},
+          methods: { rename: method },
         },
-      ),
-    )
-
-    expect(refs).toContain('interface.directory.example.dev:interface.Named')
-    expect(refs).toContain('interface.directory.example.dev:interface.Named.property.directoryName')
-    expect(refs).toContain('interface.people.example.dev:interface.Named.method.rename')
-    expect(refs).not.toContain('interface.Named')
-    expect(refs).not.toContain('interface.Named.property.legacyOnly')
-  })
-
-  test('uses the name-keyed imported interface only when the exact index is absent', () => {
-    expect(
-      schemaRefs(
-        bundleWithImports(undefined, {
-          Named: importedInterface('Named', 'legacy.example.dev', ['name']),
-        }),
-      ),
-    ).toEqual(['interface.Named', 'interface.Named.property.name'])
+      },
+    },
+  } as unknown as StudioSchemaBundle
 
-    expect(
-      schemaRefs(
-        bundleWithImports(
-          {},
-          {
-            Named: importedInterface('Named', 'legacy.example.dev', ['name']),
-          },
-        ),
-      ),
-    ).toEqual([])
-  })
+  expect(schemaRefs(bundle)).toEqual([
+    'class.Document',
+    'class.Document.property.title',
+    'class.Document.method.rename',
+    'class.directory.example.dev:class.Named',
+    'class.directory.example.dev:class.Named.property.directoryName',
+    'class.people.example.dev:class.Named',
+    'class.people.example.dev:class.Named.method.rename',
+  ])
 })

package/studio/server/introspect/schema-refs.ts

@@ -1,17 +1,6 @@
 import type { StudioSchemaBundle } from '../../shared/types'
 
-/**
- * schema-refs.ts — enumerate every SCHEMA anchor ref a bundle can target, derived
- * from the IR (the authority), NOT from `overlay.sourceSpans`.
- *
- * Source spans are a best-effort ts-morph source-location index: they cover only
- * locally-authored members and only the declaration helpers the parser recognises.
- * Using their keys as the set of "valid" targets falsely orphans real, commentable
- * targets — most notably INHERITED members surfaced in the detail pane's Inherited
- * section (kernel mixins / cross-domain interfaces, e.g. `interface.Named.property.name`),
- * which live in another package and so have no local span. This walks the IR
- * instead, mirroring exactly the refs the detail pane stamps.
- */
+/** Enumerate every schema anchor represented by the admitted render IR. */
 export function schemaRefs(bundle: StudioSchemaBundle): string[] {
   const ir = bundle.ir
   if (!ir) return []
@@ -22,46 +11,22 @@ export function schemaRefs(bundle: StudioSchemaBundle): string[] {
     methods: Record<string, unknown> | undefined,
   ) => {
     refs.add(base)
-    for (const p of Object.keys(properties ?? {})) refs.add(`${base}.property.${p}`)
-    for (const m of Object.keys(methods ?? {})) refs.add(`${base}.method.${m}`)
+    for (const property of Object.keys(properties ?? {})) refs.add(`${base}.property.${property}`)
+    for (const method of Object.keys(methods ?? {})) refs.add(`${base}.method.${method}`)
   }
 
-  for (const [name, iface] of Object.entries(ir.interfaces))
-    addMember(`interface.${name}`, iface.properties, iface.methods)
-
-  for (const [name, cls] of Object.entries(ir.classes)) {
-    const ns = cls.type === 'edge' ? 'edge' : 'class'
-    addMember(`${ns}.${name}`, cls.properties, cls.methods)
-    if (cls.type === 'edge')
-      for (const ep of cls.endpoints ?? [])
-        if (ep.name) refs.add(`edge.${name}.endpoint.${ep.name}`)
-  }
-
-  for (const name of Object.keys(ir.functions ?? {})) refs.add(`function.${name}`)
-
-  // Imported interfaces (kernel mixins + cross-domain) are rendered — and so are
-  // commentable — in the Inherited section, keyed under the `interface.` namespace.
-  // Canonical bundles retain every exact `(origin, kind, name)` identity. Iterate
-  // all of them: a short-name map must never pick one homonym by traversal order.
-  // The name-keyed bundle field remains a legacy-only fallback.
-  if (ir.importedInterfacesByKey !== undefined) {
-    for (const [key, iface] of Object.entries(ir.importedInterfacesByKey)) {
-      const anchor = importedInterfaceAnchor(key)
-      if (anchor) addMember(anchor, iface.properties, iface.methods)
+  for (const [name, definition] of Object.entries(ir.classes)) {
+    const namespace = definition.type === 'edge' ? 'edge' : 'class'
+    addMember(`${namespace}.${name}`, definition.properties, definition.methods)
+    if (definition.type === 'edge') {
+      for (const endpoint of definition.endpoints ?? []) {
+        if (endpoint.name) refs.add(`edge.${name}.endpoint.${endpoint.name}`)
+      }
     }
-  } else {
-    for (const [name, iface] of Object.entries(bundle.importedInterfaces ?? {}))
-      addMember(`interface.${name}`, iface.properties, iface.methods)
   }
-
+  for (const name of Object.keys(ir.functions)) refs.add(`function.${name}`)
+  for (const [key, definition] of Object.entries(ir.importedClassesByKey)) {
+    addMember(`class.${key}`, definition.properties, definition.methods)
+  }
   return [...refs]
 }
-
-function importedInterfaceAnchor(key: string): string | null {
-  const separator = key.lastIndexOf(':')
-  if (separator <= 0) return null
-  const ref = key.slice(separator + 1)
-  if (!ref.startsWith('interface.')) return null
-  const name = ref.slice('interface.'.length)
-  return /^[A-Za-z_$][\w$]*$/.test(name) ? `interface.${key}` : null
-}