@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/ask.js ADDED
@@ -0,0 +1,184 @@
1
+ import { Effect, Result, Schema } from "effect";
2
+ import * as AiError from "effect/ai/AiError";
3
+ import { Decision, DecisionModel } from "effect/ai";
4
+ import { isUnreachable } from "./decision.js";
5
+ import { policy } from "./policy.js";
6
+ /**
7
+ * Semantic search over the declarations, in one request.
8
+ *
9
+ * The pattern is TypeSafe's line-by-line search: put the query and the candidates
10
+ * in the state, ask one Choice over the candidates so the whole probability
11
+ * distribution is a ranking rather than a single winner, and ask one Noul for the
12
+ * absolute question the Choice cannot answer -- does this codebase answer at all.
13
+ * A Choice is relative (which of these) and a Noul is absolute (is there one), so
14
+ * the two together separate "nothing here" from "the best of a bad set".
15
+ *
16
+ * The candidates are prefiltered in code by keyword overlap. That is not a
17
+ * judgement, it is a state bound: the model reads worse as unrelated state grows,
18
+ * so the query never sees the whole workspace.
19
+ */
20
+ const AskEvidence = Schema.Struct({
21
+ query: Schema.String,
22
+ candidates: Schema.Array(Schema.Struct({
23
+ symbol: Schema.String,
24
+ kind: Schema.String,
25
+ path: Schema.String,
26
+ source: Schema.String,
27
+ /**
28
+ * The compiler's resolved type, when the run asked for a trace. Absent
29
+ * otherwise, so the request a run without `--types` sends is byte-identical
30
+ * to the one it always sent.
31
+ */
32
+ resolved: Schema.optionalKey(Schema.String),
33
+ })),
34
+ });
35
+ const existsDecision = Decision.probability({
36
+ instructions: [
37
+ "Does any declaration in `candidates` answer the question in `query`?",
38
+ "Answer about the code's meaning, not the words: a declaration answers the question when its behaviour or purpose is what the question asks about.",
39
+ "Answer true when at least one declaration answers it, however imperfectly. Answer false when the question is about something this code does not do.",
40
+ ].join("\n"),
41
+ criteria: {
42
+ false: "No declaration answers the question.",
43
+ true: "At least one declaration answers the question.",
44
+ },
45
+ });
46
+ /**
47
+ * One Noul per candidate, not one Choice over all of them.
48
+ *
49
+ * A Choice is relative and, over a couple of hundred options, it concentrates:
50
+ * one option takes almost all the probability and the rest go to zero, so it
51
+ * names a winner but not a ranking. A Noul is absolute -- "is THIS one relevant?"
52
+ * -- so every candidate gets a comparable score and the sort is a real ordering.
53
+ * The `exists` Noul keeps the absolute question the per-candidate ones cannot
54
+ * answer: whether the codebase answers at all.
55
+ */
56
+ const relevanceInstructions = (index) => [
57
+ "Is `candidates[" + index + "]` relevant to the question in `query`?",
58
+ "Answer about what the declaration DOES, not whether its name shares words with the question.",
59
+ "Answer true when a reader asking the question would want to read this declaration. Answer false for a declaration that merely mentions a related word.",
60
+ ].join("\n");
61
+ /** The candidates, ordered by keyword overlap so the state bound keeps the likely ones. */
62
+ const candidatesIn = (workspace, query) => {
63
+ const words = query
64
+ .toLowerCase()
65
+ .split(/[^a-z0-9]+/)
66
+ .filter((word) => word.length > 2);
67
+ const scored = workspace.units
68
+ .filter((unit) => unit.tokens.length >= policy.ask.minTokens)
69
+ .map((unit) => {
70
+ const haystack = (unit.name + " " + unit.file + " " + unit.text).toLowerCase();
71
+ const overlap = words.filter((word) => haystack.includes(word)).length;
72
+ return { unit, overlap };
73
+ })
74
+ .filter((entry) => words.length === 0 || entry.overlap > 0)
75
+ .sort((left, right) => right.overlap - left.overlap || left.unit.file.localeCompare(right.unit.file));
76
+ return scored.slice(0, policy.ask.maxCandidates).map((entry) => entry.unit);
77
+ };
78
+ /** One candidate as the model sees it, with the compiler's answer when there is one. */
79
+ const candidateEvidence = (unit) => {
80
+ const evidence = {
81
+ symbol: unit.name,
82
+ kind: unit.kind,
83
+ path: unit.file,
84
+ source: unit.text.slice(0, policy.ask.maxSourceChars),
85
+ };
86
+ const facts = unit.typeFacts;
87
+ if (facts === undefined)
88
+ return evidence;
89
+ return { ...evidence, resolved: facts.display };
90
+ };
91
+ /**
92
+ * Answer a question about the code.
93
+ *
94
+ * A request carries one decision per candidate, so its output grows with the
95
+ * candidate list and a whole-repository ask can exceed the provider's token
96
+ * ceiling. Two bounds keep that from being fatal: the candidate list is trimmed
97
+ * to the input budget before the request, and a request that still comes back
98
+ * too large is halved and retried -- the same degradation `check` uses for its
99
+ * chunks. Narrowing the paths remains the best answer, and is what the error
100
+ * says when even one candidate does not fit.
101
+ *
102
+ * @param workspace - The loaded workspace.
103
+ * @param query - The question, in plain language.
104
+ * @param options - The input-token budget for the request.
105
+ * @returns The existence probability and the ranked matches.
106
+ */
107
+ export const ask = (workspace, query, options = {}) => Effect.gen(function* () {
108
+ const budget = options.maxInputTokens ?? policy.ask.maxInputTokens;
109
+ const candidates = fitToBudget(candidatesIn(workspace, query), query, budget);
110
+ if (candidates.length === 0)
111
+ return { exists: 0, matches: [], considered: 0 };
112
+ const attempt = (list) => Effect.gen(function* () {
113
+ const decisions = [
114
+ ["exists", existsDecision],
115
+ ...list.map((_unit, index) => [
116
+ `candidate_${index}`,
117
+ Decision.probability({
118
+ instructions: relevanceInstructions(index),
119
+ criteria: {
120
+ false: "It does not answer the question.",
121
+ true: "It answers the question.",
122
+ },
123
+ }),
124
+ ]),
125
+ ];
126
+ const definition = Decision.make({ input: AskEvidence, decisions: Object.fromEntries(decisions) });
127
+ const decided = yield* DecisionModel.decide(definition, {
128
+ input: {
129
+ query,
130
+ candidates: list.map((unit) => candidateEvidence(unit)),
131
+ },
132
+ });
133
+ return { decided, list };
134
+ });
135
+ // Cut and retry. A model that was never reached is not a bad answer, so it
136
+ // is not retried; a request the provider rejected as too large is.
137
+ const attemptWithinBudget = () => Effect.gen(function* () {
138
+ let list = candidates;
139
+ for (;;) {
140
+ const outcome = yield* Effect.result(attempt(list));
141
+ if (Result.isSuccess(outcome))
142
+ return outcome.success;
143
+ if (list.length <= 1 || isUnreachable(outcome.failure)) {
144
+ return yield* outcome.failure;
145
+ }
146
+ list = list.slice(0, Math.max(1, Math.ceil(list.length / 2)));
147
+ }
148
+ });
149
+ const answered = yield* attemptWithinBudget();
150
+ const exists = answered.decided.answers["exists"];
151
+ const probability = exists !== undefined && "probability" in exists ? exists.probability : 0;
152
+ const matches = answered.list
153
+ .map((unit, index) => {
154
+ const answer = answered.decided.answers[`candidate_${index}`];
155
+ return {
156
+ symbol: unit.name,
157
+ symbolKind: unit.kind,
158
+ file: unit.file,
159
+ line: unit.location.line,
160
+ confidence: answer !== undefined && "probability" in answer ? answer.probability : 0,
161
+ };
162
+ })
163
+ .sort((left, right) => right.confidence - left.confidence)
164
+ .slice(0, policy.ask.top);
165
+ return { exists: probability, matches, considered: answered.list.length };
166
+ });
167
+ /**
168
+ * Keep the candidates whose evidence fits the input budget, in rank order.
169
+ *
170
+ * The estimate is the same characters-over-four the check budget uses, and the
171
+ * first candidate is always kept so a tiny budget still asks something.
172
+ */
173
+ const fitToBudget = (candidates, query, budget) => {
174
+ const kept = [];
175
+ let chars = query.length;
176
+ for (const unit of candidates) {
177
+ const cost = Math.min(unit.text.length, policy.ask.maxSourceChars) + unit.name.length + unit.file.length;
178
+ if (kept.length > 0 && Math.ceil((chars + cost) / 4) > budget)
179
+ break;
180
+ kept.push(unit);
181
+ chars += cost;
182
+ }
183
+ return kept;
184
+ };
package/dist/astro.js ADDED
@@ -0,0 +1,75 @@
1
+ const OPENING_FENCE = /^\s*---[ \t]*\r?\n/;
2
+ const CLOSING_FENCE = /^---[ \t]*\r?$/m;
3
+ const SCRIPT = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
4
+ const TYPE = /\btype\s*=\s*["']?([^"'\s>]+)/i;
5
+ const READABLE_TYPES = new Set(["module", "text/javascript", "application/javascript"]);
6
+ /** Whether a script's attributes say its content is code joggle should read. */
7
+ const readableScript = (attributes) => {
8
+ if (/\bset:(?:html|text)\b/.test(attributes))
9
+ return false;
10
+ const type = TYPE.exec(attributes)?.[1];
11
+ return type === undefined || READABLE_TYPES.has(type.toLowerCase());
12
+ };
13
+ /**
14
+ * The frontmatter's content, then each readable script's content.
15
+ *
16
+ * The frontmatter only counts at the top of the file, as Astro reads it, so a
17
+ * `---` further down is template text. Scripts are searched for after the
18
+ * frontmatter: a `<script>` string inside the frontmatter is TypeScript.
19
+ */
20
+ export const astroRegions = (text) => {
21
+ const regions = [];
22
+ let templateStart = 0;
23
+ const opening = OPENING_FENCE.exec(text);
24
+ if (opening !== null) {
25
+ const start = opening[0].length;
26
+ const closing = CLOSING_FENCE.exec(text.slice(start));
27
+ if (closing !== null) {
28
+ regions.push({ start, end: start + closing.index });
29
+ templateStart = start + closing.index + closing[0].length;
30
+ }
31
+ }
32
+ for (const match of text.slice(templateStart).matchAll(SCRIPT)) {
33
+ const attributes = match[1] ?? "";
34
+ const content = match[2] ?? "";
35
+ if (!readableScript(attributes))
36
+ continue;
37
+ const start = templateStart + match.index + match[0].indexOf(">") + 1;
38
+ regions.push({ start, end: start + content.length });
39
+ }
40
+ return regions;
41
+ };
42
+ /** The file with every character outside the regions a space, and every newline kept. */
43
+ export const blankOutside = (text, regions) => {
44
+ const blank = (from, to) => text.slice(from, to).replace(/[^\r\n]/g, " ");
45
+ let out = "";
46
+ let cursor = 0;
47
+ for (const region of regions) {
48
+ out += blank(cursor, region.start) + text.slice(region.start, region.end);
49
+ cursor = region.end;
50
+ }
51
+ return out + blank(cursor, text.length);
52
+ };
53
+ /**
54
+ * The name Astro gives a component: its file's, as an identifier.
55
+ *
56
+ * Every component declares `interface Props`, and Astro reads it by that name,
57
+ * so it is never imported elsewhere. Thirty-five units all called `Props` read
58
+ * to the name rules as one concept spelled thirty-five times.
59
+ */
60
+ export const componentName = (file) => {
61
+ const base = (file.split("/").at(-1) ?? file).replace(/\.astro$/, "");
62
+ const words = base.replace(/[^A-Za-z0-9]+(.)?/g, (_, next) => (next ?? "").toUpperCase());
63
+ return words.charAt(0).toUpperCase() + words.slice(1);
64
+ };
65
+ /** A path to an Astro component or page. */
66
+ export const isAstro = (file) => file.endsWith(".astro");
67
+ /** What the parser reads for a file: the blanked copy for `.astro`, the text otherwise. */
68
+ export const parseInputOf = ({ file, text }) => isAstro(file) ? blankOutside(text, astroRegions(text)) : text;
69
+ /**
70
+ * oxc's message for a `return` outside a function. Astro frontmatter may
71
+ * `return Astro.redirect(...)`, and oxc still returns the whole tree with it.
72
+ */
73
+ const TOP_LEVEL_RETURN = "A 'return' statement can only be used within a function body.";
74
+ /** The errors that make a parse unusable: for `.astro`, all but a top-level `return`. */
75
+ export const blockingErrors = (file, errors) => (isAstro(file) ? errors.filter((error) => error.message !== TOP_LEVEL_RETURN) : errors);
package/dist/atoms.js ADDED
@@ -0,0 +1,76 @@
1
+ import { Context, Effect, Layer, Ref, Schema } from "effect";
2
+ import { canonical } from "./canonical.js";
3
+ import { shortHash } from "./state.js";
4
+ /**
5
+ * The id of a fact: its content, hashed.
6
+ *
7
+ * Content-addressed rather than positional, and that is the whole point. The same
8
+ * declaration is the same atom in every rule and every run, so two rules that
9
+ * judge it send it once, and a question's answer can be cached against the atoms
10
+ * it referenced rather than against whichever request happened to carry them.
11
+ *
12
+ * A positional id (`a0`, `a1`) would make the id depend on the order rules ran,
13
+ * which is exactly the instability a cache cannot survive.
14
+ */
15
+ export const atomId = (value) => "a" + shortHash(canonical(value));
16
+ /**
17
+ * One declaration offered to the model, bounded.
18
+ *
19
+ * The same four fields every rule sends when it names a member: which
20
+ * declaration, where, and a slice of its source. Declared as a Schema so it is
21
+ * JSON by construction -- an atom's value must be.
22
+ */
23
+ export const CandidateSample = Schema.Struct({
24
+ name: Schema.String,
25
+ file: Schema.String,
26
+ line: Schema.Finite,
27
+ source: Schema.String,
28
+ });
29
+ /**
30
+ * The shared facts a run's questions are built from.
31
+ *
32
+ * One store for the whole run, so every rule derives a declaration's state from
33
+ * the same place. The value of that is not only fewer bytes: it is that two rules
34
+ * cannot disagree about what a declaration's resolved type is, because there is
35
+ * one atom and one id for it.
36
+ *
37
+ * A `Ref` and not a mutable map, because rules run concurrently and two of them
38
+ * may add the same atom at once.
39
+ */
40
+ export class Atoms extends Context.Service()("@joggle/Atoms") {
41
+ }
42
+ export const layer = Layer.effect(Atoms, Effect.gen(function* () {
43
+ const store = yield* Ref.make(new Map());
44
+ const add = Effect.fn("Atoms.add")(function* (value) {
45
+ const id = atomId(value);
46
+ yield* Ref.update(store, (current) => {
47
+ if (current.has(id))
48
+ return current;
49
+ const next = new Map(current);
50
+ next.set(id, value);
51
+ return next;
52
+ });
53
+ return id;
54
+ });
55
+ const addAll = Effect.fn("Atoms.addAll")(function* (values) {
56
+ const ids = [];
57
+ for (const value of values)
58
+ ids.push(yield* add(value));
59
+ return ids;
60
+ });
61
+ return Atoms.of({
62
+ add,
63
+ addAll,
64
+ values: Effect.fn("Atoms.values")(function* (ids) {
65
+ const current = yield* Ref.get(store);
66
+ const out = {};
67
+ for (const id of ids) {
68
+ const value = current.get(id);
69
+ if (value !== undefined)
70
+ out[id] = value;
71
+ }
72
+ return out;
73
+ }),
74
+ size: Effect.map(Ref.get(store), (current) => current.size),
75
+ });
76
+ }));
@@ -0,0 +1,156 @@
1
+ /** The directory part of a path, or "." when there is none. */
2
+ export const dirOf = (file) => {
3
+ const cut = file.lastIndexOf("/");
4
+ return cut === -1 ? "." : file.slice(0, cut);
5
+ };
6
+ /** The last segment of a path. */
7
+ export const baseOf = (file) => {
8
+ const cut = file.lastIndexOf("/");
9
+ return cut === -1 ? file : file.slice(cut + 1);
10
+ };
11
+ /** `components/settings-dialog` -> `SettingsDialog`. */
12
+ export const bundleNameOf = (dir) => baseOf(dir)
13
+ .split(/[-_.]/)
14
+ .filter((part) => part.length > 0)
15
+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
16
+ .join("");
17
+ const calls = (file) => file.facts.callSites.map((site) => site.name);
18
+ /** Test files are not part of a bundle's surface. */
19
+ const isTest = (file) => /\.(test|spec)\.[jt]sx?$/.test(file);
20
+ /**
21
+ * A BLOCK is an exported component: PascalCase, therefore a thing you render.
22
+ *
23
+ * Counting every export made hooks and helpers into blocks, so `hooks.ts` was
24
+ * reported as seven blocks in one file and a Remix `route.tsx` as three. Neither
25
+ * is a violation of anything -- `useExpensesGroupedState` is not a block and
26
+ * `loader` is not a block. Only components are.
27
+ */
28
+ const isBlockName = (name) => /^[A-Z][A-Za-z0-9_$]*$/.test(name);
29
+ /**
30
+ * The names a file exports that read as composition blocks: functions named
31
+ * with the block vocabulary, which is the producer half of the pattern.
32
+ */
33
+ export const blocksIn = (file) => file.units
34
+ .filter((unit) => unit.exported && unit.kind === "function" && isBlockName(unit.name))
35
+ .map((unit) => unit.name);
36
+ const declares = (file) => file.units
37
+ .filter((unit) => unit.exported && unit.kind === "function" && isBlockName(unit.name))
38
+ .map((unit) => unit.name);
39
+ /** The object literal that looks like the index's dot-notation export. */
40
+ const dotExport = (file) => {
41
+ if (file === undefined)
42
+ return [];
43
+ for (const keys of file.facts.objects.map((site) => site.keys)) {
44
+ if (keys.includes("Provider"))
45
+ return keys;
46
+ }
47
+ return [];
48
+ };
49
+ /**
50
+ * The object literal that looks like the provider's context value.
51
+ *
52
+ * The best candidate wins rather than the first, because the value may be built
53
+ * into a variable before it is passed: a provider whose literal sits above the
54
+ * JSX was reported as passing no object at all. Picking the literal with the
55
+ * most of state/actions/meta keeps that case conforming while still catching a
56
+ * value that is genuinely missing a part.
57
+ */
58
+ const providerValue = (file) => {
59
+ if (file === undefined)
60
+ return undefined;
61
+ let best;
62
+ let score = 0;
63
+ for (const keys of file.facts.objects.map((site) => site.keys)) {
64
+ const hits = TRIPARTITE.filter((key) => keys.includes(key)).length;
65
+ if (hits > score) {
66
+ score = hits;
67
+ best = keys;
68
+ }
69
+ }
70
+ return score >= 2 ? best : undefined;
71
+ };
72
+ const isIndex = (file) => baseOf(file.path).startsWith("index.");
73
+ /**
74
+ * Every directory that ATTEMPTS the composition pattern, as a bundle.
75
+ *
76
+ * A `createContext` call is the signal, but not the whole test: the directory
77
+ * must also attempt the pattern -- a provider file, a `-provider` file, or an
78
+ * index that dot-exports an object. A directory that merely calls
79
+ * `createContext` is not measured as a bundle.
80
+ */
81
+ export const findBundles = (workspace) => {
82
+ const byDir = new Map();
83
+ for (const file of workspace.files) {
84
+ const dir = dirOf(file.path);
85
+ const existing = byDir.get(dir);
86
+ if (existing === undefined)
87
+ byDir.set(dir, [file]);
88
+ else
89
+ existing.push(file);
90
+ }
91
+ const bundles = [];
92
+ for (const [dir, all] of byDir) {
93
+ const files = all.filter((file) => !isTest(file.path));
94
+ const contextFile = files.find((file) => calls(file).some((call) => call === "createContext" || call.endsWith(".createContext")));
95
+ if (contextFile === undefined)
96
+ continue;
97
+ const indexFile = files.find(isIndex);
98
+ const providerFile = files.find((file) => file.facts.jsx.some((element) => element.endsWith(".Provider")));
99
+ // A directory containing one `createContext` is not a composition bundle.
100
+ // The pattern must be ATTEMPTED: a provider file by name, or an index that
101
+ // exports an object with a `Provider` key. Without this, a plugin directory
102
+ // that happened to call createContext was measured against all four rules
103
+ // and reported as having no provider, no blocks and no hook.
104
+ const attempts = providerFile !== undefined ||
105
+ files.some((file) => /-provider\.[jt]sx?$/.test(baseOf(file.path))) ||
106
+ dotExport(indexFile).length > 0;
107
+ if (!attempts)
108
+ continue;
109
+ const blocks = files.filter((file) => file !== contextFile &&
110
+ file !== providerFile &&
111
+ !isIndex(file) &&
112
+ declares(file).length > 0);
113
+ const hookNames = files.flatMap((file) => file.units
114
+ .filter((unit) => /^use[A-Z]/.test(unit.name) && unit.kind === "function")
115
+ .map((unit) => unit.name));
116
+ bundles.push({
117
+ dir,
118
+ name: bundleNameOf(dir),
119
+ sources: files,
120
+ contextFile,
121
+ providerFile,
122
+ indexFile,
123
+ blocks,
124
+ dotExportKeys: dotExport(indexFile),
125
+ providerValueKeys: providerValue(providerFile),
126
+ hookNames,
127
+ hookFiles: files.filter((file) => file.units.some((unit) => unit.kind === "function" && /^use[A-Z]/.test(unit.name))),
128
+ });
129
+ }
130
+ return bundles.sort((a, b) => (a.dir < b.dir ? -1 : 1));
131
+ };
132
+ /**
133
+ * Whether a declared name is the component an index key refers to.
134
+ *
135
+ * The pattern's index keys are the SHORT block names -- the spec's own
136
+ * `Display`, not `GoodDisplay` -- so a direct string comparison flags every
137
+ * conforming bundle. The declared name is the key, the key prefixed by the
138
+ * bundle name, or the key as a suffix of it: the spec's `Settings.Provider`
139
+ * maps to `SettingsProvider` and its `Counter.Display` to `CounterDisplay`.
140
+ * The fixture caught this because the compliant bundle was reported as broken.
141
+ */
142
+ export const keyMatchesName = ({ bundleName, key, name }) => name === key || name === bundleName + key || name.endsWith(key);
143
+ /** Names the index promises that no block file declares. */
144
+ export const unexportedBlocks = (bundle) => {
145
+ const declared = bundle.blocks.flatMap((file) => declares(file));
146
+ return bundle.dotExportKeys.filter((key) => key !== "Provider" &&
147
+ !/^use[A-Z]/.test(key) &&
148
+ !declared.some((name) => keyMatchesName({ bundleName: bundle.name, key, name })));
149
+ };
150
+ /** Block components the index never exports. */
151
+ export const orphanBlocks = (bundle) => {
152
+ const names = bundle.blocks.flatMap((file) => declares(file));
153
+ return names.filter((name) => !bundle.dotExportKeys.some((key) => keyMatchesName({ bundleName: bundle.name, key, name })));
154
+ };
155
+ /** The canonical tripartite shape, from Pattern.md. */
156
+ export const TRIPARTITE = ["state", "actions", "meta"];
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Whether a question is worth its gate.
3
+ *
4
+ * abide's calibration, kept whole: a question answers near 0 or near 1 on real
5
+ * states when it is decisive; a question whose answers sit in the middle is weak
6
+ * (it is guessing); a question that fires on most states is noisy (its criteria
7
+ * are too loose). Below a handful of states there is nothing to say.
8
+ *
9
+ * `fired` uses joggle's own act threshold, so "noisy" means the same thing here
10
+ * as it does in a run.
11
+ */
12
+ const MIN_STATES = 5;
13
+ /** Below this a "no" is confident. */
14
+ const CONFIDENT_NO = 0.25;
15
+ /** At or above this a "yes" is clear. */
16
+ const CLEAR_YES = 0.7;
17
+ /** Firing on this share of states is a question that says yes to everything. */
18
+ const NOISY_RATE = 0.6;
19
+ const median = (values) => {
20
+ if (values.length === 0)
21
+ return 0;
22
+ const sorted = [...values].sort((left, right) => left - right);
23
+ const middle = Math.floor(sorted.length / 2);
24
+ if (sorted.length % 2 === 1)
25
+ return sorted[middle] ?? 0;
26
+ const low = sorted[middle - 1] ?? 0;
27
+ const high = sorted[middle] ?? 0;
28
+ return (low + high) / 2;
29
+ };
30
+ /**
31
+ * Summarize one question's answers over real states.
32
+ *
33
+ * `fired` counts the states the BAND would act on, not the ones above the
34
+ * probability floor: a rule whose answers are above the floor but below the
35
+ * margin is not flooding the report, it is flagging, and calibration that cannot
36
+ * see the difference calls it noisy when the report is quiet.
37
+ *
38
+ * @param states - one per candidate the rule produced: P(violated) from
39
+ * `verdictOf`, and whether the gate would act.
40
+ * @returns the counts and the verdict: decisive, weak, noisy, or skipped when
41
+ * there were too few states to say.
42
+ */
43
+ export const summarizeCalibration = (states) => {
44
+ const probabilities = states.map((state) => state.probability);
45
+ const count = states.length;
46
+ const med = median(probabilities);
47
+ const min = count === 0 ? 0 : Math.min(...probabilities);
48
+ const max = count === 0 ? 0 : Math.max(...probabilities);
49
+ const fired = states.filter((state) => state.acted).length;
50
+ let verdict;
51
+ if (count < MIN_STATES)
52
+ verdict = "skipped";
53
+ else if (fired / count >= NOISY_RATE)
54
+ verdict = "noisy";
55
+ else if (max < CLEAR_YES && med >= CONFIDENT_NO)
56
+ verdict = "weak";
57
+ else
58
+ verdict = "decisive";
59
+ return { states: count, median: med, min, max, fired, verdict };
60
+ };