@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 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, first slice; ADR-013: one source per rule set).
4
- Dependency-free (Node built-ins), it runs on a local checkout and gives the same output wherever it runs, so the docs, krizaka.com and
5
- the founder cockpit all show the architecture of the code, not of what is deployed.
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 | Nodes | Edges |
21
- | :--- | :--- | :--- |
22
- | `context` | the system (the repo) and what it reaches: external services, Krizaka libraries | system `reads` an external service, `uses` the libraries |
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 | component `imports` component (relative and `@/` imports), `uses` a container, `reads` an external service |
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(execFileSync("npx", ["--yes", "@krizaka/architecture", repoPath, "--level", "containers"], { encoding: "utf8" }));
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 yet: SonarQube Architecture (intended architecture and deviations), and rendering on krizaka.com / the docs.
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.0",
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. Dependency-free, runs on a local checkout, writes JSON and a text version.",
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.14.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 checkout: `{ level, nodes, edges }` each.
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 { id, level, kind, name, description: extra.description ?? "", technology: extra.technology, files: files.slice(0, FILE_CAP), fileCount: extra.fileCount ?? files.length };
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) => `${a.from}|${a.to}|${a.label}`.localeCompare(`${b.from}|${b.to}|${b.label}`));
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 }]) => node(externalId(ctx), "external", "external", EXTERNALS[ctx], { description: `Configured by ${[...names].sort(asc).join(", ")}`, 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) edges.add(containerId(c), containerId(byName.get(dep)), "uses", [c.manifest]);
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) importedContainers(facts, byName, f).forEach((to) => edges.add(containerId(to.from), containerId(to.target), "uses", [f.path]));
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([...facts.containers.flatMap((c) => c.deps), ...facts.files.flatMap((f) => f.imports.filter((i) => i.kind === "package").map((i) => i.name))].filter((n) => isLibrary(n, byName)));
112
- return used.size ? [node(LIBRARIES, "external", "external", "Krizaka libraries", { description: [...used].sort(asc).join(", ") })] : [];
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) => facts.containers.map((c) => {
116
- const own = facts.files.filter((f) => f.container === c.dir).map((f) => f.path);
117
- return node(containerId(c), "container", c.kind, c.name, { description: c.description, technology: c.technology, files: [c.manifest, ...own], fileCount: own.length + 1 });
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 { level: "containers", nodes: [...containerNodes(facts), ...externals, ...libraryNode(facts)].sort(byId), edges: containerEdges(facts, use).list() };
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, { description: `${facts.containers.length} container(s)`, files: facts.containers.map((c) => c.manifest) });
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:"))) edges.add(system.id, e.to, e.label, e.files);
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]) => node(id, "component", "component", g.name, { description: g.c.name, technology: g.c.technology, files: g.files }));
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)))) edges.add(from, externalId(contextOf(n)), "reads", [f.path]);
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
- /** The C4 view of a checkout: `{ schema, repo, levels: { context, containers, components } }`, deterministic. */
180
- export function buildC4(root) {
181
- const facts = scan(root);
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 { schema: SCHEMA, repo: facts.repo, levels: { context: contextLevel(facts, use, containers), containers, components: componentLevel(facts, use, containers) } };
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("usage: krizaka-architecture <repo-path> [--out file.json] [--level context|containers|components] [--text [file.md]]");
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).map((l) => l.nodes.length + " " + l.level + " node(s)").join(", ");
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
- // Reading a checkout: the files worth looking at and the workspace layout. Node built-ins only.
2
- import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
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(["node_modules", ".git", "dist", "build", ".next", ".turbo", "coverage", "out", "target", ".open-next", ".expo", ".cache", ".venv"]);
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
- export const readText = (path) => {
45
+ const readCapped = (path, cap) => {
14
46
  try {
15
- return statSync(path).size > MAX_BYTES ? "" : readFileSync(path, "utf8");
47
+ return statSync(path).size > cap ? "" : readFileSync(path, "utf8");
16
48
  } catch {
17
49
  return "";
18
50
  }
19
51
  };
20
52
 
21
- export const readJson = (path) => {
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
- export function walk(root, rel = "", out = listing()) {
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)) walk(root, path, out);
37
- } else if (ENV_FILES.test(entry.name)) {
38
- out.env.push(path);
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 yamlPackages = (yaml) => {
47
- const lines = yaml.split("\n");
48
- const start = lines.findIndex((l) => /^packages:\s*$/.test(l));
49
- if (start < 0) return [];
50
- const found = [];
51
- for (const line of lines.slice(start + 1)) {
52
- const m = /^\s*-\s*['"]?([^'"#\s]+)['"]?/.exec(line);
53
- if (m) found.push(m[1]);
54
- else if (/^\S/.test(line)) break;
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 subdirs = (root, rel) => {
91
+ const yamlPackages = (text) => {
60
92
  try {
61
- return readdirSync(join(root, rel), { withFileTypes: true }).filter((e) => e.isDirectory() && !SKIP_DIRS.has(e.name)).map((e) => posix.join(rel, e.name));
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 expand = (root, pattern) => {
68
- const clean = pattern.replace(/^\.\//, "").replace(/\/\*\*$/, "/*").replace(/\/$/, "");
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("/*") ? subdirs(root, clean.slice(0, -2)) : [clean];
71
- return dirs.filter((d) => existsSync(join(root, d, "package.json")));
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(root) {
76
- const pkg = readJson(join(root, "package.json"));
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(readText(join(root, "pnpm-workspace.yaml")))];
79
- const excluded = new Set(patterns.filter((p) => p.startsWith("!")).flatMap((p) => expand(root, p.slice(1))));
80
- return [...new Set(patterns.filter((p) => !p.startsWith("!")).flatMap((p) => expand(root, p)))].filter((d) => !excluded.has(d)).sort(asc);
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(root) {
85
- const pom = readText(join(root, "pom.xml"));
86
- return [...pom.matchAll(/<module>\s*([^<\s]+)\s*<\/module>/g)].map((m) => posix.normalize(m[1])).filter((d) => existsSync(join(root, d, "pom.xml"))).sort(asc);
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) => SPECIFIERS.flatMap((re) => [...source.matchAll(re)]).sort((a, b) => a.index - b.index).map((m) => m[1]);
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 ? [...source.matchAll(ENV_NAME)].map((m) => m[1]) : [...source.matchAll(PROCESS_ENV)].map((m) => m[1]).filter((n) => ENV_ONLY.test(n));
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
@@ -1,2 +1,3 @@
1
- export { buildC4, SCHEMA } from "./c4.mjs";
1
+ export { buildC4, buildC4FromFiles, SCHEMA } from "./c4.mjs";
2
2
  export { toText } from "./text.mjs";
3
+ export { baseVersion, globMatches, isOrgPackage, unitsOf } from "./units.mjs";
package/src/scan.mjs CHANGED
@@ -1,71 +1,115 @@
1
- // The facts of a checkout: its containers (workspace packages or Maven modules), its source files with what each imports and reads.
2
- import { basename, join, posix, resolve } from "node:path";
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 { mavenModules, readJson, readText, walk, workspaceDirs } from "./files.mjs";
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 = [["next", "Next.js", true], ["expo", "Expo", true], ["react-native", "React Native", true], ["vite", "Vite", true], ["express", "Express", true], ["fastify", "Fastify", true], ["hono", "Hono", true]];
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 = (root, dir) => {
10
- const pkg = readJson(join(root, dir, "package.json")) ?? {};
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 { dir, name: pkg.name ?? (dir === "." ? basename(resolve(root)) : posix.basename(dir)), description: pkg.description ?? "", kind: app ? "app" : "library", technology: framework?.[1] ?? "TypeScript", deps: Object.keys(deps), manifest: posix.join(dir, "package.json") };
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 artifactIds = (xml) => [...xml.matchAll(/<artifactId>\s*([^<\s]+)\s*<\/artifactId>/g)].map((m) => m[1]);
18
-
19
- const mavenContainer = (root, dir) => {
20
- const pom = readText(join(root, dir, "pom.xml"));
21
- const own = artifactIds(pom.replace(/<parent>[\s\S]*?<\/parent>/, "").replace(/<dependencies>[\s\S]*?<\/dependencies>/g, ""))[0];
22
- const deps = [...pom.matchAll(/<dependency>([\s\S]*?)<\/dependency>/g)].flatMap((m) => artifactIds(m[1]).slice(0, 1));
23
- return { dir, name: own ?? posix.basename(dir), description: (/<description>([^<]*)<\/description>/.exec(pom)?.[1] ?? "").trim(), kind: "module", technology: "Maven", deps, manifest: posix.join(dir, "pom.xml") };
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 checkout: workspace packages, else Maven modules, else the root package itself. */
27
- export function containersOf(root) {
28
- const packages = workspaceDirs(root);
29
- if (packages.length) return packages.map((d) => npmContainer(root, d));
30
- const modules = mavenModules(root);
31
- if (modules.length) return modules.map((d) => mavenContainer(root, d));
32
- return readJson(join(root, "package.json")) ? [npmContainer(root, ".")] : [];
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) => [...containers].sort((a, b) => b.dir.length - a.dir.length).find((c) => c.dir === "." || path.startsWith(`${c.dir}/`));
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).replace(/^src\//, "").split("/");
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 = (root, containers, path) => {
75
+ const factsOf = (files, containers, path) => {
47
76
  const container = containerOfPath(containers, path);
48
77
  if (!container) return undefined;
49
- const source = readText(join(root, path));
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 { path, container: container.dir, component: componentOf(container, path), imports, envs: envNamesOf(source, { declaration: false }) };
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 = (root, containers, paths) => paths.flatMap((path) => {
60
- const container = containerOfPath(containers, path);
61
- return container ? [{ path, container: container.dir, names: envNamesOf(readText(join(root, path)), { declaration: true }) }] : [];
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(root) {
66
- const repo = readJson(join(root, "package.json"))?.name ?? basename(resolve(root));
67
- const containers = containersOf(root);
68
- const found = walk(root);
69
- const files = found.code.map((p) => factsOf(root, containers, p)).filter(Boolean);
70
- return { repo, containers, files, declarations: declarationsOf(root, containers, found.env), testCount: found.tests.length };
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) => [`## ${TITLES[level.level]}`, "", ...level.nodes.map(nodeLine), "", ...(level.edges.length ? ["Relations", ...edgeLines(level)] : ["No relation found."]), ""].join("\n"));
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
+ }