@autotelic/joggle 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/JOGGLE.md +634 -0
  2. package/LICENSE +21 -0
  3. package/README.md +88 -2
  4. package/bin/joggle.js +6 -0
  5. package/dist/answer-store.js +305 -0
  6. package/dist/architecture.js +190 -0
  7. package/dist/ask.js +184 -0
  8. package/dist/astro.js +75 -0
  9. package/dist/atoms.js +76 -0
  10. package/dist/bundles.js +156 -0
  11. package/dist/calibration.js +60 -0
  12. package/dist/candidates.js +561 -0
  13. package/dist/canonical.js +24 -0
  14. package/dist/cascade.js +98 -0
  15. package/dist/check.js +854 -0
  16. package/dist/cluster.js +69 -0
  17. package/dist/config.js +195 -0
  18. package/dist/content-mappers.js +83 -0
  19. package/dist/decision.js +203 -0
  20. package/dist/fingerprint.js +61 -0
  21. package/dist/git.js +127 -0
  22. package/dist/gitignore.js +65 -0
  23. package/dist/glob.js +51 -0
  24. package/dist/imports.js +153 -0
  25. package/dist/jsonc.js +95 -0
  26. package/dist/main.js +630 -0
  27. package/dist/manifest.js +42 -0
  28. package/dist/meta.js +170 -0
  29. package/dist/moves.js +47 -0
  30. package/dist/operation.js +133 -0
  31. package/dist/parsecache.js +264 -0
  32. package/dist/plans.js +425 -0
  33. package/dist/plugin.js +71 -0
  34. package/dist/plugins.js +136 -0
  35. package/dist/policy.js +676 -0
  36. package/dist/presets/composition.js +32 -0
  37. package/dist/report.js +474 -0
  38. package/dist/reporting.js +132 -0
  39. package/dist/result.js +28 -0
  40. package/dist/roles.js +303 -0
  41. package/dist/rule.js +194 -0
  42. package/dist/rules/append-only-honoured.js +190 -0
  43. package/dist/rules/bundle-conformance.js +245 -0
  44. package/dist/rules/call-pattern.js +209 -0
  45. package/dist/rules/cluster-verdict.js +700 -0
  46. package/dist/rules/compose-types.js +250 -0
  47. package/dist/rules/data-error-as-outage.js +482 -0
  48. package/dist/rules/declared-staleness.js +242 -0
  49. package/dist/rules/dependency-fit.js +297 -0
  50. package/dist/rules/deviation-has-a-shape.js +225 -0
  51. package/dist/rules/doc-matches-code.js +191 -0
  52. package/dist/rules/duplicate-call-run.js +240 -0
  53. package/dist/rules/duplicate-implementation.js +89 -0
  54. package/dist/rules/duplicate-meaning.js +130 -0
  55. package/dist/rules/fact-or-derivation.js +202 -0
  56. package/dist/rules/field-type-drift.js +373 -0
  57. package/dist/rules/generic-carries-a-caller.js +198 -0
  58. package/dist/rules/hoist-to-domain.js +288 -0
  59. package/dist/rules/import-architecture.js +393 -0
  60. package/dist/rules/index.js +105 -0
  61. package/dist/rules/inferred-over-recorded.js +214 -0
  62. package/dist/rules/intent-drift.js +286 -0
  63. package/dist/rules/invariant-has-a-reconciler.js +190 -0
  64. package/dist/rules/language-drift.js +234 -0
  65. package/dist/rules/meaning-switched-by-flag.js +189 -0
  66. package/dist/rules/module-direction.js +231 -0
  67. package/dist/rules/name-as-address.js +216 -0
  68. package/dist/rules/name-the-primitive.js +203 -0
  69. package/dist/rules/naming-drift.js +218 -0
  70. package/dist/rules/nullability-drift.js +220 -0
  71. package/dist/rules/object-shape.js +280 -0
  72. package/dist/rules/one-concept-one-type.js +243 -0
  73. package/dist/rules/page-needs-composition.js +227 -0
  74. package/dist/rules/reimplemented-primitive.js +283 -0
  75. package/dist/rules/reversal.js +264 -0
  76. package/dist/rules/rule-judgment.js +252 -0
  77. package/dist/rules/schema-excludes-domain-value.js +190 -0
  78. package/dist/rules/shallow-module.js +204 -0
  79. package/dist/rules/single-path.js +237 -0
  80. package/dist/rules/structural-collapse.js +198 -0
  81. package/dist/rules/temporal-coupling.js +205 -0
  82. package/dist/rules/types-over-logic.js +198 -0
  83. package/dist/rules/unaccounted-drop.js +190 -0
  84. package/dist/rules/unbounded-default-read.js +227 -0
  85. package/dist/run-cache.js +132 -0
  86. package/dist/schema.js +285 -0
  87. package/dist/similarity.js +119 -0
  88. package/dist/source.js +30 -0
  89. package/dist/sql.js +34 -0
  90. package/dist/stages.js +39 -0
  91. package/dist/state.js +65 -0
  92. package/dist/testing.js +131 -0
  93. package/dist/tsconfig-scope.js +32 -0
  94. package/dist/tsgo.js +127 -0
  95. package/dist/typefacts.js +455 -0
  96. package/dist/typetrace.js +283 -0
  97. package/dist/verdict.js +65 -0
  98. package/dist/vocabulary.js +365 -0
  99. package/dist/workspace.js +1963 -0
  100. package/extensions/joggle.ts +454 -0
  101. package/package.json +85 -3
@@ -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
+ };