@autotelic/joggle 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/JOGGLE.md +634 -0
  2. package/LICENSE +21 -0
  3. package/README.md +88 -2
  4. package/bin/joggle.js +6 -0
  5. package/dist/answer-store.js +305 -0
  6. package/dist/architecture.js +190 -0
  7. package/dist/ask.js +184 -0
  8. package/dist/astro.js +75 -0
  9. package/dist/atoms.js +76 -0
  10. package/dist/bundles.js +156 -0
  11. package/dist/calibration.js +60 -0
  12. package/dist/candidates.js +561 -0
  13. package/dist/canonical.js +24 -0
  14. package/dist/cascade.js +98 -0
  15. package/dist/check.js +854 -0
  16. package/dist/cluster.js +69 -0
  17. package/dist/config.js +195 -0
  18. package/dist/content-mappers.js +83 -0
  19. package/dist/decision.js +203 -0
  20. package/dist/fingerprint.js +61 -0
  21. package/dist/git.js +127 -0
  22. package/dist/gitignore.js +65 -0
  23. package/dist/glob.js +51 -0
  24. package/dist/imports.js +153 -0
  25. package/dist/jsonc.js +95 -0
  26. package/dist/main.js +630 -0
  27. package/dist/manifest.js +42 -0
  28. package/dist/meta.js +170 -0
  29. package/dist/moves.js +47 -0
  30. package/dist/operation.js +133 -0
  31. package/dist/parsecache.js +264 -0
  32. package/dist/plans.js +425 -0
  33. package/dist/plugin.js +71 -0
  34. package/dist/plugins.js +136 -0
  35. package/dist/policy.js +676 -0
  36. package/dist/presets/composition.js +32 -0
  37. package/dist/report.js +474 -0
  38. package/dist/reporting.js +132 -0
  39. package/dist/result.js +28 -0
  40. package/dist/roles.js +303 -0
  41. package/dist/rule.js +194 -0
  42. package/dist/rules/append-only-honoured.js +190 -0
  43. package/dist/rules/bundle-conformance.js +245 -0
  44. package/dist/rules/call-pattern.js +209 -0
  45. package/dist/rules/cluster-verdict.js +700 -0
  46. package/dist/rules/compose-types.js +250 -0
  47. package/dist/rules/data-error-as-outage.js +482 -0
  48. package/dist/rules/declared-staleness.js +242 -0
  49. package/dist/rules/dependency-fit.js +297 -0
  50. package/dist/rules/deviation-has-a-shape.js +225 -0
  51. package/dist/rules/doc-matches-code.js +191 -0
  52. package/dist/rules/duplicate-call-run.js +240 -0
  53. package/dist/rules/duplicate-implementation.js +89 -0
  54. package/dist/rules/duplicate-meaning.js +130 -0
  55. package/dist/rules/fact-or-derivation.js +202 -0
  56. package/dist/rules/field-type-drift.js +373 -0
  57. package/dist/rules/generic-carries-a-caller.js +198 -0
  58. package/dist/rules/hoist-to-domain.js +288 -0
  59. package/dist/rules/import-architecture.js +393 -0
  60. package/dist/rules/index.js +105 -0
  61. package/dist/rules/inferred-over-recorded.js +214 -0
  62. package/dist/rules/intent-drift.js +286 -0
  63. package/dist/rules/invariant-has-a-reconciler.js +190 -0
  64. package/dist/rules/language-drift.js +234 -0
  65. package/dist/rules/meaning-switched-by-flag.js +189 -0
  66. package/dist/rules/module-direction.js +231 -0
  67. package/dist/rules/name-as-address.js +216 -0
  68. package/dist/rules/name-the-primitive.js +203 -0
  69. package/dist/rules/naming-drift.js +218 -0
  70. package/dist/rules/nullability-drift.js +220 -0
  71. package/dist/rules/object-shape.js +280 -0
  72. package/dist/rules/one-concept-one-type.js +243 -0
  73. package/dist/rules/page-needs-composition.js +227 -0
  74. package/dist/rules/reimplemented-primitive.js +283 -0
  75. package/dist/rules/reversal.js +264 -0
  76. package/dist/rules/rule-judgment.js +252 -0
  77. package/dist/rules/schema-excludes-domain-value.js +190 -0
  78. package/dist/rules/shallow-module.js +204 -0
  79. package/dist/rules/single-path.js +237 -0
  80. package/dist/rules/structural-collapse.js +198 -0
  81. package/dist/rules/temporal-coupling.js +205 -0
  82. package/dist/rules/types-over-logic.js +198 -0
  83. package/dist/rules/unaccounted-drop.js +190 -0
  84. package/dist/rules/unbounded-default-read.js +227 -0
  85. package/dist/run-cache.js +132 -0
  86. package/dist/schema.js +285 -0
  87. package/dist/similarity.js +119 -0
  88. package/dist/source.js +30 -0
  89. package/dist/sql.js +34 -0
  90. package/dist/stages.js +39 -0
  91. package/dist/state.js +65 -0
  92. package/dist/testing.js +131 -0
  93. package/dist/tsconfig-scope.js +32 -0
  94. package/dist/tsgo.js +127 -0
  95. package/dist/typefacts.js +455 -0
  96. package/dist/typetrace.js +283 -0
  97. package/dist/verdict.js +65 -0
  98. package/dist/vocabulary.js +365 -0
  99. package/dist/workspace.js +1963 -0
  100. package/extensions/joggle.ts +454 -0
  101. package/package.json +85 -3
@@ -0,0 +1,190 @@
1
+ import { Effect } from "effect";
2
+ import { Decision } from "effect/ai";
3
+ import { Atoms } from "../atoms.js";
4
+ import { policy } from "../policy.js";
5
+ import { verdictsOf } from "../plans.js";
6
+ import { locator, messages, reporter } from "../reporting.js";
7
+ import { budgetNote, inScope, outcome, qualityOf, } from "../rule.js";
8
+ import { mayYield, returnTypesOf } from "../result.js";
9
+ import { verdictOf } from "../verdict.js";
10
+ const RULE_ID = "joggle/unaccounted-drop";
11
+ // A shared path that discards items and does not say so.
12
+ //
13
+ // The review case: `adaptRows` skipped rows missing a person or a date for every
14
+ // caller, but only one of four endpoints surfaced `excluded`, so three silently
15
+ // returned totals that were short. The repository names this the "fallback data"
16
+ // anti-pattern in AGENTS.md, and it is joggle's own funnel principle turned on the
17
+ // code: every bound this program hits is reported, and a path that shortens its
18
+ // input without saying so produces a number that is wrong in a way nobody can see.
19
+ //
20
+ // Two facts, and neither classifies:
21
+ //
22
+ // the skip a `continue`, from the AST: the loop moved on without an item
23
+ // the boundary an EXPORTED function -- a path whose result other files read
24
+ //
25
+ // An earlier version matched adapter NAMES (`adapt`, `normalize`, a path under
26
+ // `adapters/`) and looked for the word "excluded" in the body. That decided the
27
+ // question -- is this a boundary, does it account? -- in code, coupled to one
28
+ // repository's naming (docs/rule-coupling.md). The skip is syntax, the boundary is
29
+ // the export, and whether the drop needs accounting is asked.
30
+ //
31
+ // A third fact narrows the candidates, when the type layer ran: what the function
32
+ // HANDS BACK. A path that returns a flag or nothing does not shorten the data its
33
+ // caller reads, whatever `continue` it contains. The list of non-data returns is a
34
+ // declared convention in policy, not a vocabulary in this rule.
35
+ const nonDataReturns = new Set(policy.unaccountedDrop.nonDataReturns);
36
+ export const unaccountedDrop = {
37
+ id: RULE_ID,
38
+ severity: "warn",
39
+ description: "A shared path that discards items without saying what it discarded.",
40
+ judged: true,
41
+ onUnavailable: "report",
42
+ messages: messages({
43
+ silent_drop: "{{name}} skips items as it runs, and a caller cannot see what was skipped.",
44
+ silent_drop_help: "Return what was left out -- a count, or the items -- and let the caller surface it, the way joggle's own funnel records every bound. A path that silently shortens its input produces a total that is wrong in a way nobody can see.{{unverified}}",
45
+ }),
46
+ plan: Effect.fn("joggle/unaccounted-drop")(function* (workspace, scope, context) {
47
+ const report = reporter(unaccountedDrop, locator(workspace));
48
+ const candidates = [];
49
+ for (const unit of workspace.units) {
50
+ if (unit.kind !== "function" || !unit.exported)
51
+ continue;
52
+ // A test helper that skips is scaffolding for an assertion, not a boundary
53
+ // other files read: the same reason the duplicate rules keep test
54
+ // declarations out of the candidate set.
55
+ if (unit.test)
56
+ continue;
57
+ if (unit.text.length > policy.evidence.maxSourceChars)
58
+ continue;
59
+ if (scope.changed !== undefined && !inScope(scope, unit.file))
60
+ continue;
61
+ const source = workspace.files.find((file) => file.path === unit.file);
62
+ if (source === undefined)
63
+ continue;
64
+ if (!source.facts.skips.some((skip) => skip.start >= unit.start && skip.end <= unit.end))
65
+ continue;
66
+ // A `continue` in a function that returns a flag or nothing is not a funnel
67
+ // that shortened the caller's data. Only a path that hands data back can be.
68
+ if (!mayYield(returnTypesOf(unit, source, context.nodeTypes), nonDataReturns))
69
+ continue;
70
+ candidates.push(unit);
71
+ }
72
+ if (candidates.length === 0) {
73
+ return {
74
+ plans: [],
75
+ read: () => outcome([], [
76
+ "no exported function skips an item with a `continue`",
77
+ ]),
78
+ };
79
+ }
80
+ const budget = policy.evidence.maxMembers * 12;
81
+ const judged = candidates.slice(0, budget);
82
+ const overBudget = candidates.slice(budget).map((unit) => ({
83
+ ruleId: RULE_ID,
84
+ subject: unit.name,
85
+ stage: "budget",
86
+ reason: "past the budget of " + String(budget) + " skipping paths",
87
+ }));
88
+ const atoms = yield* Atoms;
89
+ const planned = yield* Effect.forEach(judged, (unit) => Effect.gen(function* () {
90
+ const id = yield* atoms.add({
91
+ adapter: { name: unit.name, file: unit.file },
92
+ source: unit.text.slice(0, policy.evidence.maxSourceChars),
93
+ });
94
+ const plan = {
95
+ ruleId: RULE_ID,
96
+ subject: unit.name + " (" + unit.file + ")",
97
+ concerns: [unit.file],
98
+ atoms: [id],
99
+ violations: { verdict: ["unaccounted"] },
100
+ decisions: {
101
+ verdict: Decision.classify({
102
+ instructions: [
103
+ `\`atoms[${id}].source\` is an exported function, \`atoms[${id}].adapter.name\`, that skips some of the items it iterates (a \`continue\`).`,
104
+ "Does the skip go unaccounted for -- does a caller need to know how many items were left out?",
105
+ "Answer `unaccounted` when the skipped items are the caller's data: a total, a count or a list built from them would be silently short, so the function should return what it dropped.",
106
+ "Answer `accounted_elsewhere` when the caller, or another value the caller already reads, reports the exclusion.",
107
+ "Answer `internal_only` when the skipped items are not the caller's data -- a defensive skip of something the caller cannot observe, or a predicate the caller supplied.",
108
+ ].join("\n"),
109
+ criteria: {
110
+ unaccounted: "The caller cannot see what was dropped. Return it.",
111
+ accounted_elsewhere: "Something the caller reads already reports it.",
112
+ internal_only: "Not the caller's data.",
113
+ },
114
+ }),
115
+ },
116
+ read: (answers) => answers,
117
+ };
118
+ return { plan, unit };
119
+ }), { concurrency: "unbounded" });
120
+ return {
121
+ plans: planned.map((entry) => entry.plan),
122
+ read: (answers) => {
123
+ const verdicts = verdictsOf(answers);
124
+ const diagnostics = [];
125
+ const drops = [...overBudget];
126
+ planned.forEach((entry, index) => {
127
+ const unit = entry.unit;
128
+ const subject = unit.name + " (" + unit.file + ")";
129
+ const verdict = verdictOf(verdicts[index]?.["verdict"], ["unaccounted"]);
130
+ if (verdict === undefined) {
131
+ diagnostics.push(findingFor({
132
+ report,
133
+ unit,
134
+ confidence: undefined,
135
+ unverifiedReason: "no judgement was available",
136
+ }));
137
+ return;
138
+ }
139
+ if (verdict.label !== "unaccounted") {
140
+ drops.push({
141
+ ruleId: RULE_ID,
142
+ subject,
143
+ stage: "declined",
144
+ reason: verdict.label === "accounted_elsewhere"
145
+ ? "something the caller reads already reports the drop"
146
+ : "the skipped items are not the caller's data",
147
+ });
148
+ return;
149
+ }
150
+ const quality = qualityOf({
151
+ score: verdict.probability,
152
+ margin: verdict.margin,
153
+ confidence: verdict.confidence,
154
+ });
155
+ if (quality.quality === "drop") {
156
+ drops.push({ ruleId: RULE_ID, subject, stage: "gated", reason: quality.reason });
157
+ return;
158
+ }
159
+ const review = quality.quality === "review";
160
+ diagnostics.push(findingFor({
161
+ report,
162
+ unit,
163
+ confidence: verdict.confidence,
164
+ unverifiedReason: undefined,
165
+ review,
166
+ }));
167
+ });
168
+ return outcome(diagnostics, budgetNote({
169
+ unitKind: "skipping paths",
170
+ judged: budget,
171
+ candidates: candidates.length,
172
+ sample: candidates.slice(budget).map((unit) => unit.name),
173
+ }), drops);
174
+ },
175
+ };
176
+ }),
177
+ };
178
+ const findingFor = ({ report, unit, confidence, unverifiedReason, review = false, }) => report({
179
+ about: unit,
180
+ messageId: "silent_drop",
181
+ data: {
182
+ name: unit.name,
183
+ unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
184
+ },
185
+ helpId: "silent_drop_help",
186
+ identity: [RULE_ID, unit.file, unit.name].join("\u0000"),
187
+ judged: unverifiedReason === undefined,
188
+ confidence,
189
+ severity: review ? "info" : "warn",
190
+ });
@@ -0,0 +1,227 @@
1
+ import { Effect } from "effect";
2
+ import { Decision } from "effect/ai";
3
+ import { Atoms } from "../atoms.js";
4
+ import { policy } from "../policy.js";
5
+ import { verdictsOf } from "../plans.js";
6
+ import { locator, messages, reporter } from "../reporting.js";
7
+ import { budgetNote, inScope, outcome, qualityOf, } from "../rule.js";
8
+ import { verdictOf } from "../verdict.js";
9
+ const RULE_ID = "joggle/unbounded-default-read";
10
+ // A data read whose default path has no bound.
11
+ //
12
+ // From PR 1574: `/finance/payroll-review` with no params called the loader with
13
+ // no project and no date predicate -- every approved payroll row ever, aggregated
14
+ // in memory. Measured fine at the time (1 tenant, 9 months, 3.3k rows, ~150ms) but
15
+ // linear, so ~1.5s and 36.6MB at 16x. The finding is not "this is slow", it is
16
+ // "the default path grows every season and nothing bounds it".
17
+ //
18
+ // Three facts, and none classifies:
19
+ //
20
+ // the call a call to a function whose every filter is optional, with the
21
+ // argument keys it passes (`facts.callSites`)
22
+ // the callee resolved to its declaration, whose parameters are all optional
23
+ // the access the declaring file imports a data package
24
+ //
25
+ // `isDataPackage` is a framework vocabulary, like the `node:` builtins in
26
+ // `dependency-fit` -- what a database client is called, not what this repository
27
+ // calls things. Whether the read is unbounded is the question.
28
+ const isDataPackage = (specifier) => specifier === "knex" ||
29
+ specifier.startsWith("knex/") ||
30
+ specifier.startsWith("drizzle-orm") ||
31
+ specifier.startsWith("@prisma/") ||
32
+ specifier === "prisma" ||
33
+ specifier === "pg" ||
34
+ specifier.startsWith("postgres") ||
35
+ specifier.startsWith("mysql") ||
36
+ specifier.startsWith("mongodb") ||
37
+ specifier.startsWith("better-sqlite3") ||
38
+ specifier.startsWith("kysely") ||
39
+ specifier.startsWith("slonik");
40
+ export const unboundedDefaultRead = {
41
+ id: RULE_ID,
42
+ severity: "warn",
43
+ description: "A data read whose default path has no bound.",
44
+ judged: true,
45
+ onUnavailable: "report",
46
+ messages: messages({
47
+ unbounded: "{{caller}} calls `{{callee}}` -- every filter optional -- passing {{args}}.",
48
+ unbounded_help: "A default that passes no bound reads every row that ever accrued and will grow every season. Open on a window (a season, a recent range), or push the read into the database with a predicate, so the cheap path is the bounded one.{{unverified}}",
49
+ }),
50
+ plan: Effect.fn("joggle/unbounded-default-read")(function* (workspace, scope) {
51
+ const report = reporter(unboundedDefaultRead, locator(workspace));
52
+ const dataFiles = new Set();
53
+ for (const file of workspace.files) {
54
+ if (file.importStatements.some((entry) => isDataPackage(entry.specifier)))
55
+ dataFiles.add(file.path);
56
+ }
57
+ const byIdentity = new Map();
58
+ for (const unit of workspace.units)
59
+ byIdentity.set(unit.file + "#" + unit.name, unit);
60
+ // The fact list, by identity: a function whose every filter is optional.
61
+ const allOptional = new Set();
62
+ for (const file of workspace.files) {
63
+ for (const name of file.facts.allOptionalFunctions)
64
+ allOptional.add(file.path + "#" + name);
65
+ }
66
+ const textOf = new Map(workspace.files.map((file) => [file.path, file.text]));
67
+ const candidates = [];
68
+ for (const file of workspace.files) {
69
+ if (scope.changed !== undefined && !inScope(scope, file.path))
70
+ continue;
71
+ for (const unit of file.units) {
72
+ // The pairing only holds when every call has its span, the same guard
73
+ // `reimplemented-primitive` uses.
74
+ if (file.facts.callSites.length !== unit.calls.length)
75
+ continue;
76
+ file.facts.callSites.forEach((site, index) => {
77
+ const identity = unit.calls[index];
78
+ if (identity === undefined)
79
+ return;
80
+ const callee = byIdentity.get(identity);
81
+ if (callee === undefined || !allOptional.has(identity))
82
+ return;
83
+ if (!dataFiles.has(callee.file))
84
+ return;
85
+ candidates.push({
86
+ unit,
87
+ start: site.start,
88
+ callee,
89
+ argumentKeys: site.argumentKeys,
90
+ argumentCount: site.argumentCount,
91
+ });
92
+ });
93
+ }
94
+ }
95
+ if (candidates.length === 0) {
96
+ return {
97
+ plans: [],
98
+ read: () => outcome([], [
99
+ "no call reaches a data-access function whose every filter is optional",
100
+ ]),
101
+ };
102
+ }
103
+ const budget = policy.evidence.maxMembers * 12;
104
+ const judged = candidates.slice(0, budget);
105
+ const overBudget = candidates.slice(budget).map((candidate) => ({
106
+ ruleId: RULE_ID,
107
+ subject: candidate.unit.name,
108
+ stage: "budget",
109
+ reason: "past the budget of " + String(budget) + " reads",
110
+ }));
111
+ const atoms = yield* Atoms;
112
+ const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
113
+ const text = textOf.get(candidate.unit.file) ?? "";
114
+ const id = yield* atoms.add({
115
+ call: {
116
+ caller: candidate.unit.name,
117
+ file: candidate.unit.file,
118
+ call: text.slice(candidate.start, Math.min(candidate.start + 160, text.length)),
119
+ },
120
+ callee: { name: candidate.callee.name, file: candidate.callee.file },
121
+ arguments: [...candidate.argumentKeys],
122
+ source: candidate.callee.text.slice(0, policy.evidence.maxSourceChars),
123
+ });
124
+ const plan = {
125
+ ruleId: RULE_ID,
126
+ subject: candidate.unit.name + " -> " + candidate.callee.name,
127
+ concerns: [candidate.unit.file, candidate.callee.file],
128
+ atoms: [id],
129
+ violations: { verdict: ["unbounded"] },
130
+ decisions: {
131
+ verdict: Decision.classify({
132
+ instructions: [
133
+ `\`atoms[${id}].call.caller\` calls \`atoms[${id}].callee.name\` here: \`atoms[${id}].call.call\`.`,
134
+ `The callee's every filter is optional (\`atoms[${id}].source\`), and the call sets \`atoms[${id}].arguments\`.`,
135
+ "Does the default path leave the read unbounded over a table that grows?",
136
+ "Answer `unbounded` when the call passes no window, no limit and no required scope, so it reads every row that has accrued and will read more each period.",
137
+ "Answer `bounded` when something bounds it: a caller-supplied scope that is always set, a limit, a date default, or a table that does not grow.",
138
+ "Answer `not_applicable` when the callee is not a data read, or the arguments passed are already a bound.",
139
+ ].join("\n"),
140
+ criteria: {
141
+ unbounded: "No window, no limit, no required scope. It grows.",
142
+ bounded: "Something bounds it.",
143
+ not_applicable: "Not a data read, or already bounded.",
144
+ },
145
+ }),
146
+ },
147
+ read: (answers) => answers,
148
+ };
149
+ return { candidate, plan };
150
+ }), { concurrency: "unbounded" });
151
+ return {
152
+ plans: planned.map((entry) => entry.plan),
153
+ read: (answers) => {
154
+ const verdicts = verdictsOf(answers);
155
+ const diagnostics = [];
156
+ const drops = [...overBudget];
157
+ planned.forEach((entry, index) => {
158
+ const { candidate } = entry;
159
+ const subject = candidate.unit.name + " -> " + candidate.callee.name;
160
+ const verdict = verdictOf(verdicts[index]?.["verdict"], ["unbounded"]);
161
+ if (verdict === undefined) {
162
+ diagnostics.push(findingFor({
163
+ report,
164
+ entry,
165
+ confidence: undefined,
166
+ unverifiedReason: "no judgement was available",
167
+ }));
168
+ return;
169
+ }
170
+ if (verdict.label !== "unbounded") {
171
+ drops.push({
172
+ ruleId: RULE_ID,
173
+ subject,
174
+ stage: "declined",
175
+ reason: verdict.label === "bounded" ? "something bounds the read" : "not a data read",
176
+ });
177
+ return;
178
+ }
179
+ const quality = qualityOf({
180
+ score: verdict.probability,
181
+ margin: verdict.margin,
182
+ confidence: verdict.confidence,
183
+ });
184
+ if (quality.quality === "drop") {
185
+ drops.push({ ruleId: RULE_ID, subject, stage: "gated", reason: quality.reason });
186
+ return;
187
+ }
188
+ diagnostics.push(findingFor({
189
+ report,
190
+ entry,
191
+ confidence: verdict.confidence,
192
+ unverifiedReason: undefined,
193
+ review: quality.quality === "review",
194
+ }));
195
+ });
196
+ return outcome(diagnostics, budgetNote({
197
+ unitKind: "reads",
198
+ judged: budget,
199
+ candidates: candidates.length,
200
+ sample: candidates.slice(budget).map((candidate) => candidate.unit.name),
201
+ }), drops);
202
+ },
203
+ };
204
+ }),
205
+ };
206
+ const findingFor = ({ report, entry, confidence, unverifiedReason, review = false, }) => {
207
+ const passed = entry.candidate.argumentCount === 0
208
+ ? "no arguments"
209
+ : entry.candidate.argumentKeys.length === 0
210
+ ? "an object"
211
+ : entry.candidate.argumentKeys.join(", ");
212
+ return report({
213
+ about: { file: entry.candidate.unit.file, start: entry.candidate.start },
214
+ messageId: "unbounded",
215
+ data: {
216
+ caller: entry.candidate.unit.name,
217
+ callee: entry.candidate.callee.name,
218
+ args: passed,
219
+ unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
220
+ },
221
+ helpId: "unbounded_help",
222
+ identity: [RULE_ID, entry.candidate.unit.file, entry.candidate.unit.name, entry.candidate.callee.file, entry.candidate.callee.name].join("\u0000"),
223
+ judged: unverifiedReason === undefined,
224
+ confidence,
225
+ severity: review ? "info" : "warn",
226
+ });
227
+ };
@@ -0,0 +1,132 @@
1
+ import { Effect, FileSystem, Path, Result, Schema, SchemaParser } from "effect";
2
+ import { policy } from "./policy.js";
3
+ import { shortHash } from "./state.js";
4
+ import { Baseline, StoredRun } from "./schema.js";
5
+ /**
6
+ * The manifest hash: the identity of a run's inputs.
7
+ *
8
+ * @param input - The root, the bytes, the rule set, the tool and the settings.
9
+ * @returns The manifest hash.
10
+ */
11
+ export const manifestOf = ({ root, files, contents, ruleIds, tool, settings, }) => shortHash([
12
+ // The tool's own source, so a rule change cannot be forgotten. The declared
13
+ // version stays beside it as the documented fallback.
14
+ `tool=${tool}`,
15
+ `analysis=${policy.analysisVersion}`,
16
+ `decisions=${policy.decisionVersion}`,
17
+ `model=${policy.model}`,
18
+ `root=${root}`,
19
+ `rules=${[...ruleIds].sort((left, right) => left.localeCompare(right)).join(",")}`,
20
+ `settings=${settings}`,
21
+ `files=${files.length}`,
22
+ ...files.map((file) => `${file}\u0000${shortHash(contents.get(file) ?? "")}`),
23
+ ].join("\n"));
24
+ const runPath = (path, cacheDir) => path.join(cacheDir, "last-run.json");
25
+ /** The baseline is the file the config names, resolved by the caller. */
26
+ export const baselinePath = (_path, file) => file;
27
+ /**
28
+ * Reads the stored run, or nothing when it is absent or unreadable.
29
+ *
30
+ * @param fs - The file system to read from.
31
+ * @param path - The path service.
32
+ * @param cacheDir - The directory holding `last-run.json`.
33
+ * @returns The decoded run, or `undefined` for a miss.
34
+ */
35
+ export const readStored = (fs, path, cacheDir) => Effect.gen(function* () {
36
+ const file = runPath(path, cacheDir);
37
+ const exists = yield* Effect.orElseSucceed(fs.exists(file), () => false);
38
+ if (!exists)
39
+ return undefined;
40
+ const text = yield* Effect.orElseSucceed(fs.readFileString(file), () => "");
41
+ if (text.trim() === "")
42
+ return undefined;
43
+ return Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(StoredRun))(text));
44
+ });
45
+ /**
46
+ * Writes the run, so the next one can replay it.
47
+ *
48
+ * @param fs - The file system to write to.
49
+ * @param path - The path service.
50
+ * @param cacheDir - The directory holding `last-run.json`.
51
+ * @param run - The run to store.
52
+ */
53
+ export const writeStored = (fs, path, cacheDir, run) => Effect.gen(function* () {
54
+ yield* Effect.orElseSucceed(fs.makeDirectory(cacheDir, { recursive: true }), () => undefined);
55
+ yield* Effect.orElseSucceed(fs.writeFileString(runPath(path, cacheDir), JSON.stringify(run, null, 2)), () => undefined);
56
+ });
57
+ /** One accepted finding: the fragment a baseline directory holds. */
58
+ const Fragment = Schema.Struct({ identity: Schema.String });
59
+ /**
60
+ * Reads the accepted findings, or nothing when there is no baseline.
61
+ *
62
+ * A baseline is a directory of fragments -- one file per accepted finding, the
63
+ * changesets/towncrier shape -- or, for a repository written before that shape
64
+ * existed, the single JSON file. Which one it is comes from the filesystem, so
65
+ * both are read without the caller saying which.
66
+ *
67
+ * @param fs - The file system to read from.
68
+ * @param path - The path service.
69
+ * @param target - The baseline directory, or the single file.
70
+ * @returns The accepted identities, or `undefined` for a miss.
71
+ */
72
+ export const readBaseline = (fs, path, target) => Effect.gen(function* () {
73
+ const info = yield* fs.stat(target).pipe(Effect.orElseSucceed(() => undefined));
74
+ if (info === undefined)
75
+ return undefined;
76
+ if (info.type === "Directory") {
77
+ const names = yield* fs.readDirectory(target).pipe(Effect.orElseSucceed(() => []));
78
+ const identities = new Set();
79
+ for (const name of names) {
80
+ if (!name.endsWith(".json"))
81
+ continue;
82
+ const text = yield* fs.readFileString(path.join(target, name)).pipe(Effect.orElseSucceed(() => ""));
83
+ const decoded = Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(Fragment))(text));
84
+ if (decoded !== undefined)
85
+ identities.add(decoded.identity);
86
+ }
87
+ return identities.size === 0 ? undefined : identities;
88
+ }
89
+ const text = yield* fs.readFileString(target).pipe(Effect.orElseSucceed(() => ""));
90
+ const decoded = Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(Baseline))(text));
91
+ return decoded === undefined ? undefined : new Set(decoded.identities);
92
+ });
93
+ /**
94
+ * Writes the accepted findings as the new baseline.
95
+ *
96
+ * A target ending in `.json` is the single file and is written as one. A target
97
+ * that is not is a directory of fragments: one file per identity, named by the
98
+ * identity's hash, so two branches that accept different findings never touch
99
+ * the same file. A fragment no longer in the set is removed, so the directory is
100
+ * the whole baseline and not a log of every acceptance.
101
+ *
102
+ * @param fs - The file system to write to.
103
+ * @param path - The path service.
104
+ * @param target - The baseline directory, or a `.json` file for the old shape.
105
+ * @param identities - The finding identities to accept.
106
+ */
107
+ export const writeBaseline = (fs, path, target, identities) => Effect.gen(function* () {
108
+ if (target.endsWith(".json")) {
109
+ const parent = path.dirname(target);
110
+ yield* Effect.orElseSucceed(fs.makeDirectory(parent, { recursive: true }), () => undefined);
111
+ const body = JSON.stringify({ version: policy.version, identities: [...identities].sort((left, right) => left.localeCompare(right)) }, null, 2);
112
+ yield* Effect.orElseSucceed(fs.writeFileString(target, body), () => undefined);
113
+ return;
114
+ }
115
+ yield* Effect.orElseSucceed(fs.makeDirectory(target, { recursive: true }), () => undefined);
116
+ const desired = new Map();
117
+ for (const identity of identities)
118
+ desired.set(shortHash(identity) + ".json", identity);
119
+ const present = new Set(yield* fs.readDirectory(target).pipe(Effect.orElseSucceed(() => [])));
120
+ for (const [name, identity] of desired) {
121
+ if (!present.has(name)) {
122
+ yield* Effect.orElseSucceed(fs.writeFileString(path.join(target, name), JSON.stringify({ identity }, null, 2) + "\n"), () => undefined);
123
+ }
124
+ present.delete(name);
125
+ }
126
+ // What is left is an acceptance the run no longer makes: delete the file.
127
+ for (const name of present) {
128
+ if (!name.endsWith(".json"))
129
+ continue;
130
+ yield* Effect.orElseSucceed(fs.remove(path.join(target, name)), () => undefined);
131
+ }
132
+ });