@autotelic/joggle 0.0.0-stage → 0.1.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.
Files changed (101) hide show
  1. package/JOGGLE.md +634 -0
  2. package/LICENSE +21 -0
  3. package/README.md +88 -2
  4. package/bin/joggle.js +6 -0
  5. package/dist/answer-store.js +305 -0
  6. package/dist/architecture.js +190 -0
  7. package/dist/ask.js +184 -0
  8. package/dist/astro.js +75 -0
  9. package/dist/atoms.js +76 -0
  10. package/dist/bundles.js +156 -0
  11. package/dist/calibration.js +60 -0
  12. package/dist/candidates.js +561 -0
  13. package/dist/canonical.js +24 -0
  14. package/dist/cascade.js +98 -0
  15. package/dist/check.js +854 -0
  16. package/dist/cluster.js +69 -0
  17. package/dist/config.js +195 -0
  18. package/dist/content-mappers.js +83 -0
  19. package/dist/decision.js +203 -0
  20. package/dist/fingerprint.js +61 -0
  21. package/dist/git.js +127 -0
  22. package/dist/gitignore.js +65 -0
  23. package/dist/glob.js +51 -0
  24. package/dist/imports.js +153 -0
  25. package/dist/jsonc.js +95 -0
  26. package/dist/main.js +630 -0
  27. package/dist/manifest.js +42 -0
  28. package/dist/meta.js +170 -0
  29. package/dist/moves.js +47 -0
  30. package/dist/operation.js +133 -0
  31. package/dist/parsecache.js +264 -0
  32. package/dist/plans.js +425 -0
  33. package/dist/plugin.js +71 -0
  34. package/dist/plugins.js +136 -0
  35. package/dist/policy.js +676 -0
  36. package/dist/presets/composition.js +32 -0
  37. package/dist/report.js +474 -0
  38. package/dist/reporting.js +132 -0
  39. package/dist/result.js +28 -0
  40. package/dist/roles.js +303 -0
  41. package/dist/rule.js +194 -0
  42. package/dist/rules/append-only-honoured.js +190 -0
  43. package/dist/rules/bundle-conformance.js +245 -0
  44. package/dist/rules/call-pattern.js +209 -0
  45. package/dist/rules/cluster-verdict.js +700 -0
  46. package/dist/rules/compose-types.js +250 -0
  47. package/dist/rules/data-error-as-outage.js +482 -0
  48. package/dist/rules/declared-staleness.js +242 -0
  49. package/dist/rules/dependency-fit.js +297 -0
  50. package/dist/rules/deviation-has-a-shape.js +225 -0
  51. package/dist/rules/doc-matches-code.js +191 -0
  52. package/dist/rules/duplicate-call-run.js +240 -0
  53. package/dist/rules/duplicate-implementation.js +89 -0
  54. package/dist/rules/duplicate-meaning.js +130 -0
  55. package/dist/rules/fact-or-derivation.js +202 -0
  56. package/dist/rules/field-type-drift.js +373 -0
  57. package/dist/rules/generic-carries-a-caller.js +198 -0
  58. package/dist/rules/hoist-to-domain.js +288 -0
  59. package/dist/rules/import-architecture.js +393 -0
  60. package/dist/rules/index.js +105 -0
  61. package/dist/rules/inferred-over-recorded.js +214 -0
  62. package/dist/rules/intent-drift.js +286 -0
  63. package/dist/rules/invariant-has-a-reconciler.js +190 -0
  64. package/dist/rules/language-drift.js +234 -0
  65. package/dist/rules/meaning-switched-by-flag.js +189 -0
  66. package/dist/rules/module-direction.js +231 -0
  67. package/dist/rules/name-as-address.js +216 -0
  68. package/dist/rules/name-the-primitive.js +203 -0
  69. package/dist/rules/naming-drift.js +218 -0
  70. package/dist/rules/nullability-drift.js +220 -0
  71. package/dist/rules/object-shape.js +280 -0
  72. package/dist/rules/one-concept-one-type.js +243 -0
  73. package/dist/rules/page-needs-composition.js +227 -0
  74. package/dist/rules/reimplemented-primitive.js +283 -0
  75. package/dist/rules/reversal.js +264 -0
  76. package/dist/rules/rule-judgment.js +252 -0
  77. package/dist/rules/schema-excludes-domain-value.js +190 -0
  78. package/dist/rules/shallow-module.js +204 -0
  79. package/dist/rules/single-path.js +237 -0
  80. package/dist/rules/structural-collapse.js +198 -0
  81. package/dist/rules/temporal-coupling.js +205 -0
  82. package/dist/rules/types-over-logic.js +198 -0
  83. package/dist/rules/unaccounted-drop.js +190 -0
  84. package/dist/rules/unbounded-default-read.js +227 -0
  85. package/dist/run-cache.js +132 -0
  86. package/dist/schema.js +285 -0
  87. package/dist/similarity.js +119 -0
  88. package/dist/source.js +30 -0
  89. package/dist/sql.js +34 -0
  90. package/dist/stages.js +39 -0
  91. package/dist/state.js +65 -0
  92. package/dist/testing.js +131 -0
  93. package/dist/tsconfig-scope.js +32 -0
  94. package/dist/tsgo.js +127 -0
  95. package/dist/typefacts.js +455 -0
  96. package/dist/typetrace.js +283 -0
  97. package/dist/verdict.js +65 -0
  98. package/dist/vocabulary.js +365 -0
  99. package/dist/workspace.js +1963 -0
  100. package/extensions/joggle.ts +454 -0
  101. package/package.json +85 -3
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # joggle
4
+
5
+ **Cross-file judgements for a TypeScript codebase, enforced like a linter.**
6
+
7
+ [![CI](https://github.com/autotelic/joggle/actions/workflows/joggle.yml/badge.svg)](https://github.com/autotelic/joggle/actions/workflows/joggle.yml)
8
+
9
+ </div>
10
+
11
+ > "I want to build the entropy reverser — a big sausage machine where you put all
12
+ > programs into it and you turn the handle and a smaller number of programs come
13
+ > out."
14
+ >
15
+ > — Joe Armstrong, *The Mess We're In*, 2014
16
+
17
+ `tsc` checks one program. `oxlint` checks one file. joggle checks the codebase: it
18
+ indexes it into facts, generates candidates cheaply and deterministically, and asks
19
+ **Jev** the narrow questions a single file cannot answer. Are these two
20
+ declarations one thing? Does this name mean the same here as there? Is this the
21
+ primitive that already exists?
22
+
23
+ Every finding proposes one of three moves, and the report groups by them:
24
+
25
+ | move | what it says |
26
+ | --- | --- |
27
+ | **contract** | a primitive already exists; this is a second copy. Delete it and use the primitive. |
28
+ | **combine** | the primitives exist; the combination was never written. A refactor. |
29
+ | **expand** | neither: the vocabulary has to grow. A name, a type, a boundary. A design act. |
30
+
31
+ The order is a ratchet, and the report prints it that way: **the copies hide the
32
+ primitives**, so contract first, composing makes them explicit, and a new primitive
33
+ is built out of the ones you can now see. A live repository *should* be full of
34
+ these, because each is a place the code ran ahead of its vocabulary. **The number
35
+ is not the product.** [Why, and the three moves](./docs/thesis.md).
36
+
37
+ One rule is about promises rather than duplicates: `intent-drift` reads `@deprecated`
38
+ tags, checks that the replacement they name exists, and asks the model whether a live
39
+ import is a migration to finish or an intentional compatibility path. The facts stay
40
+ deterministic; only the "should this change?" question is judged.
41
+
42
+ ## Jev
43
+
44
+ A judgement model, not a generator. It answers typed questions (yes or no, a choice
45
+ among named options, a spectrum) with calibrated probabilities, and code keeps the
46
+ thresholds: a decisive answer prints, an unsure one is recorded as a notice, a no is
47
+ silent. Arithmetic, counts, spans and orderings all stay in code.
48
+
49
+ Verdicts are cached per question in `.joggle/answers/`, one sharded file per key
50
+ prefix, so commit that directory and CI replays every judgement with no key and no
51
+ tokens. The shards are line-oriented and keyed, so a branch merge is a directory
52
+ merge, and `joggle cache prune` keeps them from growing without a ceiling. A yes/no is asked three times
53
+ and the **agreement** across the asks becomes its confidence, because one number on
54
+ its own has no margin. [How joggle uses TypeSafe](./docs/typesafe.md).
55
+
56
+ The evidence panel, including source excerpts, goes to `api.typesafe.ai`. Nothing
57
+ else does, and `--offline` sends nothing at all.
58
+
59
+ ## Run it
60
+
61
+ ```sh
62
+ pnpm install && pnpm build
63
+ npm link # puts `joggle` on PATH
64
+ joggle rules # what this repository enforces, by move
65
+ joggle check src # or no paths: tsgo says what the project is
66
+ TYPESAFE_API_KEY=… joggle check src # the judged rules need the key
67
+ joggle check --offline # replay the committed verdicts, no key
68
+ ```
69
+
70
+ As a **pi extension** (`pi.extensions` → `./extensions`), so pi can run it in
71
+ whatever repository it is working in:
72
+
73
+ ```sh
74
+ pi install /absolute/path/to/joggle # global: adds the tools and the command
75
+ pi -e /absolute/path/to/joggle # one run, no install
76
+ ```
77
+
78
+ That adds `joggle_check`, `joggle_rules`, and `/joggle`.
79
+
80
+ ## Docs
81
+
82
+ [thesis.md](./docs/thesis.md) what it is for ·
83
+ [writing-rules.md](./docs/writing-rules.md) write a rule ·
84
+ [rule-coupling.md](./docs/rule-coupling.md) the audit of every rule ·
85
+ [calibration.md](./docs/calibration.md) what the questions are worth ·
86
+ [JOGGLE.md](./JOGGLE.md) the architecture ·
87
+ [docs/](./docs/README.md) everything else.
88
+
89
+ MIT.
package/bin/joggle.js ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env node
2
+ // The installed entry point. It runs the build, not the source, because Node
3
+ // refuses to strip types for files under node_modules -- which is exactly where
4
+ // this file lives once the package is installed. `pnpm build` produces dist/;
5
+ // `pnpm joggle` runs the source directly with the development export condition.
6
+ import "../dist/main.js"
@@ -0,0 +1,305 @@
1
+ import { Clock, Effect, FileSystem, Option, Order, Path, Ref, Result, Schema, SchemaParser, Semaphore } from "effect";
2
+ import { canonical } from "./canonical.js";
3
+ import { StoredAnswer } from "./plans.js";
4
+ /**
5
+ * The answer cache, as a sharded content-addressed store.
6
+ *
7
+ * One file per shard, one entry per line, and the shard is a function of the
8
+ * key alone. The key (`answerKeyFor`) already content-addresses the decision,
9
+ * the atoms it read, the model and the decision version, so two branches that
10
+ * judge different candidates write different shards -- or, when they collide on
11
+ * a shard, different lines. That is the whole design: a merge is a directory
12
+ * merge, and the residual collision is a same-line one, which the shipped merge
13
+ * driver (`joggle merge-answers`) resolves by key.
14
+ *
15
+ * The shape is Bazel's: sharded content-addressed storage, written
16
+ * deterministically (lines sorted by key) so a diff is the change and not the
17
+ * reordering, JSONL rather than pretty-printed JSON so the file is line-oriented
18
+ * and can merge at all. The prior art and the reasoning are in
19
+ * `docs/artifacts.md`.
20
+ *
21
+ * The single `answers.json` written before the shard split is still read, and
22
+ * the first write migrates it: every shard is written, then the old file is
23
+ * removed. A reader that never writes leaves it alone.
24
+ */
25
+ // How many leading hex characters name a shard. 256 files is enough granularity.
26
+ const SHARD_CHARS = 2;
27
+ /** The shard a key belongs to: its first two characters, lower-cased. */
28
+ export const shardOf = (key) => key.slice(0, SHARD_CHARS).toLowerCase().padEnd(SHARD_CHARS, "_");
29
+ /** The directory holding the shards, beside the single-file form. */
30
+ export const answersDir = (path, dir) => path.join(dir, "answers");
31
+ const singleFile = (path, dir) => path.join(dir, "answers.json");
32
+ /**
33
+ * The attributes joggle manages for the cache directory itself.
34
+ *
35
+ * Git reads a `.gitattributes` in a subdirectory and applies its patterns
36
+ * relative to that directory, so joggle can own the treatment of its own files
37
+ * without touching the repository's top-level file. `-diff` keeps the shards out
38
+ * of a diff (they are generated), `linguist-generated` keeps them out of GitHub
39
+ * language stats, and `merge=joggle-answers` names the merge driver.
40
+ */
41
+ const ATTRIBUTES = "answers/*.jsonl merge=joggle-answers linguist-generated -diff\n" +
42
+ "answers.json linguist-generated -diff\n";
43
+ /** The shape of the single file, read once for the migration. */
44
+ const SingleFile = Schema.Struct({
45
+ version: Schema.String,
46
+ entries: Schema.Record(Schema.String, StoredAnswer),
47
+ });
48
+ const decodeAnswer = Schema.fromJsonString(StoredAnswer);
49
+ /**
50
+ * One line: `<key>\t<unix-seconds>\t<json>`. A tab cannot appear unescaped in
51
+ * any of the three fields, so the split is unambiguous.
52
+ */
53
+ export const renderEntry = (entry) => entry.key + "\t" + entry.writtenAt + "\t" + canonical(entry.answer);
54
+ /** Parse a shard. A line that does not decode is skipped and COUNTED, never fatal. */
55
+ export const parseLines = (text) => {
56
+ const entries = [];
57
+ let skippedLines = 0;
58
+ for (const line of text.split("\n")) {
59
+ if (line === "")
60
+ continue;
61
+ const first = line.indexOf("\t");
62
+ const second = line.indexOf("\t", first + 1);
63
+ if (first < 0 || second < 0) {
64
+ skippedLines += 1;
65
+ continue;
66
+ }
67
+ const writtenAt = Number(line.slice(first + 1, second));
68
+ const answer = Result.getOrUndefined(SchemaParser.decodeResult(decodeAnswer)(line.slice(second + 1)));
69
+ if (answer === undefined || !Number.isFinite(writtenAt)) {
70
+ skippedLines += 1;
71
+ continue;
72
+ }
73
+ entries.push({ key: line.slice(0, first), writtenAt, answer });
74
+ }
75
+ return { entries, skippedLines };
76
+ };
77
+ const byKey = Order.mapInput(Order.String, (entry) => entry.key);
78
+ /** A shard body: entries sorted by key, newline-terminated. */
79
+ export const renderShard = (entries) => {
80
+ const sorted = [...entries].sort(byKey);
81
+ return sorted.length === 0 ? "" : sorted.map(renderEntry).join("\n") + "\n";
82
+ };
83
+ /**
84
+ * Union two sides of one shard by key.
85
+ *
86
+ * A key that only one side carries is kept. A key both sides carry with
87
+ * different content keeps the newer timestamp: for a content-addressed key the
88
+ * two answers should be identical, and the timestamp is the only signal that
89
+ * says which the model produced last. Ties keep ours.
90
+ */
91
+ export const mergeEntries = ({ ours, theirs, }) => {
92
+ const merged = new Map();
93
+ for (const entry of ours)
94
+ merged.set(entry.key, entry);
95
+ for (const entry of theirs) {
96
+ const existing = merged.get(entry.key);
97
+ if (existing === undefined || entry.writtenAt > existing.writtenAt)
98
+ merged.set(entry.key, entry);
99
+ }
100
+ return [...merged.values()];
101
+ };
102
+ /**
103
+ * A side of a merge that is not a shard at all.
104
+ *
105
+ * A tagged error rather than `Option.none`, because the reason is the whole
106
+ * value: "ours" or "theirs" is what the driver prints and what a person acts on.
107
+ */
108
+ export class NotAShard extends Schema.TaggedError()("joggle/NotAShard", {
109
+ side: Schema.String,
110
+ }) {
111
+ }
112
+ /**
113
+ * A merge of one shard, failing when a non-empty side is not a shard at all.
114
+ *
115
+ * Failing is how the driver declines: git then records an ordinary conflict,
116
+ * which is recoverable, instead of a union that silently dropped lines. Every
117
+ * line is either present or not, and a content-addressed key means the two sides
118
+ * cannot substantively disagree, so there is no base to consult.
119
+ */
120
+ export const mergeShardText = (text) => Effect.gen(function* () {
121
+ const ourEntries = parseLines(text.ours).entries;
122
+ const theirEntries = parseLines(text.theirs).entries;
123
+ if (text.ours.trim() !== "" && ourEntries.length === 0)
124
+ return yield* NotAShard.make({ side: "ours" });
125
+ if (text.theirs.trim() !== "" && theirEntries.length === 0) {
126
+ return yield* NotAShard.make({ side: "theirs" });
127
+ }
128
+ return renderShard(mergeEntries({ ours: ourEntries, theirs: theirEntries }));
129
+ });
130
+ const readText = (fs, file) => fs.readFileString(file).pipe(Effect.orElseSucceed(() => ""));
131
+ const exists = (fs, file) => fs.exists(file).pipe(Effect.orElseSucceed(() => false));
132
+ const seconds = (millis) => Math.floor(millis / 1000);
133
+ const add = (shards, entry) => {
134
+ const next = new Map(shards);
135
+ const inner = new Map(next.get(shardOf(entry.key)) ?? []);
136
+ inner.set(entry.key, entry);
137
+ next.set(shardOf(entry.key), inner);
138
+ return next;
139
+ };
140
+ const count = (shards) => {
141
+ let total = 0;
142
+ for (const entries of shards.values())
143
+ total += entries.size;
144
+ return total;
145
+ };
146
+ /**
147
+ * Open the store: read the single file and every shard into memory, and keep the
148
+ * dirty shards so a write is proportional to the change.
149
+ *
150
+ * Concurrent decisions finish at once and each writes; the permit keeps one
151
+ * writer in the files at a time. Migration is the one full write: if the single
152
+ * file was present, the first flush writes every shard before removing it, so a
153
+ * crash in between leaves both and the sharded side wins on the next read.
154
+ */
155
+ export const make = (fs, path, dir) => Effect.gen(function* () {
156
+ const single = singleFile(path, dir);
157
+ const migrating = yield* exists(fs, single);
158
+ const now = seconds(yield* Clock.currentTimeMillis);
159
+ let loaded = new Map();
160
+ if (migrating) {
161
+ const text = yield* readText(fs, single);
162
+ const decoded = Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(SingleFile))(text));
163
+ if (decoded !== undefined) {
164
+ for (const [key, answer] of Object.entries(decoded.entries))
165
+ loaded = add(loaded, { key, writtenAt: now, answer });
166
+ }
167
+ }
168
+ const shardNames = yield* fs.readDirectory(answersDir(path, dir)).pipe(Effect.orElseSucceed(() => []));
169
+ for (const name of shardNames) {
170
+ if (!name.endsWith(".jsonl"))
171
+ continue;
172
+ const text = yield* readText(fs, path.join(answersDir(path, dir), name));
173
+ // The sharded store is newer than the single file, so it wins on a key
174
+ // both carry.
175
+ for (const entry of parseLines(text).entries)
176
+ loaded = add(loaded, entry);
177
+ }
178
+ const shards = yield* Ref.make(loaded);
179
+ const dirty = yield* Ref.make(new Set());
180
+ const needsMigration = yield* Ref.make(migrating);
181
+ const writer = yield* Semaphore.make(1);
182
+ const flush = writer.withPermits(1)(Effect.gen(function* () {
183
+ // Taken and cleared in one step: a put that lands while this flush is
184
+ // writing marks a fresh set, which its own flush then writes.
185
+ const changed = yield* Ref.getAndSet(dirty, new Set());
186
+ const current = yield* Ref.get(shards);
187
+ const migrate = yield* Ref.get(needsMigration);
188
+ const targets = migrate ? [...current.keys()] : [...changed];
189
+ const target = answersDir(path, dir);
190
+ yield* fs.makeDirectory(target, { recursive: true }).pipe(Effect.orElseSucceed(() => undefined));
191
+ const attributes = path.join(dir, ".gitattributes");
192
+ if (!(yield* exists(fs, attributes))) {
193
+ yield* fs.writeFileString(attributes, ATTRIBUTES).pipe(Effect.orElseSucceed(() => undefined));
194
+ }
195
+ for (const shard of targets) {
196
+ const entries = current.get(shard);
197
+ if (entries === undefined)
198
+ continue;
199
+ yield* fs
200
+ .writeFileString(path.join(target, shard + ".jsonl"), renderShard(entries.values()))
201
+ .pipe(Effect.orElseSucceed(() => undefined));
202
+ }
203
+ if (migrate) {
204
+ yield* fs.remove(single).pipe(Effect.orElseSucceed(() => undefined));
205
+ yield* Ref.set(needsMigration, false);
206
+ }
207
+ }));
208
+ return {
209
+ get: (key) => Effect.map(Ref.get(shards), (current) => {
210
+ const entry = current.get(shardOf(key))?.get(key);
211
+ return entry === undefined ? Option.none() : Option.some(entry.answer);
212
+ }),
213
+ put: (key, answer) => Effect.gen(function* () {
214
+ const entry = { key, writtenAt: seconds(yield* Clock.currentTimeMillis), answer };
215
+ yield* Ref.update(shards, (current) => add(current, entry));
216
+ yield* Ref.update(dirty, (current) => {
217
+ const next = new Set(current);
218
+ next.add(shardOf(key));
219
+ return next;
220
+ });
221
+ yield* flush;
222
+ }),
223
+ size: Effect.map(Ref.get(shards), count),
224
+ migrate: Effect.gen(function* () {
225
+ yield* Ref.set(needsMigration, true);
226
+ yield* flush;
227
+ return count(yield* Ref.get(shards));
228
+ }),
229
+ };
230
+ });
231
+ const sizeOf = (entry) => renderEntry(entry).length + 1;
232
+ /**
233
+ * Drop cache entries and rewrite only the shards that changed.
234
+ *
235
+ * The age cut is per entry, from the timestamp each line carries. The size cut
236
+ * is oldest-first across the whole store. A shard left empty is deleted rather
237
+ * than written empty, so a pruned store is a smaller one, not one with the same
238
+ * number of files.
239
+ */
240
+ export const prune = (fs, path, dir, options = {}) => Effect.gen(function* () {
241
+ const now = options.now ?? seconds(yield* Clock.currentTimeMillis);
242
+ const cutoff = options.olderThanSeconds === undefined ? undefined : now - options.olderThanSeconds;
243
+ const target = answersDir(path, dir);
244
+ const names = yield* fs.readDirectory(target).pipe(Effect.orElseSucceed(() => []));
245
+ const keptByShard = new Map();
246
+ const dropped = [];
247
+ for (const name of names) {
248
+ if (!name.endsWith(".jsonl"))
249
+ continue;
250
+ const shard = name.slice(0, -".jsonl".length);
251
+ const text = yield* readText(fs, path.join(target, name));
252
+ for (const entry of parseLines(text).entries) {
253
+ if (cutoff !== undefined && entry.writtenAt < cutoff)
254
+ dropped.push({ shard, entry });
255
+ else {
256
+ const kept = keptByShard.get(shard) ?? [];
257
+ kept.push(entry);
258
+ keptByShard.set(shard, kept);
259
+ }
260
+ }
261
+ }
262
+ if (options.maxBytes !== undefined) {
263
+ let total = 0;
264
+ for (const entries of keptByShard.values())
265
+ for (const entry of entries)
266
+ total += sizeOf(entry);
267
+ if (total > options.maxBytes) {
268
+ // A total order: oldest first, ties by key, so the result does not
269
+ // depend on directory iteration.
270
+ const ordered = [...keptByShard.values()].flat().sort(byKey);
271
+ ordered.sort(Order.mapInput(Order.Number, (entry) => entry.writtenAt));
272
+ const removedKeys = new Set();
273
+ for (const entry of ordered) {
274
+ if (total <= options.maxBytes)
275
+ break;
276
+ removedKeys.add(entry.key);
277
+ dropped.push({ shard: shardOf(entry.key), entry });
278
+ total -= sizeOf(entry);
279
+ }
280
+ for (const [shard, entries] of keptByShard) {
281
+ keptByShard.set(shard, entries.filter((entry) => !removedKeys.has(entry.key)));
282
+ }
283
+ }
284
+ }
285
+ const touched = new Set(dropped.map((entry) => entry.shard));
286
+ for (const shard of touched) {
287
+ const entries = keptByShard.get(shard) ?? [];
288
+ const file = path.join(target, shard + ".jsonl");
289
+ if (entries.length === 0) {
290
+ yield* fs.remove(file).pipe(Effect.orElseSucceed(() => undefined));
291
+ }
292
+ else {
293
+ yield* fs.writeFileString(file, renderShard(entries)).pipe(Effect.orElseSucceed(() => undefined));
294
+ }
295
+ }
296
+ let kept = 0;
297
+ let bytes = 0;
298
+ for (const entries of keptByShard.values()) {
299
+ for (const entry of entries) {
300
+ kept += 1;
301
+ bytes += sizeOf(entry);
302
+ }
303
+ }
304
+ return { removed: dropped.length, kept, bytes };
305
+ });
@@ -0,0 +1,190 @@
1
+ import { matchesGlob } from "./config.js";
2
+ /**
3
+ * Layers in declaration order, which is dependency order.
4
+ *
5
+ * The declaration lists from most depended-upon to least, so a later layer may
6
+ * import an earlier one and never the reverse. Writing it that way means the
7
+ * bottom of the architecture is the first thing a reader sees.
8
+ */
9
+ export const layersFrom = (config) => (config.architecture?.layers ?? []).map((layer, rank) => ({
10
+ name: layer.name,
11
+ include: layer.include,
12
+ rank,
13
+ forbid: layer.forbid ?? [],
14
+ }));
15
+ /** The declared layer a file belongs to, by the first include glob it matches. */
16
+ export const layerOf = (layers, file) => layers.find((layer) => layer.include.some((glob) => matchesGlob({ glob, subject: file })));
17
+ /**
18
+ * Whether `from` may import `to`: downward, or sideways inside one layer.
19
+ *
20
+ * A file that belongs to no declared layer is not constrained: the layering
21
+ * describes what someone wrote down, and inventing a rule for the rest would be
22
+ * reporting an architecture nobody declared.
23
+ */
24
+ export const canImport = ({ layers, importer, to }) => {
25
+ const source = layerOf(layers, importer);
26
+ const target = layerOf(layers, to);
27
+ if (source === undefined || target === undefined)
28
+ return true;
29
+ return target.rank <= source.rank;
30
+ };
31
+ /**
32
+ * The nearest layer that every one of these files may import, if there is one.
33
+ *
34
+ * This is where duplicated declarations should end up. Nearest rather than
35
+ * lowest, because hoisting one level is a smaller change than hoisting four, and
36
+ * the ordering of the declared layers is what decides which is which.
37
+ */
38
+ export const sharedLayerFor = (layers, files) => {
39
+ const ranks = [];
40
+ for (const file of files) {
41
+ const layer = layerOf(layers, file);
42
+ if (layer === undefined)
43
+ return undefined;
44
+ ranks.push(layer.rank);
45
+ }
46
+ if (ranks.length === 0)
47
+ return undefined;
48
+ const limit = Math.min(...ranks);
49
+ let best;
50
+ for (const layer of layers) {
51
+ if (layer.rank >= limit)
52
+ continue;
53
+ if (best === undefined || layer.rank > best.rank)
54
+ best = layer;
55
+ }
56
+ return best;
57
+ };
58
+ /**
59
+ * Imports a layer forbids itself.
60
+ *
61
+ * The other half of a layering. `directionViolations` says which way
62
+ * dependencies may point; this says what may not cross a layer's boundary at
63
+ * all, which is what "the domain is pure" reduces to once it stops being a
64
+ * slogan: a file in the domain package importing react is a fact about an
65
+ * import graph, and facts with exact answers belong in the free layer.
66
+ *
67
+ * Nothing here is a judgement about whether the domain SHOULD be pure. That is
68
+ * declared, and this measures the distance to it.
69
+ */
70
+ export const purityViolations = (imports, layers) => {
71
+ const found = [];
72
+ for (const edge of imports.edges) {
73
+ const layer = layerOf(layers, edge.importer);
74
+ if (layer === undefined || layer.forbid.length === 0)
75
+ continue;
76
+ for (const pattern of layer.forbid) {
77
+ if (matchesGlob({ glob: pattern, subject: edge.specifier })) {
78
+ found.push({
79
+ importer: edge.importer,
80
+ specifier: edge.specifier,
81
+ layer: layer.name,
82
+ pattern,
83
+ });
84
+ }
85
+ }
86
+ }
87
+ return found.sort((left, right) => left.importer.localeCompare(right.importer) || left.specifier.localeCompare(right.specifier));
88
+ };
89
+ /**
90
+ * Imports that point back up the stack.
91
+ *
92
+ * A file in no declared layer is skipped rather than guessed at: it is not part
93
+ * of the architecture anyone described, and inventing a rank for it would report
94
+ * a rule nobody wrote. Foreign imports cannot violate a layering either -- a
95
+ * package is outside the graph being described.
96
+ */
97
+ export const directionViolations = (imports, layers) => {
98
+ const violations = [];
99
+ for (const edge of imports.edges) {
100
+ if (edge.resolution === "unresolved" || edge.importer === edge.to)
101
+ continue;
102
+ const source = layerOf(layers, edge.importer);
103
+ const target = layerOf(layers, edge.to);
104
+ if (source === undefined || target === undefined)
105
+ continue;
106
+ if (target.rank > source.rank) {
107
+ violations.push({
108
+ from: edge.importer,
109
+ to: edge.to,
110
+ fromLayer: source.name,
111
+ toLayer: target.name,
112
+ });
113
+ }
114
+ }
115
+ return violations.sort((left, right) => left.from.localeCompare(right.from) || left.to.localeCompare(right.to));
116
+ };
117
+ /**
118
+ * A cycle is the same cycle wherever the walk entered it, so rotate each one to
119
+ * its lexicographically smallest member before deciding it is new. Without this
120
+ * one three-module loop is reported three times, once per entry point.
121
+ */
122
+ const canonicalCycle = (cycle) => {
123
+ let best;
124
+ for (let index = 0; index < cycle.length; index += 1) {
125
+ const key = [...cycle.slice(index), ...cycle.slice(0, index)].join("\u0000");
126
+ if (best === undefined || key < best)
127
+ best = key;
128
+ }
129
+ return best ?? "";
130
+ };
131
+ /** Module cycles. Reported once per loop, not once per entry point. */
132
+ export const cyclesIn = (imports) => {
133
+ const adjacency = new Map();
134
+ /** Whether EVERY edge from one file to another is erased. */
135
+ const erased = new Map();
136
+ for (const edge of imports.edges) {
137
+ if (edge.resolution === "unresolved" || edge.importer === edge.to)
138
+ continue;
139
+ const existing = adjacency.get(edge.importer);
140
+ if (existing === undefined)
141
+ adjacency.set(edge.importer, [edge.to]);
142
+ else if (!existing.includes(edge.to))
143
+ existing.push(edge.to);
144
+ const key = edge.importer + "\u0000" + edge.to;
145
+ erased.set(key, (erased.get(key) ?? true) && edge.typeOnly);
146
+ }
147
+ const isErased = (from, to) => erased.get(from + "\u0000" + to) === true;
148
+ const found = [];
149
+ const seen = new Set();
150
+ const state = new Map();
151
+ const trail = [];
152
+ const visit = (file) => {
153
+ const status = state.get(file);
154
+ if (status === "done")
155
+ return;
156
+ if (status === "visiting") {
157
+ const start = trail.indexOf(file);
158
+ if (start === -1)
159
+ return;
160
+ const cycle = trail.slice(start);
161
+ const key = canonicalCycle(cycle);
162
+ if (!seen.has(key)) {
163
+ seen.add(key);
164
+ let typeOnly = true;
165
+ let runtime = true;
166
+ for (let index = 0; index < cycle.length; index += 1) {
167
+ const from = cycle[index];
168
+ const to = cycle[(index + 1) % cycle.length];
169
+ if (from === undefined || to === undefined)
170
+ continue;
171
+ if (isErased(from, to))
172
+ runtime = false;
173
+ else
174
+ typeOnly = false;
175
+ }
176
+ found.push({ loop: cycle, runtime, typeOnly });
177
+ }
178
+ return;
179
+ }
180
+ state.set(file, "visiting");
181
+ trail.push(file);
182
+ for (const next of adjacency.get(file) ?? [])
183
+ visit(next);
184
+ trail.pop();
185
+ state.set(file, "done");
186
+ };
187
+ for (const file of adjacency.keys())
188
+ visit(file);
189
+ return found;
190
+ };