@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
package/dist/schema.js ADDED
@@ -0,0 +1,285 @@
1
+ import { Schema } from "effect";
2
+ import { Move } from "./moves.js";
3
+ /* -------------------------------------------------------------------------- */
4
+ /* Diagnostics */
5
+ /* -------------------------------------------------------------------------- */
6
+ export const Severity = Schema.Literals(["error", "warn", "info"]);
7
+ /** A resolvable place in the source. `line` and `column` are 1-based. */
8
+ export const SourceLocation = Schema.Struct({
9
+ file: Schema.String,
10
+ line: Schema.Number,
11
+ column: Schema.Number,
12
+ endLine: Schema.optionalKey(Schema.Number),
13
+ endColumn: Schema.optionalKey(Schema.Number),
14
+ });
15
+ /**
16
+ * What a finding asks you to do.
17
+ *
18
+ * Five operations. A decline is not one of them: `no_issue` already exists as
19
+ * the way a question says "leave it", and a rule that finds nothing proposes
20
+ * nothing.
21
+ */
22
+ export const Operation = Schema.Literals(["merge", "split", "move", "replace", "migrate"]);
23
+ /** One place that must change, and what to do there. */
24
+ export const Edit = Schema.Struct({
25
+ file: Schema.String,
26
+ /** 1-based, like every other location in this program. */
27
+ line: Schema.Number,
28
+ column: Schema.Number,
29
+ /** One sentence a person or an agent can act on. */
30
+ instruction: Schema.String,
31
+ });
32
+ /**
33
+ * The smaller form, and everything that changes with it.
34
+ *
35
+ * The operation is settled by two estimators: a table in code, and the model's
36
+ * own read of the candidate. The cascade is never the model's -- a model that
37
+ * listed forty-seven call sites would invent them -- and neither is the set of
38
+ * operations on offer, which the import graph decides.
39
+ */
40
+ export const Repair = Schema.Struct({
41
+ operation: Operation,
42
+ /** The declaration that survives, when one does. */
43
+ keep: Schema.optionalKey(SourceLocation),
44
+ /** The declarations that go. */
45
+ remove: Schema.Array(SourceLocation),
46
+ /** The sites that must change, in the order they must change. */
47
+ cascade: Schema.Array(Edit),
48
+ /** True when every site is listed, so an agent needs no search of its own. */
49
+ complete: Schema.Boolean,
50
+ /** Why the operation settled where it did, in one sentence. */
51
+ settled: Schema.String,
52
+ });
53
+ /**
54
+ * The shape of the codebase, for the line a reader watches.
55
+ *
56
+ * A change that adds three declarations and one concept is healthy. A change
57
+ * that adds three declarations and no concept is pure entropy, and that is the
58
+ * number worth putting in front of a person.
59
+ */
60
+ export const Structure = Schema.Struct({
61
+ /** Distinct declared names, as the index counts them. */
62
+ concepts: Schema.Number,
63
+ declarations: Schema.Number,
64
+ /** Declarations sharing a name with another declaration. */
65
+ duplicated: Schema.Number,
66
+ /** Names resolving to more than one type. */
67
+ overloaded: Schema.Number,
68
+ });
69
+ /** One question's answer, as the panel shows it. */
70
+ export const PanelAnswer = Schema.Struct({
71
+ question: Schema.String,
72
+ label: Schema.optionalKey(Schema.String),
73
+ probability: Schema.optionalKey(Schema.Number),
74
+ });
75
+ /**
76
+ * The judgement behind one finding, carried through to the consumer.
77
+ *
78
+ * The blog's observability argument is that "the model chose fraud_team" is not
79
+ * an explanation -- "these six judgements, and the logic path that followed" is.
80
+ * A finding has always carried one confidence and a score; this carries every
81
+ * question that was asked, what it answered, the operation the model proposed,
82
+ * the one the table derived, and whether they agreed. Optional, so an old
83
+ * baseline or a committed answer still decodes.
84
+ */
85
+ export const JudgementPanel = Schema.Struct({
86
+ answers: Schema.Array(PanelAnswer),
87
+ operation: Schema.optionalKey(Schema.String),
88
+ derived: Schema.optionalKey(Schema.String),
89
+ agreement: Schema.optionalKey(Schema.String),
90
+ });
91
+ /**
92
+ * The only thing joggle produces. Everything else -- scanning, candidate
93
+ * generation, judgement -- exists to manufacture one of these, in the same
94
+ * shape a linter or a typechecker emits so that hosts do not have to care
95
+ * which kind of rule produced it.
96
+ */
97
+ export const Diagnostic = Schema.Struct({
98
+ ruleId: Schema.String,
99
+ severity: Severity,
100
+ /**
101
+ * Which entropy reversal this finding proposes, when it proposes one.
102
+ *
103
+ * On the finding rather than only on the rule, because one rule can propose
104
+ * more than one: `compose-types` reports advice to combine and a name
105
+ * contradiction to expand. Absent means the rule is not about entropy.
106
+ */
107
+ move: Schema.optionalKey(Move),
108
+ message: Schema.String,
109
+ help: Schema.optionalKey(Schema.String),
110
+ location: SourceLocation,
111
+ /**
112
+ * Present only when a judgement produced this diagnostic. Absent means the
113
+ * rule was deterministic, which is itself useful information for a reader.
114
+ */
115
+ confidence: Schema.optionalKey(Schema.Number),
116
+ /**
117
+ * How strongly the judgement says this is real, as a Noul probability. Unlike
118
+ * `confidence` (which summarises how peaked the Choice distribution was, and
119
+ * measured uninformative) this is comparable across every finding in a run,
120
+ * so it is what the report sorts by.
121
+ */
122
+ score: Schema.optionalKey(Schema.Number),
123
+ /**
124
+ * A stable name for this finding, for comparing runs.
125
+ *
126
+ * Built from the rule and the cluster's membership, never from line numbers:
127
+ * code moves constantly, and a baseline that reports every edit as a new
128
+ * finding is a baseline nobody reads. A rename or a new member does change it,
129
+ * which is correct -- the finding is a different finding then.
130
+ */
131
+ identity: Schema.optionalKey(Schema.String),
132
+ judged: Schema.Boolean,
133
+ /** The questions behind this finding, when a judgement produced it. */
134
+ panel: Schema.optionalKey(JudgementPanel),
135
+ /**
136
+ * The stage of the reversal a site stopped at.
137
+ *
138
+ * `contract` is a copy of a primitive, `combine` is a combination never
139
+ * written, `expand` is vocabulary that has to grow. Present only for a staged
140
+ * finding: the moves are a sequence, and the first stage that answers is the
141
+ * one a reader should act on.
142
+ */
143
+ stoppedAt: Schema.optionalKey(Schema.Literals(["contract", "combine", "expand"])),
144
+ /**
145
+ * The smaller form this finding proposes, when the rule can propose one.
146
+ *
147
+ * Absent means the finding is an observation: a rule that only warns, or a
148
+ * candidate whose operation the graph does not permit. A host that ignores
149
+ * this field still gets a working linter.
150
+ */
151
+ repair: Schema.optionalKey(Repair),
152
+ });
153
+ /** A rule id and a reason: a skip, or a bound a rule hit. */
154
+ export const Note = Schema.Struct({
155
+ ruleId: Schema.String,
156
+ reason: Schema.String,
157
+ });
158
+ /**
159
+ * How a candidate ended up not being reported.
160
+ *
161
+ * Every bound and every gate in this program is a decision not to look at
162
+ * something or not to say it, and a decision nobody can see is indistinguishable
163
+ * from a bug: the eighteen definitions of one helper stayed invisible for three
164
+ * runs because a cap discarded them silently.
165
+ *
166
+ * The stages are a closed set on purpose, so counts mean the same thing in every
167
+ * rule. A candidate that failed a gate and one that was never looked at are
168
+ * different facts, and mixing them into one number would hide exactly the
169
+ distinction worth seeing.
170
+ */
171
+ export const DropStage = Schema.Literals([
172
+ /** The model declined: it looked and found nothing. */
173
+ "declined",
174
+ /** The answer failed a gate. */
175
+ "gated",
176
+ /** No usable answer came back for this candidate. */
177
+ "unreadable",
178
+ /** The rule never asked: there was nothing to send. */
179
+ "no_evidence",
180
+ /** The run's budget ran out before this candidate. */
181
+ "budget",
182
+ ]);
183
+ export const Drop = Schema.Struct({
184
+ ruleId: Schema.String,
185
+ /** The candidate, named the way the rule names it. */
186
+ subject: Schema.String,
187
+ stage: DropStage,
188
+ /** Why, in the rule's own words. */
189
+ reason: Schema.String,
190
+ });
191
+ export const DecisionTotals = Schema.Struct({
192
+ requests: Schema.Number,
193
+ replayed: Schema.Number,
194
+ calls: Schema.Number,
195
+ unavailable: Schema.Number,
196
+ inputTokens: Schema.Number,
197
+ outputTokens: Schema.Number,
198
+ });
199
+ /**
200
+ * The previous run, kept whole so an unchanged repository costs nothing.
201
+ *
202
+ * `manifest` is a hash of everything the output depends on: the analysis and
203
+ * question versions, the model, the rule set, and the content of every analysed
204
+ * file. If it matches, the run is over before a single file is parsed.
205
+ */
206
+ export const StoredRun = Schema.Struct({
207
+ version: Schema.String,
208
+ manifest: Schema.String,
209
+ diagnostics: Schema.Array(Diagnostic),
210
+ /**
211
+ * Content hash per analysed file, so the NEXT run can say which files moved.
212
+ *
213
+ * The manifest says whether anything changed; this says what did, which is
214
+ * what lets a run scope itself to the change instead of re-deriving findings
215
+ * about code nobody touched.
216
+ */
217
+ sources: Schema.Array(Schema.Struct({
218
+ path: Schema.String,
219
+ hash: Schema.String,
220
+ /**
221
+ * Exported names, so the next run can tell a body edit from an interface
222
+ * edit: only the latter can move what a dependent's type names resolve to.
223
+ */
224
+ exports: Schema.Array(Schema.String),
225
+ })),
226
+ files: Schema.Number,
227
+ rules: Schema.Number,
228
+ /**
229
+ * The shape of the codebase this run measured.
230
+ *
231
+ * Optional so a run stored before this existed still replays, and so a replayed
232
+ * report can say it does not know rather than print a zero that looks measured.
233
+ */
234
+ structure: Schema.optionalKey(Structure),
235
+ skipped: Schema.Array(Note),
236
+ notes: Schema.Array(Note),
237
+ /**
238
+ * Candidates this run considered and did not report, with the reason.
239
+ *
240
+ * Optional so a run stored before this existed still replays: reading
241
+ * defensively and writing strictly is what keeps a cache an optimisation
242
+ * rather than a compatibility problem.
243
+ */
244
+ drops: Schema.optionalKey(Schema.Array(Drop)),
245
+ decision: DecisionTotals,
246
+ elapsedMs: Schema.Number,
247
+ });
248
+ /**
249
+ * The findings a repository has already accepted, so a later run can report
250
+ * only what changed. Committed on purpose: the point is to compare against a
251
+ * baseline that lives in the repository, not one that lives in a cache.
252
+ */
253
+ export const Baseline = Schema.Struct({
254
+ version: Schema.String,
255
+ identities: Schema.Array(Schema.String),
256
+ });
257
+ /* -------------------------------------------------------------------------- */
258
+ /* Typed errors */
259
+ /* -------------------------------------------------------------------------- */
260
+ export class WorkspaceError extends Schema.TaggedError()("joggle/WorkspaceError", {
261
+ path: Schema.String,
262
+ operation: Schema.String,
263
+ cause: Schema.Defect(),
264
+ }) {
265
+ }
266
+ export class TsgoError extends Schema.TaggedError()("joggle/TsgoError", {
267
+ operation: Schema.String,
268
+ detail: Schema.String,
269
+ }) {
270
+ }
271
+ export class GitError extends Schema.TaggedError()("joggle/GitError", {
272
+ operation: Schema.String,
273
+ detail: Schema.String,
274
+ }) {
275
+ }
276
+ /**
277
+ * A rule reported a message its own registry does not declare, or a template hole
278
+ * it gave no data for. That is a bug in the rule, not in the code under analysis.
279
+ */
280
+ export class RuleAuthoringError extends Schema.TaggedError()("joggle/RuleAuthoringError", {
281
+ ruleId: Schema.String,
282
+ messageId: Schema.String,
283
+ detail: Schema.String,
284
+ }) {
285
+ }
@@ -0,0 +1,119 @@
1
+ /*
2
+ * Shingle sets, Jaccard similarity, and the all-pairs join that uses them.
3
+ *
4
+ * This module exists because the join and the similarity it verifies with have
5
+ * to agree on what a set is. Splitting them across two files is how you end up
6
+ * with a candidate generator and a scorer that disagree about the answer.
7
+ */
8
+ /** Token bigrams, the unit of comparison between two declarations. */
9
+ export const shinglesOf = (tokens) => {
10
+ const set = new Set();
11
+ for (let index = 0; index < tokens.length - 1; index += 1) {
12
+ set.add(`${tokens[index]}\u0000${tokens[index + 1]}`);
13
+ }
14
+ return set;
15
+ };
16
+ /**
17
+ * Jaccard similarity over two shingle sets.
18
+ *
19
+ * Iterates the smaller side: an intersection cannot be larger than it, and for
20
+ * the size-skewed pairs a threshold admits, that is most of the work saved.
21
+ */
22
+ export const similarityOf = ({ left, right, }) => {
23
+ const [small, large] = left.size <= right.size ? [left, right] : [right, left];
24
+ if (small.size === 0)
25
+ return left.size === right.size ? 1 : 0;
26
+ let intersection = 0;
27
+ for (const shingle of small)
28
+ if (large.has(shingle))
29
+ intersection += 1;
30
+ const union = left.size + right.size - intersection;
31
+ return union === 0 ? 0 : intersection / union;
32
+ };
33
+ /** Convenience for callers holding tokens rather than shingle sets. */
34
+ export const similarity = ({ left, right, }) => similarityOf({ left: shinglesOf(left), right: shinglesOf(right) });
35
+ /**
36
+ * Every pair at or above a Jaccard threshold, without comparing every pair.
37
+ *
38
+ * What this replaces compared every pair inside a size window: 3,280,085
39
+ * comparisons for 7,034 declarations on one codebase, and that count grows as
40
+ * n x window -- so ten times the code costs a hundred times the work. This
41
+ * finds the same pairs while only scoring sets that share a rare shingle.
42
+ *
43
+ * The guarantee, for threshold t with shingles ordered by ascending document
44
+ * frequency: if J(A, B) >= t and |A| <= |B|, then |A n B| >= t|A|. A's prefix
45
+ * excludes only ceil(t|A|) - 1 shingles, fewer than t|A|, so at least one shared
46
+ * shingle must lie in A's prefix. Index prefixes, probe whole sets, and no
47
+ * qualifying pair can be missed. A differential test asserts that this finds
48
+ * exactly what the brute-force sweep in rule.ts finds.
49
+ */
50
+ export const allPairs = (entries, threshold) => {
51
+ if (threshold <= 0)
52
+ return [];
53
+ const frequency = new Map();
54
+ for (const entry of entries) {
55
+ for (const shingle of entry.shingles) {
56
+ frequency.set(shingle, (frequency.get(shingle) ?? 0) + 1);
57
+ }
58
+ }
59
+ // Rarest first, so a prefix holds the most discriminating shingles and the
60
+ // posting lists it produces stay short.
61
+ const rank = new Map();
62
+ [...frequency.entries()]
63
+ .sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1))
64
+ .forEach(([shingle], position) => rank.set(shingle, position));
65
+ const prefixes = entries.map((entry) => {
66
+ const sorted = [...entry.shingles].sort((a, b) => (rank.get(a) ?? 0) - (rank.get(b) ?? 0));
67
+ const keep = Math.max(1, sorted.length - Math.ceil(threshold * sorted.length) + 1);
68
+ return sorted.slice(0, keep);
69
+ });
70
+ const order = entries
71
+ .map((entry, position) => ({ size: entry.shingles.size, slot: position, callerIndex: entry.position }))
72
+ .filter((entry) => entry.size > 0)
73
+ .sort((a, b) => a.size - b.size || a.callerIndex - b.callerIndex);
74
+ const postings = new Map();
75
+ const pairs = [];
76
+ for (const current of order) {
77
+ const entry = entries[current.slot];
78
+ if (entry === undefined)
79
+ continue;
80
+ // Probe with the whole set. Only prefixes were indexed, and the argument
81
+ // above says the shared shingle lies in the smaller side's prefix -- which
82
+ // is already indexed, because the smaller side is always processed first.
83
+ const seen = new Set();
84
+ for (const shingle of entry.shingles) {
85
+ const list = postings.get(shingle);
86
+ if (list === undefined)
87
+ continue;
88
+ for (const other of list) {
89
+ if (other === current.slot || seen.has(other))
90
+ continue;
91
+ seen.add(other);
92
+ const candidate = entries[other];
93
+ if (candidate === undefined)
94
+ continue;
95
+ // Exact size filter: Jaccard cannot exceed the ratio of the smaller side
96
+ // to the larger, so a pair outside it cannot qualify.
97
+ if (candidate.shingles.size < threshold * entry.shingles.size)
98
+ continue;
99
+ const score = similarityOf({ left: candidate.shingles, right: entry.shingles });
100
+ if (score < threshold)
101
+ continue;
102
+ const left = candidate.position;
103
+ const right = entry.position;
104
+ pairs.push(left <= right ? { left, right, score } : { left: right, right: left, score });
105
+ }
106
+ }
107
+ const prefix = prefixes[current.slot];
108
+ if (prefix === undefined)
109
+ continue;
110
+ for (const shingle of prefix) {
111
+ const list = postings.get(shingle);
112
+ if (list === undefined)
113
+ postings.set(shingle, [current.slot]);
114
+ else
115
+ list.push(current.slot);
116
+ }
117
+ }
118
+ return pairs;
119
+ };
package/dist/source.js ADDED
@@ -0,0 +1,30 @@
1
+ /**
2
+ * What counts as source.
3
+ *
4
+ * This used to be TypeScript only, and it was never a decision: the extension
5
+ * list arrived with the first rebuild and nobody revisited it. On one real
6
+ * repository that meant 1,457 JavaScript files -- an entire API and an entire
7
+ * admin UI -- were never read, while the report said "287 files" with no hint
8
+ * that four fifths of the tree was missing. A partial analysis that looks
9
+ * complete is the worst output this program can produce.
10
+ *
11
+ * Both discovery paths ask this -- the directory walk and the compiler's file
12
+ * list -- so a run with paths and a run without cannot disagree about what is
13
+ * source.
14
+ *
15
+ * Declarations stay out: a `.d.ts` describes a build's output rather than a
16
+ * source file, and analysing one reports on code nobody wrote. `.astro` files
17
+ * count: their frontmatter and scripts are TypeScript, read through `astro.ts`.
18
+ *
19
+ * A content mapper's declaration output has a second shape: `App.d.svelte.ts`
20
+ * for `App.svelte`, `Page.d.vue.ts` for `Page.vue`. It ends in `.ts`, so the
21
+ * `.d.ts` check above misses it, and analysing it reports the mapper's
22
+ * scaffolding as if an author had written it.
23
+ */
24
+ export const looksLikeSource = (file) => {
25
+ if (file.endsWith(".d.ts") || file.endsWith(".d.mts") || file.endsWith(".d.cts"))
26
+ return false;
27
+ if (/\.d\.[a-z0-9]+\.ts$/iu.test(file))
28
+ return false;
29
+ return /\.(?:[cm]?[jt]sx?|astro)$/.test(file);
30
+ };
package/dist/sql.js ADDED
@@ -0,0 +1,34 @@
1
+ /** `builder('table').method(...)` -- Knex and its clones. */
2
+ const CHAINED_CALL = /\b[A-Za-z_$][\w$]*\s*\(\s*(['"`])([A-Za-z_$][\w$.]*)\1\s*\)\s*\.\s*([A-Za-z_$][\w$]*)\b/gu;
3
+ /** A table named by a builder call: `knex('payroll')`, `trx('ledger')`. */
4
+ const BUILDER_TABLE = /\b[A-Za-z_$][\w$]*\s*\(\s*(['"`])([A-Za-z_$][\w$.]*)\1\s*\)/gu;
5
+ /** A table named by a `.from(...)`. */
6
+ const FROM_TABLE = /\.\s*from\s*\(\s*(?:['"`]([A-Za-z_$][\w$.]*)['"`]|([A-Za-z_$][\w$]*))\s*\)/gu;
7
+ /** Every table call in a file, in source order. */
8
+ export const queryCallsIn = (text) => {
9
+ const found = [];
10
+ for (const match of text.matchAll(CHAINED_CALL)) {
11
+ const table = match[2];
12
+ const method = match[3];
13
+ const start = match.index;
14
+ if (table === undefined || method === undefined || start === undefined)
15
+ continue;
16
+ found.push({ table, method, start });
17
+ }
18
+ return found.sort((left, right) => left.start - right.start);
19
+ };
20
+ /** Every table a file names as a read, deduplicated. */
21
+ export const readsIn = (text) => {
22
+ const tables = new Set();
23
+ for (const match of text.matchAll(BUILDER_TABLE)) {
24
+ const table = match[2];
25
+ if (table !== undefined)
26
+ tables.add(table);
27
+ }
28
+ for (const match of text.matchAll(FROM_TABLE)) {
29
+ const table = match[1] ?? match[2];
30
+ if (table !== undefined)
31
+ tables.add(table);
32
+ }
33
+ return [...tables];
34
+ };
package/dist/stages.js ADDED
@@ -0,0 +1,39 @@
1
+ import { Schema } from "effect";
2
+ import { Move } from "./moves.js";
3
+ /*
4
+ * The reversal, as a sequence of stages rather than separate scanners.
5
+ *
6
+ * `contract` is a copy of a primitive that already exists; `combine` is a
7
+ * combination of primitives that was never written; `expand` is a concept the
8
+ * vocabulary has no name for. The order is the thesis: nothing is legible until
9
+ * the duplicates are gone, nothing can be composed until the primitives are
10
+ * legible, and a new primitive has to be built out of the ones you can now see.
11
+ *
12
+ * A site walks the stages in order, and the first stage that answers is the one
13
+ * finding it gets. That is what makes the report a decision path rather than
14
+ * three rules disagreeing about the same declaration.
15
+ */
16
+ /** What one earlier stage said about this site. It is part of the next state. */
17
+ export const StageOutcome = Schema.Struct({
18
+ stage: Move,
19
+ outcome: Schema.String,
20
+ });
21
+ /**
22
+ * The state every staged question carries: its own panel, the stage it is, and
23
+ * what the earlier stages said.
24
+ *
25
+ * The earlier outcomes are in the state on purpose. A judgement asked at stage 3
26
+ * with no knowledge of why stages 1 and 2 declined is a judgement about a
27
+ * different question, and the answer cache keys on the state, so a site that
28
+ * stopped at `combine` and a site that fell through to `expand` can never
29
+ * share an answer.
30
+ *
31
+ * The panel schema is passed in rather than made generic at the call site: the
32
+ * definition is built by the rule with its own concrete schema, so the state the
33
+ * model validates is exactly the panel the rule sent.
34
+ */
35
+ export const stagedInput = (panel) => Schema.Struct({
36
+ stage: Move,
37
+ earlier: Schema.Array(StageOutcome),
38
+ panel,
39
+ });
package/dist/state.js ADDED
@@ -0,0 +1,65 @@
1
+ import { Config, Effect, FileSystem, Option, Path } from "effect";
2
+ import { createHash } from "node:crypto";
3
+ import { homedir } from "node:os";
4
+ /*
5
+ * Where joggle's state lives, and how it is read back.
6
+ *
7
+ * Three artifacts, three lifecycles:
8
+ *
9
+ * <root>/.joggle/answers/ reviewed, committed, replayed by CI: sharded
10
+ * <root>/.joggle/baseline/ reviewed, committed: the ratchet, as fragments
11
+ * <machine cache>/joggle/<root>/ ephemeral, machine-local, never committed
12
+ *
13
+ * The first two belong to the repository, because they are decisions a person
14
+ * should be able to read in a diff and because CI replays them with no API key.
15
+ * Both are directories of small files -- one shard of answers, one fragment per
16
+ * accepted finding -- so that two branches write different files rather than the
17
+ * same one. The third is a performance artifact -- a manifest, the last report,
18
+ * and the per-file facts -- and it belongs to the machine: it is the largest, it
19
+ * churns on every edit, and writing it into a working tree means analysing
20
+ * someone else's checkout leaves litter in it. `docs/artifacts.md` is the long
21
+ * form.
22
+ *
23
+ * One machine cache serves every repository, keyed by the analysed root, so
24
+ * pointing joggle at any number of checkouts costs no per-repo setup and writes
25
+ * nothing into them.
26
+ */
27
+ /** A short content hash, used for cache keys and manifests. */
28
+ export const shortHash = (value) => createHash("sha1").update(value).digest("hex").slice(0, 16);
29
+ /** The per-machine cache root, following the platform's convention. */
30
+ export const machineCacheRoot = Effect.gen(function* () {
31
+ // A host such as pi can run with no HOME. Fall back to the passwd database,
32
+ // never to ".", because a relative root puts the cache inside the analysed
33
+ // repository -- the one place this file exists to keep it out of.
34
+ const home = yield* Config.String("HOME").pipe(Effect.orElseSucceed(() => homedir()));
35
+ const xdg = yield* Config.option(Config.String("XDG_CACHE_HOME")).pipe(Effect.orElseSucceed(() => Option.none()));
36
+ const root = Option.getOrUndefined(xdg);
37
+ if (root !== undefined && root !== "")
38
+ return root;
39
+ return process.platform === "darwin" ? `${home}/Library/Caches` : `${home}/.cache`;
40
+ }).pipe(Effect.orElseSucceed(() => homedir()));
41
+ /** A machine-local directory for one analysed root. */
42
+ export const runCacheDirFor = (root) => Effect.map(machineCacheRoot, (base) => `${base}/joggle/${shortHash(root)}`);
43
+ /**
44
+ * Where a run's answer cache goes.
45
+ *
46
+ * Explicit wins. Otherwise a repository that already has a `.joggle/` is one
47
+ * being onboarded -- its cache is a committed artifact and that is where it
48
+ * lives -- and any other checkout is one being visited, so the cache is
49
+ * machine-local and nothing is written into it. This is the rule the pi
50
+ * extension has always applied; the CLI applies it too, so the two agree and a
51
+ * tool run never litters a checkout it does not own.
52
+ *
53
+ * @param cwd - The analysed root.
54
+ * @param explicit - The value of `--cache-dir`, if given.
55
+ * @returns The directory holding `answers/`.
56
+ */
57
+ export const cacheDirFor = (cwd, explicit) => Effect.gen(function* () {
58
+ if (explicit !== undefined)
59
+ return explicit;
60
+ const fs = yield* FileSystem.FileSystem;
61
+ const path = yield* Path.Path;
62
+ const local = path.join(cwd, ".joggle");
63
+ const onboarded = yield* fs.exists(local).pipe(Effect.orElseSucceed(() => false));
64
+ return onboarded ? local : yield* runCacheDirFor(cwd);
65
+ });