@intentius/behold 0.31.0 → 0.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +64 -2787
- package/README.md +78 -13
- package/THIRD_PARTY.md +6 -5
- package/dist/chant-KLLNQOCK.js +117 -0
- package/dist/choudoufu-chant-read-MJ6DK23L.js +36 -0
- package/dist/chunk-26K6QLVB.js +157 -0
- package/dist/chunk-4IETG5U7.js +267 -0
- package/dist/chunk-7DQDWJI5.js +46 -0
- package/dist/chunk-ANJ33KX4.js +78 -0
- package/dist/chunk-C7OMVDI5.js +124 -0
- package/dist/chunk-GG3SLEYM.js +30297 -0
- package/dist/chunk-GMCRBXPQ.js +15578 -0
- package/dist/chunk-IMX6PXXA.js +1019 -0
- package/dist/chunk-JHLNY324.js +232 -0
- package/dist/chunk-JJPU2DXX.js +54 -0
- package/dist/chunk-KUHU6T4P.js +2820 -0
- package/dist/chunk-OY4EF7ZO.js +5651 -0
- package/dist/chunk-XKWCGNT2.js +8139 -0
- package/dist/chunk-YO233FHU.js +136 -0
- package/dist/cli.js +491 -72879
- package/dist/config-XKQQ4ORG.js +69 -0
- package/dist/config-run-4IMSAYPX.js +418 -0
- package/dist/declaration-5NE7H5UD.js +6867 -0
- package/dist/index.js +99 -0
- package/dist/main-4PGA5RJS.js +2509 -0
- package/dist/mcp-W2CHVEPI.js +753 -0
- package/dist/object-store-H77QSRIZ.js +1033 -0
- package/dist/src-54PT4UC5.js +1189 -0
- package/dist/tree-W23HE2EZ.js +17 -0
- package/example-choudoufu-estate/chant.workspace.json +1 -1
- package/example-terraform-estate/README.md +2 -2
- package/example-terraform-estate/chant.workspace.json +1 -1
- package/example-three-cloud/chant.workspace.json +2 -2
- package/example-three-cloud/package-lock.json +32 -515
- package/example-three-cloud/package.json +5 -5
- package/package.json +26 -13
- package/schemas/graph/v1/graph.schema.json +140 -0
- package/web/app.js +9 -4
- package/web/boot-motion.js +6 -0
- package/web/cut-around.d.ts +30 -0
- package/web/cut-around.js +138 -0
- package/web/edge-weight.d.ts +8 -2
- package/web/edge-weight.js +34 -4
- package/web/edge-weight.test.js +36 -1
- package/web/index.html +8 -20
- package/web/neighbourhood.js +105 -0
- package/web/neighbourhood.test.js +131 -0
- package/web/outside-refs.js +515 -0
- package/web/outside-refs.test.js +249 -0
- package/web/theme-paint.js +14 -0
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
// The neighbourhood of one Kubernetes object, cut from a graph the page
|
|
2
|
+
// already holds (#1081). A cluster UI (Headlamp, the Argo CD UI) shows one
|
|
3
|
+
// object; this answers "it, its neighbours in the cluster, and what it reaches
|
|
4
|
+
// outside" with no server to ask.
|
|
5
|
+
//
|
|
6
|
+
// Imports only ./cut-around.js, which imports nothing: no `node:*`, nothing
|
|
7
|
+
// from src/. `esbuild web/neighbourhood.js --bundle --platform=browser` takes
|
|
8
|
+
// it whole, and web/neighbourhood.test.js checks the module graph.
|
|
9
|
+
import { cutAround } from "./cut-around.js";
|
|
10
|
+
|
|
11
|
+
export { cutAround };
|
|
12
|
+
|
|
13
|
+
/** API group of a `K8s::<Segment>::` IR kind, for the segments that name one group. A node carrying `attrs.apiVersion` never reaches this table. */
|
|
14
|
+
const GROUP_OF_SEGMENT = {
|
|
15
|
+
Core: "",
|
|
16
|
+
Apps: "apps",
|
|
17
|
+
Batch: "batch",
|
|
18
|
+
Rbac: "rbac.authorization.k8s.io",
|
|
19
|
+
Networking: "networking.k8s.io",
|
|
20
|
+
Storage: "storage.k8s.io",
|
|
21
|
+
Policy: "policy",
|
|
22
|
+
Autoscaling: "autoscaling",
|
|
23
|
+
Apiextensions: "apiextensions.k8s.io",
|
|
24
|
+
Argo: "argoproj.io",
|
|
25
|
+
Monitoring: "monitoring.coreos.com",
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
/** Kinds with no namespace, so an identity without one still matches. */
|
|
29
|
+
const CLUSTER_SCOPED = new Set([
|
|
30
|
+
"Namespace",
|
|
31
|
+
"Node",
|
|
32
|
+
"PersistentVolume",
|
|
33
|
+
"StorageClass",
|
|
34
|
+
"ClusterRole",
|
|
35
|
+
"ClusterRoleBinding",
|
|
36
|
+
"CustomResourceDefinition",
|
|
37
|
+
"PriorityClass",
|
|
38
|
+
"IngressClass",
|
|
39
|
+
"RuntimeClass",
|
|
40
|
+
"ValidatingWebhookConfiguration",
|
|
41
|
+
"MutatingWebhookConfiguration",
|
|
42
|
+
"APIService",
|
|
43
|
+
"AppProject",
|
|
44
|
+
]);
|
|
45
|
+
|
|
46
|
+
/** Whether a node is a Kubernetes object (the lexicon chant tags it with, else its kind). */
|
|
47
|
+
export function isK8sNode(node) {
|
|
48
|
+
return !!node && (node.lexicon === "k8s" || (typeof node.kind === "string" && node.kind.startsWith("K8s::")));
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
|
|
52
|
+
|
|
53
|
+
/** `{ group, kind, namespace, name }` of a Kubernetes node, as far as it declares them. */
|
|
54
|
+
export function identityOf(node) {
|
|
55
|
+
const attrs = (node && node.attrs) || {};
|
|
56
|
+
const meta = attrs.metadata && typeof attrs.metadata === "object" ? attrs.metadata : {};
|
|
57
|
+
const parts = typeof node.kind === "string" ? node.kind.split("::") : [];
|
|
58
|
+
const kind = str(attrs.kind) || (parts[0] === "K8s" ? parts[parts.length - 1] : undefined);
|
|
59
|
+
let group;
|
|
60
|
+
const apiVersion = str(attrs.apiVersion);
|
|
61
|
+
if (apiVersion) group = apiVersion.includes("/") ? apiVersion.slice(0, apiVersion.indexOf("/")) : "";
|
|
62
|
+
else if (parts[0] === "K8s" && parts.length === 3 && parts[1] in GROUP_OF_SEGMENT) group = GROUP_OF_SEGMENT[parts[1]];
|
|
63
|
+
return { group, kind, namespace: str(meta.namespace), name: str(meta.name) };
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* The node for `{ group, kind, namespace, name }`, or null. `group` is the API
|
|
68
|
+
* group ("" or omitted for core, "apps" for Deployment). An object with no
|
|
69
|
+
* namespace joins `default`, as the apiserver defaults it (src/k8s-edges.ts),
|
|
70
|
+
* and a cluster-scoped kind matches without one. A group left out matches any
|
|
71
|
+
* group; one given never matches a node whose group is known and different.
|
|
72
|
+
*/
|
|
73
|
+
export function findK8sNode(graph, { group, kind, namespace, name } = {}) {
|
|
74
|
+
if (!kind || !name) return null;
|
|
75
|
+
const wantNamespace = CLUSTER_SCOPED.has(kind) ? undefined : namespace || "default";
|
|
76
|
+
for (const node of (graph && graph.nodes) || []) {
|
|
77
|
+
if (!isK8sNode(node)) continue;
|
|
78
|
+
const id = identityOf(node);
|
|
79
|
+
if (id.kind !== kind || id.name !== name) continue;
|
|
80
|
+
if (group !== undefined && id.group !== undefined && id.group !== group) continue;
|
|
81
|
+
if (wantNamespace !== undefined && (id.namespace || "default") !== wantNamespace) continue;
|
|
82
|
+
return node;
|
|
83
|
+
}
|
|
84
|
+
return null;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** "apps/Deployment default/web", the way a person names an object. */
|
|
88
|
+
export function describeIdentity({ group, kind, namespace, name } = {}) {
|
|
89
|
+
const k = group ? `${group}/${kind}` : `${kind}`;
|
|
90
|
+
return namespace ? `${k} ${namespace}/${name}` : `${k} ${name}`;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The cut around the object named by `identity`. Walks `depth` hops (default
|
|
95
|
+
* 1) between Kubernetes objects and `outside` hops (default 2) past the last
|
|
96
|
+
* one. An identity the graph does not hold returns no nodes and a `reason`
|
|
97
|
+
* naming it.
|
|
98
|
+
*/
|
|
99
|
+
export function neighbourhoodOf(graph, identity, opts = {}) {
|
|
100
|
+
const start = findK8sNode(graph, identity);
|
|
101
|
+
if (!start) {
|
|
102
|
+
return { nodes: [], edges: [], groups: {}, seeds: [], reason: `the graph holds no Kubernetes object ${describeIdentity(identity)}` };
|
|
103
|
+
}
|
|
104
|
+
return cutAround(graph, [start.id], { depth: 1, outside: 2, ...opts, inside: isK8sNode });
|
|
105
|
+
}
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
3
|
+
import { dirname, join, resolve } from "node:path";
|
|
4
|
+
import { cutAround, findK8sNode, identityOf, neighbourhoodOf } from "./neighbourhood.js";
|
|
5
|
+
|
|
6
|
+
const k8s = (id, kind, apiVersion, name, namespace) => ({
|
|
7
|
+
id,
|
|
8
|
+
kind,
|
|
9
|
+
lexicon: "k8s",
|
|
10
|
+
attrs: { apiVersion, kind: kind.split("::").pop(), metadata: { name, ...(namespace ? { namespace } : {}) } },
|
|
11
|
+
});
|
|
12
|
+
const tf = (id, kind) => ({ id, kind, lexicon: "terraform", attrs: {} });
|
|
13
|
+
const edge = (from, to) => ({ from, to });
|
|
14
|
+
|
|
15
|
+
/** Deployment web -> ServiceAccount runner -> google_service_account -> project, plus a second Deployment on the same account. */
|
|
16
|
+
function fixture() {
|
|
17
|
+
return {
|
|
18
|
+
nodes: [
|
|
19
|
+
k8s("web", "K8s::Apps::Deployment", "apps/v1", "web"),
|
|
20
|
+
k8s("runner", "K8s::Core::ServiceAccount", "v1", "runner"),
|
|
21
|
+
k8s("other", "K8s::Apps::Deployment", "apps/v1", "other"),
|
|
22
|
+
tf("gsa", "google_service_account"),
|
|
23
|
+
tf("project", "google_project"),
|
|
24
|
+
tf("bucket", "google_storage_bucket"),
|
|
25
|
+
],
|
|
26
|
+
edges: [edge("web", "runner"), edge("other", "runner"), edge("runner", "gsa"), edge("gsa", "project"), edge("bucket", "project")],
|
|
27
|
+
groups: { byStack: { cluster: ["web", "runner", "other"], cloud: ["gsa", "project", "bucket"] } },
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
const ids = (cut) => cut.nodes.map((n) => n.id).sort();
|
|
31
|
+
|
|
32
|
+
describe("neighbourhoodOf", () => {
|
|
33
|
+
it("keeps the Deployment, the account, the cloud identity and the project at outside 2", () => {
|
|
34
|
+
const cut = neighbourhoodOf(fixture(), { group: "apps", kind: "Deployment", name: "web" }, { depth: 1, outside: 2 });
|
|
35
|
+
expect(ids(cut)).toEqual(["gsa", "project", "runner", "web"]);
|
|
36
|
+
expect(cut.edges).toHaveLength(3);
|
|
37
|
+
expect(cut.seeds).toEqual(["web"]);
|
|
38
|
+
expect(cut.groups).toEqual({ byStack: { cluster: ["web", "runner"], cloud: ["gsa", "project"] } });
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
it("keeps the Deployment and the account only at outside 0", () => {
|
|
42
|
+
const cut = neighbourhoodOf(fixture(), { group: "apps", kind: "Deployment", name: "web" }, { depth: 1, outside: 0 });
|
|
43
|
+
expect(ids(cut)).toEqual(["runner", "web"]);
|
|
44
|
+
expect(cut.edges).toEqual([edge("web", "runner")]);
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
it("counts outside hops from the last Kubernetes node", () => {
|
|
48
|
+
const cut = neighbourhoodOf(fixture(), { group: "apps", kind: "Deployment", name: "web" }, { depth: 1, outside: 1 });
|
|
49
|
+
expect(ids(cut)).toEqual(["gsa", "runner", "web"]);
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
it("does not take a sibling that shares a dependency", () => {
|
|
53
|
+
const cut = neighbourhoodOf(fixture(), { group: "apps", kind: "Deployment", name: "web" }, { depth: 3 });
|
|
54
|
+
expect(ids(cut)).not.toContain("other");
|
|
55
|
+
expect(ids(cut)).not.toContain("bucket");
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
it("walks down from the account to what uses it", () => {
|
|
59
|
+
const cut = neighbourhoodOf(fixture(), { kind: "ServiceAccount", name: "runner" }, { depth: 1, up: false });
|
|
60
|
+
expect(ids(cut)).toEqual(["other", "runner", "web"]);
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
it("returns no nodes and a reason naming an identity that is not there", () => {
|
|
64
|
+
const cut = neighbourhoodOf(fixture(), { group: "apps", kind: "Deployment", namespace: "prod", name: "absent" });
|
|
65
|
+
expect(cut.nodes).toEqual([]);
|
|
66
|
+
expect(cut.edges).toEqual([]);
|
|
67
|
+
expect(cut.reason).toContain("apps/Deployment prod/absent");
|
|
68
|
+
});
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
describe("findK8sNode", () => {
|
|
72
|
+
it("joins an object with no namespace to default, and matches a cluster-scoped kind without one", () => {
|
|
73
|
+
const g = {
|
|
74
|
+
nodes: [
|
|
75
|
+
k8s("a", "K8s::Apps::Deployment", "apps/v1", "web", "default"),
|
|
76
|
+
k8s("b", "K8s::Apps::Deployment", "apps/v1", "web", "prod"),
|
|
77
|
+
k8s("ns", "K8s::Core::Namespace", "v1", "prod"),
|
|
78
|
+
],
|
|
79
|
+
edges: [],
|
|
80
|
+
groups: {},
|
|
81
|
+
};
|
|
82
|
+
expect(findK8sNode(g, { group: "apps", kind: "Deployment", name: "web" }).id).toBe("a");
|
|
83
|
+
expect(findK8sNode(g, { group: "apps", kind: "Deployment", namespace: "prod", name: "web" }).id).toBe("b");
|
|
84
|
+
expect(findK8sNode(g, { group: "", kind: "Namespace", name: "prod" }).id).toBe("ns");
|
|
85
|
+
expect(findK8sNode(g, { group: "batch", kind: "Deployment", name: "web" })).toBeNull();
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
it("reads the group from the IR kind when the node carries no apiVersion", () => {
|
|
89
|
+
const g = { nodes: [{ id: "d", kind: "K8s::Apps::Deployment", lexicon: "k8s", attrs: { metadata: { name: "web" } } }], edges: [], groups: {} };
|
|
90
|
+
expect(identityOf(g.nodes[0])).toMatchObject({ group: "apps", kind: "Deployment", name: "web" });
|
|
91
|
+
expect(findK8sNode(g, { group: "apps", kind: "Deployment", name: "web" }).id).toBe("d");
|
|
92
|
+
});
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
describe("cutAround", () => {
|
|
96
|
+
const chain = () => ({ nodes: ["a", "b", "c"].map((id) => tf(id, "t")), edges: [edge("a", "b"), edge("b", "c")], groups: {} });
|
|
97
|
+
|
|
98
|
+
it("up keeps what the seed needs and down keeps what needs it", () => {
|
|
99
|
+
expect(ids(cutAround(chain(), ["b"], { depth: 5, down: false }))).toEqual(["b", "c"]);
|
|
100
|
+
expect(ids(cutAround(chain(), ["b"], { depth: 5, up: false }))).toEqual(["a", "b"]);
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
it("bounds the walk by depth over a graph with no inside predicate", () => {
|
|
104
|
+
expect(ids(cutAround(chain(), ["a"], { depth: 1 }))).toEqual(["a", "b"]);
|
|
105
|
+
expect(ids(cutAround(chain(), ["a"], { depth: 2 }))).toEqual(["a", "b", "c"]);
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
it("names the ids it could not find", () => {
|
|
109
|
+
const cut = cutAround(chain(), ["a", "zz"], { depth: 1 });
|
|
110
|
+
expect(cut.missing).toEqual(["zz"]);
|
|
111
|
+
expect(cutAround(chain(), ["zz"]).reason).toContain("zz");
|
|
112
|
+
});
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
describe("module graph", () => {
|
|
116
|
+
it("imports nothing from node: and nothing outside web/", () => {
|
|
117
|
+
const seen = new Set();
|
|
118
|
+
const walk = (file) => {
|
|
119
|
+
if (seen.has(file)) return;
|
|
120
|
+
seen.add(file);
|
|
121
|
+
const text = readFileSync(file, "utf8");
|
|
122
|
+
for (const m of text.matchAll(/(?:^|\n)\s*(?:import|export)\b[^;\n]*?from\s+["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)|(?:^|\n)\s*import\s+["']([^"']+)["']/g)) {
|
|
123
|
+
const spec = m[1] || m[2] || m[3];
|
|
124
|
+
expect(spec.startsWith("./"), `${file} imports ${spec}`).toBe(true);
|
|
125
|
+
walk(resolve(dirname(file), spec));
|
|
126
|
+
}
|
|
127
|
+
};
|
|
128
|
+
walk(join(import.meta.dirname, "neighbourhood.js"));
|
|
129
|
+
expect([...seen].map((f) => f.split("/").pop()).sort()).toEqual(["cut-around.js", "neighbourhood.js"]);
|
|
130
|
+
});
|
|
131
|
+
});
|