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