@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.
- 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/cluster.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { Order } from "effect";
|
|
2
|
+
/** Connected components over an edge list, by union-find with path compression. */
|
|
3
|
+
export const components = (size, edges) => {
|
|
4
|
+
const parent = Array.from({ length: size }, (_, index) => index);
|
|
5
|
+
const find = (start) => {
|
|
6
|
+
let root = start;
|
|
7
|
+
for (;;) {
|
|
8
|
+
const next = parent[root];
|
|
9
|
+
if (next === undefined || next === root)
|
|
10
|
+
break;
|
|
11
|
+
root = next;
|
|
12
|
+
}
|
|
13
|
+
let cursor = start;
|
|
14
|
+
while (cursor !== root) {
|
|
15
|
+
const next = parent[cursor];
|
|
16
|
+
if (next === undefined || next === root)
|
|
17
|
+
break;
|
|
18
|
+
parent[cursor] = root;
|
|
19
|
+
cursor = next;
|
|
20
|
+
}
|
|
21
|
+
return root;
|
|
22
|
+
};
|
|
23
|
+
for (const [left, right] of edges) {
|
|
24
|
+
const a = find(left);
|
|
25
|
+
const b = find(right);
|
|
26
|
+
if (a !== b)
|
|
27
|
+
parent[a] = b;
|
|
28
|
+
}
|
|
29
|
+
const groups = new Map();
|
|
30
|
+
for (let index = 0; index < size; index += 1) {
|
|
31
|
+
const root = find(index);
|
|
32
|
+
const group = groups.get(root);
|
|
33
|
+
if (group === undefined)
|
|
34
|
+
groups.set(root, [index]);
|
|
35
|
+
else
|
|
36
|
+
group.push(index);
|
|
37
|
+
}
|
|
38
|
+
return [...groups.values()];
|
|
39
|
+
};
|
|
40
|
+
const byPath = Order.combine(Order.mapInput(Order.String, (unit) => unit.file), Order.mapInput(Order.Number, (unit) => unit.start));
|
|
41
|
+
/**
|
|
42
|
+
* Build a cluster: its members in path order, whether they are identical, how
|
|
43
|
+
* much they overlap, and whether any member carries a type.
|
|
44
|
+
*/
|
|
45
|
+
export const clusterOf = (members, identical, overlap) => ({
|
|
46
|
+
members: [...members].sort(byPath),
|
|
47
|
+
identical,
|
|
48
|
+
overlap,
|
|
49
|
+
// Computed here rather than passed in, so a caller cannot forget it or set it
|
|
50
|
+
// wrong.
|
|
51
|
+
typed: members.some((member) => member.typed),
|
|
52
|
+
});
|
|
53
|
+
/** The distinct declaration names in a cluster, in member order. */
|
|
54
|
+
export const namesOf = (cluster) => [
|
|
55
|
+
...new Set(cluster.members.map((member) => member.name)),
|
|
56
|
+
];
|
|
57
|
+
/**
|
|
58
|
+
* Names of a cluster, capped for display.
|
|
59
|
+
*
|
|
60
|
+
* An eighty-seven member cluster once printed all eighty-seven names into a
|
|
61
|
+
* note. A message is not a directory listing; the count carries the information
|
|
62
|
+
* and the first few carry the gist.
|
|
63
|
+
*/
|
|
64
|
+
export const nameList = ({ cluster, max = 4, }) => {
|
|
65
|
+
const names = namesOf(cluster);
|
|
66
|
+
if (names.length <= max)
|
|
67
|
+
return names.join(", ");
|
|
68
|
+
return `${names.slice(0, max).join(", ")} and ${names.length - max} more`;
|
|
69
|
+
};
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
import { Effect, FileSystem, Predicate, Result, Schema, SchemaParser } from "effect";
|
|
2
|
+
import { globSource } from "./glob.js";
|
|
3
|
+
/**
|
|
4
|
+
* The file where a repository answers "it depends on what".
|
|
5
|
+
*
|
|
6
|
+
* `plumb` and this tool draw a line: plumb asks whether one file is well formed,
|
|
7
|
+
* and its rules are written once and applied everywhere. joggle asks whether two
|
|
8
|
+
* things are the same, and whether a thing fits THIS repository. The second
|
|
9
|
+
* question has no universal answer, which is why an engineer says "it depends" -
|
|
10
|
+
* and "it depends on what" is a question with a finite answer list. This file is
|
|
11
|
+
* that list.
|
|
12
|
+
*
|
|
13
|
+
* Three parts, in the order a person meets them:
|
|
14
|
+
*
|
|
15
|
+
* evidence.repository the architecture, declared in prose, sent as context
|
|
16
|
+
* to every judgement. This is the part that turns "it
|
|
17
|
+
* depends" into "it depends on the following, which I
|
|
18
|
+
* have written down here".
|
|
19
|
+
* rules which rules run, and how loudly.
|
|
20
|
+
* ignore exceptions, by rule and by path.
|
|
21
|
+
*
|
|
22
|
+
* The judgement layer then does not have to infer the conventions of the
|
|
23
|
+
* codebase from a bounded evidence panel; it is told them. And when the answer
|
|
24
|
+
* to "it depends on what" changes, that is a one-line edit here rather than a
|
|
25
|
+
* threshold change buried in rule logic.
|
|
26
|
+
*/
|
|
27
|
+
export const JoggleConfig = Schema.Struct({
|
|
28
|
+
/**
|
|
29
|
+
* Which rules run, how loudly, and where.
|
|
30
|
+
*
|
|
31
|
+
* A rule's value is a severity, or a severity plus the paths it applies to.
|
|
32
|
+
* Scoping is what makes a PRESET usable: a preset that checks a domain layer's
|
|
33
|
+
* purity should run everywhere, while one that decomposes a domain's types
|
|
34
|
+
* should only run inside it. Without this, enabling a preset means running all
|
|
35
|
+
* of it on all of the repository, which is how people decide a linter is too
|
|
36
|
+
* noisy rather than too specific.
|
|
37
|
+
*/
|
|
38
|
+
rules: Schema.optionalKey(Schema.Record(Schema.String, Schema.Union([
|
|
39
|
+
Schema.Literals(["error", "warn", "info", "off"]),
|
|
40
|
+
Schema.Struct({
|
|
41
|
+
severity: Schema.Literals(["error", "warn", "info", "off"]),
|
|
42
|
+
/** Globs, relative to the analysed root. Absent means everywhere. */
|
|
43
|
+
paths: Schema.optionalKey(Schema.Array(Schema.String)),
|
|
44
|
+
/**
|
|
45
|
+
* What the rule does when no judgement reaches it.
|
|
46
|
+
*
|
|
47
|
+
* A rule declares this, and the declaration is right for a developer
|
|
48
|
+
* with a model key. A repository that runs joggle in CI without one
|
|
49
|
+
* may disagree: `propagate` steps the rule aside instead of printing
|
|
50
|
+
* its unjudged candidates, so the run stays deterministic. Absent
|
|
51
|
+
* means the rule's own declaration stands.
|
|
52
|
+
*/
|
|
53
|
+
onUnavailable: Schema.optionalKey(Schema.Literals(["report", "propagate", "count"])),
|
|
54
|
+
}),
|
|
55
|
+
]))),
|
|
56
|
+
/**
|
|
57
|
+
* What EVERY rule does when no judgement reaches it, unless the rule's own
|
|
58
|
+
* setting says otherwise.
|
|
59
|
+
*
|
|
60
|
+
* The same sentence was needed once per judged rule in one repository's config,
|
|
61
|
+
* because the answer is a property of the RUN rather than of any one rule: a CI
|
|
62
|
+
* run without a model key wants `count` or `propagate` for all of them. A
|
|
63
|
+
* rule's own `onUnavailable` still wins, so a repository stays specific where
|
|
64
|
+
* it matters.
|
|
65
|
+
*/
|
|
66
|
+
unavailable: Schema.optionalKey(Schema.Literals(["report", "propagate", "count"])),
|
|
67
|
+
ignore: Schema.optionalKey(Schema.Array(Schema.Struct({
|
|
68
|
+
/** Rule id, exact or with `*`. Absent means every rule. */
|
|
69
|
+
rule: Schema.optionalKey(Schema.String),
|
|
70
|
+
/** Path glob, relative to the analysed root. */
|
|
71
|
+
path: Schema.String,
|
|
72
|
+
reason: Schema.optionalKey(Schema.String),
|
|
73
|
+
}))),
|
|
74
|
+
/**
|
|
75
|
+
* Rule modules to load from the repository, in addition to the built-in set.
|
|
76
|
+
*
|
|
77
|
+
* Relative specifiers resolve against the analysed root, so a repository's own
|
|
78
|
+
* rules live with the repository's own config. A module exports `rules`.
|
|
79
|
+
*/
|
|
80
|
+
plugins: Schema.optionalKey(Schema.Array(Schema.String)),
|
|
81
|
+
/**
|
|
82
|
+
* Packages of opinions: rule modules that also carry default severities.
|
|
83
|
+
*
|
|
84
|
+
* Mechanically identical to `plugins` -- the same loader, the same module shape
|
|
85
|
+
* -- and listed separately because the intent is different. A plugin is code
|
|
86
|
+
* someone wrote for their repository. A preset is a coherent position about how
|
|
87
|
+
* code should be organised, which arrives with the severities it was designed
|
|
88
|
+
* to run at and which the repository may override.
|
|
89
|
+
*/
|
|
90
|
+
presets: Schema.optionalKey(Schema.Array(Schema.String)),
|
|
91
|
+
/**
|
|
92
|
+
* The repository's layering, if it has one.
|
|
93
|
+
*
|
|
94
|
+
* Listed from most depended-upon to least, so a later layer may import an
|
|
95
|
+
* earlier one and never the reverse. This is the part of a codebase's
|
|
96
|
+
* architecture that is DECIDABLE -- it is a property of the import graph, not
|
|
97
|
+
* of anyone's taste -- which is why it is enforced here rather than judged.
|
|
98
|
+
*/
|
|
99
|
+
architecture: Schema.optionalKey(Schema.Struct({
|
|
100
|
+
layers: Schema.Array(Schema.Struct({
|
|
101
|
+
name: Schema.String,
|
|
102
|
+
include: Schema.Array(Schema.String),
|
|
103
|
+
/**
|
|
104
|
+
* Specifiers this layer may not import.
|
|
105
|
+
*
|
|
106
|
+
* The invariant that keeps a new architecture from eroding. A domain
|
|
107
|
+
* package is pure by definition, and "pure" is not a judgement -- it
|
|
108
|
+
* is an import-graph question with an exact answer. `react*` and
|
|
109
|
+
* `fastify*` are prefix patterns on purpose: a name without a
|
|
110
|
+
* wildcard has to match exactly, so `react` does not catch
|
|
111
|
+
* `react-dom` by accident.
|
|
112
|
+
*/
|
|
113
|
+
forbid: Schema.optionalKey(Schema.Array(Schema.String)),
|
|
114
|
+
})),
|
|
115
|
+
})),
|
|
116
|
+
/**
|
|
117
|
+
* Allow the compiler to execute content-mapper packages declared in tsconfig.
|
|
118
|
+
*
|
|
119
|
+
* Off by default. A mapper is an arbitrary process that the repository's
|
|
120
|
+
* tsconfig names, so enabling it is a trust decision, like VS Code's workspace
|
|
121
|
+
* trust. With it on, `tsc` runs the mappers; joggle still indexes only the
|
|
122
|
+
* extensions it can parse, and says which declared ones it did not.
|
|
123
|
+
*/
|
|
124
|
+
runExternalCode: Schema.optionalKey(Schema.Boolean),
|
|
125
|
+
evidence: Schema.optionalKey(Schema.Struct({
|
|
126
|
+
/**
|
|
127
|
+
* The repository's architecture, in the repository's own words.
|
|
128
|
+
*
|
|
129
|
+
* Kept short on purpose. It is sent with every judgement, so it is paid
|
|
130
|
+
* for on every call, and a paragraph of aspiration is worse than a
|
|
131
|
+
* sentence of fact: "pages compose atomic blocks from
|
|
132
|
+
* components/<name>/ bundles" is worth more than "we value clean code".
|
|
133
|
+
*/
|
|
134
|
+
repository: Schema.optionalKey(Schema.String),
|
|
135
|
+
})),
|
|
136
|
+
});
|
|
137
|
+
export const emptyConfig = {};
|
|
138
|
+
/**
|
|
139
|
+
* Glob matching for path patterns: `*` stops at a separator, `**` does not.
|
|
140
|
+
*
|
|
141
|
+
* Exported because the architecture rules match file paths against declared
|
|
142
|
+
* layers, and two matchers would be two behaviours for one config file.
|
|
143
|
+
*/
|
|
144
|
+
export const matchesGlob = ({ glob, subject }) => globToRegExp(glob).test(subject);
|
|
145
|
+
const globToRegExp = (glob) => new RegExp("^" + globSource(glob, { question: false, doubleStarSkipsSlash: false }) + "$");
|
|
146
|
+
/** Whether a finding should be suppressed by the config's exceptions. */
|
|
147
|
+
export const isIgnored = ({ config, ruleId, path }) => (config.ignore ?? []).some((entry) => {
|
|
148
|
+
if (entry.rule !== undefined && !globToRegExp(entry.rule).test(ruleId))
|
|
149
|
+
return false;
|
|
150
|
+
return globToRegExp(entry.path).test(path);
|
|
151
|
+
});
|
|
152
|
+
const settingFor = (config, ruleId) => {
|
|
153
|
+
const configured = config.rules?.[ruleId];
|
|
154
|
+
if (configured === undefined)
|
|
155
|
+
return undefined;
|
|
156
|
+
return Predicate.isString(configured)
|
|
157
|
+
? { severity: configured, paths: undefined, onUnavailable: undefined }
|
|
158
|
+
: { severity: configured.severity, paths: configured.paths, onUnavailable: configured.onUnavailable };
|
|
159
|
+
};
|
|
160
|
+
/** The severity to use for a rule: the config's, or the rule's own. */
|
|
161
|
+
export const severityFor = (config, ruleId, fallback) => settingFor(config, ruleId)?.severity ?? fallback;
|
|
162
|
+
/**
|
|
163
|
+
* What a rule does when no judgement reaches it: the config's answer, or the
|
|
164
|
+
* rule's own.
|
|
165
|
+
*
|
|
166
|
+
* A repository without a model key can say "step aside" (`propagate`) or "count
|
|
167
|
+
* them, do not print them" (`count`) for the rules whose unjudged candidates it
|
|
168
|
+
* does not want, while a developer's machine keeps the rule's own declaration.
|
|
169
|
+
* The rule's own setting wins; then the run's `unavailable`; then the rule's.
|
|
170
|
+
*/
|
|
171
|
+
export const unavailableFor = (config, ruleId, fallback) => settingFor(config, ruleId)?.onUnavailable ?? config.unavailable ?? fallback;
|
|
172
|
+
/**
|
|
173
|
+
* Whether a rule's configuration lets it speak about this file.
|
|
174
|
+
*
|
|
175
|
+
* Applied to the FINDING, not to the rule. A rule reads the whole workspace -- a
|
|
176
|
+
* duplicate is by definition about more than one file -- so scoping a rule out
|
|
177
|
+
* of a file it is not configured for would mean it could not see that file at
|
|
178
|
+
* all, and a duplicate across the boundary would vanish rather than be reported
|
|
179
|
+
* or not. What is scoped is where the answer may be reported.
|
|
180
|
+
*/
|
|
181
|
+
export const appliesAt = ({ config, ruleId, path }) => {
|
|
182
|
+
const paths = settingFor(config, ruleId)?.paths;
|
|
183
|
+
return paths === undefined || paths.some((glob) => matchesGlob({ glob, subject: path }));
|
|
184
|
+
};
|
|
185
|
+
/** Whether a rule runs at all under this config. */
|
|
186
|
+
export const isEnabled = (config, ruleId, fallback) => severityFor(config, ruleId, fallback) !== "off";
|
|
187
|
+
/** Read a repository's config, or the empty config when it has none. */
|
|
188
|
+
export const loadConfig = (file) => Effect.gen(function* () {
|
|
189
|
+
const fs = yield* FileSystem.FileSystem;
|
|
190
|
+
const exists = yield* Effect.orElseSucceed(fs.exists(file), () => false);
|
|
191
|
+
if (!exists)
|
|
192
|
+
return emptyConfig;
|
|
193
|
+
const text = yield* Effect.orElseSucceed(fs.readFileString(file), () => "");
|
|
194
|
+
return Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(JoggleConfig))(text)) ?? emptyConfig;
|
|
195
|
+
});
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { Effect, FileSystem, Path, Predicate, Result, Schema, SchemaParser } from "effect";
|
|
2
|
+
import { stripJsonc } from "./jsonc.js";
|
|
3
|
+
/**
|
|
4
|
+
* The content mappers a project declares, read from its tsconfig chain.
|
|
5
|
+
*
|
|
6
|
+
* TypeScript 7.1 lets a project register a package that turns a foreign file
|
|
7
|
+
* (`.vue`, `.svelte`, `.mdx`) into virtual TypeScript. The compiler then needs
|
|
8
|
+
* `--runExternalCode`, because a mapper is an arbitrary process. joggle does not
|
|
9
|
+
* run mappers on its own: it reports what a project declared and what it could
|
|
10
|
+
* index, so a run cannot claim to have looked at a file it never read.
|
|
11
|
+
*
|
|
12
|
+
* `extends` is followed for the same reason: a shared base config is where a
|
|
13
|
+
* monorepo puts the mapper, and reading only the leaf would report "none" for a
|
|
14
|
+
* project that has three.
|
|
15
|
+
*/
|
|
16
|
+
const ContentMapper = Schema.Struct({
|
|
17
|
+
package: Schema.String,
|
|
18
|
+
extensions: Schema.Array(Schema.String),
|
|
19
|
+
});
|
|
20
|
+
const Tsconfig = Schema.Struct({
|
|
21
|
+
extends: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)])),
|
|
22
|
+
contentMappers: Schema.optionalKey(Schema.Array(ContentMapper)),
|
|
23
|
+
});
|
|
24
|
+
const decode = SchemaParser.decodeUnknownResult(Schema.fromJsonString(Tsconfig));
|
|
25
|
+
/** The `extends` entries that name a file rather than a package. */
|
|
26
|
+
const baseFiles = (value) => value === undefined ? [] : Predicate.isString(value) ? [value] : value;
|
|
27
|
+
/**
|
|
28
|
+
* Read one tsconfig, then its bases, collecting extension → package.
|
|
29
|
+
*
|
|
30
|
+
* A package `extends` (`@acme/tsconfig`) is not resolved: joggle does not read
|
|
31
|
+
* node_modules to answer a question about this project's own configuration, and
|
|
32
|
+
* a mapper declared only there is outside what this scan can see.
|
|
33
|
+
*/
|
|
34
|
+
const readChain = (fs, path, file, seen, into) => Effect.gen(function* () {
|
|
35
|
+
const absolute = path.resolve(file);
|
|
36
|
+
if (seen.has(absolute))
|
|
37
|
+
return;
|
|
38
|
+
seen.add(absolute);
|
|
39
|
+
const text = yield* Effect.orElseSucceed(fs.readFileString(absolute), () => undefined);
|
|
40
|
+
if (text === undefined)
|
|
41
|
+
return;
|
|
42
|
+
const decoded = Result.getOrUndefined(decode(stripJsonc(text)));
|
|
43
|
+
if (decoded === undefined)
|
|
44
|
+
return;
|
|
45
|
+
for (const base of baseFiles(decoded.extends)) {
|
|
46
|
+
if (!base.startsWith(".") && !base.startsWith("/"))
|
|
47
|
+
continue;
|
|
48
|
+
const candidate = path.resolve(path.dirname(absolute), base);
|
|
49
|
+
const named = candidate.endsWith(".json") ? candidate : candidate + ".json";
|
|
50
|
+
const exists = yield* Effect.orElseSucceed(fs.exists(named), () => false);
|
|
51
|
+
yield* readChain(fs, path, exists ? named : candidate, seen, into);
|
|
52
|
+
}
|
|
53
|
+
// The leaf wins: a project that extends a base and re-registers an
|
|
54
|
+
// extension is saying which mapper this project means.
|
|
55
|
+
for (const mapper of decoded.contentMappers ?? []) {
|
|
56
|
+
for (const extension of mapper.extensions)
|
|
57
|
+
into.set(extension, mapper.package);
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
/**
|
|
61
|
+
* The content mappers this project declares, merged along its tsconfig chain.
|
|
62
|
+
*
|
|
63
|
+
* @param root - The project root.
|
|
64
|
+
* @returns one entry per mapper package, with the extensions it won.
|
|
65
|
+
*/
|
|
66
|
+
export const contentMappersOf = (root) => Effect.gen(function* () {
|
|
67
|
+
const fs = yield* FileSystem.FileSystem;
|
|
68
|
+
const path = yield* Path.Path;
|
|
69
|
+
const into = new Map();
|
|
70
|
+
yield* readChain(fs, path, path.join(root, "tsconfig.json"), new Set(), into);
|
|
71
|
+
const byPackage = new Map();
|
|
72
|
+
for (const [extension, packageName] of into) {
|
|
73
|
+
const found = byPackage.get(packageName) ?? [];
|
|
74
|
+
found.push(extension);
|
|
75
|
+
byPackage.set(packageName, found);
|
|
76
|
+
}
|
|
77
|
+
return [...byPackage.entries()]
|
|
78
|
+
.sort(([left], [right]) => left.localeCompare(right))
|
|
79
|
+
.map(([packageName, extensions]) => ({
|
|
80
|
+
package: packageName,
|
|
81
|
+
extensions: [...extensions].sort((left, right) => left.localeCompare(right)),
|
|
82
|
+
}));
|
|
83
|
+
});
|
package/dist/decision.js
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
import { Config, Context, Effect, FileSystem, Layer, Option, Path, Predicate, Redacted, Ref, Result, Schedule, Schema, SchemaParser, Semaphore, } from "effect";
|
|
2
|
+
import * as AiError from "effect/ai/AiError";
|
|
3
|
+
import { Decision, DecisionModel } from "effect/ai";
|
|
4
|
+
import { TypeSafeClient, TypeSafeDecisionModel, TypeSafeSchema } from "@effect/ai-typesafe";
|
|
5
|
+
import { canonical } from "./canonical.js";
|
|
6
|
+
import { policy } from "./policy.js";
|
|
7
|
+
import { make as makeAnswerStore } from "./answer-store.js";
|
|
8
|
+
import { answerOf, memoize, PlanAnswers, storedOf } from "./plans.js";
|
|
9
|
+
// The judged half of joggle, as Effect's own DecisionModel.
|
|
10
|
+
//
|
|
11
|
+
// Built from scratch, this is the shape the AI surface wants: a rule declares a
|
|
12
|
+
// Decision.Definition with a typed input and named decisions; the rule calls
|
|
13
|
+
// DecisionModel.decide once per candidate; Effect builds the System One
|
|
14
|
+
// questions, calls the provider, validates the answers and returns them typed.
|
|
15
|
+
//
|
|
16
|
+
// joggle adds exactly three things, and nothing about the questions: a persisted
|
|
17
|
+
// cache, so CI replays reviewed verdicts with no API key; offline mode, so a run
|
|
18
|
+
// can be answered from the cache alone; and token accounting, so a run can say
|
|
19
|
+
// what it spent.
|
|
20
|
+
//
|
|
21
|
+
// The cache sits on the WIRE, not above the answers. A caching TypeSafeClient is
|
|
22
|
+
// provided to TypeSafeDecisionModel, so every decide -- a fresh call and a replay
|
|
23
|
+
// alike -- runs through Effect's validation. A cached answer cannot become a
|
|
24
|
+
// malformed answer just because it took the short path.
|
|
25
|
+
//
|
|
26
|
+
// The cache key is derived from the encoded state and the questions, which is the
|
|
27
|
+
// thing the provider is asked. An input that is part of the request is therefore
|
|
28
|
+
// part of the key by construction: the old judge carried the repository in the
|
|
29
|
+
// state and forgot it in the key, and the fix is to have only one of them.
|
|
30
|
+
/** The run's judgement accounting, read once at the end of a run. */
|
|
31
|
+
export class DecisionStats extends Context.Service()("@joggle/DecisionStats") {
|
|
32
|
+
}
|
|
33
|
+
const emptyStats = {
|
|
34
|
+
requests: 0,
|
|
35
|
+
replayed: 0,
|
|
36
|
+
calls: 0,
|
|
37
|
+
unavailable: 0,
|
|
38
|
+
inputTokens: 0,
|
|
39
|
+
outputTokens: 0,
|
|
40
|
+
};
|
|
41
|
+
const storePath = (path, cacheDir) => path.join(cacheDir, "wire.json");
|
|
42
|
+
const CacheFile = Schema.Struct({
|
|
43
|
+
version: Schema.String,
|
|
44
|
+
entries: Schema.Record(Schema.String, TypeSafeSchema.SystemOneResponse),
|
|
45
|
+
});
|
|
46
|
+
/**
|
|
47
|
+
* The key of one wire request: the model, the state and the questions, plus the
|
|
48
|
+
* decision version. Exported because the replay file is a contract.
|
|
49
|
+
*/
|
|
50
|
+
export const cacheKeyFor = (payload) => canonical({
|
|
51
|
+
decisionVersion: policy.decisionVersion,
|
|
52
|
+
model: payload.model,
|
|
53
|
+
state: payload.state,
|
|
54
|
+
questions: payload.questions,
|
|
55
|
+
});
|
|
56
|
+
/**
|
|
57
|
+
* True when the model was never reached: no key, or offline with no cached
|
|
58
|
+
* judgement. A rule treats that as "step aside", not as "every candidate is
|
|
59
|
+
* unreadable", and the predicate lives here so the rules that ask agree.
|
|
60
|
+
*/
|
|
61
|
+
export const isUnreachable = (error) => error.reason._tag === "AuthenticationError" || error.reason._tag === "UnknownError";
|
|
62
|
+
/**
|
|
63
|
+
* One place that builds joggle's AI errors.
|
|
64
|
+
*
|
|
65
|
+
* The module and method are how a failure is attributed, and two call sites that
|
|
66
|
+
* write them by hand are two chances to disagree. The parameters are positional
|
|
67
|
+
* so that the call does not recreate the shape the object-shape rule reports.
|
|
68
|
+
*
|
|
69
|
+
* @param at - The joggle module and the operation within it, as one value so a
|
|
70
|
+
* transposed call cannot compile.
|
|
71
|
+
* @param reason - The provider's reason.
|
|
72
|
+
* @returns The wrapped error.
|
|
73
|
+
*/
|
|
74
|
+
export const decisionError = (at, reason) => AiError.make({ module: at[0], method: at[1], reason });
|
|
75
|
+
/**
|
|
76
|
+
* A judgement that cannot be made, in the provider's own error vocabulary.
|
|
77
|
+
*
|
|
78
|
+
* A missing key is an authentication failure, because that is what it is. An
|
|
79
|
+
* offline miss is unknown, because the cache is the only thing that could have
|
|
80
|
+
* answered. A rule treats both as "the model was not reached" and steps aside,
|
|
81
|
+
* rather than reporting every candidate as unreadable.
|
|
82
|
+
*/
|
|
83
|
+
const missingKey = () => decisionError(["joggle/Decision", "systemOne"], AiError.AuthenticationError.make({
|
|
84
|
+
kind: "MissingKey",
|
|
85
|
+
description: "TYPESAFE_API_KEY is not set",
|
|
86
|
+
}));
|
|
87
|
+
const offlineMiss = () => decisionError(["joggle/Decision", "systemOne"], AiError.UnknownError.make({ description: "offline mode and no cached judgement" }));
|
|
88
|
+
/**
|
|
89
|
+
* Provides a caching DecisionModel and the run's judgement stats.
|
|
90
|
+
*
|
|
91
|
+
* The caching client wraps the provider client. The decision model is the
|
|
92
|
+
* provider's own, so the only joggle code between a rule and the wire is the
|
|
93
|
+
* cache.
|
|
94
|
+
*/
|
|
95
|
+
export const layer = (options) => Layer.effectContext(Effect.gen(function* () {
|
|
96
|
+
const fs = yield* FileSystem.FileSystem;
|
|
97
|
+
const path = yield* Path.Path;
|
|
98
|
+
const apiKey = Option.getOrUndefined(options.apiKey);
|
|
99
|
+
// Overridable so a self-hosted or enterprise deployment can be used when
|
|
100
|
+
// the evidence panels must not leave the organisation's boundary.
|
|
101
|
+
const baseUrl = yield* Config.String("TYPESAFE_BASE_URL").pipe(Effect.orElseSucceed(() => policy.decision.baseUrl));
|
|
102
|
+
const inner = yield* TypeSafeClient.make({
|
|
103
|
+
apiKey: apiKey === undefined ? undefined : Redacted.make(apiKey),
|
|
104
|
+
apiUrl: `${baseUrl}/v1`,
|
|
105
|
+
});
|
|
106
|
+
const file = storePath(path, options.wireCacheDir ?? options.cacheDir);
|
|
107
|
+
const load = Effect.gen(function* () {
|
|
108
|
+
const empty = {};
|
|
109
|
+
const exists = yield* Effect.orElseSucceed(fs.exists(file), () => false);
|
|
110
|
+
if (!exists)
|
|
111
|
+
return empty;
|
|
112
|
+
const text = yield* Effect.orElseSucceed(fs.readFileString(file), () => "");
|
|
113
|
+
if (text.trim() === "")
|
|
114
|
+
return empty;
|
|
115
|
+
const decoded = Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(CacheFile))(text));
|
|
116
|
+
return decoded === undefined ? empty : decoded.entries;
|
|
117
|
+
});
|
|
118
|
+
const entries = yield* Ref.make(yield* load);
|
|
119
|
+
const stats = yield* Ref.make(emptyStats);
|
|
120
|
+
// Decisions run concurrently, so several calls can finish at once and each
|
|
121
|
+
// one writes the whole cache. The permit keeps one writer in the file at a
|
|
122
|
+
// time, so a full write cannot interleave with another.
|
|
123
|
+
const writer = yield* Semaphore.make(1);
|
|
124
|
+
const flush = writer.withPermits(1)(Effect.gen(function* () {
|
|
125
|
+
const current = yield* Ref.get(entries);
|
|
126
|
+
const body = JSON.stringify({ version: policy.version, entries: current }, null, 2);
|
|
127
|
+
yield* Effect.orElseSucceed(fs.makeDirectory(options.cacheDir, { recursive: true }), () => undefined);
|
|
128
|
+
yield* Effect.orElseSucceed(fs.writeFileString(file, body), () => undefined);
|
|
129
|
+
}));
|
|
130
|
+
const client = TypeSafeClient.TypeSafeClient.of({
|
|
131
|
+
client: inner.client,
|
|
132
|
+
listModels: inner.listModels,
|
|
133
|
+
systemOne: (payload) => Effect.gen(function* () {
|
|
134
|
+
const key = cacheKeyFor(payload);
|
|
135
|
+
const before = yield* Ref.get(entries);
|
|
136
|
+
const cached = before[key];
|
|
137
|
+
if (cached !== undefined) {
|
|
138
|
+
yield* Ref.update(stats, (current) => ({
|
|
139
|
+
...current,
|
|
140
|
+
requests: current.requests + 1,
|
|
141
|
+
replayed: current.replayed + 1,
|
|
142
|
+
}));
|
|
143
|
+
return cached;
|
|
144
|
+
}
|
|
145
|
+
yield* Ref.update(stats, (current) => ({ ...current, requests: current.requests + 1 }));
|
|
146
|
+
if (apiKey === undefined) {
|
|
147
|
+
yield* Ref.update(stats, (current) => ({ ...current, unavailable: current.unavailable + 1 }));
|
|
148
|
+
return yield* missingKey();
|
|
149
|
+
}
|
|
150
|
+
if (options.offline) {
|
|
151
|
+
yield* Ref.update(stats, (current) => ({ ...current, unavailable: current.unavailable + 1 }));
|
|
152
|
+
return yield* offlineMiss();
|
|
153
|
+
}
|
|
154
|
+
const response = yield* inner.systemOne(payload).pipe(
|
|
155
|
+
// Backpressure is the provider's own classification, so
|
|
156
|
+
// `isRetryable` decides instead of a hand-written status list.
|
|
157
|
+
Effect.retry({
|
|
158
|
+
while: (error) => error.isRetryable,
|
|
159
|
+
schedule: Schedule.exponential("400 millis").pipe(Schedule.jittered, Schedule.upTo({ times: 6 })),
|
|
160
|
+
}));
|
|
161
|
+
yield* Ref.update(stats, (current) => ({
|
|
162
|
+
...current,
|
|
163
|
+
calls: current.calls + 1,
|
|
164
|
+
inputTokens: current.inputTokens + (response.usage?.input_tokens ?? 0),
|
|
165
|
+
outputTokens: current.outputTokens + (response.usage?.output_tokens ?? 0),
|
|
166
|
+
}));
|
|
167
|
+
yield* Ref.update(entries, (current) => ({ ...current, [key]: response }));
|
|
168
|
+
yield* flush;
|
|
169
|
+
return response;
|
|
170
|
+
}),
|
|
171
|
+
});
|
|
172
|
+
const providerModel = yield* TypeSafeDecisionModel.make({ model: policy.model }).pipe(Effect.provideService(TypeSafeClient.TypeSafeClient, client));
|
|
173
|
+
// The per-question cache, above the wire.
|
|
174
|
+
//
|
|
175
|
+
// The wire cache is keyed on a whole request, so a batched request would
|
|
176
|
+
// lose every question's answer when one of them changed. This one is keyed
|
|
177
|
+
// on the question and the atoms it read, which is what makes a batched
|
|
178
|
+
// request keep the independence a per-candidate request had.
|
|
179
|
+
//
|
|
180
|
+
// The store is sharded and content-addressed: one file per shard, one
|
|
181
|
+
// entry per line, sorted, with the key naming the shard. Two branches that
|
|
182
|
+
// judge different candidates never touch the same line, and the shipped
|
|
183
|
+
// merge driver resolves the residual case by key. A legacy single
|
|
184
|
+
// `answers.json` is read and migrated on the first write. See
|
|
185
|
+
// `docs/artifacts.md`.
|
|
186
|
+
const answers = yield* makeAnswerStore(fs, path, options.cacheDir);
|
|
187
|
+
const planAnswers = {
|
|
188
|
+
get: (key) => Effect.map(answers.get(key), (stored) => Option.map(stored, answerOf)),
|
|
189
|
+
put: (key, answer) => answers.put(key, storedOf(answer)),
|
|
190
|
+
};
|
|
191
|
+
// Every answer is remembered per decision, so the committed cache is the
|
|
192
|
+
// replay path and the wire cache is only a performance artifact.
|
|
193
|
+
const base = memoize(providerModel, planAnswers);
|
|
194
|
+
const decisionModel = options.onAnswer === undefined
|
|
195
|
+
? base
|
|
196
|
+
: DecisionModel.DecisionModel.of(Object.assign({}, base, {
|
|
197
|
+
decide: (definition, decideOptions) => Effect.tap(base.decide(definition, decideOptions), (decided) => Effect.sync(() => options.onAnswer?.({
|
|
198
|
+
decisions: definition.decisions,
|
|
199
|
+
answers: decided.answers,
|
|
200
|
+
}))),
|
|
201
|
+
}));
|
|
202
|
+
return Context.make(DecisionModel.DecisionModel, decisionModel).pipe(Context.add(DecisionStats, { read: Ref.get(stats) }), Context.add(PlanAnswers, planAnswers));
|
|
203
|
+
}));
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { Effect, FileSystem, Order, Path } from "effect";
|
|
2
|
+
import { shortHash } from "./state.js";
|
|
3
|
+
/*
|
|
4
|
+
* A hash of the tool's own source, which is the version nobody has to remember.
|
|
5
|
+
*
|
|
6
|
+
* `policy.analysisVersion` is a hand-bumped string, and a hand-bumped string is a
|
|
7
|
+
* promise to remember. Forgetting it means the next run replays a report produced
|
|
8
|
+
* by rules that no longer exist -- which happened twice in one session, and both
|
|
9
|
+
* times the output looked entirely plausible, because a stale report is not
|
|
10
|
+
* malformed, it is just wrong.
|
|
11
|
+
*
|
|
12
|
+
* So the version is not maintained by hand. The tool hashes its own sources
|
|
13
|
+
* and puts that hash in the run manifest, and a change to a rule, a threshold or a
|
|
14
|
+
* question cannot be missed because it cannot be omitted. `analysisVersion`
|
|
15
|
+
* survives as the fallback for when the sources cannot be read, and as the
|
|
16
|
+
* deliberate override for when a change is meant NOT to invalidate a run -- a
|
|
17
|
+
* refactor, say, that provably cannot alter output.
|
|
18
|
+
*
|
|
19
|
+
* The cost is one pass over the tool's own source per run, which is a couple of
|
|
20
|
+
* dozen small files, and it is paid once per run rather than once per file.
|
|
21
|
+
*/
|
|
22
|
+
/**
|
|
23
|
+
* Where this module lives, which is the directory to hash.
|
|
24
|
+
*
|
|
25
|
+
* Read from the module's own URL so it follows the tool wherever it is installed:
|
|
26
|
+
* `src/` when run from source, `dist/` from a published package. Undefined when
|
|
27
|
+
* the runtime does not expose it, in which case the declared version is used.
|
|
28
|
+
*/
|
|
29
|
+
const sourceDirectory = () => {
|
|
30
|
+
const here = import.meta.dirname;
|
|
31
|
+
return here.length > 0 ? here : undefined;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* Sources are hashed, not the whole directory: a stray `.joggle` cache or a
|
|
35
|
+
* `node_modules` under the tool's own folder is not part of the tool.
|
|
36
|
+
*/
|
|
37
|
+
const isSource = (name) => name.endsWith(".ts") || name.endsWith(".js");
|
|
38
|
+
/**
|
|
39
|
+
* Hash this tool's own source, so a rule or threshold change cannot be
|
|
40
|
+
* forgotten. `declared` is the fallback for a build that ships no source.
|
|
41
|
+
*/
|
|
42
|
+
export const sourceFingerprint = (declared) => Effect.gen(function* () {
|
|
43
|
+
const directory = sourceDirectory();
|
|
44
|
+
if (directory === undefined)
|
|
45
|
+
return declared;
|
|
46
|
+
const fs = yield* FileSystem.FileSystem;
|
|
47
|
+
const path = yield* Path.Path;
|
|
48
|
+
// Any failure here is a fallback, never an error: a run that cannot read its
|
|
49
|
+
// own source still has the declared version and still produces a report.
|
|
50
|
+
const names = yield* Effect.orElseSucceed(fs.readDirectory(directory, { recursive: true }), () => []);
|
|
51
|
+
const sources = names.filter(isSource).sort(Order.String);
|
|
52
|
+
if (sources.length === 0)
|
|
53
|
+
return declared;
|
|
54
|
+
const parts = [];
|
|
55
|
+
for (const name of sources) {
|
|
56
|
+
const text = yield* Effect.orElseSucceed(fs.readFileString(path.join(directory, name)), () => "");
|
|
57
|
+
parts.push(name + "\u0000" + text);
|
|
58
|
+
}
|
|
59
|
+
// Sorted by name, and the name is inside the hash, so a rename is a change.
|
|
60
|
+
return shortHash(parts.join("\u0001"));
|
|
61
|
+
});
|