@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.
- 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
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
import { Effect, Order } from "effect";
|
|
2
|
+
import { Decision } from "effect/ai";
|
|
3
|
+
import { Atoms } from "../atoms.js";
|
|
4
|
+
import { policy } from "../policy.js";
|
|
5
|
+
import { containmentPairs } from "../candidates.js";
|
|
6
|
+
import {} from "../plans.js";
|
|
7
|
+
import { verdictsOf } from "../plans.js";
|
|
8
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
9
|
+
import { verdictOf } from "../verdict.js";
|
|
10
|
+
import { outcome, qualityOf, } from "../rule.js";
|
|
11
|
+
import { typeUnits, unitFields } from "../workspace.js";
|
|
12
|
+
const RULE_ID = "joggle/compose-types";
|
|
13
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
14
|
+
const VIOLATIONS = { verdict: ["composes", "same_name_drift"] };
|
|
15
|
+
// A type that lists every field of another type.
|
|
16
|
+
//
|
|
17
|
+
// The COMPOSE case is advice and is recorded rather than printed; the name-drift
|
|
18
|
+
// case -- one name declared twice with different fields -- is a defect and is the
|
|
19
|
+
// finding. See the read.
|
|
20
|
+
//
|
|
21
|
+
// "Composed of smaller canonical things" is a principle until it becomes a set
|
|
22
|
+
// comparison, and a set comparison is free. `B.fields` containing `A.fields` as a
|
|
23
|
+
// proper subset means B is A plus something. Whether B is GENUINELY an A -- or two
|
|
24
|
+
// declarations that happen to share field names, or the same name declared twice
|
|
25
|
+
// with different fields -- is the judgement, and it used to be left to the reader.
|
|
26
|
+
/**
|
|
27
|
+
* A declaration's OWN fields, with the compiler's type where there is one.
|
|
28
|
+
*
|
|
29
|
+
* The field list stays the declaration's (an inherited field is already part of
|
|
30
|
+
* the type it extends, and flattening inheritance would make every subclass look
|
|
31
|
+
* like a copy of its base). The TYPE is the checker's: an annotation is what the
|
|
32
|
+
* author promised, and two fields whose annotations read alike can resolve to
|
|
33
|
+
* different things.
|
|
34
|
+
*/
|
|
35
|
+
const resolvedFieldsOf = (unit) => {
|
|
36
|
+
const facts = unit.typeFacts;
|
|
37
|
+
if (facts === undefined)
|
|
38
|
+
return unit.fieldTypes;
|
|
39
|
+
const resolved = new Map();
|
|
40
|
+
for (const [field, annotation] of unit.fieldTypes) {
|
|
41
|
+
const member = facts.members.find((entry) => entry.name === field);
|
|
42
|
+
resolved.set(field, member === undefined ? annotation : member.type);
|
|
43
|
+
}
|
|
44
|
+
return resolved;
|
|
45
|
+
};
|
|
46
|
+
/**
|
|
47
|
+
* Whether two declarations of one field can compose.
|
|
48
|
+
*
|
|
49
|
+
* Equality is too strict: this rule missed a genuine finding because two of four
|
|
50
|
+
* shared fields are written differently -- `signal` as `AbortSignal | undefined`
|
|
51
|
+
* on one side and `AbortSignal` on the other, `retry` as `RetryPolicy` against
|
|
52
|
+
* `Partial<RetryPolicy>`. Composition resolves both. What it does not resolve is
|
|
53
|
+
* `string` against `number`, which intersects to never. So the test is whether one
|
|
54
|
+
* declaration mentions everything the other does.
|
|
55
|
+
*/
|
|
56
|
+
export const composeTypes = {
|
|
57
|
+
id: RULE_ID,
|
|
58
|
+
severity: "warn",
|
|
59
|
+
description: "A type that repeats every field of another type instead of composing it.",
|
|
60
|
+
judged: true,
|
|
61
|
+
move: "combine",
|
|
62
|
+
onUnavailable: "report",
|
|
63
|
+
messages: messages({
|
|
64
|
+
same_name_drift: "{{name}} is declared in two places and they differ by {{count}} field(s): {{fields}}.",
|
|
65
|
+
same_name_drift_help: "{{name}} is declared at {{wholeAt}} and at {{partAt}} with different fields, so any code that moves between the two is relying on which one it imported.{{unverified}}",
|
|
66
|
+
composes_shared_fields: "{{name}} lists all {{partFields}} field(s) of {{part}} and adds {{count}}.",
|
|
67
|
+
composes_shared_fields_help: "Declare it as {{name}} = {{part}} & { {{fields}} } so the shared part stays canonical and cannot drift from {{part}} ({{partAt}}).{{unverified}}",
|
|
68
|
+
}),
|
|
69
|
+
plan: Effect.fn("joggle/compose-types")(function* (workspace, scope) {
|
|
70
|
+
const report = reporter(composeTypes, locator(workspace));
|
|
71
|
+
const all = workspace.units.filter(typeUnits(policy.composeTypes.minFields));
|
|
72
|
+
if (all.length === 0) {
|
|
73
|
+
return {
|
|
74
|
+
plans: [],
|
|
75
|
+
read: () => outcome([], [
|
|
76
|
+
"no type declaration has " +
|
|
77
|
+
policy.composeTypes.minFields +
|
|
78
|
+
" or more fields, so nothing had a field set to compare",
|
|
79
|
+
]),
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
// Containment lives in the candidate engine: one declaration's own field set
|
|
83
|
+
// is a proper subset of another's. Field-NAME containment is the fact; whether
|
|
84
|
+
// the two are genuinely one type composed of another is the question.
|
|
85
|
+
const candidates = containmentPairs({
|
|
86
|
+
units: workspace.units,
|
|
87
|
+
kinds: ["interface", "type"],
|
|
88
|
+
minFields: policy.composeTypes.minFields,
|
|
89
|
+
maxTypes: policy.composeTypes.maxTypes,
|
|
90
|
+
scope,
|
|
91
|
+
});
|
|
92
|
+
if (candidates.length === 0) {
|
|
93
|
+
return {
|
|
94
|
+
plans: [],
|
|
95
|
+
read: () => outcome([], [
|
|
96
|
+
all.length +
|
|
97
|
+
" type declaration(s) in " +
|
|
98
|
+
new Set(all.map((unit) => [...unitFields(unit)].sort(Order.String).join("\u0000"))).size +
|
|
99
|
+
" distinct field set(s); none contains another as a proper subset",
|
|
100
|
+
]),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
const atoms = yield* Atoms;
|
|
104
|
+
const planned = yield* Effect.forEach(candidates, (candidate) => Effect.gen(function* () {
|
|
105
|
+
const { whole, part, added } = candidate;
|
|
106
|
+
const sameName = whole.name === part.name;
|
|
107
|
+
// The state is the pair and the fields they share, with the declared type
|
|
108
|
+
// of each shared field, so the question can weigh "is B genuinely an A".
|
|
109
|
+
const partFields = resolvedFieldsOf(part);
|
|
110
|
+
const wholeFields = resolvedFieldsOf(whole);
|
|
111
|
+
const shared = unitFields(part).map((field) => ({
|
|
112
|
+
field,
|
|
113
|
+
partType: partFields.get(field) ?? null,
|
|
114
|
+
wholeType: wholeFields.get(field) ?? null,
|
|
115
|
+
}));
|
|
116
|
+
const id = yield* atoms.add({
|
|
117
|
+
whole: { name: whole.name, file: whole.file, line: whole.location.line },
|
|
118
|
+
part: { name: part.name, file: part.file, line: part.location.line },
|
|
119
|
+
sameName,
|
|
120
|
+
shared,
|
|
121
|
+
added,
|
|
122
|
+
});
|
|
123
|
+
const plan = {
|
|
124
|
+
ruleId: RULE_ID,
|
|
125
|
+
subject: whole.name + " (lists " + part.name + ")",
|
|
126
|
+
concerns: [whole.file, part.file],
|
|
127
|
+
atoms: [id],
|
|
128
|
+
violations: VIOLATIONS,
|
|
129
|
+
decisions: {
|
|
130
|
+
verdict: Decision.classify({
|
|
131
|
+
instructions: [
|
|
132
|
+
`\`atoms[${id}].whole\` (${whole.name}) lists all ${unitFields(part).length} field(s) of \`atoms[${id}].part\` (${part.name}) and adds ${added.length}: ${added.join(", ")}.`,
|
|
133
|
+
sameName
|
|
134
|
+
? "The two declarations share a NAME."
|
|
135
|
+
: "The two declarations have different names.",
|
|
136
|
+
`\`atoms[${id}].shared\` is each shared field with its type on both sides.`,
|
|
137
|
+
"How do these two declarations relate?",
|
|
138
|
+
"Answer `composes` when the whole is genuinely the part plus more, so it should be written as the part intersected with the added fields.",
|
|
139
|
+
"When `atoms[${id}].sameName` is true the two declarations share a NAME, so answer `same_name_drift`: composing a type with itself is nonsense, however the fields line up.",
|
|
140
|
+
"When one side is a raw or wire mirror -- a `*Row`, an `Unparsed*`, a `*Json` -- the two are different artefacts rather than one composition, so answer `independent`.",
|
|
141
|
+
`\`atoms[${id}].whole.file\` and \`atoms[${id}].part.file\` are the two files. When one name appears in two deployables that cannot import each other, such as a server under services/rest and a client under services/ui, each side must define its own shape: answer \`independent\`, however the fields line up.`,
|
|
142
|
+
"Answer `same_name_drift` when the two share a name inside one deployable and one has drifted from the other, so one should be renamed or the two unified.",
|
|
143
|
+
"Answer `independent` when the shared fields are a coincidence and the two types are unrelated.",
|
|
144
|
+
"Answer `already_composed` when the whole already states its composition, so there is nothing to change.",
|
|
145
|
+
].join("\n"),
|
|
146
|
+
criteria: {
|
|
147
|
+
composes: "The whole is the part plus more. Write it as part & { the added fields }.",
|
|
148
|
+
same_name_drift: "One name, two different shapes. Rename one, or unify them.",
|
|
149
|
+
independent: "Coincidental overlap, or two different artefacts (a domain type and its raw or wire mirror). The two are unrelated.",
|
|
150
|
+
already_composed: "The composition is already written.",
|
|
151
|
+
},
|
|
152
|
+
}),
|
|
153
|
+
},
|
|
154
|
+
read: (answers) => answers,
|
|
155
|
+
};
|
|
156
|
+
return { candidate, id, plan };
|
|
157
|
+
}), { concurrency: "unbounded" });
|
|
158
|
+
return {
|
|
159
|
+
plans: planned.map((value) => value.plan),
|
|
160
|
+
read: (answers) => {
|
|
161
|
+
const verdicts = verdictsOf(answers);
|
|
162
|
+
const diagnostics = [];
|
|
163
|
+
const drops = [];
|
|
164
|
+
planned.forEach((value, index) => {
|
|
165
|
+
const { whole, part } = value.candidate;
|
|
166
|
+
const subject = whole.name + " (lists " + part.name + ")";
|
|
167
|
+
const answer = verdicts[index];
|
|
168
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
169
|
+
if (verdict === undefined) {
|
|
170
|
+
diagnostics.push(findingFor({
|
|
171
|
+
report,
|
|
172
|
+
candidate: value.candidate,
|
|
173
|
+
confidence: undefined,
|
|
174
|
+
unverifiedReason: "no judgement was available",
|
|
175
|
+
label: undefined,
|
|
176
|
+
review: false,
|
|
177
|
+
}));
|
|
178
|
+
return;
|
|
179
|
+
}
|
|
180
|
+
// Two moves, one rule. `composes` is a COMBINE: the primitives exist
|
|
181
|
+
// and the combination was never written, so it is a notice -- every one
|
|
182
|
+
// true, none urgent, and all of them the low band of the same question.
|
|
183
|
+
// A shared name is an EXPAND: one name means two things, so the
|
|
184
|
+
// vocabulary has to grow.
|
|
185
|
+
if (verdict.label !== "same_name_drift" && verdict.label !== "composes") {
|
|
186
|
+
drops.push({
|
|
187
|
+
ruleId: RULE_ID,
|
|
188
|
+
subject,
|
|
189
|
+
stage: "declined",
|
|
190
|
+
reason: verdict.label === "already_composed"
|
|
191
|
+
? "the composition is already stated"
|
|
192
|
+
: "the shared fields are a coincidence",
|
|
193
|
+
});
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
const quality = qualityOf({
|
|
197
|
+
score: verdict.probability,
|
|
198
|
+
margin: verdict.margin,
|
|
199
|
+
confidence: verdict.confidence,
|
|
200
|
+
});
|
|
201
|
+
if (quality.quality === "drop") {
|
|
202
|
+
drops.push({
|
|
203
|
+
ruleId: RULE_ID,
|
|
204
|
+
subject,
|
|
205
|
+
stage: "gated",
|
|
206
|
+
reason: quality.reason,
|
|
207
|
+
});
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
const review = quality.quality === "review";
|
|
211
|
+
diagnostics.push(findingFor({
|
|
212
|
+
report,
|
|
213
|
+
candidate: value.candidate,
|
|
214
|
+
confidence: verdict.confidence,
|
|
215
|
+
unverifiedReason: undefined,
|
|
216
|
+
label: verdict.label,
|
|
217
|
+
review,
|
|
218
|
+
}));
|
|
219
|
+
});
|
|
220
|
+
return outcome(diagnostics, [], drops);
|
|
221
|
+
},
|
|
222
|
+
};
|
|
223
|
+
}),
|
|
224
|
+
};
|
|
225
|
+
const findingFor = ({ report, candidate, confidence, unverifiedReason, label, review, }) => {
|
|
226
|
+
const { whole, part, added } = candidate;
|
|
227
|
+
const drifted = label === "same_name_drift" || (label === undefined && whole.name === part.name);
|
|
228
|
+
return report({
|
|
229
|
+
about: whole,
|
|
230
|
+
messageId: drifted ? "same_name_drift" : "composes_shared_fields",
|
|
231
|
+
data: {
|
|
232
|
+
name: whole.name,
|
|
233
|
+
part: part.name,
|
|
234
|
+
count: added.length,
|
|
235
|
+
fields: added.join(drifted ? ", " : "; "),
|
|
236
|
+
partFields: unitFields(part).length,
|
|
237
|
+
wholeAt: whole.file + ":" + whole.location.line,
|
|
238
|
+
partAt: part.file + ":" + part.location.line,
|
|
239
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
240
|
+
},
|
|
241
|
+
helpId: drifted ? "same_name_drift_help" : "composes_shared_fields_help",
|
|
242
|
+
identity: [RULE_ID, whole.file, whole.name, part.name, drifted ? "drift" : "compose"].join("\u0000"),
|
|
243
|
+
judged: unverifiedReason === undefined,
|
|
244
|
+
confidence,
|
|
245
|
+
severity: review || !drifted ? "info" : "warn",
|
|
246
|
+
// One rule, two moves: writing a combination of primitives, or discovering
|
|
247
|
+
// that one name means two things and the vocabulary has to grow.
|
|
248
|
+
move: drifted ? "expand" : "combine",
|
|
249
|
+
});
|
|
250
|
+
};
|