@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.
- package/JOGGLE.md +634 -0
- package/LICENSE +21 -0
- package/README.md +88 -2
- package/bin/joggle.js +6 -0
- package/dist/answer-store.js +305 -0
- package/dist/architecture.js +190 -0
- package/dist/ask.js +184 -0
- package/dist/astro.js +75 -0
- package/dist/atoms.js +76 -0
- package/dist/bundles.js +156 -0
- package/dist/calibration.js +60 -0
- package/dist/candidates.js +561 -0
- package/dist/canonical.js +24 -0
- package/dist/cascade.js +98 -0
- package/dist/check.js +854 -0
- package/dist/cluster.js +69 -0
- package/dist/config.js +195 -0
- package/dist/content-mappers.js +83 -0
- package/dist/decision.js +203 -0
- package/dist/fingerprint.js +61 -0
- package/dist/git.js +127 -0
- package/dist/gitignore.js +65 -0
- package/dist/glob.js +51 -0
- package/dist/imports.js +153 -0
- package/dist/jsonc.js +95 -0
- package/dist/main.js +630 -0
- package/dist/manifest.js +42 -0
- package/dist/meta.js +170 -0
- package/dist/moves.js +47 -0
- package/dist/operation.js +133 -0
- package/dist/parsecache.js +264 -0
- package/dist/plans.js +425 -0
- package/dist/plugin.js +71 -0
- package/dist/plugins.js +136 -0
- package/dist/policy.js +676 -0
- package/dist/presets/composition.js +32 -0
- package/dist/report.js +474 -0
- package/dist/reporting.js +132 -0
- package/dist/result.js +28 -0
- package/dist/roles.js +303 -0
- package/dist/rule.js +194 -0
- package/dist/rules/append-only-honoured.js +190 -0
- package/dist/rules/bundle-conformance.js +245 -0
- package/dist/rules/call-pattern.js +209 -0
- package/dist/rules/cluster-verdict.js +700 -0
- package/dist/rules/compose-types.js +250 -0
- package/dist/rules/data-error-as-outage.js +482 -0
- package/dist/rules/declared-staleness.js +242 -0
- package/dist/rules/dependency-fit.js +297 -0
- package/dist/rules/deviation-has-a-shape.js +225 -0
- package/dist/rules/doc-matches-code.js +191 -0
- package/dist/rules/duplicate-call-run.js +240 -0
- package/dist/rules/duplicate-implementation.js +89 -0
- package/dist/rules/duplicate-meaning.js +130 -0
- package/dist/rules/fact-or-derivation.js +202 -0
- package/dist/rules/field-type-drift.js +373 -0
- package/dist/rules/generic-carries-a-caller.js +198 -0
- package/dist/rules/hoist-to-domain.js +288 -0
- package/dist/rules/import-architecture.js +393 -0
- package/dist/rules/index.js +105 -0
- package/dist/rules/inferred-over-recorded.js +214 -0
- package/dist/rules/intent-drift.js +286 -0
- package/dist/rules/invariant-has-a-reconciler.js +190 -0
- package/dist/rules/language-drift.js +234 -0
- package/dist/rules/meaning-switched-by-flag.js +189 -0
- package/dist/rules/module-direction.js +231 -0
- package/dist/rules/name-as-address.js +216 -0
- package/dist/rules/name-the-primitive.js +203 -0
- package/dist/rules/naming-drift.js +218 -0
- package/dist/rules/nullability-drift.js +220 -0
- package/dist/rules/object-shape.js +280 -0
- package/dist/rules/one-concept-one-type.js +243 -0
- package/dist/rules/page-needs-composition.js +227 -0
- package/dist/rules/reimplemented-primitive.js +283 -0
- package/dist/rules/reversal.js +264 -0
- package/dist/rules/rule-judgment.js +252 -0
- package/dist/rules/schema-excludes-domain-value.js +190 -0
- package/dist/rules/shallow-module.js +204 -0
- package/dist/rules/single-path.js +237 -0
- package/dist/rules/structural-collapse.js +198 -0
- package/dist/rules/temporal-coupling.js +205 -0
- package/dist/rules/types-over-logic.js +198 -0
- package/dist/rules/unaccounted-drop.js +190 -0
- package/dist/rules/unbounded-default-read.js +227 -0
- package/dist/run-cache.js +132 -0
- package/dist/schema.js +285 -0
- package/dist/similarity.js +119 -0
- package/dist/source.js +30 -0
- package/dist/sql.js +34 -0
- package/dist/stages.js +39 -0
- package/dist/state.js +65 -0
- package/dist/testing.js +131 -0
- package/dist/tsconfig-scope.js +32 -0
- package/dist/tsgo.js +127 -0
- package/dist/typefacts.js +455 -0
- package/dist/typetrace.js +283 -0
- package/dist/verdict.js +65 -0
- package/dist/vocabulary.js +365 -0
- package/dist/workspace.js +1963 -0
- package/extensions/joggle.ts +454 -0
- package/package.json +85 -3
package/README.md
CHANGED
|
@@ -1,3 +1,89 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# joggle
|
|
4
|
+
|
|
5
|
+
**Cross-file judgements for a TypeScript codebase, enforced like a linter.**
|
|
6
|
+
|
|
7
|
+
[](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
|
+
};
|