@autotelic/joggle 0.0.0-stage → 0.1.2

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/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";
@@ -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
+ });