@k8ts/instruments 0.11.3 → 0.12.0

package/src/core/graph/resource/ident/ident.ts

@@ -0,0 +1,140 @@
+import type { DummyResource } from "../dummy"
+import type { Gvk, Gvk_Base } from "../gvk"
+import type { ResourceRef, ResourceRef_Constructor_For } from "../ref"
+import type { ResourceIdent_sFormat } from "./parsing"
+
+export const separator = "/"
+
+/** Parsed representation of a reference key string. */
+export interface ResourceIdent_Parsed {
+    /** The Kubernetes resource kind */
+    kind: string
+    /** The resource name */
+    name: string
+}
+
+type nsKind = Gvk<"v1/Namespace">
+
+/**
+ * Options for creating a RefKey instance.
+ *
+ * @template Name - The resource name type
+ */
+export interface ResourceIdent_Options<Name extends string = string> {
+    /** The resource name */
+    name: Name
+    /** Optional namespace for namespaced resources. Can be a RefKey, string, or Ref2 */
+    namespace?: ResourceIdent<nsKind> | string | ResourceRef<nsKind>
+}
+
+export interface ResourceIdent_Like {
+    readonly kind: Gvk_Base
+    readonly name: string
+    readonly namespace: string | undefined
+}
+
+/**
+ * A unique identifier for a k8s resource consisting of a Kind, name, and namespace. Used by
+ * resources to reference other resources. Serves as the basis for the {@link DummyResource} resource
+ * type.
+ *
+ * Important: This class is ambiguous because it can represent keys for namespaced resources but
+ * ignore the namespace. Needs some kind of refactor.
+ */
+export class ResourceIdent<K extends Gvk_Base = Gvk_Base, Name extends string = string> {
+    /** The resource name */
+    name: string
+    /** The optional namespace for namespaced resources */
+    namespace: string | undefined
+
+    /**
+     * Creates a new RefKey instance.
+     *
+     * @param kind - The Kubernetes resource kind
+     * @param options - Configuration options including name and optional namespace
+     */
+    constructor(
+        readonly kind: K,
+        options: ResourceIdent_Options<Name>
+    ) {
+        this.name = options.name
+        if (typeof options.namespace === "string") {
+            this.namespace = options.namespace
+        } else if (options.namespace && "ident" in options.namespace) {
+            this.namespace = options.namespace.ident.name
+        } else if (options.namespace) {
+            this.namespace = options.namespace.name
+        } else {
+            this.namespace = undefined
+        }
+    }
+
+    rename<NewName extends string>(newName: NewName) {
+        return new ResourceIdent<K, NewName>(this.kind, {
+            name: newName,
+            namespace: this.namespace
+        })
+    }
+
+    /**
+     * Returns the string representation of this reference key. Format: "Kind/Namespace/Name" or
+     * "Kind/Name" for cluster-scoped resources.
+     */
+    get string(): ResourceIdent_sFormat<K["value"], Name> {
+        return [this.kind.value, this.namespace, this.name]
+            .filter(x => !!x)
+            .join(separator) as ResourceIdent_sFormat<K["value"], Name>
+    }
+
+    /**
+     * Checks if this RefKey is equal to another RefKey by comparing kind, name, and namespace.
+     *
+     * @param other - The RefKey to compare with
+     * @returns True if both RefKeys have the same kind, name, and namespace
+     */
+    equals(other: ResourceIdent): boolean {
+        if (other == null) {
+            return false
+        }
+        if (typeof other !== "object") {
+            return false
+        }
+        return (
+            this.kind.equals(other.kind) &&
+            this.name === other.name &&
+            this.namespace === other.namespace
+        )
+    }
+
+    /**
+     * Returns the string representation of this reference key.
+     *
+     * @returns The reference key in string format
+     */
+    toString() {
+        return this.string
+    }
+
+    /**
+     * Creates an External reference to this resource.
+     *
+     * @template P - The external properties type
+     * @param options - Optional external properties configuration
+     * @returns An External instance with the specified features
+     */
+    DummyResource(): DummyResource<K> {
+        const DummyResource: ResourceRef_Constructor_For<DummyResource<K>> =
+            require("../dummy").DummyResource
+        const self = this
+
+        const className = `${this.kind.value}DummyResource`
+        const cls = {
+            [className]: class extends DummyResource {
+                get kind() {
+                    return self.kind
+                }
+            }
+        }[className]
+        return new cls(this.name, this.namespace, {}) as DummyResource<K>
+    }
+}

package/src/core/graph/resource/ident/index.ts

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

package/src/core/graph/resource/ident/parsing.ts

@@ -0,0 +1,36 @@
+import { type ResourceIdent_Parsed, separator } from "./ident"
+
+/**
+ * Attempts to parse a reference key string into its kind and name components. Returns undefined if
+ * the string cannot be parsed.
+ *
+ * @param ref - The reference key string to parse (format: "Kind/Name")
+ * @returns The parsed reference key, or undefined if parsing fails
+ */
+
+export function tryParse(ref: string): ResourceIdent_Parsed | undefined {
+    if (typeof ref !== "string") {
+        return undefined
+    }
+    if (ref == null) {
+        return undefined
+    }
+    if (typeof ref === "object") {
+        return undefined
+    }
+    const [kind, name] = ref.split(separator).map(s => s.trim())
+    if (!kind || !name) {
+        return undefined
+    }
+    return {
+        kind,
+        name
+    }
+} /**
+ * String format template for reference keys.
+ *
+ * @template Kind - The Kubernetes resource kind
+ * @template Name - The resource name
+ */
+
+export type ResourceIdent_sFormat<Kind extends string, Name extends string> = `${Kind}/${Name}`

package/src/core/graph/resource/index.ts

@@ -1,9 +1,10 @@
-export * from "./api-kind"
-export * from "./child"
-export * from "./entity"
-export * from "./external"
-export * from "./field"
-export * from "./node"
-export * from "./ref-key"
-export * from "./reference"
-export * from "./top"
+export * from "./dummy"
+export * from "./forward"
+export * from "./gvk"
+export * from "./ident"
+export * from "./k8s-resource"
+export * from "./part"
+export * from "./props"
+export * from "./ref"
+export * from "./resource"
+export * from "./vertex"

package/src/core/graph/resource/k8s-resource.ts

@@ -0,0 +1,98 @@
+import { Metadata } from "@k8ts/metadata"
+import { doddle } from "doddle"
+import { omit } from "lodash"
+import StackTracey from "stacktracey"
+import {
+    type K8tsManifest,
+    type K8tsManifest_GVK,
+    type K8tsManifest_Metadata
+} from "../../manifest"
+import { Trace_Source, TraceEmbedder } from "../../tracing"
+import { K8tsGraphError } from "../error"
+import { OriginContextTracker } from "../origin/tracker"
+import type {
+    ResourceTop_CreationOptions,
+    ResourceTop_CreationOptions_Input
+} from "./creation-options"
+import type { Resource_Props_Top } from "./props"
+import { ResourceEntity } from "./resource"
+let globalEntityId = 1
+export abstract class K8sResource<
+    Name extends string = string,
+    Props extends Resource_Props_Top = Resource_Props_Top
+> extends ResourceEntity<Name, Props> {
+    readonly metadata: Metadata
+    protected readonly _creation: ResourceTop_CreationOptions
+    protected readonly __entity_id__ = (() => {
+        return `${this.kind.value}_${this.ident.name}_${(globalEntityId++).toString(16)}`
+    })()
+    constructor(name: Name, props: Props, creationOptions?: ResourceTop_CreationOptions_Input) {
+        const ownOrigin = creationOptions?.origins?.own ?? OriginContextTracker.current
+        if (!ownOrigin) {
+            throw new K8tsGraphError(`Resource ${name} must be created within an Origin context`)
+        }
+        super(name, ownOrigin.namespace, props)
+        this._creation = {
+            origins: {
+                own: ownOrigin,
+                subscope: creationOptions?.origins?.subscope ?? ownOrigin
+            }
+        }
+        this.metadata = new Metadata(props.$metadata)
+            .overwrite(creationOptions?.metadata)
+            .overwrite({
+                "^k8ts.org/entity-id": this.__entity_id__
+            })
+
+        this._creation.origins.own["__attach_resource__"](this)
+        TraceEmbedder.add(this, new Trace_Source(new StackTracey().slice(2)))
+    }
+
+    protected __scope__<F extends (...args: any[]) => any>(fn: F): F {
+        const bound = this._creation.origins.subscope["__bind__"](fn)
+        return bound
+    }
+
+    protected get __origin__() {
+        return this._creation.origins.own
+    }
+
+    protected get __metadata__(): K8tsManifest_Metadata {
+        const self = this
+        return {
+            name: self.ident.name,
+            namespace: self.ident.namespace,
+            labels: self.metadata.labels,
+            annotations: self.metadata.annotations
+        }
+    }
+
+    protected get __gvk__(): K8tsManifest_GVK {
+        return {
+            apiVersion: this.kind.parent!.url,
+            kind: this.kind.value
+        }
+    }
+
+    protected abstract __body__(): object
+
+    protected __manifest__(): K8tsManifest | Promise<K8tsManifest> {
+        return doddle(async () => {
+            const body = await this.__body__()
+            // We want the body to be after the metadata and the gvk
+            // But we don't want it to override anything if it has extra keys
+            const trimmedBody = omit(body, ["metadata", "apiVersion", "kind"])
+            const a = {
+                ...this.__gvk__,
+                metadata: this.__metadata__,
+                ...trimmedBody
+            }
+            this.__origin__["__emit__"]("resource/manifested", {
+                origin: this.__origin__,
+                manifest: a,
+                resource: this
+            })
+            return a
+        }).pull()
+    }
+}

package/src/core/graph/resource/part.ts

@@ -0,0 +1,26 @@
+import type { Gvk_Base } from "./gvk"
+import type { Resource_Props } from "./props"
+import { ResourceEntity } from "./resource"
+
+export abstract class ResourcePart<
+    Props extends Resource_Props = Resource_Props
+> extends ResourceEntity<string, Props> {
+    abstract get kind(): Gvk_Base
+    #parent: ResourceEntity
+    constructor(parent: ResourceEntity, name: string, props: Props) {
+        const parentNs = parent.ident.namespace
+
+        super(name, parentNs, props)
+        this.#parent = parent
+    }
+
+    protected get __parent__(): ResourceEntity {
+        return this.#parent
+    }
+
+    protected abstract __submanifest__(): object
+
+    protected get __origin__() {
+        return this.__parent__["__origin__"]
+    }
+}

package/src/core/graph/resource/props.ts

@@ -0,0 +1,11 @@
+import type { Metadata_Input } from "@k8ts/metadata"
+
+export interface Resource_Props<ResultType extends object = object> {
+    $$manifest?: ResultType
+    $noEmit?: boolean
+}
+
+export interface Resource_Props_Top<ResultType extends object = object>
+    extends Resource_Props<ResultType> {
+    $metadata?: Metadata_Input
+}

package/src/core/graph/resource/ref.ts

@@ -0,0 +1,33 @@
+import type { EntityRef } from "../entity"
+import type { GVK_Like } from "./gvk"
+import type { ResourceVertex } from "./vertex"
+
+export type ResourceRef_Constructor_For<R extends ResourceRef = ResourceRef> = {
+    prototype: R
+} & (abstract new (...args: any[]) => R)
+export type ResourceRef_Constructor<K extends GVK_Like = GVK_Like> = ResourceRef_Constructor_For<
+    ResourceRef<K>
+>
+export type ResourceRef<
+    _Kind extends GVK_Like = GVK_Like,
+    Name extends string = string
+> = EntityRef & {
+    noEmit: boolean
+    kind: _Kind
+    ident: {
+        name: Name
+        namespace?: string
+    }
+    is<Type>(cls: abstract new (...args: any[]) => Type): this is Type
+    is<_Kind extends GVK_Like>(kind: _Kind): this is ResourceRef<_Kind>
+    equals(other: any): boolean
+    __vertex__: ResourceVertex
+}
+
+export type ResourceRef_HasKeys<X extends ResourceRef, Else = never> = [X] extends [
+    {
+        keys: (infer K extends string)[]
+    }
+]
+    ? K
+    : Else

package/src/core/graph/resource/resource.ts

@@ -0,0 +1,78 @@
+import { getNiceClassName } from "what-are-you"
+import { ResourceIdent } from "."
+
+import { display } from "../../../utils"
+import { getDeepPropertyDescriptor } from "../../../utils/util"
+import { EntityBase } from "../entity"
+import { K8tsGraphError } from "../error"
+import type { OriginEntity } from "../origin"
+import { ForwardRef } from "./forward"
+import type { Gvk_Base } from "./gvk"
+import { Resource_Props } from "./props"
+import { type ResourceRef } from "./ref"
+import { ResourceVertex } from "./vertex"
+@display({
+    simple: s => s.__vertex__,
+    pretty: s => s.__vertex__
+})
+export abstract class ResourceEntity<
+        Name extends string = string,
+        Props extends Resource_Props = Resource_Props
+    >
+    extends EntityBase<ResourceVertex, ResourceEntity, ResourceRef>
+    implements ResourceRef
+{
+    abstract get kind(): Gvk_Base
+    ident: ResourceIdent<Gvk_Base, Name>
+    readonly props: Props
+    constructor(name: Name, namespace: string | undefined, props: Props) {
+        super()
+        this.props = props
+
+        const desc = getDeepPropertyDescriptor(this, "kind")
+        if (!desc || !desc.get) {
+            throw new K8tsGraphError(
+                `ResourceEntity subclass ${getNiceClassName(this)} must implement the 'kind' property as a getter, but it's missing or not a getter.`
+            )
+        }
+        const kind = (this as any).kind as Gvk_Base
+        this.ident = new ResourceIdent(kind, {
+            name: name,
+            namespace: namespace
+        })
+    }
+
+    get noEmit() {
+        return this.props.$noEmit === true
+    }
+    set noEmit(value: boolean) {
+        this.props.$noEmit = value
+    }
+    is<K extends this["kind"]>(kind: K): this is { kind: K }
+    is<Inst extends ResourceRef = ResourceRef>(
+        cls: abstract new (...args: any[]) => Inst
+    ): this is Inst
+    is(cls: any): boolean {
+        if (typeof cls === "function") {
+            return this instanceof cls
+        }
+        return this.kind.equals(cls)
+    }
+    equals(other: any): boolean {
+        if (!other) {
+            return false
+        }
+        if (ForwardRef.is(other)) {
+            return other.equals(this)
+        }
+        if (other instanceof ResourceEntity) {
+            return Object.is(this, other)
+        }
+        return false
+    }
+
+    protected abstract get __origin__(): OriginEntity
+    get __vertex__(): ResourceVertex {
+        return new ResourceVertex(this.__origin__.__vertex__, this)
+    }
+}

package/src/core/graph/resource/vertex.ts

@@ -0,0 +1,134 @@
+import { Metadata } from "@k8ts/metadata"
+import chalk from "chalk"
+import { seq } from "doddle"
+import { Display, display } from "../../../utils/mixin/display"
+import { TraceEmbedder } from "../../tracing"
+import { Formats } from "../entity"
+import { K8tsGraphError } from "../error"
+import { OriginVertex } from "../origin/vertex"
+import { Vertex } from "../vertex"
+import type { Gvk } from "./gvk"
+import { ResourceIdent } from "./ident"
+import type { ResourceRef_Constructor_For } from "./ref"
+import type { ResourceEntity } from "./resource"
+
+@display({
+    simple: s => `[${s.shortFqn}]`,
+    pretty(resource, format) {
+        format ??= "global"
+
+        let kindName = chalk.greenBright(resource.kind.value)
+        if (format !== "lowkey") {
+            kindName = chalk.bold(kindName)
+        }
+        const parts = [kindName]
+        if (resource.namespace) {
+            parts.push(chalk.yellowBright(resource.namespace))
+        }
+        parts.push(chalk.blueBright(resource.name))
+        const mainPart = parts.join("/")
+        let originPart = `${Display.get(resource.origin).prefix!()}`
+        let text = ""
+
+        text += mainPart
+        if (format !== "local") {
+            text = `${originPart}${text}`
+        }
+        if (format === "source") {
+            text += ` (at ${resource.trace.format()})`
+        }
+        return text
+    }
+})
+export class ResourceVertex extends Vertex<ResourceVertex, ResourceEntity> {
+    get fullFqn() {
+        return [this.kind.dns, this.namespace, this.name].filter(Boolean).join("/")
+    }
+    get ident(): ResourceIdent {
+        return this.entity.ident
+    }
+    get kind() {
+        return this.entity.kind as Gvk
+    }
+    get hasInheritedNoEmit() {
+        return (
+            this.noEmit ||
+            this.origin.hasInheritedNoEmit ||
+            this.ancestors.some(x => x.noEmit).pull()
+        )
+    }
+    get namespace() {
+        return this.ident.namespace
+    }
+
+    get trace() {
+        return TraceEmbedder.get(this.entity)
+    }
+
+    get isExported() {
+        return this.metadata?.tryGet("#k8ts.org/exported") ?? false
+    }
+
+    get metadata() {
+        return "metadata" in this.entity ? (this.entity.metadata as Metadata) : undefined
+    }
+
+    get noEmit(): boolean {
+        return "noEmit" in this.entity ? (this.entity.noEmit as boolean) : false
+    }
+    set noEmit(v: boolean) {
+        this.entity.noEmit = v
+    }
+
+    when<EntityTypeCtor extends ResourceRef_Constructor_For>(
+        type: EntityTypeCtor,
+        fn: (entity: InstanceType<EntityTypeCtor>) => void
+    ) {
+        const entity = this.entity as InstanceType<EntityTypeCtor>
+        if (entity instanceof type) {
+            fn(entity)
+        }
+    }
+
+    as<EntityType extends ResourceEntity>(type: ResourceRef_Constructor_For<EntityType>) {
+        const entity = this.entity as EntityType
+        if (entity instanceof type) {
+            return entity
+        }
+        throw new K8tsGraphError(
+            `This node is for an entity of type ${entity.constructor.name}, not ${type.name}`
+        )
+    }
+
+    get origins() {
+        const self = this
+        return seq(function* () {
+            let current: OriginVertex | null = self.origin
+            while (current) {
+                yield current
+                current = current.parent
+            }
+        })
+    }
+
+    get shortFqn() {
+        return `${this.origin.name}:${this.ident}`
+    }
+
+    get localName() {
+        return this.ident.string
+    }
+
+    format(format: Formats) {
+        return Display.get(this).pretty(format)
+    }
+    get name() {
+        return this.entity.ident.name
+    }
+    constructor(
+        readonly origin: OriginVertex,
+        readonly entity: ResourceEntity
+    ) {
+        super(entity)
+    }
+}