@krizaka/architecture 0.1.0 → 0.2.1
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/README.md +41 -11
- package/package.json +10 -4
- package/src/c4.mjs +93 -21
- package/src/cli.mjs +6 -2
- package/src/files.mjs +100 -46
- package/src/imports.mjs +7 -2
- package/src/index.d.ts +54 -0
- package/src/index.mjs +2 -1
- package/src/scan.mjs +81 -37
- package/src/text.mjs +10 -1
- package/src/units.mjs +369 -0
package/README.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
# @krizaka/architecture
|
|
2
2
|
|
|
3
|
-
The C4 view of a repository, **generated from its code** (krizaka/.github#355
|
|
4
|
-
|
|
5
|
-
the founder cockpit all show the architecture of the
|
|
3
|
+
The C4 view of a repository, **generated from its code and its manifests** (krizaka/.github#355; ADR-013: one source per rule set;
|
|
4
|
+
ADR-027: the one generator of a repository's current state). It runs on a local checkout or on a map of files and gives the same
|
|
5
|
+
output wherever it runs, so the docs, krizaka.com, the org's architecture and the founder cockpit all show the architecture of the
|
|
6
|
+
code on `main`, not of what is deployed.
|
|
7
|
+
|
|
8
|
+
Since 0.2.0 it is **no longer dependency-free**: it reads each manifest with its parser — `yaml` (pnpm workspace and lockfile),
|
|
9
|
+
`smol-toml` (Cargo, pyproject) and `fast-xml-parser` (Maven), pinned — because ADR-026 refuses a regex over a structured format.
|
|
6
10
|
|
|
7
11
|
```bash
|
|
8
12
|
npx krizaka-architecture ../my-repo --out c4.json # the three levels
|
|
@@ -11,17 +15,39 @@ npx krizaka-architecture ../my-repo --out c4.json --text c4.md # plus the tex
|
|
|
11
15
|
```
|
|
12
16
|
|
|
13
17
|
```js
|
|
14
|
-
import { buildC4, toText } from "@krizaka/architecture";
|
|
18
|
+
import { buildC4, buildC4FromFiles, toText, unitsOf } from "@krizaka/architecture";
|
|
15
19
|
const c4 = buildC4("/path/to/checkout"); // { schema: "krizaka.c4/1", repo, levels: { context, containers, components } }
|
|
20
|
+
const same = buildC4FromFiles(files, { name: "my-repo" }); // files: Map<repo-relative path, text>, e.g. from a tarball
|
|
21
|
+
const units = unitsOf(files); // every unit with its version and the org dependencies that build it
|
|
16
22
|
```
|
|
17
23
|
|
|
24
|
+
Also exported: `isOrgPackage` (per ecosystem), `baseVersion` (`^0.19.0` → `0.19.0`) and `globMatches` (a workspace glob against
|
|
25
|
+
a directory).
|
|
26
|
+
|
|
27
|
+
## The units and their versions (`unitsOf`)
|
|
28
|
+
|
|
29
|
+
A unit is what a manifest declares, each with `path`, `manifest`, `ecosystem`, `language`, `name`, `version`, `published` (an org
|
|
30
|
+
package others can depend on) and `dependsOn`: its **org dependencies** (`@krizaka/*`, `com.krizaka*`, `krizaka-*` crates,
|
|
31
|
+
`krizaka*` Python packages), each with the `range` the manifest says, `have` — the version that builds the unit — and `from`
|
|
32
|
+
(`lockfile` or `range`), `dev`, and for Maven `parent`.
|
|
33
|
+
|
|
34
|
+
| Ecosystem | Units | The version that builds it |
|
|
35
|
+
| :-------- | :----------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
|
|
36
|
+
| npm | the root `package.json` and every workspace member (`pnpm-workspace.yaml`, `workspaces`; `**` and `!` globs) | `pnpm-lock.yaml` importers, else `package-lock.json` (per workspace, then hoisted at the root), else the range's plain version |
|
|
37
|
+
| Maven | the root `pom.xml` and its `<module>`s, recursively; `packaging` and `modules` | the declared version (properties resolved); an imported BOM and the org parent are dependencies, a managed one says `managed` |
|
|
38
|
+
| Cargo | every `Cargo.toml` with a `[package]` (`publish = false` is not published) | the version, or the git `tag` / `rev` |
|
|
39
|
+
| Python | every `pyproject.toml` with a `[project]`, else a `requirements.txt` in a folder of its own | the PEP 508 specifier as the range |
|
|
40
|
+
|
|
41
|
+
A manifest that does not parse is left out, never thrown. Container nodes of the `containers` level carry their unit's
|
|
42
|
+
`ecosystem`, `language`, `version`, `published` and `dependsOn` when the manifest at their directory says one.
|
|
43
|
+
|
|
18
44
|
## What is read
|
|
19
45
|
|
|
20
|
-
| Level
|
|
21
|
-
|
|
|
22
|
-
| `context`
|
|
23
|
-
| `containers` | npm/yarn `workspaces` and `pnpm-workspace.yaml` packages (`app` or `library`; a Next.js, Expo, Vite, Express, Fastify or Hono dependency, or `apps/`, makes an app), Maven `<module>`s, or the root package alone | container `uses` another (a declared dependency or an import) and `reads` an external service
|
|
24
|
-
| `components` | the first folder under `src/` (or the container root) of each container; `root` for loose files
|
|
46
|
+
| Level | Nodes | Edges |
|
|
47
|
+
| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `context` | the system (the repo) and what it reaches: external services, Krizaka libraries | system `reads` an external service, `uses` the libraries |
|
|
49
|
+
| `containers` | npm/yarn `workspaces` and `pnpm-workspace.yaml` packages (`app` or `library`; a Next.js, Expo, Vite, Express, Fastify or Hono dependency, or `apps/`, makes an app), Maven `<module>`s, or the root package alone; each with its unit's version and org dependencies | container `uses` another (a declared dependency or an import) and `reads` an external service |
|
|
50
|
+
| `components` | the first folder under `src/` (or the container root) of each container; `root` for loose files | component `imports` component (relative and `@/` imports), `uses` a container, `reads` an external service |
|
|
25
51
|
|
|
26
52
|
External services come from the **env declarations** (`lib/env.ts`, `env.ts`, `.env.example`) and `process.env.X` reads, by the org contexts
|
|
27
53
|
(`DATABASE_`, `AUTH_`, `MEDIA_`, `MAIL_`, `PUSH_`, `PAYMENTS_`, `REALTIME_`, `ABUSE_`, `OBSERVABILITY_`, `AI_`): a vendor is a value, so it never
|
|
@@ -37,7 +63,11 @@ The founder cockpit runs it per repo on the Mac and reads `{ nodes, edges, level
|
|
|
37
63
|
|
|
38
64
|
```js
|
|
39
65
|
import { execFileSync } from "node:child_process";
|
|
40
|
-
const level = JSON.parse(
|
|
66
|
+
const level = JSON.parse(
|
|
67
|
+
execFileSync("npx", ["--yes", "@krizaka/architecture", repoPath, "--level", "containers"], { encoding: "utf8" }),
|
|
68
|
+
);
|
|
41
69
|
```
|
|
42
70
|
|
|
43
|
-
Not in this package
|
|
71
|
+
Not in this package: the intent and the target (the LikeC4 models of each system's home, ADR-027), the joins across repositories
|
|
72
|
+
(latest tags, behind, links) and the drawing: the org's architecture assembler in krizaka/.github `tools/architecture/` reads this
|
|
73
|
+
package's output for every repository.
|
package/package.json
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@krizaka/architecture",
|
|
3
|
-
"version": "0.1
|
|
4
|
-
"description": "The C4 view of a repository, generated from its code: containers from the workspaces, components from the folders, the imports between them, the external services from the env declarations.
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "The C4 view of a repository, generated from its code and manifests: containers from the workspaces (with their version and the org dependencies that build them, from the lockfile), Maven modules, crates and Python projects, components from the folders, the imports between them, the external services from the env declarations. Runs on a local checkout or a map of files, writes JSON and a text version.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"krizaka",
|
|
7
7
|
"c4",
|
|
8
8
|
"architecture",
|
|
9
|
-
"dependencies"
|
|
9
|
+
"dependencies",
|
|
10
|
+
"versions"
|
|
10
11
|
],
|
|
11
12
|
"homepage": "https://ts.krizaka.com/architecture",
|
|
12
13
|
"bugs": "https://github.com/krizaka/krizaka-ts/issues",
|
|
@@ -36,10 +37,15 @@
|
|
|
36
37
|
"LICENSE"
|
|
37
38
|
],
|
|
38
39
|
"sideEffects": false,
|
|
40
|
+
"dependencies": {
|
|
41
|
+
"fast-xml-parser": "5.12.0",
|
|
42
|
+
"smol-toml": "1.9.1",
|
|
43
|
+
"yaml": "2.8.3"
|
|
44
|
+
},
|
|
39
45
|
"devDependencies": {
|
|
40
46
|
"@types/node": "^22.10.0",
|
|
41
47
|
"eslint": "^9.39.0",
|
|
42
|
-
"@krizaka/config": "^0.
|
|
48
|
+
"@krizaka/config": "^0.23.0"
|
|
43
49
|
},
|
|
44
50
|
"engines": {
|
|
45
51
|
"node": ">=22"
|
package/src/c4.mjs
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
|
-
// The three C4 levels (context, containers, components) from the facts of a
|
|
1
|
+
// The three C4 levels (context, containers, components) from the facts of a repository: `{ level, nodes, edges }` each.
|
|
2
|
+
import { basename, resolve } from "node:path";
|
|
3
|
+
|
|
4
|
+
import { filesOfCheckout } from "./files.mjs";
|
|
2
5
|
import { contextOf } from "./imports.mjs";
|
|
3
6
|
import { asc } from "./order.mjs";
|
|
4
7
|
import { componentOf, containerOfPath, scan } from "./scan.mjs";
|
|
@@ -23,7 +26,16 @@ const byId = (a, b) => asc(a.id, b.id);
|
|
|
23
26
|
|
|
24
27
|
const node = (id, level, kind, name, extra = {}) => {
|
|
25
28
|
const files = [...new Set(extra.files ?? [])].sort(asc);
|
|
26
|
-
return {
|
|
29
|
+
return {
|
|
30
|
+
id,
|
|
31
|
+
level,
|
|
32
|
+
kind,
|
|
33
|
+
name,
|
|
34
|
+
description: extra.description ?? "",
|
|
35
|
+
technology: extra.technology,
|
|
36
|
+
files: files.slice(0, FILE_CAP),
|
|
37
|
+
fileCount: extra.fileCount ?? files.length,
|
|
38
|
+
};
|
|
27
39
|
};
|
|
28
40
|
|
|
29
41
|
/** Edges merged by (from, to, label): the number of files behind it and the first of them. */
|
|
@@ -37,7 +49,9 @@ class Edges {
|
|
|
37
49
|
this.#map.set(key, edge);
|
|
38
50
|
}
|
|
39
51
|
list() {
|
|
40
|
-
return [...this.#map.values()].sort((a, b) =>
|
|
52
|
+
return [...this.#map.values()].sort((a, b) =>
|
|
53
|
+
`${a.from}|${a.to}|${a.label}`.localeCompare(`${b.from}|${b.to}|${b.label}`),
|
|
54
|
+
);
|
|
41
55
|
}
|
|
42
56
|
}
|
|
43
57
|
|
|
@@ -74,7 +88,12 @@ const externalNodes = (use) => {
|
|
|
74
88
|
agg.set(ctx, entry);
|
|
75
89
|
}
|
|
76
90
|
}
|
|
77
|
-
return [...agg].map(([ctx, { names, files }]) =>
|
|
91
|
+
return [...agg].map(([ctx, { names, files }]) =>
|
|
92
|
+
node(externalId(ctx), "external", "external", EXTERNALS[ctx], {
|
|
93
|
+
description: `Configured by ${[...names].sort(asc).join(", ")}`,
|
|
94
|
+
files,
|
|
95
|
+
}),
|
|
96
|
+
);
|
|
78
97
|
};
|
|
79
98
|
|
|
80
99
|
const workspaceByName = (containers) => new Map(containers.map((c) => [c.name, c]));
|
|
@@ -94,11 +113,15 @@ function containerEdges(facts, use) {
|
|
|
94
113
|
const byName = workspaceByName(facts.containers);
|
|
95
114
|
for (const c of facts.containers) {
|
|
96
115
|
for (const dep of c.deps) {
|
|
97
|
-
if (byName.has(dep) && dep !== c.name)
|
|
116
|
+
if (byName.has(dep) && dep !== c.name)
|
|
117
|
+
edges.add(containerId(c), containerId(byName.get(dep)), "uses", [c.manifest]);
|
|
98
118
|
else if (isLibrary(dep, byName)) edges.add(containerId(c), LIBRARIES, "uses", [c.manifest]);
|
|
99
119
|
}
|
|
100
120
|
}
|
|
101
|
-
for (const f of facts.files)
|
|
121
|
+
for (const f of facts.files)
|
|
122
|
+
importedContainers(facts, byName, f).forEach((to) =>
|
|
123
|
+
edges.add(containerId(to.from), containerId(to.target), "uses", [f.path]),
|
|
124
|
+
);
|
|
102
125
|
for (const [dir, byCtx] of use) {
|
|
103
126
|
const from = facts.containers.find((c) => c.dir === dir);
|
|
104
127
|
for (const [ctx, { files }] of byCtx) edges.add(containerId(from), externalId(ctx), "reads", [...files]);
|
|
@@ -108,25 +131,55 @@ function containerEdges(facts, use) {
|
|
|
108
131
|
|
|
109
132
|
const libraryNode = (facts) => {
|
|
110
133
|
const byName = workspaceByName(facts.containers);
|
|
111
|
-
const used = new Set(
|
|
112
|
-
|
|
134
|
+
const used = new Set(
|
|
135
|
+
[
|
|
136
|
+
...facts.containers.flatMap((c) => c.deps),
|
|
137
|
+
...facts.files.flatMap((f) => f.imports.filter((i) => i.kind === "package").map((i) => i.name)),
|
|
138
|
+
].filter((n) => isLibrary(n, byName)),
|
|
139
|
+
);
|
|
140
|
+
return used.size
|
|
141
|
+
? [node(LIBRARIES, "external", "external", "Krizaka libraries", { description: [...used].sort(asc).join(", ") })]
|
|
142
|
+
: [];
|
|
143
|
+
};
|
|
144
|
+
|
|
145
|
+
/** What the manifests say about a container: the unit at its directory, of its ecosystem (version, org dependencies). */
|
|
146
|
+
const unitFields = (facts, c) => {
|
|
147
|
+
const unit = facts.units.find((u) => u.path === c.dir && u.ecosystem === c.ecosystem);
|
|
148
|
+
if (!unit) return {};
|
|
149
|
+
const { ecosystem, language, version, published, dependsOn } = unit;
|
|
150
|
+
return { ecosystem, language, version, published, dependsOn };
|
|
113
151
|
};
|
|
114
152
|
|
|
115
|
-
const containerNodes = (facts) =>
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
153
|
+
const containerNodes = (facts) =>
|
|
154
|
+
facts.containers.map((c) => {
|
|
155
|
+
const own = facts.files.filter((f) => f.container === c.dir).map((f) => f.path);
|
|
156
|
+
const base = node(containerId(c), "container", c.kind, c.name, {
|
|
157
|
+
description: c.description,
|
|
158
|
+
technology: c.technology,
|
|
159
|
+
files: [c.manifest, ...own],
|
|
160
|
+
fileCount: own.length + 1,
|
|
161
|
+
});
|
|
162
|
+
return { ...base, ...unitFields(facts, c) };
|
|
163
|
+
});
|
|
119
164
|
|
|
120
165
|
const containerLevel = (facts, use) => {
|
|
121
166
|
const used = new Set([...use.values()].flatMap((m) => [...m.keys()]));
|
|
122
167
|
const externals = externalNodes(use).filter((n) => used.has(n.id.slice("external:".length).toUpperCase()));
|
|
123
|
-
return {
|
|
168
|
+
return {
|
|
169
|
+
level: "containers",
|
|
170
|
+
nodes: [...containerNodes(facts), ...externals, ...libraryNode(facts)].sort(byId),
|
|
171
|
+
edges: containerEdges(facts, use).list(),
|
|
172
|
+
};
|
|
124
173
|
};
|
|
125
174
|
|
|
126
175
|
const contextLevel = (facts, use, containers) => {
|
|
127
|
-
const system = node(`system:${facts.repo}`, "system", "system", facts.repo, {
|
|
176
|
+
const system = node(`system:${facts.repo}`, "system", "system", facts.repo, {
|
|
177
|
+
description: `${facts.containers.length} container(s)`,
|
|
178
|
+
files: facts.containers.map((c) => c.manifest),
|
|
179
|
+
});
|
|
128
180
|
const edges = new Edges();
|
|
129
|
-
for (const e of containers.edges.filter((x) => x.to.startsWith("external:")))
|
|
181
|
+
for (const e of containers.edges.filter((x) => x.to.startsWith("external:")))
|
|
182
|
+
edges.add(system.id, e.to, e.label, e.files);
|
|
130
183
|
const externals = containers.nodes.filter((n) => n.level === "external");
|
|
131
184
|
return { level: "context", nodes: [system, ...externals].sort(byId), edges: edges.list() };
|
|
132
185
|
};
|
|
@@ -140,7 +193,9 @@ const componentNodes = (facts) => {
|
|
|
140
193
|
g.files.push(f.path);
|
|
141
194
|
groups.set(id, g);
|
|
142
195
|
}
|
|
143
|
-
return [...groups].map(([id, g]) =>
|
|
196
|
+
return [...groups].map(([id, g]) =>
|
|
197
|
+
node(id, "component", "component", g.name, { description: g.c.name, technology: g.c.technology, files: g.files }),
|
|
198
|
+
);
|
|
144
199
|
};
|
|
145
200
|
|
|
146
201
|
/** The edge one import of a file draws from its component: to another container, or to another component of the same one. */
|
|
@@ -164,7 +219,8 @@ function componentEdges(facts, use) {
|
|
|
164
219
|
const edge = importEdge(facts, byName, c, from, imp);
|
|
165
220
|
if (edge) edges.add(...edge, [f.path]);
|
|
166
221
|
}
|
|
167
|
-
for (const n of f.envs.filter((name) => use.get(f.container)?.has(contextOf(name))))
|
|
222
|
+
for (const n of f.envs.filter((name) => use.get(f.container)?.has(contextOf(name))))
|
|
223
|
+
edges.add(from, externalId(contextOf(n)), "reads", [f.path]);
|
|
168
224
|
}
|
|
169
225
|
return edges;
|
|
170
226
|
}
|
|
@@ -176,10 +232,26 @@ const componentLevel = (facts, use, containers) => {
|
|
|
176
232
|
return { level: "components", nodes: [...componentNodes(facts), ...refs].sort(byId), edges };
|
|
177
233
|
};
|
|
178
234
|
|
|
179
|
-
/**
|
|
180
|
-
|
|
181
|
-
|
|
235
|
+
/**
|
|
236
|
+
* The C4 view of a repository's files (`path -> text`, repo-relative): `{ schema, repo, levels }`, deterministic. `name` is the
|
|
237
|
+
* repository's name when its root package.json has none.
|
|
238
|
+
*/
|
|
239
|
+
export function buildC4FromFiles(files, { name } = {}) {
|
|
240
|
+
const facts = scan(files, name ?? "repository");
|
|
182
241
|
const use = envUse(facts);
|
|
183
242
|
const containers = containerLevel(facts, use);
|
|
184
|
-
return {
|
|
243
|
+
return {
|
|
244
|
+
schema: SCHEMA,
|
|
245
|
+
repo: facts.repo,
|
|
246
|
+
levels: {
|
|
247
|
+
context: contextLevel(facts, use, containers),
|
|
248
|
+
containers,
|
|
249
|
+
components: componentLevel(facts, use, containers),
|
|
250
|
+
},
|
|
251
|
+
};
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/** The C4 view of a checkout on disk: the same as `buildC4FromFiles` on the files it reads there. */
|
|
255
|
+
export function buildC4(root) {
|
|
256
|
+
return buildC4FromFiles(filesOfCheckout(root), { name: basename(resolve(root)) });
|
|
185
257
|
}
|
package/src/cli.mjs
CHANGED
|
@@ -16,7 +16,9 @@ const flag = (name) => {
|
|
|
16
16
|
const repoPath = args.find((a, i) => !a.startsWith("--") && !(args[i - 1] ?? "").startsWith("--"));
|
|
17
17
|
|
|
18
18
|
if (!repoPath || !existsSync(resolve(repoPath))) {
|
|
19
|
-
console.error(
|
|
19
|
+
console.error(
|
|
20
|
+
"usage: krizaka-architecture <repo-path> [--out file.json] [--level context|containers|components] [--text [file.md]]",
|
|
21
|
+
);
|
|
20
22
|
process.exit(2);
|
|
21
23
|
}
|
|
22
24
|
|
|
@@ -35,6 +37,8 @@ else if (text !== true) process.stdout.write(json);
|
|
|
35
37
|
if (typeof text === "string") writeFileSync(resolve(text), toText(c4));
|
|
36
38
|
else if (text === true) process.stdout.write(toText(c4));
|
|
37
39
|
if (typeof out === "string") {
|
|
38
|
-
const counts = Object.values(c4.levels)
|
|
40
|
+
const counts = Object.values(c4.levels)
|
|
41
|
+
.map((l) => l.nodes.length + " " + l.level + " node(s)")
|
|
42
|
+
.join(", ");
|
|
39
43
|
console.log(`${c4.repo}: ${counts} -> ${out}`);
|
|
40
44
|
}
|
package/src/files.mjs
CHANGED
|
@@ -1,87 +1,141 @@
|
|
|
1
|
-
//
|
|
2
|
-
|
|
1
|
+
// The files the generator reads, as one map `path -> text` (repo-relative, "/"), whether they come from a checkout on disk or
|
|
2
|
+
// from somewhere else (a tarball, a fixture): code, env declarations, manifests and lockfiles. Everything after this file works
|
|
3
|
+
// on the map, so the same files give the same view wherever they come from.
|
|
4
|
+
import { readdirSync, readFileSync, statSync } from "node:fs";
|
|
3
5
|
import { join, posix } from "node:path";
|
|
4
6
|
|
|
7
|
+
import { parse as parseYaml } from "yaml";
|
|
8
|
+
|
|
5
9
|
import { asc } from "./order.mjs";
|
|
10
|
+
import { readPom } from "./units.mjs";
|
|
6
11
|
|
|
7
|
-
const SKIP_DIRS = new Set([
|
|
12
|
+
const SKIP_DIRS = new Set([
|
|
13
|
+
"node_modules",
|
|
14
|
+
".git",
|
|
15
|
+
"dist",
|
|
16
|
+
"build",
|
|
17
|
+
".next",
|
|
18
|
+
".turbo",
|
|
19
|
+
"coverage",
|
|
20
|
+
"out",
|
|
21
|
+
"target",
|
|
22
|
+
".open-next",
|
|
23
|
+
".expo",
|
|
24
|
+
".cache",
|
|
25
|
+
".venv",
|
|
26
|
+
]);
|
|
8
27
|
const CODE = /\.(?:[cm]?[jt]sx?)$/;
|
|
9
28
|
const TEST = /(?:\.(?:test|spec|stories)\.[cm]?[jt]sx?$|(?:^|\/)(?:__tests__|test|tests|e2e|fixtures)\/)/;
|
|
10
29
|
const ENV_FILES = /^(?:env\.(?:[cm]?[jt]s)|\.env\.(?:example|sample|template))$/;
|
|
30
|
+
const MANIFESTS = new Set([
|
|
31
|
+
"package.json",
|
|
32
|
+
"pnpm-workspace.yaml",
|
|
33
|
+
"pnpm-lock.yaml",
|
|
34
|
+
"package-lock.json",
|
|
35
|
+
"tsconfig.json",
|
|
36
|
+
"pom.xml",
|
|
37
|
+
"Cargo.toml",
|
|
38
|
+
"pyproject.toml",
|
|
39
|
+
"requirements.txt",
|
|
40
|
+
]);
|
|
11
41
|
const MAX_BYTES = 1_000_000;
|
|
42
|
+
// A lockfile of a large workspace is bigger than a source file; it is read whole, up to this size.
|
|
43
|
+
const MAX_MANIFEST_BYTES = 16_000_000;
|
|
12
44
|
|
|
13
|
-
|
|
45
|
+
const readCapped = (path, cap) => {
|
|
14
46
|
try {
|
|
15
|
-
return statSync(path).size >
|
|
47
|
+
return statSync(path).size > cap ? "" : readFileSync(path, "utf8");
|
|
16
48
|
} catch {
|
|
17
49
|
return "";
|
|
18
50
|
}
|
|
19
51
|
};
|
|
20
52
|
|
|
21
|
-
|
|
22
|
-
try {
|
|
23
|
-
return JSON.parse(readText(path));
|
|
24
|
-
} catch {
|
|
25
|
-
return undefined;
|
|
26
|
-
}
|
|
27
|
-
};
|
|
28
|
-
|
|
29
|
-
/** Every code file and env declaration file of a checkout, as repo-relative paths with "/". Tests are listed apart. */
|
|
30
|
-
const listing = () => ({ code: [], tests: [], env: [] });
|
|
53
|
+
const wanted = (name) => MANIFESTS.has(name) || ENV_FILES.test(name) || CODE.test(name);
|
|
31
54
|
|
|
32
|
-
|
|
55
|
+
/** The files of a checkout the generator reads (code, env declarations, manifests, lockfiles), build folders left out. */
|
|
56
|
+
export function filesOfCheckout(root, rel = "", out = new Map()) {
|
|
33
57
|
for (const entry of readdirSync(join(root, rel), { withFileTypes: true })) {
|
|
34
58
|
const path = rel ? `${rel}/${entry.name}` : entry.name;
|
|
35
59
|
if (entry.isDirectory()) {
|
|
36
|
-
if (!SKIP_DIRS.has(entry.name))
|
|
37
|
-
} else if (
|
|
38
|
-
out.
|
|
39
|
-
} else if (CODE.test(entry.name)) {
|
|
40
|
-
(TEST.test(path) ? out.tests : out.code).push(path);
|
|
60
|
+
if (!SKIP_DIRS.has(entry.name)) filesOfCheckout(root, path, out);
|
|
61
|
+
} else if (wanted(entry.name)) {
|
|
62
|
+
out.set(path, readCapped(join(root, path), MANIFESTS.has(entry.name) ? MAX_MANIFEST_BYTES : MAX_BYTES));
|
|
41
63
|
}
|
|
42
64
|
}
|
|
43
65
|
return out;
|
|
44
66
|
}
|
|
45
67
|
|
|
46
|
-
const
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
if (
|
|
54
|
-
else if (
|
|
68
|
+
const skippedPath = (path) => path.split("/").some((part) => SKIP_DIRS.has(part));
|
|
69
|
+
const baseName = (path) => path.slice(path.lastIndexOf("/") + 1);
|
|
70
|
+
|
|
71
|
+
/** The code files, the tests and the env declaration files of a map, sorted; build folders left out. */
|
|
72
|
+
export function classify(files) {
|
|
73
|
+
const out = { code: [], tests: [], env: [] };
|
|
74
|
+
for (const path of [...files.keys()].filter((p) => !skippedPath(p)).sort(asc)) {
|
|
75
|
+
if (ENV_FILES.test(baseName(path))) out.env.push(path);
|
|
76
|
+
else if (CODE.test(path)) (TEST.test(path) ? out.tests : out.code).push(path);
|
|
77
|
+
}
|
|
78
|
+
return out;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export const textOf = (files, path) => files.get(path) ?? "";
|
|
82
|
+
|
|
83
|
+
export const jsonOf = (files, path) => {
|
|
84
|
+
try {
|
|
85
|
+
return JSON.parse(textOf(files, path));
|
|
86
|
+
} catch {
|
|
87
|
+
return undefined;
|
|
55
88
|
}
|
|
56
|
-
return found;
|
|
57
89
|
};
|
|
58
90
|
|
|
59
|
-
const
|
|
91
|
+
const yamlPackages = (text) => {
|
|
60
92
|
try {
|
|
61
|
-
|
|
93
|
+
const packages = parseYaml(text)?.packages;
|
|
94
|
+
return Array.isArray(packages) ? packages.filter((p) => typeof p === "string") : [];
|
|
62
95
|
} catch {
|
|
63
96
|
return [];
|
|
64
97
|
}
|
|
65
98
|
};
|
|
66
99
|
|
|
67
|
-
const
|
|
68
|
-
|
|
100
|
+
const hasPackage = (files, dir) => files.has(posix.join(dir, "package.json"));
|
|
101
|
+
|
|
102
|
+
/** The direct sub-folders of `rel` that hold a package.json (build folders left out). */
|
|
103
|
+
const packageSubdirs = (files, rel) => {
|
|
104
|
+
const prefix = `${rel}/`;
|
|
105
|
+
const found = new Set();
|
|
106
|
+
for (const path of files.keys()) {
|
|
107
|
+
if (!path.startsWith(prefix) || !path.endsWith("/package.json")) continue;
|
|
108
|
+
const parts = path.slice(prefix.length).split("/");
|
|
109
|
+
if (parts.length === 2 && !SKIP_DIRS.has(parts[0])) found.add(`${rel}/${parts[0]}`);
|
|
110
|
+
}
|
|
111
|
+
return [...found];
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
const expand = (files, pattern) => {
|
|
115
|
+
const clean = pattern
|
|
116
|
+
.replace(/^\.\//, "")
|
|
117
|
+
.replace(/\/\*\*$/, "/*")
|
|
118
|
+
.replace(/\/$/, "");
|
|
69
119
|
if (clean.includes("*") && !clean.endsWith("/*")) return [];
|
|
70
|
-
const dirs = clean.endsWith("/*") ?
|
|
71
|
-
return dirs.filter((d) =>
|
|
120
|
+
const dirs = clean.endsWith("/*") ? packageSubdirs(files, clean.slice(0, -2)) : [clean];
|
|
121
|
+
return dirs.filter((d) => hasPackage(files, d));
|
|
72
122
|
};
|
|
73
123
|
|
|
74
124
|
/** The directories of the workspace packages (npm/yarn `workspaces` and pnpm-workspace.yaml); [] when the repo is not a workspace. */
|
|
75
|
-
export function workspaceDirs(
|
|
76
|
-
const pkg =
|
|
125
|
+
export function workspaceDirs(files) {
|
|
126
|
+
const pkg = jsonOf(files, "package.json");
|
|
77
127
|
const declared = Array.isArray(pkg?.workspaces) ? pkg.workspaces : (pkg?.workspaces?.packages ?? []);
|
|
78
|
-
const patterns = [...declared, ...yamlPackages(
|
|
79
|
-
const excluded = new Set(patterns.filter((p) => p.startsWith("!")).flatMap((p) => expand(
|
|
80
|
-
return [...new Set(patterns.filter((p) => !p.startsWith("!")).flatMap((p) => expand(
|
|
128
|
+
const patterns = [...declared, ...yamlPackages(textOf(files, "pnpm-workspace.yaml"))];
|
|
129
|
+
const excluded = new Set(patterns.filter((p) => p.startsWith("!")).flatMap((p) => expand(files, p.slice(1))));
|
|
130
|
+
return [...new Set(patterns.filter((p) => !p.startsWith("!")).flatMap((p) => expand(files, p)))]
|
|
131
|
+
.filter((d) => !excluded.has(d))
|
|
132
|
+
.sort(asc);
|
|
81
133
|
}
|
|
82
134
|
|
|
83
|
-
/** The Maven modules listed by the root pom (one level), as repo-relative directories. */
|
|
84
|
-
export function mavenModules(
|
|
85
|
-
const pom =
|
|
86
|
-
return [...
|
|
135
|
+
/** The Maven modules listed by the root pom (one level), as repo-relative directories that hold a pom.xml. */
|
|
136
|
+
export function mavenModules(files) {
|
|
137
|
+
const pom = readPom(textOf(files, "pom.xml"));
|
|
138
|
+
return [...new Set((pom?.modules ?? []).map((m) => posix.normalize(m)))]
|
|
139
|
+
.filter((d) => files.has(posix.join(d, "pom.xml")))
|
|
140
|
+
.sort(asc);
|
|
87
141
|
}
|
package/src/imports.mjs
CHANGED
|
@@ -14,7 +14,10 @@ const ENV_ONLY = new RegExp(`^(?:NEXT_PUBLIC_)?(?:${CONTEXTS})_[A-Z0-9_]*[A-Z0-9
|
|
|
14
14
|
const PROCESS_ENV = /(?:process\.env|import\.meta\.env)\.([A-Z][A-Z0-9_]+)/g;
|
|
15
15
|
|
|
16
16
|
/** The module specifiers a source names, in source order. */
|
|
17
|
-
export const specifiersOf = (source) =>
|
|
17
|
+
export const specifiersOf = (source) =>
|
|
18
|
+
SPECIFIERS.flatMap((re) => [...source.matchAll(re)])
|
|
19
|
+
.sort((a, b) => a.index - b.index)
|
|
20
|
+
.map((m) => m[1]);
|
|
18
21
|
|
|
19
22
|
/** `@scope/name/sub` -> `@scope/name`; `name/sub` -> `name`; a relative, alias or built-in path -> undefined. */
|
|
20
23
|
export function packageOf(specifier) {
|
|
@@ -34,7 +37,9 @@ const strip = (names) => names.map((n) => n.replace(/^NEXT_PUBLIC_/, ""));
|
|
|
34
37
|
|
|
35
38
|
/** The env names of the declared contexts: every one a declaration file lists, only the ones a source file reads. */
|
|
36
39
|
export function envNamesOf(source, { declaration }) {
|
|
37
|
-
const found = declaration
|
|
40
|
+
const found = declaration
|
|
41
|
+
? [...source.matchAll(ENV_NAME)].map((m) => m[1])
|
|
42
|
+
: [...source.matchAll(PROCESS_ENV)].map((m) => m[1]).filter((n) => ENV_ONLY.test(n));
|
|
38
43
|
return [...new Set(strip(found))].sort(asc);
|
|
39
44
|
}
|
|
40
45
|
|
package/src/index.d.ts
CHANGED
|
@@ -1,5 +1,42 @@
|
|
|
1
1
|
export type C4LevelName = "context" | "containers" | "components";
|
|
2
2
|
|
|
3
|
+
export type Ecosystem = "npm" | "maven" | "cargo" | "python";
|
|
4
|
+
export type Language = "typescript" | "javascript" | "java" | "rust" | "python";
|
|
5
|
+
|
|
6
|
+
/** An org dependency of a unit: `@krizaka/*`, `com.krizaka*` (`groupId:artifactId`), a `krizaka-*` crate, a `krizaka*` Python package. */
|
|
7
|
+
export interface OrgDependency {
|
|
8
|
+
ecosystem: Ecosystem;
|
|
9
|
+
name: string;
|
|
10
|
+
/** What the manifest says: a range, a version, `managed` (Maven, from a BOM), a git tag or rev. */
|
|
11
|
+
range: string;
|
|
12
|
+
/** The version that builds the unit: the lockfile's for npm, else the pin's plain version; null when neither says one. */
|
|
13
|
+
have: string | null;
|
|
14
|
+
from: "lockfile" | "range";
|
|
15
|
+
/** A development (or test-scope) dependency. */
|
|
16
|
+
dev: boolean;
|
|
17
|
+
/** Maven: the dependency is the unit's parent POM. */
|
|
18
|
+
parent?: boolean;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** A unit of a repository: a package.json of the workspace, a module of the Maven reactor, a crate or a Python project. */
|
|
22
|
+
export interface Unit {
|
|
23
|
+
/** Repo-relative directory, `.` for the root. */
|
|
24
|
+
path: string;
|
|
25
|
+
manifest: string;
|
|
26
|
+
ecosystem: Ecosystem;
|
|
27
|
+
language: Language;
|
|
28
|
+
/** The package name (`groupId:artifactId` for Maven); null for a requirements.txt alone. */
|
|
29
|
+
name: string | null;
|
|
30
|
+
version: string | null;
|
|
31
|
+
/** An org package others can depend on (not private, in the org's namespace). */
|
|
32
|
+
published: boolean;
|
|
33
|
+
/** Maven only. */
|
|
34
|
+
packaging?: string;
|
|
35
|
+
/** Maven only: the directories of its modules. */
|
|
36
|
+
modules?: string[];
|
|
37
|
+
dependsOn: OrgDependency[];
|
|
38
|
+
}
|
|
39
|
+
|
|
3
40
|
export interface C4Node {
|
|
4
41
|
id: string;
|
|
5
42
|
level: "system" | "container" | "component" | "external";
|
|
@@ -10,6 +47,12 @@ export interface C4Node {
|
|
|
10
47
|
/** Repo-relative files behind the node (capped at 200; `fileCount` is the true number). */
|
|
11
48
|
files: string[];
|
|
12
49
|
fileCount: number;
|
|
50
|
+
/** A container's unit, when its manifest says one: */
|
|
51
|
+
ecosystem?: Ecosystem;
|
|
52
|
+
language?: Language;
|
|
53
|
+
version?: string | null;
|
|
54
|
+
published?: boolean;
|
|
55
|
+
dependsOn?: OrgDependency[];
|
|
13
56
|
}
|
|
14
57
|
|
|
15
58
|
export interface C4Edge {
|
|
@@ -34,5 +77,16 @@ export interface C4 {
|
|
|
34
77
|
}
|
|
35
78
|
|
|
36
79
|
export const SCHEMA: "krizaka.c4/1";
|
|
80
|
+
/** The C4 view of a checkout on disk. */
|
|
37
81
|
export function buildC4(repoPath: string): C4;
|
|
82
|
+
/** The C4 view of a repository's files (`path -> text`, repo-relative): the same output as `buildC4` for the same files. */
|
|
83
|
+
export function buildC4FromFiles(files: Map<string, string>, options?: { name?: string }): C4;
|
|
38
84
|
export function toText(c4: C4): string;
|
|
85
|
+
/** Every unit of a repository's files, sorted by path then ecosystem. */
|
|
86
|
+
export function unitsOf(files: Map<string, string>): Unit[];
|
|
87
|
+
/** Is a package an org package, per ecosystem? */
|
|
88
|
+
export const isOrgPackage: Record<Ecosystem, (name: string) => boolean>;
|
|
89
|
+
/** "0.19.0" from "^0.19.0", "~0.19.0", ">=0.19.0" or "0.19.0"; null for `workspace:`, tags, git or complex ranges. */
|
|
90
|
+
export function baseVersion(range: string | null | undefined): string | null;
|
|
91
|
+
/** Does a directory match a workspace glob (`apps/*`, `packages/**`, `deploy/backup`)? */
|
|
92
|
+
export function globMatches(glob: string, dir: string): boolean;
|
package/src/index.mjs
CHANGED
package/src/scan.mjs
CHANGED
|
@@ -1,71 +1,115 @@
|
|
|
1
|
-
// The facts of a
|
|
2
|
-
|
|
1
|
+
// The facts of a repository's files: its containers (workspace packages or Maven modules) with the unit each one is, its source
|
|
2
|
+
// files with what each imports and reads.
|
|
3
|
+
import { posix } from "node:path";
|
|
3
4
|
|
|
4
|
-
import {
|
|
5
|
+
import { classify, jsonOf, mavenModules, textOf, workspaceDirs } from "./files.mjs";
|
|
5
6
|
import { envNamesOf, localTarget, packageOf, specifiersOf } from "./imports.mjs";
|
|
7
|
+
import { readPom, unitsOf } from "./units.mjs";
|
|
6
8
|
|
|
7
|
-
const FRAMEWORKS = [
|
|
9
|
+
const FRAMEWORKS = [
|
|
10
|
+
["next", "Next.js", true],
|
|
11
|
+
["expo", "Expo", true],
|
|
12
|
+
["react-native", "React Native", true],
|
|
13
|
+
["vite", "Vite", true],
|
|
14
|
+
["express", "Express", true],
|
|
15
|
+
["fastify", "Fastify", true],
|
|
16
|
+
["hono", "Hono", true],
|
|
17
|
+
];
|
|
8
18
|
|
|
9
|
-
const npmContainer = (
|
|
10
|
-
const pkg =
|
|
19
|
+
const npmContainer = (files, dir, repo) => {
|
|
20
|
+
const pkg = jsonOf(files, posix.join(dir, "package.json")) ?? {};
|
|
11
21
|
const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
|
|
12
22
|
const framework = FRAMEWORKS.find(([name]) => name in (pkg.dependencies ?? {}));
|
|
13
23
|
const app = /^apps?\//.test(dir) || Boolean(framework?.[2]) || Boolean(pkg.private && pkg.scripts?.start);
|
|
14
|
-
return {
|
|
24
|
+
return {
|
|
25
|
+
dir,
|
|
26
|
+
name: pkg.name ?? (dir === "." ? repo : posix.basename(dir)),
|
|
27
|
+
description: pkg.description ?? "",
|
|
28
|
+
kind: app ? "app" : "library",
|
|
29
|
+
technology: framework?.[1] ?? "TypeScript",
|
|
30
|
+
ecosystem: "npm",
|
|
31
|
+
deps: Object.keys(deps),
|
|
32
|
+
manifest: posix.join(dir, "package.json"),
|
|
33
|
+
};
|
|
15
34
|
};
|
|
16
35
|
|
|
17
|
-
const
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
36
|
+
const mavenContainer = (files, dir) => {
|
|
37
|
+
const pom = readPom(textOf(files, posix.join(dir, "pom.xml")));
|
|
38
|
+
return {
|
|
39
|
+
dir,
|
|
40
|
+
name: pom?.artifactId ?? posix.basename(dir),
|
|
41
|
+
description: pom?.description ?? "",
|
|
42
|
+
kind: "module",
|
|
43
|
+
technology: "Maven",
|
|
44
|
+
ecosystem: "maven",
|
|
45
|
+
deps: pom?.dependencyIds ?? [],
|
|
46
|
+
manifest: posix.join(dir, "pom.xml"),
|
|
47
|
+
};
|
|
24
48
|
};
|
|
25
49
|
|
|
26
|
-
/** The containers of a
|
|
27
|
-
export function containersOf(
|
|
28
|
-
const packages = workspaceDirs(
|
|
29
|
-
if (packages.length) return packages.map((d) => npmContainer(
|
|
30
|
-
const modules = mavenModules(
|
|
31
|
-
if (modules.length) return modules.map((d) => mavenContainer(
|
|
32
|
-
return
|
|
50
|
+
/** The containers of a repository: workspace packages, else Maven modules, else the root package itself. */
|
|
51
|
+
export function containersOf(files, repo) {
|
|
52
|
+
const packages = workspaceDirs(files);
|
|
53
|
+
if (packages.length) return packages.map((d) => npmContainer(files, d, repo));
|
|
54
|
+
const modules = mavenModules(files);
|
|
55
|
+
if (modules.length) return modules.map((d) => mavenContainer(files, d));
|
|
56
|
+
return jsonOf(files, "package.json") ? [npmContainer(files, ".", repo)] : [];
|
|
33
57
|
}
|
|
34
58
|
|
|
35
59
|
const insideOf = (dir, path) => (dir === "." ? path : path.slice(dir.length + 1));
|
|
36
60
|
|
|
37
61
|
/** The container a repo path belongs to: the deepest directory that contains it. */
|
|
38
|
-
export const containerOfPath = (containers, path) =>
|
|
62
|
+
export const containerOfPath = (containers, path) =>
|
|
63
|
+
[...containers]
|
|
64
|
+
.sort((a, b) => b.dir.length - a.dir.length)
|
|
65
|
+
.find((c) => c.dir === "." || path.startsWith(`${c.dir}/`));
|
|
39
66
|
|
|
40
67
|
/** The component of a path inside its container: the first folder under `src/` (or the container root), `root` for loose files. */
|
|
41
68
|
export function componentOf(container, path) {
|
|
42
|
-
const segments = insideOf(container.dir, path)
|
|
69
|
+
const segments = insideOf(container.dir, path)
|
|
70
|
+
.replace(/^src\//, "")
|
|
71
|
+
.split("/");
|
|
43
72
|
return segments.length < 2 ? "root" : segments[0];
|
|
44
73
|
}
|
|
45
74
|
|
|
46
|
-
const factsOf = (
|
|
75
|
+
const factsOf = (files, containers, path) => {
|
|
47
76
|
const container = containerOfPath(containers, path);
|
|
48
77
|
if (!container) return undefined;
|
|
49
|
-
const source =
|
|
78
|
+
const source = textOf(files, path);
|
|
50
79
|
const imports = specifiersOf(source).flatMap((spec) => {
|
|
51
80
|
const name = packageOf(spec);
|
|
52
81
|
if (name) return [{ kind: "package", name }];
|
|
53
82
|
const target = localTarget(spec, path, container.dir);
|
|
54
83
|
return target ? [{ kind: "local", target }] : [];
|
|
55
84
|
});
|
|
56
|
-
return {
|
|
85
|
+
return {
|
|
86
|
+
path,
|
|
87
|
+
container: container.dir,
|
|
88
|
+
component: componentOf(container, path),
|
|
89
|
+
imports,
|
|
90
|
+
envs: envNamesOf(source, { declaration: false }),
|
|
91
|
+
};
|
|
57
92
|
};
|
|
58
93
|
|
|
59
|
-
const declarationsOf = (
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
94
|
+
const declarationsOf = (files, containers, paths) =>
|
|
95
|
+
paths.flatMap((path) => {
|
|
96
|
+
const container = containerOfPath(containers, path);
|
|
97
|
+
return container
|
|
98
|
+
? [{ path, container: container.dir, names: envNamesOf(textOf(files, path), { declaration: true }) }]
|
|
99
|
+
: [];
|
|
100
|
+
});
|
|
63
101
|
|
|
64
|
-
/** Everything the C4 levels are built from. */
|
|
65
|
-
export function scan(
|
|
66
|
-
const repo =
|
|
67
|
-
const containers = containersOf(
|
|
68
|
-
const found =
|
|
69
|
-
|
|
70
|
-
|
|
102
|
+
/** Everything the C4 levels are built from: `name` is the repository's name when its root package.json has none. */
|
|
103
|
+
export function scan(files, name) {
|
|
104
|
+
const repo = jsonOf(files, "package.json")?.name ?? name;
|
|
105
|
+
const containers = containersOf(files, repo);
|
|
106
|
+
const found = classify(files);
|
|
107
|
+
return {
|
|
108
|
+
repo,
|
|
109
|
+
containers,
|
|
110
|
+
units: unitsOf(files),
|
|
111
|
+
files: found.code.map((p) => factsOf(files, containers, p)).filter(Boolean),
|
|
112
|
+
declarations: declarationsOf(files, containers, found.env),
|
|
113
|
+
testCount: found.tests.length,
|
|
114
|
+
};
|
|
71
115
|
}
|
package/src/text.mjs
CHANGED
|
@@ -20,6 +20,15 @@ function edgeLines(level) {
|
|
|
20
20
|
}
|
|
21
21
|
|
|
22
22
|
export function toText(c4) {
|
|
23
|
-
const blocks = Object.values(c4.levels).map((level) =>
|
|
23
|
+
const blocks = Object.values(c4.levels).map((level) =>
|
|
24
|
+
[
|
|
25
|
+
`## ${TITLES[level.level]}`,
|
|
26
|
+
"",
|
|
27
|
+
...level.nodes.map(nodeLine),
|
|
28
|
+
"",
|
|
29
|
+
...(level.edges.length ? ["Relations", ...edgeLines(level)] : ["No relation found."]),
|
|
30
|
+
"",
|
|
31
|
+
].join("\n"),
|
|
32
|
+
);
|
|
24
33
|
return `# ${c4.repo}: C4 from the code\n\n${blocks.join("\n")}`;
|
|
25
34
|
}
|
package/src/units.mjs
ADDED
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
// The units of one repository, read from its manifests with their own parsers (ADR-026: no regex over a structured format).
|
|
2
|
+
// A unit is a package.json of the workspace, a module of the Maven reactor, a crate or a Python project; each carries the org
|
|
3
|
+
// dependencies it declares (`@krizaka/*`, `com.krizaka*`, `krizaka-*` crates, `krizaka*` Python packages) with the version
|
|
4
|
+
// that builds it: the lockfile's for npm, the pin otherwise.
|
|
5
|
+
import { XMLParser } from "fast-xml-parser";
|
|
6
|
+
import { parse as parseToml } from "smol-toml";
|
|
7
|
+
import { parse as parseYaml } from "yaml";
|
|
8
|
+
|
|
9
|
+
import { asc } from "./order.mjs";
|
|
10
|
+
|
|
11
|
+
const NPM_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
|
|
12
|
+
const CARGO_FIELDS = ["dependencies", "dev-dependencies", "build-dependencies"];
|
|
13
|
+
const SKIPPED_DIRS = new Set([
|
|
14
|
+
"node_modules",
|
|
15
|
+
"target",
|
|
16
|
+
"dist",
|
|
17
|
+
"build",
|
|
18
|
+
".next",
|
|
19
|
+
"fixtures",
|
|
20
|
+
"__fixtures__",
|
|
21
|
+
"vendor",
|
|
22
|
+
]);
|
|
23
|
+
const PLAIN = /^(?:\^|~|>=)?(\d+\.\d+\.\d+)$/;
|
|
24
|
+
const PEP508_NAME = /^[A-Za-z0-9][\w.-]*/;
|
|
25
|
+
const PROPERTY = /^\$\{([\w.-]+)\}$/;
|
|
26
|
+
const NODE_MODULES = "node_modules/";
|
|
27
|
+
const xml = new XMLParser({
|
|
28
|
+
ignoreAttributes: true,
|
|
29
|
+
parseTagValue: false,
|
|
30
|
+
isArray: (name) => name === "module" || name === "dependency",
|
|
31
|
+
});
|
|
32
|
+
|
|
33
|
+
/** Is a package an org package, per ecosystem? Maven ids are `groupId:artifactId`. */
|
|
34
|
+
export const isOrgPackage = {
|
|
35
|
+
npm: (name) => name.startsWith("@krizaka/"),
|
|
36
|
+
maven: (id) => id.startsWith("com.krizaka:") || id.startsWith("com.krizaka."),
|
|
37
|
+
cargo: (name) => name.startsWith("krizaka-"),
|
|
38
|
+
python: (name) => name.toLowerCase().startsWith("krizaka"),
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
/** "0.19.0" from "^0.19.0", "~0.19.0", ">=0.19.0" or "0.19.0"; null for `workspace:`, tags, git or complex ranges. */
|
|
42
|
+
export const baseVersion = (range) => PLAIN.exec(String(range ?? "").trim())?.[1] ?? null;
|
|
43
|
+
|
|
44
|
+
const dirOf = (path) => (path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : ".");
|
|
45
|
+
const joinPath = (dir, rel) => (dir === "." ? rel : `${dir}/${rel}`).replaceAll("/./", "/").replace(/\/$/, "");
|
|
46
|
+
const skipped = (path) => path.split("/").some((part) => SKIPPED_DIRS.has(part));
|
|
47
|
+
const byKey = (key) => (a, b) => asc(a[key] ?? "", b[key] ?? "");
|
|
48
|
+
const manifestsNamed = (files, name) =>
|
|
49
|
+
[...files.keys()].filter((p) => (p === name || p.endsWith(`/${name}`)) && !skipped(p)).sort(asc);
|
|
50
|
+
|
|
51
|
+
function safely(parse, text) {
|
|
52
|
+
try {
|
|
53
|
+
return parse(text);
|
|
54
|
+
} catch {
|
|
55
|
+
return null;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const parseJson = (text) => safely(JSON.parse, text ?? "");
|
|
60
|
+
|
|
61
|
+
/** Does a directory match a workspace glob (`apps/*`, `packages/**`, `deploy/backup`)? */
|
|
62
|
+
export function globMatches(glob, dir) {
|
|
63
|
+
const want = glob.replace(/^\.\//, "").replace(/\/$/, "").split("/");
|
|
64
|
+
const have = dir.split("/");
|
|
65
|
+
const walk = (i, j) => {
|
|
66
|
+
if (i === want.length) return j === have.length;
|
|
67
|
+
if (want[i] === "**") return [...new Array(have.length - j + 1).keys()].some((k) => walk(i + 1, j + k));
|
|
68
|
+
return j < have.length && (want[i] === "*" || want[i] === have[j]) && walk(i + 1, j + 1);
|
|
69
|
+
};
|
|
70
|
+
return walk(0, 0);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function workspaceGlobs(files) {
|
|
74
|
+
const pnpm = safely(parseYaml, files.get("pnpm-workspace.yaml") ?? "");
|
|
75
|
+
const root = parseJson(files.get("package.json"));
|
|
76
|
+
const fromRoot = Array.isArray(root?.workspaces) ? root.workspaces : root?.workspaces?.packages;
|
|
77
|
+
return (pnpm?.packages ?? fromRoot ?? []).filter((g) => typeof g === "string");
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Versions by unit path and package, filled once per pair. */
|
|
81
|
+
class Locked {
|
|
82
|
+
#map = new Map();
|
|
83
|
+
put(unit, name, version) {
|
|
84
|
+
if (!isOrgPackage.npm(name) || !baseVersion(version)) return;
|
|
85
|
+
const byName = this.#map.get(unit) ?? new Map();
|
|
86
|
+
if (!byName.has(name)) byName.set(name, version);
|
|
87
|
+
this.#map.set(unit, byName);
|
|
88
|
+
}
|
|
89
|
+
/** A unit's lookup: its own version, else the root's (a package hoisted at the root builds every workspace). */
|
|
90
|
+
of(unit) {
|
|
91
|
+
const own = this.#map.get(unit);
|
|
92
|
+
const root = this.#map.get(".");
|
|
93
|
+
return { get: (name) => own?.get(name) ?? root?.get(name) };
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function lockedByPnpm(text, locked) {
|
|
98
|
+
const importers = safely(parseYaml, text ?? "")?.importers ?? {};
|
|
99
|
+
for (const [unit, importer] of Object.entries(importers)) {
|
|
100
|
+
const entries = NPM_FIELDS.flatMap((field) => Object.entries(importer?.[field] ?? {}));
|
|
101
|
+
for (const [name, entry] of entries) {
|
|
102
|
+
const version = typeof entry === "string" ? entry : entry?.version;
|
|
103
|
+
locked.put(unit, name, String(version ?? "").split("(")[0]);
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
function lockedByNpm(text, locked) {
|
|
109
|
+
for (const [where, entry] of Object.entries(parseJson(text)?.packages ?? {})) {
|
|
110
|
+
const at = where.lastIndexOf(NODE_MODULES);
|
|
111
|
+
if (at < 0) continue;
|
|
112
|
+
const unit = at === 0 ? "." : where.slice(0, at - 1);
|
|
113
|
+
if (!unit.includes(NODE_MODULES.slice(0, -1)))
|
|
114
|
+
locked.put(unit, where.slice(at + NODE_MODULES.length), entry?.version);
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** The version the npm lockfile resolved, per unit: `pnpm-lock.yaml` importers, then `package-lock.json` packages. */
|
|
119
|
+
function lockedVersions(files) {
|
|
120
|
+
const locked = new Locked();
|
|
121
|
+
lockedByPnpm(files.get("pnpm-lock.yaml"), locked);
|
|
122
|
+
lockedByNpm(files.get("package-lock.json"), locked);
|
|
123
|
+
return locked;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function npmDeps(pkg, locked) {
|
|
127
|
+
const deps = new Map();
|
|
128
|
+
for (const field of NPM_FIELDS) {
|
|
129
|
+
for (const [name, range] of Object.entries(pkg?.[field] ?? {})) {
|
|
130
|
+
if (!isOrgPackage.npm(name) || deps.has(name)) continue;
|
|
131
|
+
const resolved = locked.get(name) ?? null;
|
|
132
|
+
deps.set(name, {
|
|
133
|
+
ecosystem: "npm",
|
|
134
|
+
name,
|
|
135
|
+
range: String(range),
|
|
136
|
+
have: resolved ?? baseVersion(range),
|
|
137
|
+
from: resolved ? "lockfile" : "range",
|
|
138
|
+
dev: field === "devDependencies",
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return [...deps.values()].sort(byKey("name"));
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** The npm units: the root package.json and every package.json the workspace globs name. */
|
|
146
|
+
function npmUnits(files) {
|
|
147
|
+
const globs = workspaceGlobs(files);
|
|
148
|
+
const include = globs.filter((g) => !g.startsWith("!"));
|
|
149
|
+
const exclude = globs.filter((g) => g.startsWith("!")).map((g) => g.slice(1));
|
|
150
|
+
const member = (dir) =>
|
|
151
|
+
dir === "." || (include.some((g) => globMatches(g, dir)) && !exclude.some((g) => globMatches(g, dir)));
|
|
152
|
+
const locked = lockedVersions(files);
|
|
153
|
+
const units = [];
|
|
154
|
+
for (const path of manifestsNamed(files, "package.json")) {
|
|
155
|
+
const dir = dirOf(path);
|
|
156
|
+
const pkg = member(dir) ? parseJson(files.get(path)) : null;
|
|
157
|
+
if (!pkg) continue;
|
|
158
|
+
const typed = files.has(joinPath(dir, "tsconfig.json")) || files.has("tsconfig.json");
|
|
159
|
+
units.push({
|
|
160
|
+
path: dir,
|
|
161
|
+
manifest: path,
|
|
162
|
+
ecosystem: "npm",
|
|
163
|
+
language: typed ? "typescript" : "javascript",
|
|
164
|
+
name: pkg.name ?? null,
|
|
165
|
+
version: pkg.version ?? null,
|
|
166
|
+
published: Boolean(pkg.name) && pkg.private !== true && isOrgPackage.npm(pkg.name),
|
|
167
|
+
dependsOn: npmDeps(pkg, locked.of(dir)),
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
return units;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
const text = (value) => (value === undefined || value === null ? null : String(value).trim());
|
|
174
|
+
const listOf = (value) => (Array.isArray(value) ? value : [value].filter(Boolean));
|
|
175
|
+
|
|
176
|
+
function resolveProperty(value, props) {
|
|
177
|
+
const ref = PROPERTY.exec(value ?? "");
|
|
178
|
+
return ref ? text(props[ref[1]]) : text(value);
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** The artifactId of every `<dependency>` anywhere in a parsed POM (dependencies, management, plugins, profiles). */
|
|
182
|
+
function everyDependency(node, out = []) {
|
|
183
|
+
if (Array.isArray(node)) node.forEach((child) => everyDependency(child, out));
|
|
184
|
+
else if (node && typeof node === "object") {
|
|
185
|
+
for (const [key, child] of Object.entries(node)) {
|
|
186
|
+
if (key === "dependency") listOf(child).forEach((d) => d?.artifactId && out.push(text(d.artifactId)));
|
|
187
|
+
everyDependency(child, out);
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
return out;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function mavenDep(id, version, extra = {}) {
|
|
194
|
+
return {
|
|
195
|
+
ecosystem: "maven",
|
|
196
|
+
name: id,
|
|
197
|
+
range: version ?? "managed",
|
|
198
|
+
have: baseVersion(version),
|
|
199
|
+
from: "range",
|
|
200
|
+
dev: false,
|
|
201
|
+
...extra,
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
function pomDeps(project, parent) {
|
|
206
|
+
const props = project.properties ?? {};
|
|
207
|
+
// A BOM's managed list is not a dependency; an imported BOM is.
|
|
208
|
+
const imported = listOf(project.dependencyManagement?.dependencies?.dependency).filter(
|
|
209
|
+
(d) => text(d.scope) === "import",
|
|
210
|
+
);
|
|
211
|
+
const deps = new Map();
|
|
212
|
+
for (const dep of [...listOf(project.dependencies?.dependency), ...imported]) {
|
|
213
|
+
const id = `${resolveProperty(text(dep.groupId), props)}:${text(dep.artifactId)}`;
|
|
214
|
+
if (isOrgPackage.maven(id) && !deps.has(id))
|
|
215
|
+
deps.set(id, mavenDep(id, resolveProperty(text(dep.version), props), { dev: text(dep.scope) === "test" }));
|
|
216
|
+
}
|
|
217
|
+
if (parent && isOrgPackage.maven(parent.id))
|
|
218
|
+
deps.set(parent.id, mavenDep(parent.id, parent.version, { parent: true }));
|
|
219
|
+
return [...deps.values()].sort(byKey("name"));
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* One pom.xml: its coordinates (`id` is `groupId:artifactId`), description, packaging, modules, the org dependencies (an
|
|
224
|
+
* imported BOM and the org parent included) and the artifactId of every dependency it names. null when it does not parse.
|
|
225
|
+
*/
|
|
226
|
+
export function readPom(body) {
|
|
227
|
+
const project = safely((t) => xml.parse(t), body ?? "")?.project;
|
|
228
|
+
if (!project || typeof project !== "object") return null;
|
|
229
|
+
const parent = project.parent
|
|
230
|
+
? {
|
|
231
|
+
id: `${text(project.parent.groupId)}:${text(project.parent.artifactId)}`,
|
|
232
|
+
version: text(project.parent.version),
|
|
233
|
+
}
|
|
234
|
+
: null;
|
|
235
|
+
const groupId = text(project.groupId) ?? text(project.parent?.groupId);
|
|
236
|
+
return {
|
|
237
|
+
id: `${groupId}:${text(project.artifactId)}`,
|
|
238
|
+
artifactId: text(project.artifactId),
|
|
239
|
+
description: text(project.description) ?? "",
|
|
240
|
+
version: text(project.version) ?? parent?.version ?? null,
|
|
241
|
+
packaging: text(project.packaging) ?? "jar",
|
|
242
|
+
modules: listOf(project.modules?.module).map(text).filter(Boolean),
|
|
243
|
+
dependsOn: pomDeps(project, parent),
|
|
244
|
+
dependencyIds: everyDependency(project),
|
|
245
|
+
};
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** The Maven units: the root pom.xml and its modules, recursively (a module whose pom is not in the files is left out). */
|
|
249
|
+
function mavenUnits(files) {
|
|
250
|
+
const units = [];
|
|
251
|
+
const seen = new Set();
|
|
252
|
+
const visit = (dir) => {
|
|
253
|
+
const manifest = joinPath(dir, "pom.xml");
|
|
254
|
+
if (seen.has(manifest) || !files.has(manifest)) return;
|
|
255
|
+
seen.add(manifest);
|
|
256
|
+
const pom = readPom(files.get(manifest));
|
|
257
|
+
if (!pom) return;
|
|
258
|
+
units.push({
|
|
259
|
+
path: dir,
|
|
260
|
+
manifest,
|
|
261
|
+
ecosystem: "maven",
|
|
262
|
+
language: "java",
|
|
263
|
+
name: pom.id,
|
|
264
|
+
version: pom.version,
|
|
265
|
+
packaging: pom.packaging,
|
|
266
|
+
published: isOrgPackage.maven(pom.id),
|
|
267
|
+
dependsOn: pom.dependsOn,
|
|
268
|
+
modules: pom.modules.map((m) => joinPath(dir, m)),
|
|
269
|
+
});
|
|
270
|
+
pom.modules.forEach((m) => visit(joinPath(dir, m)));
|
|
271
|
+
};
|
|
272
|
+
visit(".");
|
|
273
|
+
return units;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
function cargoRange(spec) {
|
|
277
|
+
if (typeof spec === "string") return spec;
|
|
278
|
+
return String(spec?.version ?? spec?.tag ?? spec?.rev ?? "git");
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
function cargoDeps(manifest) {
|
|
282
|
+
const deps = new Map();
|
|
283
|
+
for (const field of CARGO_FIELDS) {
|
|
284
|
+
for (const [name, spec] of Object.entries(manifest?.[field] ?? {})) {
|
|
285
|
+
if (!isOrgPackage.cargo(name) || deps.has(name)) continue;
|
|
286
|
+
const range = cargoRange(spec);
|
|
287
|
+
const dev = field === "dev-dependencies";
|
|
288
|
+
deps.set(name, {
|
|
289
|
+
ecosystem: "cargo",
|
|
290
|
+
name,
|
|
291
|
+
range,
|
|
292
|
+
have: baseVersion(range.replace(/^v/, "")),
|
|
293
|
+
from: "range",
|
|
294
|
+
dev,
|
|
295
|
+
});
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
return [...deps.values()].sort(byKey("name"));
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/** The crates: every Cargo.toml with a [package] (a bare [workspace] root is not a unit). */
|
|
302
|
+
function cargoUnits(files) {
|
|
303
|
+
const units = [];
|
|
304
|
+
for (const path of manifestsNamed(files, "Cargo.toml")) {
|
|
305
|
+
const pkg = safely(parseToml, files.get(path) ?? "")?.package;
|
|
306
|
+
if (!pkg?.name) continue;
|
|
307
|
+
units.push({
|
|
308
|
+
path: dirOf(path),
|
|
309
|
+
manifest: path,
|
|
310
|
+
ecosystem: "cargo",
|
|
311
|
+
language: "rust",
|
|
312
|
+
name: pkg.name,
|
|
313
|
+
version: typeof pkg.version === "string" ? pkg.version : null,
|
|
314
|
+
published: isOrgPackage.cargo(pkg.name) && pkg.publish !== false,
|
|
315
|
+
dependsOn: cargoDeps(safely(parseToml, files.get(path))),
|
|
316
|
+
});
|
|
317
|
+
}
|
|
318
|
+
return units;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
function pythonDeps(lines) {
|
|
322
|
+
const deps = new Map();
|
|
323
|
+
for (const line of lines.map((l) => String(l).trim())) {
|
|
324
|
+
const name = PEP508_NAME.exec(line)?.[0];
|
|
325
|
+
if (!name || !isOrgPackage.python(name) || deps.has(name)) continue;
|
|
326
|
+
deps.set(name, {
|
|
327
|
+
ecosystem: "python",
|
|
328
|
+
name,
|
|
329
|
+
range: line.slice(name.length).trim(),
|
|
330
|
+
have: null,
|
|
331
|
+
from: "range",
|
|
332
|
+
dev: false,
|
|
333
|
+
});
|
|
334
|
+
}
|
|
335
|
+
return [...deps.values()].sort(byKey("name"));
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
const pythonUnit = (path, name, version, dependsOn) => ({
|
|
339
|
+
path: dirOf(path),
|
|
340
|
+
manifest: path,
|
|
341
|
+
ecosystem: "python",
|
|
342
|
+
language: "python",
|
|
343
|
+
name,
|
|
344
|
+
version,
|
|
345
|
+
published: Boolean(name) && isOrgPackage.python(name),
|
|
346
|
+
dependsOn,
|
|
347
|
+
});
|
|
348
|
+
|
|
349
|
+
/** The Python projects: every pyproject.toml with a [project], else a requirements.txt in a folder of its own. */
|
|
350
|
+
function pythonUnits(files) {
|
|
351
|
+
const units = [];
|
|
352
|
+
for (const path of manifestsNamed(files, "pyproject.toml")) {
|
|
353
|
+
const project = safely(parseToml, files.get(path) ?? "")?.project;
|
|
354
|
+
if (project?.name)
|
|
355
|
+
units.push(pythonUnit(path, project.name, project.version ?? null, pythonDeps(project.dependencies ?? [])));
|
|
356
|
+
}
|
|
357
|
+
const dirs = new Set(units.map((u) => u.path));
|
|
358
|
+
for (const path of manifestsNamed(files, "requirements.txt").filter((p) => !dirs.has(dirOf(p)))) {
|
|
359
|
+
units.push(pythonUnit(path, null, null, pythonDeps((files.get(path) ?? "").split("\n"))));
|
|
360
|
+
}
|
|
361
|
+
return units;
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
/** Every unit of a repository, sorted by path then ecosystem: the same files give the same list. */
|
|
365
|
+
export function unitsOf(files) {
|
|
366
|
+
return [...npmUnits(files), ...mavenUnits(files), ...cargoUnits(files), ...pythonUnits(files)].sort(
|
|
367
|
+
(a, b) => asc(a.path, b.path) || asc(a.ecosystem, b.ecosystem),
|
|
368
|
+
);
|
|
369
|
+
}
|