@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,365 @@
|
|
|
1
|
+
import { Schema } from "effect";
|
|
2
|
+
import { Decision } from "effect/ai";
|
|
3
|
+
/*
|
|
4
|
+
* Every word the model is asked to choose between, in one file.
|
|
5
|
+
*
|
|
6
|
+
* jev keeps its thresholds AND its whole vocabulary in a config module with no
|
|
7
|
+
* imports: five dimensions, thirty mechanism strings, four rubric levels. Tuning
|
|
8
|
+
* that system is editing data. joggle had the thresholds in policy.ts and the
|
|
9
|
+
* vocabulary scattered through the rules that used them, which meant the only way
|
|
10
|
+
* to compare two questions was to read two files -- and comparing them side by
|
|
11
|
+
* side is exactly how you notice that one of them has no way to say "this is
|
|
12
|
+
* fine", which is the bug the previous commit fixed.
|
|
13
|
+
*
|
|
14
|
+
* The split is by whether a string depends on the candidate. A string that is the
|
|
15
|
+
* same for every candidate lives here. A criterion that names the member being
|
|
16
|
+
* kept, or counts the declarations shown, is built in the rule that knows those
|
|
17
|
+
* facts -- so the WORDS still come from here, through a template.
|
|
18
|
+
*/
|
|
19
|
+
/** The shared question for exact and near duplicates. */
|
|
20
|
+
export const duplicateVocabulary = {
|
|
21
|
+
redundant: {
|
|
22
|
+
true: "One declaration would serve better than several.",
|
|
23
|
+
false: "The repetition is justified.",
|
|
24
|
+
},
|
|
25
|
+
/**
|
|
26
|
+
* What a declaration IS, which decides what to do about it being duplicated.
|
|
27
|
+
*
|
|
28
|
+
* The same duplication has opposite prescriptions depending on this answer and
|
|
29
|
+
* nothing else. A wire contract defined on both sides of a service boundary is
|
|
30
|
+
* correct -- two packages that must not depend on each other share a shape,
|
|
31
|
+
* not a module. A domain concept defined on both sides is the defect the whole
|
|
32
|
+
* architecture exists to prevent. The package fact says which can reach which;
|
|
33
|
+
* the model is the thing that can tell what the declaration is.
|
|
34
|
+
*/
|
|
35
|
+
role: {
|
|
36
|
+
wire_contract: "A shape that crosses a process or protocol boundary: a request body, a response, a serialized record.",
|
|
37
|
+
domain_concept: "A thing the business has an opinion about, with rules or meaning attached to it.",
|
|
38
|
+
implementation_detail: "A helper that exists to make other code work, and means nothing on its own.",
|
|
39
|
+
framework_glue: "A shape a framework requires, such as route props, loader data, or a config object.",
|
|
40
|
+
},
|
|
41
|
+
/**
|
|
42
|
+
* How much it MATTERS, which is a different question from whether it is true.
|
|
43
|
+
*
|
|
44
|
+
* The report used to sort by redundancy -- "are these one thing?" -- and on one
|
|
45
|
+
* repository that put the lowest score in the whole report on a spec that
|
|
46
|
+
* re-implements the function it tests, while three placeholder aliases that
|
|
47
|
+
* were all `any` sat above it at 0.68. Both answers were correct. Sorting by
|
|
48
|
+
* the answer to the wrong question is how a real finding ends up last.
|
|
49
|
+
*
|
|
50
|
+
* A Score, not a Noul, because "would a reader be better off" is a degree and a
|
|
51
|
+
* Noul throws the degree away: 0.55 and 0.95 both mean yes, and the report
|
|
52
|
+
* sorts on this answer, so the degree is the thing that was wanted. The levels
|
|
53
|
+
* are ordered lowest to highest. Their descriptions live in the question's
|
|
54
|
+
* instructions, because a Rate's criteria ARE the level names.
|
|
55
|
+
*/
|
|
56
|
+
consequenceLevels: [
|
|
57
|
+
"no_difference",
|
|
58
|
+
"slightly_clearer",
|
|
59
|
+
"meaningfully_better",
|
|
60
|
+
"removes_a_hazard",
|
|
61
|
+
],
|
|
62
|
+
/**
|
|
63
|
+
* What the DIFFERENCE between two near-identical declarations is.
|
|
64
|
+
*
|
|
65
|
+
* This is the question that separates a merge from a move, and nothing asked it
|
|
66
|
+
* before: `role` says what a declaration is, and `relationship` says where the
|
|
67
|
+
* files sit, and neither says whether the thing that differs between the copies
|
|
68
|
+
* is a value or a meaning.
|
|
69
|
+
*/
|
|
70
|
+
difference: {
|
|
71
|
+
value: "The same thing with a different constant, option or parameter, so one could take the other's.",
|
|
72
|
+
meaning: "A different concept that happens to read alike.",
|
|
73
|
+
unclear: "The evidence does not say.",
|
|
74
|
+
},
|
|
75
|
+
/**
|
|
76
|
+
* What to DO about it, asked rather than tabulated.
|
|
77
|
+
*
|
|
78
|
+
* `prescriptionFor` was a table over `(role, relationship)`, and a table over
|
|
79
|
+
* two answers is the code deciding an order the model can decide in one
|
|
80
|
+
* question. It is asked instead, with the facts the table used to encode as
|
|
81
|
+
* STATE rather than as branches: the operations the import graph permits are
|
|
82
|
+
* already computed, so the options are the ones that can actually happen.
|
|
83
|
+
*/
|
|
84
|
+
prescription: {
|
|
85
|
+
merge: "Delete the copies and import one. These files can reach each other, so the survivor is available to all of them.",
|
|
86
|
+
move: "The shared part belongs somewhere every copy can depend on. Move it there and import it from each site.",
|
|
87
|
+
split: "One name with two meanings. Give each meaning its own name and declaration.",
|
|
88
|
+
share_a_contract: "Keep both declarations and give them one shared contract to agree on. For when no permitted operation can replace one with the other.",
|
|
89
|
+
leave_it: "Framework shapes and stable copies that nobody will change. Leave them as they are.",
|
|
90
|
+
},
|
|
91
|
+
verdict: {
|
|
92
|
+
collapse: "They are one thing. Keep one of them and delete the rest.",
|
|
93
|
+
keep_variants: "Related but deliberately separate, such as a special case of a general routine. Keep them all.",
|
|
94
|
+
no_issue: "Coincidentally similar. They are different things. Change nothing.",
|
|
95
|
+
},
|
|
96
|
+
};
|
|
97
|
+
/** Name pairs: two spellings of one concept, or two different concepts. */
|
|
98
|
+
export const nameVocabulary = {
|
|
99
|
+
oneConcept: {
|
|
100
|
+
true: "One concept, so one name should go.",
|
|
101
|
+
false: "Two concepts, so both names are correct.",
|
|
102
|
+
},
|
|
103
|
+
/**
|
|
104
|
+
* The two "one concept" options differ only in WHICH name survives, so the
|
|
105
|
+
* sentence is one template and the rule supplies the symbol.
|
|
106
|
+
*/
|
|
107
|
+
standardize: (symbol) => "One concept, two spellings. Standardize on `" + symbol + "`.",
|
|
108
|
+
noIssue: "Two different concepts. Both names are correct. Change nothing.",
|
|
109
|
+
};
|
|
110
|
+
/**
|
|
111
|
+
* What "extract this into a bundle" means, per kind of file.
|
|
112
|
+
*
|
|
113
|
+
* This is the `mechanisms[dimension]` shape from the TypeSafe docs: the first
|
|
114
|
+
* question's ANSWER selects the OPTIONS of the second. A route page and a modal
|
|
115
|
+
* are both worth asking about, but a bundle means a different thing to each -- a
|
|
116
|
+
* route owns a screen and its navigation state, a modal owns one interaction and
|
|
117
|
+
* its dismissal. Asking both with one vocabulary is how a question gets an answer
|
|
118
|
+
* that is true of neither.
|
|
119
|
+
*/
|
|
120
|
+
export const pageVerdictByRole = {
|
|
121
|
+
route_page: {
|
|
122
|
+
extract_to_bundle: "Its state and its screen-wide pieces belong in a bundle with `{ state, actions, meta }`, exported by dot notation.",
|
|
123
|
+
extract_some: "Part of it does, such as the panel that always travels with the data it reads.",
|
|
124
|
+
no_issue: "No. This page's state is genuinely its own and a provider would be ceremony between it and its children.",
|
|
125
|
+
},
|
|
126
|
+
modal: {
|
|
127
|
+
extract_to_bundle: "Its draft state and its steps belong in a bundle, so the form and its actions are not threaded through each step.",
|
|
128
|
+
extract_some: "Part of it does, such as the step controls that repeat per field.",
|
|
129
|
+
no_issue: "No. A modal with one piece of state and one submit needs no provider to share anything.",
|
|
130
|
+
},
|
|
131
|
+
layout: {
|
|
132
|
+
extract_to_bundle: "It owns state that its children read, which is a bundle's job rather than a layout's.",
|
|
133
|
+
extract_some: "Part of it does, such as the chrome that several children configure.",
|
|
134
|
+
no_issue: "No. A layout that renders children and owns nothing is exactly what a layout should be.",
|
|
135
|
+
},
|
|
136
|
+
};
|
|
137
|
+
/**
|
|
138
|
+
* What a module is FOR, asked once per module rather than once per declaration.
|
|
139
|
+
*
|
|
140
|
+
* The same classification-first move as the page rule and the dependency check,
|
|
141
|
+
* one level up: "business logic at the edge" only means something at an edge, so
|
|
142
|
+
* the first question is whether this is one. On one repository this separated
|
|
143
|
+
* 1,259 declarations into the modules that could contain a hoist candidate and the
|
|
144
|
+
* modules that could not, and it gives every later question the context it was
|
|
145
|
+
* previously missing.
|
|
146
|
+
*/
|
|
147
|
+
export const moduleRoles = {
|
|
148
|
+
domain_core: "The rules and shapes the business is about. Other modules depend on it and it depends on nothing internal.",
|
|
149
|
+
transport_edge: "HTTP: handlers, routes, request parsing, response shaping, status codes.",
|
|
150
|
+
rendering_edge: "A user interface: components, routes, forms, view state.",
|
|
151
|
+
infrastructure: "A database, a queue, a mail sender, or a client for a third party.",
|
|
152
|
+
/**
|
|
153
|
+
* The machinery of the tool or library itself.
|
|
154
|
+
*
|
|
155
|
+
* Added because running joggle against its own source put `check.ts`,
|
|
156
|
+
* `report.ts`, `decision.ts` and `rule.ts` in `not_applicable` -- the bucket meant
|
|
157
|
+
* for tests, scripts and configuration. Nothing should be hoisted out of an
|
|
158
|
+
* engine either, so the outcome was right, but it was right by accident: the
|
|
159
|
+
* model reached for the nearest option because the vocabulary had none for a
|
|
160
|
+
* repository that IS the application. `not_applicable` is where a mistake hides,
|
|
161
|
+
* since a declaration wrongly put there is silently never a candidate.
|
|
162
|
+
*/
|
|
163
|
+
library_core: "The machinery of this tool or library itself, which exists to serve code outside it.",
|
|
164
|
+
utilities: "Generic helpers that would make sense in any codebase.",
|
|
165
|
+
not_applicable: "Tests, scripts, migrations, seeds or configuration.",
|
|
166
|
+
};
|
|
167
|
+
/**
|
|
168
|
+
* Which roles are edges, for the rules that ask "is this the outer layer?".
|
|
169
|
+
*
|
|
170
|
+
* `EDGE_ROLES` was a constant set, and it is the same defect `roleRank` had: it
|
|
171
|
+
* hardcodes that transport and rendering are the outer layer. With a rank in
|
|
172
|
+
* hand it is derivable -- an edge is the highest layer this repository has --
|
|
173
|
+
* and a rule that needs the set builds it from the answer.
|
|
174
|
+
*/
|
|
175
|
+
export const edgeRolesOf = (ranks) => {
|
|
176
|
+
let top = Number.NEGATIVE_INFINITY;
|
|
177
|
+
for (const rank of ranks.values())
|
|
178
|
+
if (rank > top)
|
|
179
|
+
top = rank;
|
|
180
|
+
const edges = new Set();
|
|
181
|
+
for (const [role, rank] of ranks)
|
|
182
|
+
if (rank === top)
|
|
183
|
+
edges.add(role);
|
|
184
|
+
return edges;
|
|
185
|
+
};
|
|
186
|
+
/**
|
|
187
|
+
* Whether a module can hold a declaration that has crept out of the core.
|
|
188
|
+
*
|
|
189
|
+
* The constant, kept for the vocabulary's own tests and as the fallback a rule
|
|
190
|
+
* uses when no rank was decided. A rule with ranks should call `edgeRolesOf`.
|
|
191
|
+
*/
|
|
192
|
+
export const EDGE_ROLES = new Set(["transport_edge", "rendering_edge"]);
|
|
193
|
+
/** The rank a role label means, for the arithmetic. */
|
|
194
|
+
export const rankOfLabel = {
|
|
195
|
+
utilities: 0,
|
|
196
|
+
// A module the run could not classify still occupies a layer; the helpers and
|
|
197
|
+
// third-party clients that nothing internal depends on sit at the bottom.
|
|
198
|
+
below_everything: 0,
|
|
199
|
+
infrastructure: 1,
|
|
200
|
+
// The machinery of a tool or library sits at its own repository's level.
|
|
201
|
+
derives_from: 2,
|
|
202
|
+
domain_core: 2,
|
|
203
|
+
library_core: 2,
|
|
204
|
+
domain: 2,
|
|
205
|
+
transport_edge: 3,
|
|
206
|
+
rendering_edge: 3,
|
|
207
|
+
};
|
|
208
|
+
/**
|
|
209
|
+
* The layer ordering, as data the rules read.
|
|
210
|
+
*
|
|
211
|
+
* `rankOf(role)` is the model's answer written back into one number, which is
|
|
212
|
+
* the same shape `roleRank` had -- except the table is now the labels, and the
|
|
213
|
+
* answer comes from the repository rather than from this file.
|
|
214
|
+
*/
|
|
215
|
+
export const rankOf = (label) => rankOfLabel[label];
|
|
216
|
+
/**
|
|
217
|
+
* The rank question, whole.
|
|
218
|
+
*
|
|
219
|
+
* Lives here rather than in `roles.ts` because every string a model is asked to
|
|
220
|
+
* choose between belongs in one file -- the same reason the rest of this module
|
|
221
|
+
* exists.
|
|
222
|
+
*/
|
|
223
|
+
const RankEvidence = Schema.Struct({
|
|
224
|
+
repository: Schema.optionalKey(Schema.String),
|
|
225
|
+
roles: Schema.Array(Schema.String),
|
|
226
|
+
});
|
|
227
|
+
export const RoleRanking = Decision.make({
|
|
228
|
+
input: RankEvidence,
|
|
229
|
+
decisions: {
|
|
230
|
+
order: Decision.classify({
|
|
231
|
+
instructions: [
|
|
232
|
+
"Put the roles in `roles` in this codebase's dependency order, lowest first.",
|
|
233
|
+
"A module in a lower layer must never depend on a module in a higher one.",
|
|
234
|
+
"The lowest layer holds things everything else may use: generic helpers and third-party clients.",
|
|
235
|
+
"Above that sits the domain: the rules and shapes the business is about.",
|
|
236
|
+
"Above the domain sit the edges: HTTP that calls it and UI that renders it.",
|
|
237
|
+
"`library_core` is the machinery of a tool or library; place it where this repository's engine actually sits.",
|
|
238
|
+
"`not_applicable` is outside the order: tests, scripts and configuration are not part of it.",
|
|
239
|
+
"Choose the option whose description names the role that should sit LOWEST in this repository.",
|
|
240
|
+
].join("\n"),
|
|
241
|
+
criteria: Object.fromEntries(Object.entries(moduleRoles).map(([role, description]) => [role, description])),
|
|
242
|
+
}),
|
|
243
|
+
},
|
|
244
|
+
});
|
|
245
|
+
/** The order, for the note. */
|
|
246
|
+
export const layerOrder = [
|
|
247
|
+
"utilities",
|
|
248
|
+
"infrastructure",
|
|
249
|
+
"domain_core",
|
|
250
|
+
"transport_edge",
|
|
251
|
+
];
|
|
252
|
+
/**
|
|
253
|
+
* What a declaration is doing, which decides whether its location is a problem.
|
|
254
|
+
*
|
|
255
|
+
* The same distinction the duplicate rule needs, one level up. A calculation is a
|
|
256
|
+
* domain rule in any file; a status code is a transport concern in any file. The
|
|
257
|
+
* model is asked what the thing IS, and the code decides whether that is where it
|
|
258
|
+
* belongs.
|
|
259
|
+
*/
|
|
260
|
+
export const dutyVocabulary = {
|
|
261
|
+
domain_logic: "A rule, invariant or calculation about the business: something that would be true of the company even if this software were rewritten.",
|
|
262
|
+
recording: "Freezing a decision with its instant, its authority and the inputs it was made from. `orchestration` is the nearest label and it is wrong: recording owns the rule that the record may not be rewritten. `infrastructure` is wrong for the same reason it is right for a query: the database is where it lands, not what it is.",
|
|
263
|
+
derivation: "Materialising a view of records for cheap reads, joins and aggregates. `mechanical` is the nearest label and it says no business meaning, which is the opposite of the problem: a stale projection is a business claim made from stored data.",
|
|
264
|
+
reconciliation: "Restoring an invariant that spans rows and time. `domain_logic` is nearly right and is exactly what makes it dangerous: it invites the repair to be read as a pure function, when the thing being repaired is stored data.",
|
|
265
|
+
request_validation: "A rule about what the endpoint will ACCEPT: which fields are required, which values are in range, which options are mutually exclusive, and what earns a 400. It constrains the transport contract, not the business, and the same endpoint's UI may hold a different set of rules.",
|
|
266
|
+
input_adaptation: "Reshaping input into what another layer expects: mapping database columns or a form's fields onto a domain schema. The rule is the domain's; this only converts.",
|
|
267
|
+
mechanical: "A cache key, an identifier, a lookup table or a memoisation argument: a value that exists to make other code fast or addressable, with no business meaning.",
|
|
268
|
+
transport_concern: "Parsing a request, shaping a response, choosing a status code, or reading a header.",
|
|
269
|
+
rendering: "Producing markup, or preparing data purely for display.",
|
|
270
|
+
orchestration: "Calling other things in order, owning no rules of its own.",
|
|
271
|
+
infrastructure: "Talking to a database, a queue, a file system or a third-party service. A function that takes a database handle -- Knex, a transaction, a connection -- is infrastructure however much business logic it reads out of rows: the domain is pure by design, so moving the query into it is the wrong repair.",
|
|
272
|
+
not_applicable: "None of these: a helper with no meaning outside its immediate caller.",
|
|
273
|
+
};
|
|
274
|
+
/**
|
|
275
|
+
* Whether a 5xx is the right answer to a row that is not there.
|
|
276
|
+
*
|
|
277
|
+
* The amplifier the nullability work cannot see: the data is legitimately
|
|
278
|
+
* absent, and the endpoint reports a server outage for it. One question, three
|
|
279
|
+
* options, and the code reads the answer -- which is what Jev is for.
|
|
280
|
+
*/
|
|
281
|
+
export const dataErrorVocabulary = {
|
|
282
|
+
row_absence_is_normal: "The row being absent, or its data being undecodable, is a normal outcome for this request. A 5xx tells the caller the server is broken when it is not: it should be a 404, an empty list, or a 4xx the caller caused.",
|
|
283
|
+
row_absence_is_an_error: "The failure is a genuine server fault, or an empty row here means data that must exist does not, so a 5xx is honest.",
|
|
284
|
+
not_applicable: "The branch is not about a row's absence.",
|
|
285
|
+
};
|
|
286
|
+
/**
|
|
287
|
+
* Whether a file is already where logic like this belongs.
|
|
288
|
+
*
|
|
289
|
+
* The question a declared `domain` layer would have answered. Asked instead of
|
|
290
|
+
* configured, so a repository that has not written its layering down still gets
|
|
291
|
+
* an answer -- and one that HAS written it down can pin this decision later.
|
|
292
|
+
*/
|
|
293
|
+
export const homeVocabulary = {
|
|
294
|
+
already_there: "Yes: this is a domain or model package, which is where rules live.",
|
|
295
|
+
route_or_handler: "No: a route, a handler or an HTTP edge, which should be calling a rule rather than containing one.",
|
|
296
|
+
component_or_feature: "No: a component or feature directory, which should be rendering a rule's answer rather than deciding it.",
|
|
297
|
+
not_applicable: "Cannot tell from the path.",
|
|
298
|
+
};
|
|
299
|
+
/**
|
|
300
|
+
* Whether a dependency fits what a module is for.
|
|
301
|
+
*
|
|
302
|
+
* Its own export rather than a corner of another purpose's vocabulary, because
|
|
303
|
+
* this rule is its own opinion: a repository that enables duplication checks and
|
|
304
|
+
* not this one should never see these words.
|
|
305
|
+
*/
|
|
306
|
+
export const dependencyVocabulary = {
|
|
307
|
+
belongs: "This dependency fits what this module is for.",
|
|
308
|
+
framework_expected: "This module is exactly where that framework belongs.",
|
|
309
|
+
violates: "This module should not depend on that, and the architecture says why.",
|
|
310
|
+
};
|
|
311
|
+
/**
|
|
312
|
+
* The page rule's decisions, whole.
|
|
313
|
+
*
|
|
314
|
+
* Every string here is fixed, so there is nothing to build per candidate and
|
|
315
|
+
* nothing to keep in the rule.
|
|
316
|
+
*/
|
|
317
|
+
export const pageDecisions = {
|
|
318
|
+
role: Decision.classify({
|
|
319
|
+
instructions: [
|
|
320
|
+
"What kind of file is `page.path`?",
|
|
321
|
+
"Classify the file by what it is, not by whether it conforms. This answer decides which question is asked next, so a wrong classification wastes the rest of the request.",
|
|
322
|
+
"Choose \"not_applicable\" when it is none of these.",
|
|
323
|
+
].join("\n"),
|
|
324
|
+
criteria: {
|
|
325
|
+
route_page: "A route's own page: it owns layout and state for one screen.",
|
|
326
|
+
modal: "A dialog or modal: it owns state for one interaction and is opened and closed rather than navigated to.",
|
|
327
|
+
layout: "A shell that renders children and owns little or no state of its own.",
|
|
328
|
+
not_applicable: "A helper, a loader, a test, or something else this pattern does not apply to.",
|
|
329
|
+
},
|
|
330
|
+
}),
|
|
331
|
+
verdict: Decision.classify({
|
|
332
|
+
instructions: [
|
|
333
|
+
"Should this file's state and markup live in a composition bundle instead?",
|
|
334
|
+
"Inspect `page`.",
|
|
335
|
+
"The pattern earns its keep when several blocks share state that this file currently threads itself. A file with its own state and no sharing between pieces does not need it.",
|
|
336
|
+
"Judge whether a bundle would remove real duplication of state, not whether this file is long.",
|
|
337
|
+
"Choose `no_issue` when the state is this file's own and nothing is shared.",
|
|
338
|
+
].join("\n"),
|
|
339
|
+
criteria: {
|
|
340
|
+
extract_to_bundle: "Its state and its pieces belong in a bundle with `{ state, actions, meta }`, exported by dot notation.",
|
|
341
|
+
extract_some: "Part of it does, such as a repeated block or a group of elements that always travel together.",
|
|
342
|
+
no_issue: "No. The state is genuinely this file's own and a provider would be ceremony.",
|
|
343
|
+
},
|
|
344
|
+
}),
|
|
345
|
+
primary_gap: Decision.classify({
|
|
346
|
+
instructions: [
|
|
347
|
+
"What is the single most useful thing to change about `page.path`?",
|
|
348
|
+
"Name the gap a reviewer would fix first, or `no_issue` when there is nothing to fix.",
|
|
349
|
+
"Choose `no_issue` when there is nothing to fix.",
|
|
350
|
+
].join("\n"),
|
|
351
|
+
criteria: {
|
|
352
|
+
state_belongs_in_provider: "State threaded here belongs in a provider the pieces read directly.",
|
|
353
|
+
markup_belongs_in_blocks: "Markup inlined here belongs in named blocks, one per file.",
|
|
354
|
+
no_provider_root: "It needs the bundle's provider at its composition root.",
|
|
355
|
+
no_issue: "Nothing; leave this page as it is.",
|
|
356
|
+
},
|
|
357
|
+
}),
|
|
358
|
+
worth_fixing: Decision.probability({
|
|
359
|
+
instructions: "Is extracting a bundle from this page worth a reviewer's time? A page that works and shares nothing is not worth restructuring for its own sake.",
|
|
360
|
+
criteria: {
|
|
361
|
+
false: "Leave it alone.",
|
|
362
|
+
true: "A reviewer should look at this.",
|
|
363
|
+
},
|
|
364
|
+
}),
|
|
365
|
+
};
|