@k8ts/instruments 0.1.0

package/src/forward-exports/delayed-exports.ts

@@ -0,0 +1,155 @@
+import { seq } from "doddle"
+import { ProxyOperationError } from "../error"
+import { Origin } from "../graph/origin-node"
+import type { LiveRefable } from "../reference"
+import { ForwardRef } from "../reference"
+
+export type FutureExports<Exps extends LiveRefable> = FutureExports.FutureExports<Exps>
+export namespace FutureExports {
+    export type FutureExports<Exps extends LiveRefable> = _ExportsByKey<Exps>
+    type _ExportsByKey<Exports extends LiveRefable = LiveRefable> = {
+        [E in Exports as `${E["kind"]["name"]}/${E["node"]["key"]["name"]}`]: ForwardRef<E>
+    }
+    export interface Props<
+        Actual extends object = object,
+        Exports extends LiveRefable = LiveRefable
+    > {
+        readonly origin: Origin
+        readonly actual: Actual
+        readonly exports: Iterable<Exports>
+    }
+
+    export function make<T extends LiveRefable, Actual extends object>(
+        props: Props<Actual, T>
+    ): Actual & FutureExports<LiveRefable> {
+        const handler = new Handler(props)
+        return new Proxy(props.actual, handler) as any
+    }
+    class Handler implements ProxyHandler<object> {
+        constructor(private readonly _props: Props) {}
+
+        #createImmutableError(action: string) {
+            return new ProxyOperationError(
+                `Tried to ${action} an the exports constructs of ${this._props.origin}, but it is immutable.`
+            )
+        }
+
+        defineProperty(_: object, property: string | symbol, __: PropertyDescriptor): boolean {
+            throw this.#createImmutableError(`define property ${String(property)} on`)
+        }
+
+        deleteProperty(_: object, property: string | symbol): boolean {
+            throw this.#createImmutableError(`delete property ${String(property)} from`)
+        }
+
+        getPrototypeOf(_: Iterable<LiveRefable>): object | null {
+            return Reflect.getPrototypeOf(this._target)
+        }
+
+        get seq() {
+            return seq(this._props.exports)
+        }
+
+        #isValidReferant(prop: PropertyKey) {
+            return this._props.origin.resourceKinds.tryParse(prop as string) != null
+        }
+
+        get _target() {
+            return this._props.actual
+        }
+
+        get(target: any, property: string | symbol): any {
+            const key = property as string
+            if (Reflect.has(this._target, key)) {
+                const x = Reflect.get(this._target, property)
+                if (typeof x === "function") {
+                    return x.bind(this._target)
+                }
+                return x
+            }
+
+            const refKey = this._props.origin.resourceKinds.tryParse(key)
+            if (refKey == null) {
+                return undefined
+            }
+            const cls = this._props.origin.resourceKinds.getClass(refKey)
+            return ForwardRef.make({
+                class: cls,
+                key: refKey,
+                origin: this._props.origin,
+                namespace: this._props.origin.meta.tryGet("namespace"),
+                resolver: this.seq
+                    .find(exp => exp.node.key.equals(refKey))
+                    .map(x => {
+                        if (x == null) {
+                            throw new ProxyOperationError(
+                                `Failed to resolve forward reference to ${refKey} in ${this._props.origin}.`
+                            )
+                        }
+                        return x
+                    })
+            })
+        }
+
+        has(_: Iterable<LiveRefable>, p: string | symbol): boolean {
+            if (Reflect.has(this._target, p)) {
+                return true
+            }
+            if (!this.#isValidReferant(p)) {
+                return false
+            }
+            return true
+        }
+
+        isExtensible(target: Iterable<LiveRefable>): boolean {
+            return false
+        }
+
+        preventExtensions(target: Iterable<LiveRefable>): boolean {
+            return true
+        }
+
+        ownKeys(target: Iterable<LiveRefable>): ArrayLike<string | symbol> {
+            throw new ProxyOperationError(
+                `Cannot list all keys of a dynamic exports construct for ${this._props.origin}.`
+            )
+        }
+
+        set(
+            target: Iterable<LiveRefable>,
+            p: string | symbol,
+            newValue: any,
+            receiver: any
+        ): boolean {
+            throw this.#createImmutableError(`set property ${String(p)} on`)
+        }
+
+        setPrototypeOf(target: Iterable<LiveRefable>, v: any): boolean {
+            throw this.#createImmutableError(`set prototype of`)
+        }
+
+        _tryTargetDescriptor(p: PropertyKey) {
+            return Object.getOwnPropertyDescriptor(this._target, p)
+        }
+
+        getOwnPropertyDescriptor(
+            target: Iterable<LiveRefable>,
+            p: string | symbol
+        ): PropertyDescriptor | undefined {
+            const desc = this._tryTargetDescriptor(p)
+            if (desc) {
+                return desc
+            }
+            const value = this.get(this._target, p)
+            if (value == null) {
+                return undefined
+            }
+            return {
+                configurable: false,
+                enumerable: true,
+                value,
+                writable: false
+            }
+        }
+    }
+}

package/src/forward-exports/index.ts

@@ -0,0 +1 @@
+export * from "./delayed-exports"

package/src/graph/base-node.ts

@@ -0,0 +1,125 @@
+import { Seq, seq } from "doddle"
+import { hash, Set } from "immutable"
+import { Kind } from "../api-kind"
+import { RefKey } from "../ref-key"
+import { ForwardRef } from "../reference"
+import { NeedsEdge } from "./dependencies"
+
+export interface BaseEntity<Node extends BaseNode<Node>> {
+    readonly node: Node
+
+    readonly shortFqn: string
+    readonly kind: Kind.Identifier
+    readonly name: string
+}
+
+export abstract class BaseNode<
+    Node extends BaseNode<Node, Entity>,
+    Entity extends BaseEntity<Node> = BaseEntity<Node>
+> {
+    abstract readonly key: RefKey
+    get kind() {
+        return this.key.kind
+    }
+
+    abstract readonly kids: Seq<Node>
+    abstract readonly needs: Seq<NeedsEdge<Node>>
+    abstract readonly parent: Node | null
+    protected get _asNode() {
+        return this as any as Node
+    }
+
+    constructor(readonly _entity: Entity) {}
+
+    get shortFqn() {
+        return `${this.kind.name}/${this.name}`
+    }
+    get root(): Node {
+        return (this.ancestors.at(-1).pull() as any) ?? (this as any)
+    }
+    get name() {
+        return this.key.name
+    }
+    get isRoot() {
+        return this.parent === null
+    }
+
+    hashCode() {
+        return hash(this)
+    }
+    equals(other: any) {
+        if (ForwardRef.is(other)) {
+            return other.equals(this)
+        }
+        return this === other
+    }
+
+    readonly ancestors = seq(() => {
+        const seen = Set<Node>()
+        const recurse = function* (from: Node): Iterable<Node> {
+            const parent = from.parent
+            if (parent && !seen.has(parent)) {
+                seen.add(parent)
+                yield parent
+                yield* recurse(parent)
+            }
+        }
+        return seq(recurse.bind(null, this._asNode))
+    }).cache()
+
+    readonly descendants = seq(() => {
+        const self = this
+        let seen = Set<Node>()
+        const recurse = function* (from: Node): Iterable<Node> {
+            for (const kid of from.kids) {
+                if (seen.has(kid)) {
+                    continue
+                }
+                seen = seen.add(kid)
+                yield kid
+                yield* recurse(kid)
+            }
+        }
+        return seq(recurse.bind(null, self._asNode))
+    }).cache()
+
+    isParentOf(other: Node): boolean {
+        if (ForwardRef.is(other)) {
+            return other.isChildOf(this._asNode)
+        }
+        return Set(this.descendants).has(other)
+    }
+
+    isChildOf(other: Node): boolean {
+        if (ForwardRef.is(other)) {
+            return other.isParentOf(this._asNode)
+        }
+        return this.equals(other) || Set(this.ancestors).has(other._asNode)
+    }
+
+    isNeeding(other: Node): boolean {
+        return this.needsGraph.some(x => x.needed.equals(other)).pull()
+    }
+
+    readonly needsGraph = seq(() => {
+        let resources = Set<Node>()
+        const recurseIntoDependency = function* (root: NeedsEdge<Node>): Iterable<NeedsEdge<Node>> {
+            yield root
+            if (resources.has(root.needed)) {
+                return
+            }
+            resources = resources.add(root.needed)
+
+            const ownDeps = root.needed.needs
+            for (const needsEdge of ownDeps) {
+                yield* recurseIntoDependency(needsEdge)
+            }
+        }
+        return seq(recurseIntoDependency.bind(null, new NeedsEdge<Node>("self", this._asNode)))
+            .after(() => {
+                resources = Set()
+            })
+            .cache()
+    })
+}
+export type Formats = "short" | "fqn" | "shortFqn"

package/src/graph/base-origin-entity.ts

@@ -0,0 +1,44 @@
+import { Meta } from "@k8ts/metadata"
+import chalk from "chalk"
+import { doddle, Doddle } from "doddle"
+import { Kind } from "../api-kind"
+import { displayers } from "../displayers"
+import { RefKey } from "../ref-key"
+import { Origin, OriginEntity } from "./origin-node"
+export interface OriginEntityProps {
+    meta?: Meta.Input
+    alias?: string
+}
+@displayers({
+    simple: x => `[${x.shortFqn}]`,
+    pretty(origin) {
+        const kindPart = chalk.greenBright.bold(origin.kind.name)
+        const originName = chalk.cyan(origin.name)
+        return `${kindPart}/${originName}`
+    }
+})
+export abstract class BaseOriginEntity<Props extends OriginEntityProps = OriginEntityProps>
+    implements OriginEntity
+{
+    abstract readonly kind: Kind.Kind
+    #node: Doddle<Origin>
+
+    meta: Meta
+    get alias() {
+        return this.props.alias ?? undefined
+    }
+    get node() {
+        return this.#node.pull()
+    }
+    constructor(
+        readonly name: string,
+        readonly props: Props,
+        parent: Origin | null
+    ) {
+        this.#node = doddle(() => new Origin(parent, this, RefKey.make(this.kind, name)))
+        this.meta = Meta.make(props.meta)
+    }
+    get shortFqn() {
+        return this.node.shortFqn
+    }
+}

package/src/graph/dependencies.ts

@@ -0,0 +1,27 @@
+import chalk from "chalk"
+import { pretty } from "../_string"
+import { displayers } from "../displayers"
+import { BaseNode } from "./base-node"
+import { ResourceEntity } from "./resource-node"
+
+export namespace Dependencies {
+    export type Input = Record<string, ResourceEntity>
+}
+export function dependencies(record: Dependencies.Input) {
+    return Object.entries(record).map(([key, value]) => {
+        return new NeedsEdge(key, value.node)
+    })
+}
+@displayers({
+    simple: s => [s.why, "-->", s.needed],
+    pretty: (dep, format) => {
+        const neededFmt = pretty`${["lowkey", dep.needed]}`
+        return [`${chalk.gray.italic.white(`${dep.why}`)}`, "➜ ", chalk.italic(`${neededFmt}`)]
+    }
+})
+export class NeedsEdge<Node extends BaseNode<Node>> {
+    constructor(
+        readonly why: string,
+        readonly needed: Node
+    ) {}
+}

package/src/graph/index.ts

@@ -0,0 +1,6 @@
+export * from "./base-node"
+export * from "./base-origin-entity"
+export * from "./dependencies"
+export * from "./origin-node"
+export * from "./relations"
+export * from "./resource-node"

package/src/graph/origin-node.ts

@@ -0,0 +1,118 @@
+import { Meta } from "@k8ts/metadata"
+import chalk from "chalk"
+import { doddle, seq, Seq } from "doddle"
+import StackTracey from "stacktracey"
+import { getMarkerForIndex, toSuperScript } from "../_string"
+import { displayers } from "../displayers"
+import { KindMap } from "../kind-map"
+import { RefKey } from "../ref-key"
+import { TraceEmbedder } from "../tracing"
+import { Trace } from "../tracing/trace"
+import { BaseEntity, BaseNode } from "./base-node"
+import { ResourceNode } from "./resource-node"
+@displayers({
+    simple: s => `[${s.shortFqn}]`,
+    prefix: s => {
+        if (s.name === "EXTERNAL") {
+            return "🌐"
+        }
+        return getMarkerForIndex(s.index, s._entity.alias ?? toSuperScript(s.index))
+    },
+    pretty(origin, format) {
+        const kindName = chalk.greenBright.bold(origin.kind.name)
+        const resourceName = chalk.cyan(origin.name)
+        const pref = this.prefix!()
+
+        return `${kindName}:${resourceName} (${pref})`
+    }
+})
+export class Origin extends BaseNode<Origin, OriginEntity> implements Iterable<ResourceNode> {
+    private _kids = [] as Origin[]
+    get kids() {
+        return seq(this._kids)
+    }
+    get meta() {
+        return this._entity.meta
+    }
+    readonly index: number
+    private readonly _getIndex = doddle(() => {
+        let index = 1
+        return () => index++
+    }).pull()
+    constructor(
+        readonly parent: Origin | null,
+        entity: OriginEntity,
+        readonly key: RefKey
+    ) {
+        super(entity)
+        this.index = parent?._getIndex() ?? 0
+        this._kindMap = new KindMap(undefined, parent?._kindMap)
+    }
+    get resourceKinds() {
+        return this._kindMap
+    }
+    private _kindMap: KindMap
+    private _attached = [] as ResourceNode[]
+
+    get needs() {
+        return seq.empty()
+    }
+    [Symbol.iterator]() {
+        return this.resources[Symbol.iterator]()
+    }
+    readonly attachedTree: Seq<ResourceNode> = seq(() => {
+        const self = this
+        const desc = self.descendants.prepend(this).concatMap(function* (x) {
+            yield* self.resources
+            for (const kid of self.kids) {
+                yield* kid.resources
+            }
+        })
+        return desc
+    }).cache()
+
+    get resources() {
+        return this._attached
+    }
+    static registerWithOrigin<F extends Function>(ctor: F) {
+        const prototype = ctor.prototype
+        for (const key of Object.getOwnPropertyNames(prototype)) {
+            const value = prototype[key]
+            if (!key.match(/^[A-Z]/) || typeof value !== "function") {
+                continue
+            }
+            const orig = prototype[key]
+            prototype[key] = {
+                [key](this: any, ...args: any[]) {
+                    const result = orig.apply(this, args) as BaseEntity<any>
+                    if (
+                        typeof result === "object" &&
+                        "node" in result &&
+                        result.node instanceof ResourceNode
+                    ) {
+                        result.node.origin.__attach_resource__([result.node])
+                        TraceEmbedder.set(result.node, new Trace(new StackTracey().slice(1)))
+                    }
+                    return result
+                }
+            }[key]
+        }
+    }
+
+    private __attach_child__(child: Origin) {
+        this._kids.push(child)
+    }
+
+    private __attach_resource__(resources: ResourceNode | Iterable<ResourceNode>) {
+        resources = Symbol.iterator in resources ? resources : [resources]
+        for (const resource of resources) {
+            this._attached.push(resource)
+        }
+    }
+}
+export interface OriginEntity extends BaseEntity<Origin> {
+    alias?: string
+    meta: Meta
+}
+
+export const auto_register = Origin.registerWithOrigin

package/src/graph/relations.ts

@@ -0,0 +1,62 @@
+import { Embedder } from "../_embedder/base"
+import { Dependencies, dependencies, NeedsEdge } from "./dependencies"
+import { ResourceEntity, ResourceNode } from "./resource-node"
+
+export namespace Relations {
+    export interface Out {
+        needs: () => Iterable<NeedsEdge<ResourceNode>>
+        parent: () => ResourceNode | null
+        kids: () => ResourceNode[]
+    }
+
+    export type In<Target extends ResourceEntity = ResourceEntity> = {
+        needs: (self: Target) => Dependencies.Input
+        parent: (self: Target) => ResourceEntity | null
+        kids: (self: Target) => ResourceEntity[]
+    } & {
+        [key: string]: (self: Target, ...args: any[]) => any
+    }
+}
+
+class RelationsService {
+    private _system = new Embedder<ResourceEntity, Relations.In>("relations")
+
+    implement(
+        ctor: abstract new (...args: any[]) => ResourceEntity,
+        input: Relations.In<ResourceEntity>
+    ) {
+        const existing = this._system.tryGet(ctor.prototype)
+        if (existing) {
+            input = Object.assign({}, existing, input)
+        }
+        this._system.set(ctor.prototype, input)
+    }
+
+    get(target: ResourceEntity): Relations.Out {
+        const input = this._system.get(target)
+        const o = {
+            kids: () => input.kids?.call(o, target).map(x => x.node) ?? [],
+            parent: () => input.parent?.call(o, target)?.node ?? null,
+            needs: () => dependencies(input.needs?.call(o, target) ?? {})
+        }
+        return o
+    }
+
+    get decorator() {
+        return <
+            Target extends abstract new (...args: any[]) => ResourceEntity,
+            Impl extends Partial<Relations.In<InstanceType<Target>>> | "none"
+        >(
+            input: Impl
+        ) => {
+            return (ctor: Target) => {
+                this.implement(ctor, input === "none" ? {} : (input as any))
+                return ctor
+            }
+        }
+    }
+}
+export const Relations = new RelationsService()
+export const relations = Relations.decorator
+
+// writing the decorator itself

package/src/graph/resource-node.ts

@@ -0,0 +1,104 @@
+import { MutableMeta } from "@k8ts/metadata"
+import chalk from "chalk"
+import { seq } from "doddle"
+import { displayers } from "../displayers"
+import { RefKey } from "../ref-key"
+import { TraceEmbedder } from "../tracing"
+import { BaseEntity, BaseNode, Formats } from "./base-node"
+import { Origin } from "./origin-node"
+import { Relations } from "./relations"
+
+@displayers({
+    simple: s => `[${s.shortFqn}]`,
+    pretty(resource, format) {
+        format ??= "global"
+
+        let kindName = chalk.greenBright(resource.kind.name)
+        if (format !== "lowkey") {
+            kindName = chalk.bold(kindName)
+        }
+        const resourceName = chalk.blueBright(resource.name)
+        const mainPart = `${kindName}/${resourceName}`
+        let originPart = ` (${displayers.get(resource.origin).prefix!()})`
+        let text = ""
+
+        text += mainPart
+        if (format !== "local") {
+            text += originPart
+        }
+        return text
+    }
+})
+export class ResourceNode extends BaseNode<ResourceNode, ResourceEntity> {
+    get needs() {
+        return seq(this._relations.needs)
+    }
+
+    get trace() {
+        return TraceEmbedder.get(this)
+    }
+
+    get isExported() {
+        return this.meta?.tryGet("#k8ts.org/is-exported") ?? false
+    }
+
+    get meta() {
+        return "meta" in this._entity ? (this._entity.meta as MutableMeta) : undefined
+    }
+
+    get isExternal() {
+        return this.origins.some(x => x.name === "EXTERNAL").pull()
+    }
+
+    get origins() {
+        const self = this
+        return seq(function* () {
+            let current: Origin | null = self.origin
+            while (current) {
+                yield current
+                current = current.parent
+            }
+        })
+    }
+
+    get kids() {
+        return seq(this._relations.kids)
+    }
+
+    get parent() {
+        return this._relations.parent()
+    }
+
+    override get shortFqn() {
+        return `${this.origin.name}:${this.key}`
+    }
+
+    get localName() {
+        return this.key.string
+    }
+
+    format(format: Formats) {
+        switch (format) {
+            case "short":
+                return this.name
+            case "fqn":
+                return this.key.string
+            case "shortFqn":
+                return this.key.name
+        }
+    }
+    private get _relations() {
+        return Relations.get(this._entity)
+    }
+    constructor(
+        readonly origin: Origin,
+        readonly entity: ResourceEntity,
+        readonly key: RefKey
+    ) {
+        super(entity)
+    }
+}
+export interface MetadataEntity extends BaseEntity<ResourceNode> {
+    meta: MutableMeta
+}
+export interface ResourceEntity extends BaseEntity<ResourceNode> {}