@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/dist/plans.js
ADDED
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
import { Context, Effect, Option, Schema } from "effect";
|
|
2
|
+
import * as AiError from "effect/ai/AiError";
|
|
3
|
+
import { Decision, DecisionModel } from "effect/ai";
|
|
4
|
+
import { Atoms } from "./atoms.js";
|
|
5
|
+
import { canonical } from "./canonical.js";
|
|
6
|
+
import { policy } from "./policy.js";
|
|
7
|
+
import { shortHash } from "./state.js";
|
|
8
|
+
export class PlanAnswers extends Context.Service()("@joggle/PlanAnswers") {
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* One cached answer, on disk.
|
|
12
|
+
*
|
|
13
|
+
* The `kind` field is added so the decoder can tell the three answer shapes
|
|
14
|
+
* apart. Without it, a Rate answer would satisfy the Classify schema -- it has a
|
|
15
|
+
* `label` and a `probabilities` -- and its `rating` would be dropped silently on
|
|
16
|
+
* the way back in.
|
|
17
|
+
*/
|
|
18
|
+
export const StoredAnswer = Schema.Union([
|
|
19
|
+
Schema.Struct({
|
|
20
|
+
kind: Schema.Literal("Rate"),
|
|
21
|
+
rating: Schema.Number,
|
|
22
|
+
label: Schema.String,
|
|
23
|
+
probabilities: Schema.Record(Schema.String, Schema.Number),
|
|
24
|
+
confidence: Schema.optionalKey(Schema.Number),
|
|
25
|
+
}),
|
|
26
|
+
Schema.Struct({
|
|
27
|
+
kind: Schema.Literal("Classify"),
|
|
28
|
+
label: Schema.String,
|
|
29
|
+
probabilities: Schema.Record(Schema.String, Schema.Number),
|
|
30
|
+
confidence: Schema.optionalKey(Schema.Number),
|
|
31
|
+
}),
|
|
32
|
+
Schema.Struct({
|
|
33
|
+
kind: Schema.Literal("Probability"),
|
|
34
|
+
probability: Schema.Number,
|
|
35
|
+
consistency: Schema.optionalKey(Schema.Number),
|
|
36
|
+
}),
|
|
37
|
+
]);
|
|
38
|
+
/**
|
|
39
|
+
* The agreement carried alongside an answer, when a Noul was asked more than
|
|
40
|
+
* once.
|
|
41
|
+
*
|
|
42
|
+
* `Decision.Answer` does not model it because it is OUR reduction, not the
|
|
43
|
+
* provider's answer: `answerPlansRaw` attaches it, `storedOf` persists it, and
|
|
44
|
+
* `verdictOf` reads it as a Noul's margin.
|
|
45
|
+
*/
|
|
46
|
+
export const consistencyOf = (answer) => answer.consistency;
|
|
47
|
+
/** An answer with its consistency attached, when it has one. */
|
|
48
|
+
export const withConsistency = (answer, consistency) => {
|
|
49
|
+
if (consistency === undefined)
|
|
50
|
+
return answer;
|
|
51
|
+
// SAFETY: the extra field is our own reduction over the repeats, read back only
|
|
52
|
+
// through `consistencyOf` and persisted by `storedOf`; every caller that treats
|
|
53
|
+
// the value as a `Decision.Answer` ignores it.
|
|
54
|
+
return { ...answer, consistency };
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* Reduce a Noul's repeated asks to one answer and its agreement.
|
|
58
|
+
*
|
|
59
|
+
* The mean is the answer; the agreement is the share that sided with the
|
|
60
|
+
* majority, 1 when every ask agreed and 0.5 at a coin flip. A separate function
|
|
61
|
+
* so the arithmetic is testable without a model.
|
|
62
|
+
*
|
|
63
|
+
* @param values - one probability per ask, in request order.
|
|
64
|
+
* @returns the mean and the agreement, or undefined when there are none.
|
|
65
|
+
*/
|
|
66
|
+
export const reduceRepeats = (values) => {
|
|
67
|
+
if (values.length === 0)
|
|
68
|
+
return undefined;
|
|
69
|
+
const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
|
|
70
|
+
const yes = values.filter((value) => value >= 0.5).length / values.length;
|
|
71
|
+
return { probability: mean, consistency: Math.max(yes, 1 - yes) };
|
|
72
|
+
};
|
|
73
|
+
/** The stored form of an answer, for the cache file. */
|
|
74
|
+
export const storedOf = (answer) => {
|
|
75
|
+
if ("probability" in answer) {
|
|
76
|
+
const consistency = consistencyOf(answer);
|
|
77
|
+
return consistency === undefined
|
|
78
|
+
? { kind: "Probability", probability: answer.probability }
|
|
79
|
+
: { kind: "Probability", probability: answer.probability, consistency };
|
|
80
|
+
}
|
|
81
|
+
if ("rating" in answer) {
|
|
82
|
+
const rate = {
|
|
83
|
+
kind: "Rate",
|
|
84
|
+
rating: answer.rating,
|
|
85
|
+
label: answer.label,
|
|
86
|
+
probabilities: answer.probabilities,
|
|
87
|
+
};
|
|
88
|
+
return answer.confidence === undefined ? rate : { ...rate, confidence: answer.confidence };
|
|
89
|
+
}
|
|
90
|
+
const classify = {
|
|
91
|
+
kind: "Classify",
|
|
92
|
+
label: answer.label,
|
|
93
|
+
probabilities: answer.probabilities,
|
|
94
|
+
};
|
|
95
|
+
return answer.confidence === undefined ? classify : { ...classify, confidence: answer.confidence };
|
|
96
|
+
};
|
|
97
|
+
/** The answer back from its stored form. */
|
|
98
|
+
export const answerOf = (stored) => {
|
|
99
|
+
if (stored.kind === "Probability") {
|
|
100
|
+
return withConsistency({ probability: stored.probability }, stored.consistency);
|
|
101
|
+
}
|
|
102
|
+
if (stored.kind === "Rate") {
|
|
103
|
+
const rate = {
|
|
104
|
+
rating: stored.rating,
|
|
105
|
+
label: stored.label,
|
|
106
|
+
probabilities: stored.probabilities,
|
|
107
|
+
};
|
|
108
|
+
return stored.confidence === undefined ? rate : { ...rate, confidence: stored.confidence };
|
|
109
|
+
}
|
|
110
|
+
const classify = { label: stored.label, probabilities: stored.probabilities };
|
|
111
|
+
return stored.confidence === undefined ? classify : { ...classify, confidence: stored.confidence };
|
|
112
|
+
};
|
|
113
|
+
/**
|
|
114
|
+
* The key of one question's answer: the question, the atoms it read, and the
|
|
115
|
+
* model.
|
|
116
|
+
*
|
|
117
|
+
* Per question rather than per request, which is the whole reason a batched call
|
|
118
|
+
* does not lose cache granularity: adding a question to a request leaves every
|
|
119
|
+
* other question's key unchanged, and so does changing a declaration the other
|
|
120
|
+
* questions do not name.
|
|
121
|
+
*/
|
|
122
|
+
export const answerKeyFor = (decision, material) => shortHash(canonical({
|
|
123
|
+
model: policy.model,
|
|
124
|
+
decisionVersion: policy.decisionVersion,
|
|
125
|
+
decision,
|
|
126
|
+
material,
|
|
127
|
+
}));
|
|
128
|
+
/** The provider's shape for one answer, so a cached answer can be re-validated. */
|
|
129
|
+
const asProviderAnswer = (decision, answer) => {
|
|
130
|
+
if (decision._tag === "Probability") {
|
|
131
|
+
return "probability" in answer
|
|
132
|
+
? Option.some({ _tag: "Probability", probability: answer.probability })
|
|
133
|
+
: Option.none();
|
|
134
|
+
}
|
|
135
|
+
if (!("label" in answer) || !("probabilities" in answer))
|
|
136
|
+
return Option.none();
|
|
137
|
+
if (decision._tag === "Classify") {
|
|
138
|
+
const base = { _tag: "Classify", label: answer.label, probabilities: answer.probabilities };
|
|
139
|
+
return Option.some(answer.confidence === undefined ? base : { ...base, confidence: answer.confidence });
|
|
140
|
+
}
|
|
141
|
+
if (!("rating" in answer))
|
|
142
|
+
return Option.none();
|
|
143
|
+
const base = { _tag: "Rate", rating: answer.rating, probabilities: answer.probabilities };
|
|
144
|
+
return Option.some(answer.confidence === undefined ? base : { ...base, confidence: answer.confidence });
|
|
145
|
+
};
|
|
146
|
+
/**
|
|
147
|
+
* Validate a cached answer through the same model that validated it when it was
|
|
148
|
+
* first received.
|
|
149
|
+
*
|
|
150
|
+
* The cache is a file on disk, so a cached answer is not automatically a valid
|
|
151
|
+
* one. Re-building a `DecisionModel` whose provider is the cache and asking it to
|
|
152
|
+
* answer the question again runs Effect's own checks -- labels inside the
|
|
153
|
+
* criteria, distributions summing to one, ratings in range -- without a second
|
|
154
|
+
* implementation of them here. An answer that fails is a miss, not a wrong one.
|
|
155
|
+
*/
|
|
156
|
+
const revalidate = (decision, answer) => Effect.gen(function* () {
|
|
157
|
+
const provider = asProviderAnswer(decision, answer);
|
|
158
|
+
if (Option.isNone(provider))
|
|
159
|
+
return Option.none();
|
|
160
|
+
const model = yield* DecisionModel.make({
|
|
161
|
+
decide: () => Effect.succeed({
|
|
162
|
+
answers: { q: provider.value },
|
|
163
|
+
usage: { inputTokens: undefined, outputTokens: undefined },
|
|
164
|
+
}),
|
|
165
|
+
});
|
|
166
|
+
const definition = Decision.make({ input: Schema.Json, decisions: { q: decision } });
|
|
167
|
+
const decided = yield* model.decide(definition, { input: null }).pipe(Effect.orElseSucceed(() => undefined));
|
|
168
|
+
if (decided === undefined)
|
|
169
|
+
return Option.none();
|
|
170
|
+
const validated = decided.answers["q"];
|
|
171
|
+
return validated === undefined ? Option.none() : Option.some(validated);
|
|
172
|
+
});
|
|
173
|
+
/**
|
|
174
|
+
* A DecisionModel that remembers every answer, one decision at a time.
|
|
175
|
+
*
|
|
176
|
+
* The wire cache remembers a whole REQUEST, and that cannot be the replay path:
|
|
177
|
+
* its key changes when any question in the request changes, and the file it
|
|
178
|
+
* writes is far too large to commit. This remembers one answer at a time, keyed
|
|
179
|
+
* by the decision and the state it was answered against, so a reviewed verdict
|
|
180
|
+
* replays with no key and no tokens, and a request whose questions are all
|
|
181
|
+
* remembered never reaches the model at all.
|
|
182
|
+
*
|
|
183
|
+
* A cached answer is validated through the same checks the provider's answer
|
|
184
|
+
* passed, so the cache is not a path around them. An answer that fails is a miss.
|
|
185
|
+
*/
|
|
186
|
+
export const memoize = (inner, cache) => DecisionModel.DecisionModel.of({
|
|
187
|
+
[DecisionModel.TypeId]: DecisionModel.TypeId,
|
|
188
|
+
decide: (definition, options) => Effect.gen(function* () {
|
|
189
|
+
const entries = Object.entries(definition.decisions);
|
|
190
|
+
const answers = {};
|
|
191
|
+
const missing = {};
|
|
192
|
+
const keys = new Map();
|
|
193
|
+
for (const [name, decision] of entries) {
|
|
194
|
+
const key = answerKeyFor(decision, options.input);
|
|
195
|
+
keys.set(name, key);
|
|
196
|
+
const stored = yield* cache.get(key);
|
|
197
|
+
if (Option.isSome(stored)) {
|
|
198
|
+
const valid = yield* revalidate(decision, stored.value);
|
|
199
|
+
if (Option.isSome(valid)) {
|
|
200
|
+
answers[name] = withConsistency(valid.value, consistencyOf(stored.value));
|
|
201
|
+
continue;
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
missing[name] = decision;
|
|
205
|
+
}
|
|
206
|
+
let usage = DecisionModel.DecisionUsage.make({});
|
|
207
|
+
if (Object.keys(missing).length > 0) {
|
|
208
|
+
// A Noul asked `repeats` times, in the same request and for the same
|
|
209
|
+
// reason as `answerPlansRaw`: one yes/no has no margin. A rule that
|
|
210
|
+
// answers its own questions directly (`DecisionModel.decide`) passes
|
|
211
|
+
// through here, so the reduction cannot live only in the plan engine.
|
|
212
|
+
const repeats = policy.decision.consistency.repeats;
|
|
213
|
+
const requested = {};
|
|
214
|
+
const asked = new Map();
|
|
215
|
+
for (const [name, decision] of Object.entries(missing)) {
|
|
216
|
+
const names = decision._tag === "Probability"
|
|
217
|
+
? Array.from({ length: repeats }, (_, index) => name + "~" + String(index))
|
|
218
|
+
: [name];
|
|
219
|
+
for (const one of names)
|
|
220
|
+
requested[one] = decision;
|
|
221
|
+
asked.set(name, names);
|
|
222
|
+
}
|
|
223
|
+
const response = yield* inner.decide(Decision.make({ input: definition.input, decisions: requested }), options);
|
|
224
|
+
usage = response.usage;
|
|
225
|
+
for (const name of Object.keys(missing)) {
|
|
226
|
+
const names = asked.get(name) ?? [name];
|
|
227
|
+
const gathered = names
|
|
228
|
+
.map((one) => response.answers[one])
|
|
229
|
+
.filter((answer) => answer !== undefined);
|
|
230
|
+
const first = gathered[0];
|
|
231
|
+
if (first === undefined)
|
|
232
|
+
continue;
|
|
233
|
+
let answer = first;
|
|
234
|
+
if (missing[name]?._tag === "Probability") {
|
|
235
|
+
const values = gathered.flatMap((one) => ("probability" in one ? [one.probability] : []));
|
|
236
|
+
const reduced = reduceRepeats(values);
|
|
237
|
+
if (reduced === undefined)
|
|
238
|
+
continue;
|
|
239
|
+
answer = withConsistency({ probability: reduced.probability }, reduced.consistency);
|
|
240
|
+
}
|
|
241
|
+
answers[name] = answer;
|
|
242
|
+
const key = keys.get(name);
|
|
243
|
+
if (key !== undefined)
|
|
244
|
+
yield* cache.put(key, answer);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
const ordered = {};
|
|
248
|
+
for (const [name] of entries) {
|
|
249
|
+
const answer = answers[name];
|
|
250
|
+
if (answer !== undefined)
|
|
251
|
+
ordered[name] = answer;
|
|
252
|
+
}
|
|
253
|
+
// SAFETY: every name in the definition has an answer here -- the provider
|
|
254
|
+
// validated the missing ones and the cache validated the rest -- and the
|
|
255
|
+
// record was built in the definition's own order.
|
|
256
|
+
const complete = ordered;
|
|
257
|
+
return { answers: complete, usage };
|
|
258
|
+
}),
|
|
259
|
+
});
|
|
260
|
+
/**
|
|
261
|
+
* A plan's answers, in the rule's own type.
|
|
262
|
+
*
|
|
263
|
+
* The engine erases the verdict type so plans from different rules can travel in
|
|
264
|
+
* one request; this puts it back at the boundary, where the rule knows every
|
|
265
|
+
* answer came from its own decisions and is in the order it asked them.
|
|
266
|
+
*/
|
|
267
|
+
export const verdictsOf = (answers) =>
|
|
268
|
+
// SAFETY: the caller built these plans, so each answer is the type its own
|
|
269
|
+
// decisions produced; the engine erased it only to batch rules together.
|
|
270
|
+
answers;
|
|
271
|
+
/**
|
|
272
|
+
* Cut plans into requests that fit the provider's ceiling.
|
|
273
|
+
*
|
|
274
|
+
* The engine's goal is one request, and the provider's token limit is the reason
|
|
275
|
+
* it cannot always be one. A plan's cost is the state it needs -- the atoms it
|
|
276
|
+
* named -- so the cut is by that, not by plan count: one cluster of twelve large
|
|
277
|
+
* declarations costs more than forty small ones.
|
|
278
|
+
*/
|
|
279
|
+
export const chunkPlans = (plans, maxChars) => Effect.gen(function* () {
|
|
280
|
+
const atoms = yield* Atoms;
|
|
281
|
+
const chunks = [];
|
|
282
|
+
let current = [];
|
|
283
|
+
let size = 0;
|
|
284
|
+
for (const plan of plans) {
|
|
285
|
+
const state = yield* atoms.values([...new Set(plan.atoms)]);
|
|
286
|
+
const cost = canonical(state).length;
|
|
287
|
+
if (current.length > 0 && size + cost > maxChars) {
|
|
288
|
+
chunks.push({ plans: current, chars: size });
|
|
289
|
+
current = [];
|
|
290
|
+
size = 0;
|
|
291
|
+
}
|
|
292
|
+
current.push(plan);
|
|
293
|
+
size += cost;
|
|
294
|
+
}
|
|
295
|
+
if (current.length > 0)
|
|
296
|
+
chunks.push({ plans: current, chars: size });
|
|
297
|
+
return chunks;
|
|
298
|
+
});
|
|
299
|
+
/* -------------------------------------------------------------------------- */
|
|
300
|
+
/* The engine */
|
|
301
|
+
/* -------------------------------------------------------------------------- */
|
|
302
|
+
/**
|
|
303
|
+
* Answer many plans in one request, from the cache where it can.
|
|
304
|
+
*
|
|
305
|
+
* Three things happen here that a per-candidate call cannot do:
|
|
306
|
+
*
|
|
307
|
+
* - Two plans that ask the same decision against the same atoms ask it once.
|
|
308
|
+
* - Every decision's atoms go into ONE state, so a declaration two rules both
|
|
309
|
+
* judge is sent once.
|
|
310
|
+
* - A decision already answered from cache is not sent, so a request carries only
|
|
311
|
+
* what is genuinely new. That is what keeps a batched call from losing the
|
|
312
|
+
* per-candidate cache granularity a per-candidate call had.
|
|
313
|
+
*
|
|
314
|
+
* The state is `{ atoms: { id: value } }` and the decisions reference it by id.
|
|
315
|
+
* A plan-local state (`declarations`, `files`) could not be merged into one
|
|
316
|
+
* request without rewriting every instruction; atoms can.
|
|
317
|
+
*/
|
|
318
|
+
export const answerPlansRaw = (plans) => Effect.gen(function* () {
|
|
319
|
+
if (plans.length === 0)
|
|
320
|
+
return [];
|
|
321
|
+
const atoms = yield* Atoms;
|
|
322
|
+
const cache = yield* PlanAnswers;
|
|
323
|
+
// One entry per DISTINCT decision. The map is insertion-ordered, so the
|
|
324
|
+
// request is deterministic for a given set of plans.
|
|
325
|
+
//
|
|
326
|
+
// The request name keeps the decision's own name and adds the plan's index,
|
|
327
|
+
// because two plans nearly always ask a decision with the same name (`verdict`
|
|
328
|
+
// in every cluster) and the request needs distinct keys. The name is for the
|
|
329
|
+
// request only; the cache is keyed on the decision and its atoms.
|
|
330
|
+
const distinct = new Map();
|
|
331
|
+
plans.forEach((plan, planIndex) => {
|
|
332
|
+
for (const [name, decision] of Object.entries(plan.decisions)) {
|
|
333
|
+
const key = answerKeyFor(decision, plan.atoms);
|
|
334
|
+
if (!distinct.has(key)) {
|
|
335
|
+
distinct.set(key, { decision, atoms: plan.atoms, requestName: `${name}@${planIndex}` });
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
});
|
|
339
|
+
const answers = new Map();
|
|
340
|
+
const pending = [];
|
|
341
|
+
for (const [key, entry] of distinct) {
|
|
342
|
+
const stored = yield* cache.get(key);
|
|
343
|
+
if (Option.isSome(stored)) {
|
|
344
|
+
const valid = yield* revalidate(entry.decision, stored.value);
|
|
345
|
+
if (Option.isSome(valid)) {
|
|
346
|
+
answers.set(key, withConsistency(valid.value, consistencyOf(stored.value)));
|
|
347
|
+
continue;
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
pending.push({ key });
|
|
351
|
+
}
|
|
352
|
+
if (pending.length > 0) {
|
|
353
|
+
const ids = [...new Set(pending.flatMap((entry) => distinct.get(entry.key)?.atoms ?? []))];
|
|
354
|
+
const state = yield* atoms.values(ids);
|
|
355
|
+
const decisions = {};
|
|
356
|
+
const names = new Map();
|
|
357
|
+
// A Noul is asked `repeats` times, in the SAME request: one yes/no carries
|
|
358
|
+
// no margin, so the agreement across asks is the second signal a Choice
|
|
359
|
+
// gets from its own distribution. A Choice is asked once.
|
|
360
|
+
const repeats = policy.decision.consistency.repeats;
|
|
361
|
+
for (const entry of pending) {
|
|
362
|
+
const found = distinct.get(entry.key);
|
|
363
|
+
if (found === undefined)
|
|
364
|
+
continue;
|
|
365
|
+
const requestNames = found.decision._tag === "Probability"
|
|
366
|
+
? Array.from({ length: repeats }, (_, index) => found.requestName + "~" + String(index))
|
|
367
|
+
: [found.requestName];
|
|
368
|
+
for (const name of requestNames)
|
|
369
|
+
decisions[name] = found.decision;
|
|
370
|
+
names.set(entry.key, requestNames);
|
|
371
|
+
}
|
|
372
|
+
const definition = Decision.make({ input: Schema.Json, decisions });
|
|
373
|
+
const decided = yield* DecisionModel.decide(definition, { input: { atoms: state } });
|
|
374
|
+
for (const entry of pending) {
|
|
375
|
+
const requestNames = names.get(entry.key);
|
|
376
|
+
if (requestNames === undefined)
|
|
377
|
+
continue;
|
|
378
|
+
const decision = distinct.get(entry.key)?.decision;
|
|
379
|
+
const gathered = requestNames
|
|
380
|
+
.map((name) => decided.answers[name])
|
|
381
|
+
.filter((answer) => answer !== undefined);
|
|
382
|
+
if (decision?._tag === "Probability") {
|
|
383
|
+
const values = gathered.flatMap((answer) => ("probability" in answer ? [answer.probability] : []));
|
|
384
|
+
const reduced = reduceRepeats(values);
|
|
385
|
+
if (reduced === undefined)
|
|
386
|
+
continue;
|
|
387
|
+
answers.set(entry.key, withConsistency({ probability: reduced.probability }, reduced.consistency));
|
|
388
|
+
continue;
|
|
389
|
+
}
|
|
390
|
+
const first = gathered[0];
|
|
391
|
+
if (first !== undefined)
|
|
392
|
+
answers.set(entry.key, first);
|
|
393
|
+
}
|
|
394
|
+
for (const entry of pending) {
|
|
395
|
+
const answer = answers.get(entry.key);
|
|
396
|
+
if (answer !== undefined)
|
|
397
|
+
yield* cache.put(entry.key, answer);
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
return plans.map((plan) => {
|
|
401
|
+
const collected = {};
|
|
402
|
+
for (const [name, decision] of Object.entries(plan.decisions)) {
|
|
403
|
+
const answer = answers.get(answerKeyFor(decision, plan.atoms));
|
|
404
|
+
if (answer !== undefined)
|
|
405
|
+
collected[name] = answer;
|
|
406
|
+
}
|
|
407
|
+
return collected;
|
|
408
|
+
});
|
|
409
|
+
});
|
|
410
|
+
/**
|
|
411
|
+
* Answer the plans and READ them, which is what the engine consumes.
|
|
412
|
+
*
|
|
413
|
+
* The raw records are a separate function so a caller that needs the answers
|
|
414
|
+
* themselves -- the calibrator, which reduces each decision -- can have them
|
|
415
|
+
* without a rule's `read` already having consumed them.
|
|
416
|
+
*
|
|
417
|
+
* @param plans - the plans to answer.
|
|
418
|
+
* @returns one `read` output per plan, in order.
|
|
419
|
+
*/
|
|
420
|
+
export const answerPlans = (plans) => answerPlansRaw(plans).pipe(Effect.map((records) => records.map((record, index) =>
|
|
421
|
+
// SAFETY: the caller built these plans, so each record is the answer
|
|
422
|
+
// shape its own plan's decisions produced and `read` returns the A that
|
|
423
|
+
// plan declared. The record was erased only so the plans could be
|
|
424
|
+
// answered together.
|
|
425
|
+
plans[index]?.read(record))));
|
package/dist/plugin.js
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The surface a rule author writes against.
|
|
3
|
+
*
|
|
4
|
+
* A linter is a registry, and a registry is only half a plugin system. The other
|
|
5
|
+
* half is this file: one entry point exporting everything a rule needs, so an
|
|
6
|
+
* opinion of your own is a module that imports `@autotelic/joggle/plugin` rather than three
|
|
7
|
+
* relative paths into a package's internals.
|
|
8
|
+
*
|
|
9
|
+
* That distinction is not cosmetic. `../../../src/rule.ts` is a path a rule
|
|
10
|
+
* author has to guess and a maintainer is free to move; `@autotelic/joggle/plugin` is a
|
|
11
|
+
* promise. Everything re-exported here is supported, and anything not here is
|
|
12
|
+
* not -- which is also how a rule author knows what they are allowed to rely on.
|
|
13
|
+
*
|
|
14
|
+
* The split follows what a rule actually does:
|
|
15
|
+
*
|
|
16
|
+
* write one defineRule, finding, outcome, the Rule interface
|
|
17
|
+
* read the code Workspace, Unit, ImportGraph, SourceFile, Cluster
|
|
18
|
+
* ask a question Decision, DecisionModel, the answer readers
|
|
19
|
+
* decide in code qualityOf, marginOfAnswer, declined, the gate vocabulary
|
|
20
|
+
* know the shape policy, the layer and composition helpers
|
|
21
|
+
*
|
|
22
|
+
* A deterministic rule needs only the first two, and that is deliberate: most
|
|
23
|
+
* opinions are free, and the API should make the free path the easy one.
|
|
24
|
+
*/
|
|
25
|
+
/* Writing a rule. */
|
|
26
|
+
export * from "./rule.js";
|
|
27
|
+
/* Reporting: the message registry, and naming a subject instead of a location. */
|
|
28
|
+
export * from "./reporting.js";
|
|
29
|
+
/* The fence: the authorship rules a rule module must keep. */
|
|
30
|
+
export * from "./meta.js";
|
|
31
|
+
/* The shapes a rule produces and reads. */
|
|
32
|
+
export * from "./schema.js";
|
|
33
|
+
/* The code under analysis. */
|
|
34
|
+
export * from "./workspace.js";
|
|
35
|
+
export * from "./imports.js";
|
|
36
|
+
export * from "./cluster.js";
|
|
37
|
+
export * from "./similarity.js";
|
|
38
|
+
/*
|
|
39
|
+
* Asking.
|
|
40
|
+
*
|
|
41
|
+
* A judged rule declares an Effect Decision and calls DecisionModel.decide. The
|
|
42
|
+
* two namespaces, and `Schema` for the input panel, are what that takes, so they
|
|
43
|
+
* are part of the promise rather than an import a rule author has to find.
|
|
44
|
+
*/
|
|
45
|
+
export { Decision, DecisionModel } from "effect/ai";
|
|
46
|
+
/*
|
|
47
|
+
* The shared facts, and the engine that answers questions about them.
|
|
48
|
+
*
|
|
49
|
+
* A judged rule builds a `Plan` from the run's atoms and the engine answers every
|
|
50
|
+
* plan in one request, from cache where it can. A rule that batches its own
|
|
51
|
+
* candidates by hand is a rule that has taken over a job the engine now does.
|
|
52
|
+
*/
|
|
53
|
+
export * from "./atoms.js";
|
|
54
|
+
export * from "./plans.js";
|
|
55
|
+
/* The one reduction from an answer to P(violated), and the verdict it yields. */
|
|
56
|
+
export * from "./verdict.js";
|
|
57
|
+
/* Deciding, and the vocabulary decisions are made in. */
|
|
58
|
+
export * from "./policy.js";
|
|
59
|
+
export * from "./vocabulary.js";
|
|
60
|
+
/* Architecture: layers, direction, purity, and where something may reach. */
|
|
61
|
+
export * from "./architecture.js";
|
|
62
|
+
/* The shared harness for rules whose unit is a set of declarations. */
|
|
63
|
+
export * from "./rules/cluster-verdict.js";
|
|
64
|
+
/* The registry, so a preset can compose other presets. */
|
|
65
|
+
export * from "./plugins.js";
|
|
66
|
+
export * from "./rules/index.js";
|
|
67
|
+
/*
|
|
68
|
+
* `Effect` itself, because a rule's `run` returns one. Leaving it out would make
|
|
69
|
+
* the surface unusable for the one thing every rule must do.
|
|
70
|
+
*/
|
|
71
|
+
export { Effect, Schema } from "effect";
|
package/dist/plugins.js
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
|
|
2
|
+
if (typeof path === "string" && /^\.\.?\//.test(path)) {
|
|
3
|
+
return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
|
|
4
|
+
return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
|
|
5
|
+
});
|
|
6
|
+
}
|
|
7
|
+
return path;
|
|
8
|
+
};
|
|
9
|
+
import { Effect, FileSystem, Path } from "effect";
|
|
10
|
+
import { pathToFileURL } from "node:url";
|
|
11
|
+
import { shortHash } from "./state.js";
|
|
12
|
+
const EXTENSIONS = [".ts", ".tsx", ".mts", ".js", ".mjs", ".cjs", "/index.ts", "/index.js"];
|
|
13
|
+
/**
|
|
14
|
+
* What to hand to `import`.
|
|
15
|
+
*
|
|
16
|
+
* A bare specifier is returned UNCHANGED, so the runtime resolves it. That is
|
|
17
|
+
* what makes a published plugin work without this knowing how packages are
|
|
18
|
+
* installed -- and it is how a preset shipped alongside the tool is found by its
|
|
19
|
+
* own package name, since Node resolves a package's name from inside it.
|
|
20
|
+
*
|
|
21
|
+
* Converting it to a file URL first, which is what this did, turns
|
|
22
|
+
* `@autotelic/joggle/presets/composition` into a path under the working directory and fails
|
|
23
|
+
* with "cannot find module /repo/@autotelic/joggle/presets/composition".
|
|
24
|
+
*/
|
|
25
|
+
const resolve = ({ specifier, cwd, path }) => Effect.gen(function* () {
|
|
26
|
+
if (!specifier.startsWith(".") && !specifier.startsWith("/"))
|
|
27
|
+
return specifier;
|
|
28
|
+
const fs = yield* FileSystem.FileSystem;
|
|
29
|
+
const base = path.isAbsolute(specifier) ? specifier : path.join(cwd, specifier);
|
|
30
|
+
for (const candidate of [base, ...EXTENSIONS.map((extension) => base + extension)]) {
|
|
31
|
+
if (yield* Effect.orElseSucceed(fs.exists(candidate), () => false)) {
|
|
32
|
+
return pathToFileURL(candidate).href;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return pathToFileURL(base).href;
|
|
36
|
+
});
|
|
37
|
+
const configOf = (module) => {
|
|
38
|
+
if (typeof module !== "object" || module === null)
|
|
39
|
+
return undefined;
|
|
40
|
+
const declared = module["config"];
|
|
41
|
+
return declared !== undefined && typeof declared === "object"
|
|
42
|
+
? declared
|
|
43
|
+
: undefined;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* Several plugins' defaults, first one winning on a conflict.
|
|
47
|
+
*
|
|
48
|
+
* Ordered rather than merged-last-wins because the order is the repository's:
|
|
49
|
+
* the presets it lists first are the ones it expects to shape the run.
|
|
50
|
+
*/
|
|
51
|
+
export const mergeConfigs = (configs) => {
|
|
52
|
+
const rules = {};
|
|
53
|
+
const ignore = [];
|
|
54
|
+
for (const config of [...configs].reverse()) {
|
|
55
|
+
for (const [id, setting] of Object.entries(config.rules ?? {}))
|
|
56
|
+
rules[id] = setting;
|
|
57
|
+
ignore.push(...(config.ignore ?? []));
|
|
58
|
+
}
|
|
59
|
+
return {
|
|
60
|
+
...(Object.keys(rules).length === 0 ? {} : { rules }),
|
|
61
|
+
...(ignore.length === 0 ? {} : { ignore }),
|
|
62
|
+
};
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* The repository's config over a preset's defaults.
|
|
66
|
+
*
|
|
67
|
+
* Per rule, so a preset that enables twenty opinions and sets their severities
|
|
68
|
+
* lets the repository turn one of them off without restating the other nineteen.
|
|
69
|
+
*/
|
|
70
|
+
export const withDefaults = ({ defaults, own, }) => ({
|
|
71
|
+
...defaults,
|
|
72
|
+
...own,
|
|
73
|
+
rules: { ...defaults.rules, ...own.rules },
|
|
74
|
+
ignore: [...(own.ignore ?? []), ...(defaults.ignore ?? [])],
|
|
75
|
+
// Omitted rather than set to undefined: exact optional properties distinguish
|
|
76
|
+
// the two, and a key present-but-undefined is not the same shape as an absent one.
|
|
77
|
+
...(own.architecture === undefined && defaults.architecture === undefined
|
|
78
|
+
? {}
|
|
79
|
+
: { architecture: own.architecture ?? defaults.architecture }),
|
|
80
|
+
...(own.evidence === undefined && defaults.evidence === undefined
|
|
81
|
+
? {}
|
|
82
|
+
: { evidence: own.evidence ?? defaults.evidence }),
|
|
83
|
+
...(own.plugins === undefined ? {} : { plugins: own.plugins }),
|
|
84
|
+
...(own.presets === undefined ? {} : { presets: own.presets }),
|
|
85
|
+
});
|
|
86
|
+
const rulesOf = (module) => {
|
|
87
|
+
if (typeof module !== "object" || module === null)
|
|
88
|
+
return [];
|
|
89
|
+
const exported = module["rules"];
|
|
90
|
+
return Array.isArray(exported) ? exported : [];
|
|
91
|
+
};
|
|
92
|
+
/** Load the configured rule modules, relative specifiers resolved against the analysed root. */
|
|
93
|
+
export const loadPlugins = (specifiers, cwd) => Effect.gen(function* () {
|
|
94
|
+
if (specifiers.length === 0) {
|
|
95
|
+
return { rules: [], failures: [], fingerprints: [], config: {} };
|
|
96
|
+
}
|
|
97
|
+
const fs = yield* FileSystem.FileSystem;
|
|
98
|
+
const path = yield* Path.Path;
|
|
99
|
+
const rules = [];
|
|
100
|
+
const failures = [];
|
|
101
|
+
const fingerprints = [];
|
|
102
|
+
const configs = [];
|
|
103
|
+
for (const specifier of specifiers) {
|
|
104
|
+
// A specifier that resolves to nothing is not special-cased: `import`
|
|
105
|
+
// fails on it and the runtime's own message is the failure reason, which
|
|
106
|
+
// is more accurate than anything this could invent.
|
|
107
|
+
const resolved = yield* resolve({ specifier, cwd, path });
|
|
108
|
+
const attempt = yield* Effect.tryPromise({
|
|
109
|
+
try: () => import(__rewriteRelativeImportExtension(resolved)),
|
|
110
|
+
catch: (cause) => (cause instanceof Error ? cause.message : String(cause)),
|
|
111
|
+
}).pipe(Effect.map((module) => ({ ok: true, module })), Effect.catch((reason) => Effect.succeed({ ok: false, reason })));
|
|
112
|
+
if (!attempt.ok) {
|
|
113
|
+
failures.push({ specifier, reason: attempt.reason });
|
|
114
|
+
continue;
|
|
115
|
+
}
|
|
116
|
+
const found = rulesOf(attempt.module);
|
|
117
|
+
if (found.length === 0) {
|
|
118
|
+
failures.push({ specifier, reason: "loaded, but exports no `rules` array" });
|
|
119
|
+
continue;
|
|
120
|
+
}
|
|
121
|
+
rules.push(...found);
|
|
122
|
+
const declared = configOf(attempt.module);
|
|
123
|
+
if (declared !== undefined)
|
|
124
|
+
configs.push(declared);
|
|
125
|
+
// The plugin's own source, so editing it invalidates the run cache the same
|
|
126
|
+
// way editing this package does.
|
|
127
|
+
const text = yield* Effect.orElseSucceed(fs.readFileString(resolved), () => "");
|
|
128
|
+
fingerprints.push(specifier + "\u0000" + shortHash(text));
|
|
129
|
+
}
|
|
130
|
+
return {
|
|
131
|
+
rules,
|
|
132
|
+
failures,
|
|
133
|
+
fingerprints,
|
|
134
|
+
config: mergeConfigs(configs),
|
|
135
|
+
};
|
|
136
|
+
});
|