@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
package/dist/manifest.js
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { Effect, FileSystem, Path, Result, Schema, SchemaParser } from "effect";
|
|
2
|
+
const PackageManifestJson = Schema.Struct({
|
|
3
|
+
name: Schema.NonEmptyString,
|
|
4
|
+
description: Schema.optionalKey(Schema.String),
|
|
5
|
+
dependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
|
|
6
|
+
peerDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
|
|
7
|
+
devDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
|
|
8
|
+
});
|
|
9
|
+
/**
|
|
10
|
+
* Reads and decodes the `package.json` in one directory.
|
|
11
|
+
*
|
|
12
|
+
* @param directory - The directory to read `package.json` from.
|
|
13
|
+
* @returns The decoded manifest, or `undefined` when the file is absent or does
|
|
14
|
+
* not name the package.
|
|
15
|
+
*/
|
|
16
|
+
export const manifestAt = (directory) => Effect.gen(function* () {
|
|
17
|
+
const fs = yield* FileSystem.FileSystem;
|
|
18
|
+
const path = yield* Path.Path;
|
|
19
|
+
const file = path.join(directory, "package.json");
|
|
20
|
+
const exists = yield* Effect.orElseSucceed(fs.exists(file), () => false);
|
|
21
|
+
if (!exists)
|
|
22
|
+
return undefined;
|
|
23
|
+
const text = yield* Effect.orElseSucceed(fs.readFileString(file), () => "");
|
|
24
|
+
const decoded = Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(PackageManifestJson))(text));
|
|
25
|
+
if (decoded === undefined)
|
|
26
|
+
return undefined;
|
|
27
|
+
// Every kind of dependency, because the question this answers is "has the
|
|
28
|
+
// package declared it?" and a devDependency is a declaration. Restricting
|
|
29
|
+
// this to runtime dependencies flagged `chai` and `@faker-js/faker` as
|
|
30
|
+
// undeclared imports, which they are not -- the distinction between runtime
|
|
31
|
+
// and development belongs to the judgement about whether an import FITS, and
|
|
32
|
+
// that is the model's question, not this one's.
|
|
33
|
+
const declares = [];
|
|
34
|
+
for (const field of ["dependencies", "peerDependencies", "devDependencies"]) {
|
|
35
|
+
declares.push(...Object.keys(decoded[field] ?? {}));
|
|
36
|
+
}
|
|
37
|
+
return {
|
|
38
|
+
name: decoded.name,
|
|
39
|
+
summary: decoded.description,
|
|
40
|
+
declares,
|
|
41
|
+
};
|
|
42
|
+
});
|
package/dist/meta.js
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
// Meta-rules: the fence for rule authors.
|
|
2
|
+
//
|
|
3
|
+
// plumb ships rules that lint its own plugin authors (`require-create-once`,
|
|
4
|
+
// `require-rule-tester`, `no-manual-ancestor-walks`). joggle had none, which is
|
|
5
|
+
// why this session shipped a rule with no `violations`, an unbounded atom and an
|
|
6
|
+
// inline message before anyone noticed. These are the same idea: a small, named
|
|
7
|
+
// set of invariants every rule in this repository must keep, checkable from the
|
|
8
|
+
// source and enforced by a test.
|
|
9
|
+
//
|
|
10
|
+
// They are deliberately source-level. A rule's `plan` cannot be run without a
|
|
11
|
+
// workspace and a model, so the check reads what a rule declares rather than what
|
|
12
|
+
// it does -- the same trade plumb's meta-rules make over the plugin source.
|
|
13
|
+
/**
|
|
14
|
+
* The `atoms.add({...})` arguments in a source, by balanced braces.
|
|
15
|
+
*
|
|
16
|
+
* A source scan rather than a parse: the check only needs to see whether an atom
|
|
17
|
+
* carries a whole file, and the balanced-brace walk is enough to tell that from a
|
|
18
|
+
* sliced one.
|
|
19
|
+
*/
|
|
20
|
+
export const atomPayloads = (source) => {
|
|
21
|
+
const found = [];
|
|
22
|
+
const marker = "atoms.add(";
|
|
23
|
+
let cursor = source.indexOf(marker);
|
|
24
|
+
while (cursor !== -1) {
|
|
25
|
+
const open = cursor + marker.length;
|
|
26
|
+
let depth = 0;
|
|
27
|
+
let index = open;
|
|
28
|
+
for (; index < source.length; index += 1) {
|
|
29
|
+
const character = source[index];
|
|
30
|
+
if (character === "(" || character === "{")
|
|
31
|
+
depth += 1;
|
|
32
|
+
else if (character === ")" || character === "}") {
|
|
33
|
+
depth -= 1;
|
|
34
|
+
if (depth === 0)
|
|
35
|
+
break;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
found.push(source.slice(open, index + 1));
|
|
39
|
+
cursor = source.indexOf(marker, index);
|
|
40
|
+
}
|
|
41
|
+
return found;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* True when the payload carries a whole file rather than a slice of one.
|
|
45
|
+
*
|
|
46
|
+
* The signal is a literal `.text` (or `text:`) with no `.slice(` beside it. A
|
|
47
|
+
* named field such as `source: candidate.text` is the rule's own bounded
|
|
48
|
+
* sample, whose bound is set where the candidate is built, and this check cannot
|
|
49
|
+
* see that far -- so it does not guess.
|
|
50
|
+
*/
|
|
51
|
+
const unbounded = (payload) => /(\.text\b|\btext\s*:)/.test(payload) && !payload.includes(".slice(");
|
|
52
|
+
/** A regex literal on its own line: ` /^(format|shown)/,`. */
|
|
53
|
+
const REGEX_LINE = /^\s*\/[^/*\n][^\n]*\/[gimsuy]*,?\s*$/m;
|
|
54
|
+
/** A regex literal in an arrow body: `=> /^(route|page)\.tsx?$/.test(…)`. */
|
|
55
|
+
const REGEX_ARROW = /=>\s*\/[^/*\n][^\n]*\/[gimsuy]*/;
|
|
56
|
+
/** A regex literal applied inline: `/^[a-z]$/.test(name)`. */
|
|
57
|
+
const REGEX_APPLIED = /\/[^/*\n][^/\n]*\/[gimsuy]*\.(test|exec|match)\(/;
|
|
58
|
+
/** A named array or a Set: where a literal vocabulary starts. */
|
|
59
|
+
const VOCABULARY_OPEN = /(new Set\(\[|^\s*(?:export )?const [A-Z][A-Z0-9_]*[^=\n]*= \[)/m;
|
|
60
|
+
/** The bracket-balanced literal that starts at or after `from`. */
|
|
61
|
+
const balanced = (source, from) => {
|
|
62
|
+
const open = source.indexOf("[", from);
|
|
63
|
+
if (open === -1)
|
|
64
|
+
return "";
|
|
65
|
+
let depth = 0;
|
|
66
|
+
for (let index = open; index < source.length && index < open + 2000; index += 1) {
|
|
67
|
+
const character = source[index];
|
|
68
|
+
if (character === "[")
|
|
69
|
+
depth += 1;
|
|
70
|
+
else if (character === "]") {
|
|
71
|
+
depth -= 1;
|
|
72
|
+
if (depth === 0)
|
|
73
|
+
return source.slice(open, index + 1);
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
return source.slice(open, open + 2000);
|
|
77
|
+
};
|
|
78
|
+
/**
|
|
79
|
+
* The coupling in one rule source.
|
|
80
|
+
*
|
|
81
|
+
* @param source - the rule module's text.
|
|
82
|
+
* @returns one entry per mechanical coupling found.
|
|
83
|
+
*/
|
|
84
|
+
export const couplingIn = (source) => {
|
|
85
|
+
const found = [];
|
|
86
|
+
if (source.includes("new RegExp(")) {
|
|
87
|
+
found.push({ couplingKind: "regex", detail: "builds a RegExp" });
|
|
88
|
+
}
|
|
89
|
+
const literal = REGEX_LINE.exec(source) ?? REGEX_ARROW.exec(source) ?? REGEX_APPLIED.exec(source);
|
|
90
|
+
if (literal !== null) {
|
|
91
|
+
found.push({ couplingKind: "regex", detail: "a regex literal: " + literal[0].trim().slice(0, 70) });
|
|
92
|
+
}
|
|
93
|
+
const open = VOCABULARY_OPEN.exec(source);
|
|
94
|
+
if (open !== null) {
|
|
95
|
+
// The literal's OWN brackets, not a window past them: a window ran into the
|
|
96
|
+
// rule's messages registry and counted message ids as a vocabulary. And the
|
|
97
|
+
// `[` after the `=`, not the one in a type annotation (`readonly [string, string]`).
|
|
98
|
+
const at = open[0].startsWith("new Set")
|
|
99
|
+
? open.index + open[0].indexOf("[")
|
|
100
|
+
: source.indexOf("[", source.indexOf("=", open.index));
|
|
101
|
+
const words = balanced(source, at).match(/["'][a-z][A-Za-z0-9_]*["']/g) ?? [];
|
|
102
|
+
if (words.length >= 3) {
|
|
103
|
+
found.push({
|
|
104
|
+
couplingKind: "vocabulary",
|
|
105
|
+
detail: "a literal vocabulary of " + String(words.length) + ": " + words.slice(0, 6).join(", "),
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return found;
|
|
110
|
+
};
|
|
111
|
+
/**
|
|
112
|
+
* The authorship rules, checked against a set of rule sources and their tests.
|
|
113
|
+
*
|
|
114
|
+
* @param input - the rule sources, the tests' texts, and the shared cluster module.
|
|
115
|
+
* @returns one finding per broken rule, empty when every rule keeps them.
|
|
116
|
+
*/
|
|
117
|
+
export const metaFindings = (input) => {
|
|
118
|
+
const found = [];
|
|
119
|
+
const namesThisRule = (rule) => input.tests.some((test) => rule.ruleIds.some((id) => test.includes(id)) ||
|
|
120
|
+
rule.names.some((name) => new RegExp("\\b" + name + "\\b").test(test)));
|
|
121
|
+
for (const rule of input.rules) {
|
|
122
|
+
// A rule may opt out of one meta-rule with `meta-allow: <rule>` and a stated
|
|
123
|
+
// reason. The opt-out is explicit and greppable, the way a recorded decision
|
|
124
|
+
// is: an author can make the exception, but not hide it.
|
|
125
|
+
const push = (metaRule, detail) => {
|
|
126
|
+
if (!new RegExp("meta-allow:\\s*" + metaRule).test(rule.text)) {
|
|
127
|
+
found.push({ metaRule, rule: rule.name, detail });
|
|
128
|
+
}
|
|
129
|
+
};
|
|
130
|
+
if (!namesThisRule(rule)) {
|
|
131
|
+
push("require-test", "no test names this rule or any symbol it exports");
|
|
132
|
+
}
|
|
133
|
+
// joggle is the JUDGED layer: the cross-file questions a linter and a
|
|
134
|
+
// typechecker cannot answer. A rule that is not judged is one of those tools'
|
|
135
|
+
// jobs -- `unused-import` belongs in oxlint, a type error in tsc -- and a
|
|
136
|
+
// deterministic rule in joggle is a candidate generator that forgot to ask.
|
|
137
|
+
if (!rule.judged) {
|
|
138
|
+
push("require-judged", "a rule that is not judged is a linter or typechecker job, not a joggle question");
|
|
139
|
+
}
|
|
140
|
+
if (!rule.judged)
|
|
141
|
+
continue;
|
|
142
|
+
// A judged rule that builds plans must declare what violates it, or
|
|
143
|
+
// calibration cannot reduce its question. A rule that answers its own
|
|
144
|
+
// question has no plan to reduce and is outside that.
|
|
145
|
+
if (rule.text.includes("plan:") && !rule.text.includes("violations")) {
|
|
146
|
+
if (!(rule.delegates && input.shared.includes("violations"))) {
|
|
147
|
+
push("require-violations", "a planned rule declares no violating labels, so it cannot be calibrated");
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
// A judged rule must read a judgement's quality and act on every band. A band
|
|
151
|
+
// is not a reason to discard an answer, and it is not a reason to shout one
|
|
152
|
+
// either: the rule decides what each band does.
|
|
153
|
+
if (!rule.text.includes("qualityOf")) {
|
|
154
|
+
if (!(rule.delegates && input.shared.includes("qualityOf"))) {
|
|
155
|
+
push("band-the-answer", "no gate reads a judgement's quality, so a band cannot decide what to do");
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
for (const payload of atomPayloads(rule.text)) {
|
|
159
|
+
if (unbounded(payload)) {
|
|
160
|
+
push("bounded-atoms", "an atom carries a whole file; put a bounded sample in it");
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
// How the rule DECIDES, not what it declares: a regex or a literal
|
|
164
|
+
// vocabulary that classifies meaning belongs to Jev (docs/rule-coupling.md).
|
|
165
|
+
for (const coupling of couplingIn(rule.text)) {
|
|
166
|
+
push("no-pattern-classifier", coupling.couplingKind + " -- " + coupling.detail);
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
return found;
|
|
170
|
+
};
|
package/dist/moves.js
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { Schema } from "effect";
|
|
2
|
+
/**
|
|
3
|
+
* What kind of entropy reversal a finding proposes.
|
|
4
|
+
*
|
|
5
|
+
* joggle is the entropy reverser (Armstrong): you press the frontier out, build
|
|
6
|
+
* things, and then look at what you built and ask *can I rebuild this out of the
|
|
7
|
+
* primitives I already have?* When the answer is no, the finding is one of three
|
|
8
|
+
* things, and they are not interchangeable:
|
|
9
|
+
*
|
|
10
|
+
* contract a primitive already exists here. Delete the copy and use it.
|
|
11
|
+
* combine the primitives exist; the combination was just never written.
|
|
12
|
+
* expand neither -- the vocabulary has to grow: a name, a type, a boundary.
|
|
13
|
+
*
|
|
14
|
+
* `contract` is cleanup. `combine` is a refactor. `expand` is a design act, and
|
|
15
|
+
* it is the scarcest and most valuable of the three -- in the framing this comes
|
|
16
|
+
* from, it is "we are introducing a new pattern, and that is a change request."
|
|
17
|
+
*
|
|
18
|
+
* Absent means the rule is not about entropy at all: it checks the code against a
|
|
19
|
+
* requirement (a cycle, a layering, a contract) rather than asking what the code
|
|
20
|
+
* could be rebuilt from.
|
|
21
|
+
*/
|
|
22
|
+
export const moveValues = ["contract", "combine", "expand"];
|
|
23
|
+
export const Move = Schema.Literals(moveValues);
|
|
24
|
+
/**
|
|
25
|
+
* The ratchet order.
|
|
26
|
+
*
|
|
27
|
+
* Contract first: the copies hide the primitives, so nothing else is legible
|
|
28
|
+
* until they are gone. Then combine, because composing makes the primitives
|
|
29
|
+
* explicit. Then expand, because a new primitive has to be built out of the ones
|
|
30
|
+
* you can now see. This is "clean the leaves first" applied to the report.
|
|
31
|
+
*/
|
|
32
|
+
export const moveOrder = ["contract", "combine", "expand"];
|
|
33
|
+
/** What each move means, in the reader's words. */
|
|
34
|
+
export const moveVocabulary = {
|
|
35
|
+
contract: {
|
|
36
|
+
label: "contract",
|
|
37
|
+
blurb: "A primitive already exists here. Delete the copy and use it.",
|
|
38
|
+
},
|
|
39
|
+
combine: {
|
|
40
|
+
label: "combine",
|
|
41
|
+
blurb: "The primitives exist. Write the combination.",
|
|
42
|
+
},
|
|
43
|
+
expand: {
|
|
44
|
+
label: "expand",
|
|
45
|
+
blurb: "The vocabulary has to grow: a new name, a type, a boundary.",
|
|
46
|
+
},
|
|
47
|
+
};
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { policy } from "./policy.js";
|
|
2
|
+
import { qualityOf } from "./rule.js";
|
|
3
|
+
// The operations a rule proposes, and how one is settled.
|
|
4
|
+
//
|
|
5
|
+
// Two estimators, and they are diverse by construction. `derivedOperation` is a
|
|
6
|
+
// table a person wrote once; the model's own read sees the whole candidate. Their
|
|
7
|
+
// errors are different, so agreement is evidence and disagreement is a signal --
|
|
8
|
+
// the method the approximation book opens with, applied to the tool rather than
|
|
9
|
+
// to a physics problem.
|
|
10
|
+
//
|
|
11
|
+
// The table is NOT a proof. It reads like one, and the first version of this file
|
|
12
|
+
// presented it as one, which is the exact defect `joggle/rule-judgment` exists to
|
|
13
|
+
// find: a person's opinion wearing the costume of a rule. So it is named for what
|
|
14
|
+
// it is, it is cross-checked, and a disagreement is reported rather than hidden.
|
|
15
|
+
/** The words a Choice offers for one operation. */
|
|
16
|
+
export const describeOperation = (operation) => {
|
|
17
|
+
switch (operation) {
|
|
18
|
+
case "merge":
|
|
19
|
+
return "Keep one of them and delete the rest. The copies can reach each other, so the others can import the survivor.";
|
|
20
|
+
case "split":
|
|
21
|
+
return "One name, two meanings. Give the two meanings two names, and give each its own declaration.";
|
|
22
|
+
case "move":
|
|
23
|
+
return "The shared part belongs somewhere all of them can depend on. Move it there and import it.";
|
|
24
|
+
case "replace":
|
|
25
|
+
return "An existing declaration already does this. Call it instead.";
|
|
26
|
+
case "migrate":
|
|
27
|
+
return "The declaration changed and its dependents must follow. Update each site.";
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
/** The package a file belongs to, by its nearest manifest. */
|
|
31
|
+
const packageOf = (workspace, file) => {
|
|
32
|
+
const cut = file.lastIndexOf("/");
|
|
33
|
+
const directory = cut === -1 ? "." : file.slice(0, cut);
|
|
34
|
+
return workspace.manifests.get(directory)?.name;
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* What the graph permits. A fact, so the model cannot propose the impossible.
|
|
38
|
+
*
|
|
39
|
+
* `merge` needs the copies to live in one package: a declaration in a package
|
|
40
|
+
* that cannot depend on another cannot be replaced by it. joggle has already told
|
|
41
|
+
* a Remix app to import a type from a Fastify service, and this is what stops it.
|
|
42
|
+
*
|
|
43
|
+
* @param workspace - The analysed workspace, for the package boundaries.
|
|
44
|
+
* @param members - The declarations that would collapse into one.
|
|
45
|
+
* @returns The operations the repository permits here.
|
|
46
|
+
*/
|
|
47
|
+
export const permitted = (workspace, members) => relationshipOf(workspace, members) === "same_package" ? ["merge", "move"] : ["move"];
|
|
48
|
+
/**
|
|
49
|
+
* The package relationship, decided from the manifests.
|
|
50
|
+
*
|
|
51
|
+
* This used to be a QUESTION. It is not a judgement: the manifest above a file
|
|
52
|
+
* names its package, so whether two declarations can reach each other is a fact
|
|
53
|
+
* about the repository, and asking a model to infer it from paths was asking it
|
|
54
|
+
* to repeat work the code had already done. A repository with no manifests has
|
|
55
|
+
* one deployable as far as the graph can say.
|
|
56
|
+
*
|
|
57
|
+
* @param workspace - the analysed workspace, for the nearest manifests.
|
|
58
|
+
* @param members - the declarations that would collapse into one.
|
|
59
|
+
* @returns whether they sit under one package or several.
|
|
60
|
+
*/
|
|
61
|
+
export const relationshipOf = (workspace, members) => {
|
|
62
|
+
const named = new Set(members
|
|
63
|
+
.map((member) => packageOf(workspace, member.file))
|
|
64
|
+
.filter((name) => name !== undefined));
|
|
65
|
+
return named.size <= 1 ? "same_package" : "different_packages";
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* The table. ONE estimator, and a policy rather than a proof.
|
|
69
|
+
*
|
|
70
|
+
* It is a PEER of the model's own read, not a stage before it: `settle` compares
|
|
71
|
+
* the two and reports a disagreement rather than letting either decide alone.
|
|
72
|
+
* That is what the `difference` question is for -- it is the one input the model
|
|
73
|
+
* supplies to the table, and the table's answer is then a second opinion rather
|
|
74
|
+
* than a verdict the question was designed to rubber-stamp.
|
|
75
|
+
*
|
|
76
|
+
* @param input.candidate - What the candidate is: a name declared twice, a name
|
|
77
|
+
* with two meanings, or logic in the wrong place. A fact, not an answer.
|
|
78
|
+
* @param input.oneThing - The probability that the declarations are one concept.
|
|
79
|
+
* @param input.difference - Whether the difference between them is a value or a
|
|
80
|
+
* meaning.
|
|
81
|
+
* @returns The operation the answers imply, or undefined when they imply none.
|
|
82
|
+
*/
|
|
83
|
+
export const derivedOperation = (input) => {
|
|
84
|
+
if (input.candidate === "overloaded")
|
|
85
|
+
return "split";
|
|
86
|
+
if (input.candidate === "misplaced")
|
|
87
|
+
return "move";
|
|
88
|
+
if (input.oneThing < policy.decision.gates.probabilityFloor)
|
|
89
|
+
return undefined;
|
|
90
|
+
if (input.difference === "value")
|
|
91
|
+
return "merge";
|
|
92
|
+
if (input.difference === "meaning")
|
|
93
|
+
return "move";
|
|
94
|
+
return undefined;
|
|
95
|
+
};
|
|
96
|
+
/**
|
|
97
|
+
* Reconcile the table with the model's own read, as peers.
|
|
98
|
+
*
|
|
99
|
+
* Agreement is the strongest signal this tool has, because the two methods fail
|
|
100
|
+
* differently. Disagreement is not a failure: it is the case a person should
|
|
101
|
+
* look at, so it is reported rather than resolved.
|
|
102
|
+
*
|
|
103
|
+
* Neither decides first. The table is a policy a person wrote; the model read
|
|
104
|
+
* the whole candidate. A question built so that one of them is pre-computed is a
|
|
105
|
+
* question whose answer was fixed before it was asked -- the defect the deleted
|
|
106
|
+
* `merge_changes_behavior` had -- so both are read and compared.
|
|
107
|
+
*
|
|
108
|
+
* @param input.derived - The table's answer, or undefined when it has none.
|
|
109
|
+
* @param input.proposed - The model's answer, or undefined when it declined.
|
|
110
|
+
* @param input.margin - Winner minus runner-up in the model's own distribution.
|
|
111
|
+
* @param input.confidence - The provider's confidence in its answer.
|
|
112
|
+
*/
|
|
113
|
+
export const settle = (input) => {
|
|
114
|
+
if (input.proposed === undefined) {
|
|
115
|
+
return { operation: undefined, quality: "drop", reason: "the model declined" };
|
|
116
|
+
}
|
|
117
|
+
if (input.derived === undefined) {
|
|
118
|
+
const quality = qualityOf({ score: 0.5, margin: input.margin, confidence: input.confidence });
|
|
119
|
+
return {
|
|
120
|
+
operation: input.proposed,
|
|
121
|
+
quality: quality.quality,
|
|
122
|
+
reason: "the table had no opinion, so the model's read stands alone",
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
if (input.derived === input.proposed) {
|
|
126
|
+
return { operation: input.proposed, quality: "act", reason: "the table and the model agree" };
|
|
127
|
+
}
|
|
128
|
+
return {
|
|
129
|
+
operation: input.proposed,
|
|
130
|
+
quality: "review",
|
|
131
|
+
reason: "the table says " + input.derived + ", the model says " + input.proposed,
|
|
132
|
+
};
|
|
133
|
+
};
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
import { Effect, FileSystem, Path, Result, Schema, SchemaParser } from "effect";
|
|
2
|
+
import { shortHash } from "./state.js";
|
|
3
|
+
import { shinglesOf } from "./similarity.js";
|
|
4
|
+
import { ParsedImport } from "./imports.js";
|
|
5
|
+
import { SourceLocation } from "./schema.js";
|
|
6
|
+
import { StructureFacts, tokenize, UnitKind, } from "./workspace.js";
|
|
7
|
+
/**
|
|
8
|
+
* Parsing, as a cached unit of work keyed by its inputs.
|
|
9
|
+
*
|
|
10
|
+
* The idea is from a talk about Turbopack's incremental engine (docs/turbo.md):
|
|
11
|
+
* every expensive operation becomes a cached unit whose key is derived from what
|
|
12
|
+
* it reads, because "I don't really trust developers to write correct cache keys
|
|
13
|
+
* or track inputs by hand".
|
|
14
|
+
*
|
|
15
|
+
* The measurement that justifies it: on one repository the whole-run fingerprint
|
|
16
|
+
* meant any change at all re-parsed 2,456 files, and `read+parse` was 2.3 of the
|
|
17
|
+
* 2.4 seconds the workspace took. A one-line edit cost 2.3 seconds to answer a
|
|
18
|
+
* question about one file.
|
|
19
|
+
*
|
|
20
|
+
* A parse reads exactly two things -- the text of the file and the parser -- so
|
|
21
|
+
* the key is exactly those two. The text comes from the call site, which already
|
|
22
|
+
* has it; the parser is the tool's own fingerprint, checked when the cache is
|
|
23
|
+
* opened. There is no third thing a parse could depend on.
|
|
24
|
+
*
|
|
25
|
+
* WHAT IS STORED, AND WHAT IS NOT. Only the ANALYSIS: the units, their imports
|
|
26
|
+
* and the file's structural facts. Not the file's text, which the caller already
|
|
27
|
+
* has in memory; not a unit's text, which is a slice of it; not a unit's tokens,
|
|
28
|
+
* which are a function of its shape; and not its shingles, which are a function
|
|
29
|
+
* of its tokens. The first version stored all of it and produced a 67 megabyte
|
|
30
|
+
* cache for 2,456 files -- most of it the same bytes said four different ways.
|
|
31
|
+
*
|
|
32
|
+
* WHAT THIS DOES NOT DO. It is not a reactive graph. Turbopack tracks which cell
|
|
33
|
+
* read which and propagates invalidation upward with early cutoff; this is one
|
|
34
|
+
* layer of that idea, at the point where 96% of the time is. A dependency graph
|
|
35
|
+
* over eight thousand units would cost more to maintain than it saves at this
|
|
36
|
+
* size, and the talk is honest about the overheads -- memory, and "global
|
|
37
|
+
* algorithms harm incrementality" -- that such a system brings with it.
|
|
38
|
+
*/
|
|
39
|
+
export const CACHE_VERSION = "14";
|
|
40
|
+
/** One parse's key: which file, and what it said. */
|
|
41
|
+
export const keyOf = ({ file, text }) => file + "\u0000" + shortHash(text);
|
|
42
|
+
/** A unit minus everything derivable from the file's text. */
|
|
43
|
+
const encodeUnit = (unit) => ({
|
|
44
|
+
kind: unit.kind,
|
|
45
|
+
name: unit.name,
|
|
46
|
+
start: unit.start,
|
|
47
|
+
end: unit.end,
|
|
48
|
+
location: unit.location,
|
|
49
|
+
namePosition: unit.namePosition,
|
|
50
|
+
exported: unit.exported,
|
|
51
|
+
shape: unit.shape,
|
|
52
|
+
normalizedHash: unit.normalizedHash,
|
|
53
|
+
typeRefs: unit.typeRefs,
|
|
54
|
+
typed: unit.typed,
|
|
55
|
+
variants: unit.variants,
|
|
56
|
+
values: unit.values,
|
|
57
|
+
fieldTypes: Object.fromEntries(unit.fieldTypes),
|
|
58
|
+
bases: unit.composed.map((base) => base.name),
|
|
59
|
+
test: unit.test,
|
|
60
|
+
...(unit.doc === undefined ? {} : { doc: unit.doc }),
|
|
61
|
+
});
|
|
62
|
+
const encodeSourceFile = (file) => ({
|
|
63
|
+
units: file.units.map(encodeUnit),
|
|
64
|
+
imports: file.importStatements,
|
|
65
|
+
facts: file.facts,
|
|
66
|
+
});
|
|
67
|
+
/**
|
|
68
|
+
* A cached parse: the analysis, and nothing the file's text can give back.
|
|
69
|
+
*
|
|
70
|
+
* One Schema for the whole file rather than hand-written checks, because this is
|
|
71
|
+
* genuinely external. It is a file on disk that can be truncated by an interrupted
|
|
72
|
+
* write, edited by hand, or left over from a different tool -- so it is worth
|
|
73
|
+
* DECODING rather than casting, and every type here is derived from the decoder
|
|
74
|
+
* instead of declared beside it.
|
|
75
|
+
*
|
|
76
|
+
* The AST is not treated this way, and the reason is measured rather than
|
|
77
|
+
* assumed: decoding one node costs 213ns against 3ns for a typeof check, a factor
|
|
78
|
+
* of 73, and joggle walks millions of nodes per run. oxc produced that AST in this
|
|
79
|
+
* process and `parseSync` has a type for it, so validating it would be validating
|
|
80
|
+
* our own output at 73 times the price.
|
|
81
|
+
*/
|
|
82
|
+
const EncodedUnit = Schema.Struct({
|
|
83
|
+
kind: UnitKind,
|
|
84
|
+
name: Schema.String,
|
|
85
|
+
start: Schema.Number,
|
|
86
|
+
end: Schema.Number,
|
|
87
|
+
location: SourceLocation,
|
|
88
|
+
// Absent in caches written before the checker facts keyed on it; the version
|
|
89
|
+
// bump rebuilds them, and the fallback keeps a stale entry decodable.
|
|
90
|
+
namePosition: Schema.optionalKey(Schema.Number),
|
|
91
|
+
exported: Schema.Boolean,
|
|
92
|
+
shape: Schema.String,
|
|
93
|
+
normalizedHash: Schema.String,
|
|
94
|
+
typeRefs: Schema.Array(Schema.String),
|
|
95
|
+
typed: Schema.Boolean,
|
|
96
|
+
// Absent in caches written before the node space was widened; the version bump
|
|
97
|
+
// rebuilds them, and an old entry decodes as "no variants, no values".
|
|
98
|
+
variants: Schema.optionalKey(Schema.Array(Schema.String)),
|
|
99
|
+
values: Schema.optionalKey(Schema.Array(Schema.String)),
|
|
100
|
+
fieldTypes: Schema.Record(Schema.String, Schema.String),
|
|
101
|
+
// Absent in caches written before composition was recorded; the version bump
|
|
102
|
+
// rebuilds them, and this keeps a stale entry decodable rather than an issue.
|
|
103
|
+
bases: Schema.optionalKey(Schema.Array(Schema.String)),
|
|
104
|
+
test: Schema.Boolean,
|
|
105
|
+
doc: Schema.optionalKey(Schema.String),
|
|
106
|
+
});
|
|
107
|
+
const EncodedFile = Schema.Struct({
|
|
108
|
+
units: Schema.Array(EncodedUnit),
|
|
109
|
+
imports: Schema.Array(ParsedImport),
|
|
110
|
+
facts: StructureFacts,
|
|
111
|
+
});
|
|
112
|
+
const CacheFile = Schema.Struct({
|
|
113
|
+
version: Schema.String,
|
|
114
|
+
tool: Schema.String,
|
|
115
|
+
entries: Schema.Record(Schema.String, EncodedFile),
|
|
116
|
+
});
|
|
117
|
+
/**
|
|
118
|
+
* The decoder, chosen so that a failure is RECORDED.
|
|
119
|
+
*
|
|
120
|
+
* `decodeUnknownResult` returns the schema issue as data rather than throwing it
|
|
121
|
+
* away, which is the part that matters: a cache that has quietly stopped working
|
|
122
|
+
* used to look exactly like a cold one, forever.
|
|
123
|
+
*/
|
|
124
|
+
const decodeCache = SchemaParser.decodeUnknownResult(Schema.fromJsonString(CacheFile));
|
|
125
|
+
/**
|
|
126
|
+
* A unit, rebuilt from a decoded entry and the text the caller already has.
|
|
127
|
+
*
|
|
128
|
+
* The text is a slice of the file, and the tokens and shingles are functions of
|
|
129
|
+
* the shape, so none of the three are stored -- which is most of why the cache is
|
|
130
|
+
* 12 megabytes rather than 67.
|
|
131
|
+
*
|
|
132
|
+
* A span that does not fit the file it claims to come from is a corrupt entry, and
|
|
133
|
+
* a corrupt entry is a miss.
|
|
134
|
+
*/
|
|
135
|
+
const unitFrom = (entry, source) => {
|
|
136
|
+
const { file, text } = source;
|
|
137
|
+
// A span that does not fit the file it claims to come from is a corrupt entry,
|
|
138
|
+
// and a corrupt entry is a miss.
|
|
139
|
+
if (entry.start < 0 || entry.start > entry.end || entry.end > text.length)
|
|
140
|
+
return undefined;
|
|
141
|
+
const tokens = tokenize(entry.shape);
|
|
142
|
+
return {
|
|
143
|
+
kind: entry.kind,
|
|
144
|
+
name: entry.name,
|
|
145
|
+
file,
|
|
146
|
+
start: entry.start,
|
|
147
|
+
end: entry.end,
|
|
148
|
+
location: entry.location,
|
|
149
|
+
namePosition: entry.namePosition ?? entry.start,
|
|
150
|
+
exported: entry.exported,
|
|
151
|
+
text: text.slice(entry.start, entry.end),
|
|
152
|
+
shape: entry.shape,
|
|
153
|
+
tokens,
|
|
154
|
+
shingles: shinglesOf(tokens),
|
|
155
|
+
normalizedHash: entry.normalizedHash,
|
|
156
|
+
typeRefs: entry.typeRefs,
|
|
157
|
+
typed: entry.typed,
|
|
158
|
+
variants: entry.variants ?? [],
|
|
159
|
+
values: entry.values ?? [],
|
|
160
|
+
fieldTypes: new Map(Object.entries(entry.fieldTypes)),
|
|
161
|
+
composed: (entry.bases ?? []).map((name) => ({ name, resolvedTo: "" })),
|
|
162
|
+
test: entry.test,
|
|
163
|
+
// Three fields the resolution pass fills in, so none is stored: the calls a
|
|
164
|
+
// declaration makes depend on the whole file set, exactly as its resolved
|
|
165
|
+
// types do.
|
|
166
|
+
typeSignature: "",
|
|
167
|
+
// Filled by the resolution pass once the whole file set is known, exactly as
|
|
168
|
+
// the calls and the resolved type names are, so it is not stored.
|
|
169
|
+
typeFacts: undefined,
|
|
170
|
+
calls: [],
|
|
171
|
+
callSignature: "",
|
|
172
|
+
doc: entry.doc,
|
|
173
|
+
};
|
|
174
|
+
};
|
|
175
|
+
/** A whole file's parse, or undefined when any unit of it is unusable. */
|
|
176
|
+
const sourceFileFrom = (entry, source) => {
|
|
177
|
+
const units = [];
|
|
178
|
+
for (const raw of entry.units) {
|
|
179
|
+
const unit = unitFrom(raw, source);
|
|
180
|
+
if (unit === undefined)
|
|
181
|
+
return undefined;
|
|
182
|
+
units.push(unit);
|
|
183
|
+
}
|
|
184
|
+
return {
|
|
185
|
+
path: source.file,
|
|
186
|
+
text: source.text,
|
|
187
|
+
units,
|
|
188
|
+
importStatements: entry.imports,
|
|
189
|
+
facts: entry.facts,
|
|
190
|
+
};
|
|
191
|
+
};
|
|
192
|
+
/**
|
|
193
|
+
* The cache on disk, discarded whole when the tool's own source has changed.
|
|
194
|
+
*
|
|
195
|
+
* The parser is part of the tool, so an entry produced by a different parser is
|
|
196
|
+
* not a cache hit -- it is a wrong answer. That is the same reasoning as the run
|
|
197
|
+
* manifest, applied to the operation that dominates the run.
|
|
198
|
+
*/
|
|
199
|
+
export const loadParses = ({ cacheDir, tool }) => Effect.gen(function* () {
|
|
200
|
+
const fs = yield* FileSystem.FileSystem;
|
|
201
|
+
const path = yield* Path.Path;
|
|
202
|
+
const store = path.join(cacheDir, "parses.json");
|
|
203
|
+
// The map holds the ENCODED form, so saving serializes what is already there
|
|
204
|
+
// rather than walking every unit a second time to write it out.
|
|
205
|
+
const issues = [];
|
|
206
|
+
const entries = new Map();
|
|
207
|
+
const exists = yield* Effect.orElseSucceed(fs.exists(store), () => false);
|
|
208
|
+
if (exists) {
|
|
209
|
+
const body = yield* Effect.orElseSucceed(fs.readFileString(store), () => "");
|
|
210
|
+
// One decode for the whole file. A cache from a different tool version is
|
|
211
|
+
// discarded whole rather than repaired: the parser is part of the tool, so
|
|
212
|
+
// an entry it did not produce is a wrong answer, not a slow one.
|
|
213
|
+
const decoded = decodeCache(body);
|
|
214
|
+
if (Result.isFailure(decoded)) {
|
|
215
|
+
// An empty or absent cache is not damage; a file that will not parse is.
|
|
216
|
+
if (body.trim() !== "")
|
|
217
|
+
issues.push("the cache file did not match the expected shape");
|
|
218
|
+
}
|
|
219
|
+
else if (decoded.success.version === CACHE_VERSION && decoded.success.tool === tool) {
|
|
220
|
+
// A version or tool mismatch is not damage either: the cache is discarded
|
|
221
|
+
// whole and rebuilt, which is what an upgrade is supposed to do.
|
|
222
|
+
for (const [key, value] of Object.entries(decoded.success.entries))
|
|
223
|
+
entries.set(key, value);
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
let hits = 0;
|
|
227
|
+
let misses = 0;
|
|
228
|
+
const parses = {
|
|
229
|
+
get: (relative, text) => {
|
|
230
|
+
const stored = entries.get(keyOf({ file: relative, text }));
|
|
231
|
+
// Decoded against the text the CALLER has, which is the whole reason the
|
|
232
|
+
// text is not in the cache: it is already here.
|
|
233
|
+
const rebuilt = stored === undefined ? undefined : sourceFileFrom(stored, { file: relative, text });
|
|
234
|
+
if (rebuilt === undefined) {
|
|
235
|
+
misses += 1;
|
|
236
|
+
return undefined;
|
|
237
|
+
}
|
|
238
|
+
hits += 1;
|
|
239
|
+
return rebuilt;
|
|
240
|
+
},
|
|
241
|
+
set: (relative, text, parsed) => {
|
|
242
|
+
entries.set(keyOf({ file: relative, text }), encodeSourceFile(parsed));
|
|
243
|
+
},
|
|
244
|
+
hits: () => hits,
|
|
245
|
+
misses: () => misses,
|
|
246
|
+
};
|
|
247
|
+
return {
|
|
248
|
+
parses,
|
|
249
|
+
issues,
|
|
250
|
+
// Only when something was parsed. A run that read twenty thousand entries
|
|
251
|
+
// and wrote them all back is a run where the cache costs more than it saves.
|
|
252
|
+
save: Effect.gen(function* () {
|
|
253
|
+
if (misses === 0)
|
|
254
|
+
return;
|
|
255
|
+
const body = JSON.stringify({
|
|
256
|
+
version: CACHE_VERSION,
|
|
257
|
+
tool,
|
|
258
|
+
entries: Object.fromEntries(entries),
|
|
259
|
+
});
|
|
260
|
+
yield* Effect.orElseSucceed(fs.makeDirectory(cacheDir, { recursive: true }), () => undefined);
|
|
261
|
+
yield* Effect.orElseSucceed(fs.writeFileString(store, body), () => undefined);
|
|
262
|
+
}),
|
|
263
|
+
};
|
|
264
|
+
});
|