urtext 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +229 -0
- package/dist/analyze/blast-radius.d.ts +28 -0
- package/dist/analyze/blast-radius.js +163 -0
- package/dist/analyze/canonical.d.ts +27 -0
- package/dist/analyze/canonical.js +74 -0
- package/dist/analyze/citations.d.ts +256 -0
- package/dist/analyze/citations.js +945 -0
- package/dist/analyze/effects.d.ts +15 -0
- package/dist/analyze/effects.js +255 -0
- package/dist/analyze/fact.d.ts +42 -0
- package/dist/analyze/fact.js +46 -0
- package/dist/analyze/guards.d.ts +70 -0
- package/dist/analyze/guards.js +211 -0
- package/dist/analyze/index.d.ts +26 -0
- package/dist/analyze/index.js +52 -0
- package/dist/analyze/program.d.ts +15 -0
- package/dist/analyze/program.js +229 -0
- package/dist/analyze/surface.d.ts +48 -0
- package/dist/analyze/surface.js +396 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +12 -0
- package/dist/cli.d.ts +110 -0
- package/dist/cli.js +502 -0
- package/dist/extract/diff.d.ts +35 -0
- package/dist/extract/diff.js +116 -0
- package/dist/extract/git.d.ts +12 -0
- package/dist/extract/git.js +247 -0
- package/dist/extract/index.d.ts +4 -0
- package/dist/extract/index.js +57 -0
- package/dist/extract/intent.d.ts +64 -0
- package/dist/extract/intent.js +238 -0
- package/dist/extract/scope.d.ts +160 -0
- package/dist/extract/scope.js +284 -0
- package/dist/extract/symbols.d.ts +24 -0
- package/dist/extract/symbols.js +230 -0
- package/dist/interpret/client.d.ts +27 -0
- package/dist/interpret/client.js +80 -0
- package/dist/interpret/index.d.ts +41 -0
- package/dist/interpret/index.js +86 -0
- package/dist/interpret/prompt.d.ts +23 -0
- package/dist/interpret/prompt.js +128 -0
- package/dist/interpret/schema.d.ts +74 -0
- package/dist/interpret/schema.js +103 -0
- package/dist/report/conceal.d.ts +63 -0
- package/dist/report/conceal.js +129 -0
- package/dist/report/coverage.d.ts +43 -0
- package/dist/report/coverage.js +56 -0
- package/dist/report/html.d.ts +4 -0
- package/dist/report/html.js +634 -0
- package/dist/report/markdown.d.ts +2 -0
- package/dist/report/markdown.js +168 -0
- package/dist/report/model.d.ts +303 -0
- package/dist/report/model.js +289 -0
- package/dist/report/pdf.d.ts +2 -0
- package/dist/report/pdf.js +217 -0
- package/dist/report/terminal.d.ts +2 -0
- package/dist/report/terminal.js +206 -0
- package/dist/report/write.d.ts +105 -0
- package/dist/report/write.js +160 -0
- package/dist/score/index.d.ts +94 -0
- package/dist/score/index.js +572 -0
- package/dist/score/reach.d.ts +126 -0
- package/dist/score/reach.js +320 -0
- package/dist/score/reconcile.d.ts +52 -0
- package/dist/score/reconcile.js +208 -0
- package/dist/types.d.ts +221 -0
- package/dist/types.js +10 -0
- package/fonts/DejaVuSans-Bold.ttf +0 -0
- package/fonts/DejaVuSans-Oblique.ttf +0 -0
- package/fonts/DejaVuSans.ttf +0 -0
- package/fonts/DejaVuSansMono.ttf +0 -0
- package/fonts/LICENSE +187 -0
- package/package.json +44 -0
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
import { minPossibleAnalyzerScore, rankWithAbsorption, tierFor } from "./index.js";
|
|
2
|
+
import { referenceCount } from "./reach.js";
|
|
3
|
+
/**
|
|
4
|
+
* Strictly below `minPossibleAnalyzerScore()` (currently 6, an
|
|
5
|
+
* `effect_removed` timing effect) — never the raw `WEIGHTS.factKind`
|
|
6
|
+
* minimum, which ignores the effect multiplier `scoreFact` applies and put
|
|
7
|
+
* the old hardcoded ceiling (14) 8 points above a score an analyzer can
|
|
8
|
+
* actually produce. Derived, not hand-copied, so a future weight change can
|
|
9
|
+
* only move this number, never leave it stale above a fact it is supposed
|
|
10
|
+
* to sit under.
|
|
11
|
+
*/
|
|
12
|
+
export const MODEL_CEILING = minPossibleAnalyzerScore() / 2;
|
|
13
|
+
/**
|
|
14
|
+
* The model's severity, defensively bounded to the 0..1 range its type
|
|
15
|
+
* documents but does not enforce. `reconcile` is the trust boundary between
|
|
16
|
+
* unbelieved model output and a believed finding, so it must not assume the
|
|
17
|
+
* model behaved: an out-of-range value here is not hypothetical malice, just
|
|
18
|
+
* an unvalidated float from a network response. Unclamped, a `NaN`
|
|
19
|
+
* `severity` would produce a `NaN` score, and `NaN` compares false against
|
|
20
|
+
* everything, so the final sort would stop being a sort for every finding it
|
|
21
|
+
* touches — and an out-of-range value would let the model assign itself a
|
|
22
|
+
* ceiling `reconcile` never agreed to.
|
|
23
|
+
*/
|
|
24
|
+
function clampSeverity(severity) {
|
|
25
|
+
if (!Number.isFinite(severity))
|
|
26
|
+
return 0;
|
|
27
|
+
return Math.min(Math.max(severity, 0), 1);
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The fewest references at which an unabsorbed blast_radius finding that no
|
|
31
|
+
* claim explains still earns a standalone row. "X changed and is referenced
|
|
32
|
+
* in one place" names no problem and barely any cost — a sixth of the first
|
|
33
|
+
* real dogfood report was exactly that row.
|
|
34
|
+
*
|
|
35
|
+
* Enforced here, after model claims attach, and not in `foldReach` where
|
|
36
|
+
* the fact-level fold happens: a claim citing the fact can only attach to a
|
|
37
|
+
* finding that still exists, so filtering earlier silently dropped the
|
|
38
|
+
* claim — the one kind of loss this pipeline is built to refuse. A finding
|
|
39
|
+
* a claim did attach to survives at its normal `inferred` tier, because
|
|
40
|
+
* model context is exactly what promotes the row out of "filler". Only the
|
|
41
|
+
* claim-free standalone row disappears: absorption into siblings happened
|
|
42
|
+
* back in `foldReach`, before any of this, so amplified findings are
|
|
43
|
+
* untouched, and the reach entry itself is recorded regardless.
|
|
44
|
+
* `test/score/reconcile.test.ts` pins the survival edge and both sides of
|
|
45
|
+
* the numeric line, so moving this number either way fails a test.
|
|
46
|
+
*/
|
|
47
|
+
export const MIN_STANDALONE_REFERENCES = 2;
|
|
48
|
+
/**
|
|
49
|
+
* True for the rows `MIN_STANDALONE_REFERENCES` suppresses: a finding that
|
|
50
|
+
* is still a bare blast_radius fact's own row (grouping never produces one
|
|
51
|
+
* and absorption never lets one survive to here), below the threshold, with
|
|
52
|
+
* no claim attached. The fact lookup uses the finding id because an
|
|
53
|
+
* unabsorbed fact's finding keeps its fact's id — anything synthesized
|
|
54
|
+
* (groups, standalone claims) misses the map and is kept.
|
|
55
|
+
*/
|
|
56
|
+
function isSuppressedStandaloneReach(finding, byId) {
|
|
57
|
+
if (finding.claim)
|
|
58
|
+
return false;
|
|
59
|
+
const fact = byId.get(finding.id);
|
|
60
|
+
if (!fact || fact.kind !== "blast_radius")
|
|
61
|
+
return false;
|
|
62
|
+
return referenceCount(fact) < MIN_STANDALONE_REFERENCES;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Merges what the analyzers found with what the model said.
|
|
66
|
+
*
|
|
67
|
+
* The asymmetry is the point: a claim can only ever annotate a fact or
|
|
68
|
+
* stand alone, and a fact survives as a finding whether or not the model
|
|
69
|
+
* mentions it — with exactly one scoped exception, a claim-free lonely
|
|
70
|
+
* blast_radius row under MIN_STANDALONE_REFERENCES, filtered after claims
|
|
71
|
+
* attach and disclosed through `onSuppressed` rather than dropped in
|
|
72
|
+
* silence. The rule is pinned by "keeps every fact except a claim-free
|
|
73
|
+
* sub-threshold reach row as a finding even when the model says nothing"
|
|
74
|
+
* and the exception by "suppresses a claim-free lonely one-reference reach
|
|
75
|
+
* finding", both in test/score/reconcile.test.ts.
|
|
76
|
+
*
|
|
77
|
+
* A claim never edits a fact's file, line, or evidence — if the model
|
|
78
|
+
* asserts a location, it is ignored in favour of the analyzer's, because
|
|
79
|
+
* the analyzer's came from the code.
|
|
80
|
+
*
|
|
81
|
+
* The marker on a claim travels to the finding it lands on and nothing else:
|
|
82
|
+
* `test/score/reconcile.test.ts`, "changes no score and no ordering, with the
|
|
83
|
+
* marker or without it".
|
|
84
|
+
*/
|
|
85
|
+
export function reconcile(facts, claims,
|
|
86
|
+
// Called with how many claims lost the first-claim-wins race below — a
|
|
87
|
+
// later claim naming an already-explained finding is dropped, and the
|
|
88
|
+
// reader cannot know the model said two things about it unless the caller
|
|
89
|
+
// says so. Invoked only when the count is nonzero, so `review` in
|
|
90
|
+
// `../cli.ts` can turn it into one warnings line without branching.
|
|
91
|
+
onDroppedClaims,
|
|
92
|
+
// Called with how many claim-free standalone reach rows the
|
|
93
|
+
// MIN_STANDALONE_REFERENCES filter removed. A row that vanishes from
|
|
94
|
+
// every surface with no trace leaves even the machine-readable output
|
|
95
|
+
// unable to say the filter ran at all — the same disclosure rule as
|
|
96
|
+
// `onDroppedClaims` above, and the same contract: invoked only when the
|
|
97
|
+
// count is nonzero.
|
|
98
|
+
onSuppressed) {
|
|
99
|
+
const byId = new Map(facts.map((f) => [f.id, f]));
|
|
100
|
+
const { findings: ranked, absorbedBy } = rankWithAbsorption(facts);
|
|
101
|
+
// Indexed so a standalone finding's id can stay unique even when two
|
|
102
|
+
// claims share a model-generated `id` — a model's ids are not guaranteed
|
|
103
|
+
// unique the way a fact's are, so the array position backstops it.
|
|
104
|
+
const indexed = claims.map((claim, i) => ({ claim, i }));
|
|
105
|
+
// Every claim that names a real fact resolves to the id of the finding
|
|
106
|
+
// that fact's information ends up on — its own finding, ordinarily, but
|
|
107
|
+
// `absorbedBy` redirects to whichever finding absorbed it if `rank`
|
|
108
|
+
// folded it into a sibling's reach or a file's export group. The model is
|
|
109
|
+
// shown facts, not findings, so citing a fact that a machine step later
|
|
110
|
+
// merged away is expected behaviour, not a mistake — on a real range a
|
|
111
|
+
// large share of facts get folded this way.
|
|
112
|
+
//
|
|
113
|
+
// First claim wins when the target repeats, deterministically: claims are
|
|
114
|
+
// walked in the order they arrived, and once a target finding has an
|
|
115
|
+
// explanation, a later duplicate does not silently override it. This
|
|
116
|
+
// covers two distinct collisions with one rule — two claims naming the
|
|
117
|
+
// same fact, and two claims naming two different facts that both
|
|
118
|
+
// absorbed into the same finding.
|
|
119
|
+
const attachTo = new Map();
|
|
120
|
+
// Losers of the first-claim-wins race, counted so the drop is disclosed
|
|
121
|
+
// rather than silent. Dangling references are not in this count: they are
|
|
122
|
+
// dropped for a different, documented reason (below), and counting them
|
|
123
|
+
// here would present "the model named a fact that doesn't exist" as "the
|
|
124
|
+
// model said more about a finding".
|
|
125
|
+
let dropped = 0;
|
|
126
|
+
for (const entry of indexed) {
|
|
127
|
+
const { correspondsTo } = entry.claim;
|
|
128
|
+
// A `correspondsTo` naming no real fact is a dangling reference, not a
|
|
129
|
+
// claim to attach or recover — it is dropped further down by simply
|
|
130
|
+
// never being added here or to the standalone list.
|
|
131
|
+
if (!correspondsTo || !byId.has(correspondsTo))
|
|
132
|
+
continue;
|
|
133
|
+
const targetId = absorbedBy.get(correspondsTo) ?? correspondsTo;
|
|
134
|
+
if (!attachTo.has(targetId)) {
|
|
135
|
+
attachTo.set(targetId, { claim: entry.claim, factId: correspondsTo });
|
|
136
|
+
}
|
|
137
|
+
else {
|
|
138
|
+
dropped++;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
if (dropped > 0)
|
|
142
|
+
onDroppedClaims?.(dropped);
|
|
143
|
+
const findings = ranked.map((finding) => {
|
|
144
|
+
const entry = attachTo.get(finding.id);
|
|
145
|
+
if (!entry)
|
|
146
|
+
return finding;
|
|
147
|
+
// `entry.factId` is `entry.claim.correspondsTo` by construction above,
|
|
148
|
+
// so this call is defensive, not a live discrimination: `tierFor` can
|
|
149
|
+
// only ever return `inferred` here. Going through the real function
|
|
150
|
+
// anyway, rather than hardcoding `"inferred"`, keeps this in lockstep
|
|
151
|
+
// with `tierFor`'s own definition of what makes a claim count as
|
|
152
|
+
// corresponding, instead of a second copy of that rule drifting apart
|
|
153
|
+
// from it. `fact` is always defined here: `attachTo` only ever stores a
|
|
154
|
+
// `factId` that passed `byId.has(...)` above, but a `Map.get` cannot
|
|
155
|
+
// carry that proof through its return type, so the guard stays as the
|
|
156
|
+
// narrowing it is rather than a `!` assertion claiming more certainty
|
|
157
|
+
// than the compiler has.
|
|
158
|
+
const fact = byId.get(entry.factId);
|
|
159
|
+
if (!fact)
|
|
160
|
+
return finding;
|
|
161
|
+
return {
|
|
162
|
+
...finding,
|
|
163
|
+
tier: tierFor(fact, entry.claim),
|
|
164
|
+
claim: { summary: entry.claim.summary, reasoning: entry.claim.reasoning },
|
|
165
|
+
// The marker travels with the claim to wherever it attaches, including
|
|
166
|
+
// the attach-to-absorber path: one rule, not two — `attachTo` is
|
|
167
|
+
// already keyed by the finding the claim lands on, so the redirected
|
|
168
|
+
// claim arrives here like any other. Spread conditionally because the
|
|
169
|
+
// field is absent-or-true — there is no "not beyond intent" state to
|
|
170
|
+
// write.
|
|
171
|
+
...(entry.claim.beyondIntent ? { beyondIntent: true } : {}),
|
|
172
|
+
};
|
|
173
|
+
});
|
|
174
|
+
// After the claims are on, not before — see MIN_STANDALONE_REFERENCES.
|
|
175
|
+
const kept = findings.filter((f) => !isSuppressedStandaloneReach(f, byId));
|
|
176
|
+
if (kept.length < findings.length)
|
|
177
|
+
onSuppressed?.(findings.length - kept.length);
|
|
178
|
+
// Only a claim with no `correspondsTo` at all stands alone. One that names
|
|
179
|
+
// a `correspondsTo` pointing at no real fact is a dangling reference, not
|
|
180
|
+
// a standalone observation — it is dropped rather than promoted, because
|
|
181
|
+
// treating "the model named a fact that doesn't exist" the same as "the
|
|
182
|
+
// model wasn't talking about a fact" would let a wrong id manufacture a
|
|
183
|
+
// finding out of nothing.
|
|
184
|
+
const standalone = indexed
|
|
185
|
+
.filter(({ claim }) => !claim.correspondsTo)
|
|
186
|
+
.map(({ claim, i }) => ({
|
|
187
|
+
id: `claim:${i}:${claim.id}`,
|
|
188
|
+
tier: "model",
|
|
189
|
+
file: claim.file,
|
|
190
|
+
line: claim.line,
|
|
191
|
+
title: claim.summary,
|
|
192
|
+
body: claim.reasoning,
|
|
193
|
+
// MODEL_CEILING already sits strictly below the weakest score an
|
|
194
|
+
// analyzer can produce, so a severity clamped to [0, 1] scales this
|
|
195
|
+
// linearly up to — at maximum severity, reaching, but by
|
|
196
|
+
// construction never crossing — that ceiling.
|
|
197
|
+
score: clampSeverity(claim.severity) * MODEL_CEILING,
|
|
198
|
+
evidence: [],
|
|
199
|
+
...(claim.beyondIntent ? { beyondIntent: true } : {}),
|
|
200
|
+
}));
|
|
201
|
+
return [...kept, ...standalone].sort((a, b) => b.score - a.score ||
|
|
202
|
+
a.file.localeCompare(b.file) ||
|
|
203
|
+
a.line - b.line ||
|
|
204
|
+
// Final tiebreak so the sort is total: without it, findings tied on
|
|
205
|
+
// score/file/line fall back to array (insertion) order, which is an
|
|
206
|
+
// accident of iteration, not a guarantee.
|
|
207
|
+
a.id.localeCompare(b.id));
|
|
208
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
import type ts from "typescript";
|
|
2
|
+
/** Sentinel revision: read files from the working tree rather than git. */
|
|
3
|
+
export declare const WORKTREE = "WORKTREE";
|
|
4
|
+
/**
|
|
5
|
+
* Directory, relative to the repository root, that urtext writes its own
|
|
6
|
+
* reports into. Lives here rather than in `report/write.ts` because
|
|
7
|
+
* `extract/diff.ts` needs it too — the untracked-file count has to leave
|
|
8
|
+
* urtext's own output out — and neither of those two modules should have to
|
|
9
|
+
* import the other to agree on the name.
|
|
10
|
+
*/
|
|
11
|
+
export declare const REPORT_DIR = ".urtext";
|
|
12
|
+
export interface RevRange {
|
|
13
|
+
/** Revision to treat as "before". A commit-ish. */
|
|
14
|
+
from: string;
|
|
15
|
+
/** Revision to treat as "after". A commit-ish, or WORKTREE. */
|
|
16
|
+
to: string;
|
|
17
|
+
/** Human-readable description, e.g. "vs origin/main". */
|
|
18
|
+
label: string;
|
|
19
|
+
}
|
|
20
|
+
export interface Hunk {
|
|
21
|
+
oldStart: number;
|
|
22
|
+
oldLines: number;
|
|
23
|
+
newStart: number;
|
|
24
|
+
newLines: number;
|
|
25
|
+
}
|
|
26
|
+
export type SymbolKind = "function" | "method" | "class" | "type" | "enum" | "variable";
|
|
27
|
+
export interface ChangedSymbol {
|
|
28
|
+
name: string;
|
|
29
|
+
/**
|
|
30
|
+
* Dotted path through every scope that encloses the declaration —
|
|
31
|
+
* "Gamma.method", "wrapper.local", "N.x" — and equal to `name` only for a
|
|
32
|
+
* declaration at the top level of the file. Identity is keyed on this, not
|
|
33
|
+
* on `name`: two classes in one file may each declare `render`, and a
|
|
34
|
+
* function's local may share a name with an export beside it. A scope with
|
|
35
|
+
* no name of its own contributes a sentinel rather than nothing (see
|
|
36
|
+
* `extract/scope.ts`), so this is qualified all the way up in every case.
|
|
37
|
+
*/
|
|
38
|
+
qualifiedName: string;
|
|
39
|
+
kind: SymbolKind;
|
|
40
|
+
/**
|
|
41
|
+
* Carries an `export` modifier at the top level of the file. Deliberately not
|
|
42
|
+
* phrased as "is part of the file's public surface", because it is narrower
|
|
43
|
+
* than that: a declaration exported by a separate statement — `function
|
|
44
|
+
* helper() {}` plus `export { helper }` — has no modifier of its own, comes
|
|
45
|
+
* out `false`, and so gets no blast radius and no row in the report's
|
|
46
|
+
* API-surface table. That table lists the omission rather than implying it
|
|
47
|
+
* covers everything. A namespace member is `false` too, and that one is
|
|
48
|
+
* right: an importer reaches it through the namespace, not by its bare name,
|
|
49
|
+
* which is the only name `blastRadiusAnalyzer` can look up. A class member is
|
|
50
|
+
* always `false`.
|
|
51
|
+
*/
|
|
52
|
+
exported: boolean;
|
|
53
|
+
/** 1-based, inclusive, in the "after" file. Zero for removed symbols. */
|
|
54
|
+
range: {
|
|
55
|
+
startLine: number;
|
|
56
|
+
endLine: number;
|
|
57
|
+
};
|
|
58
|
+
change: "added" | "modified" | "removed";
|
|
59
|
+
}
|
|
60
|
+
export type FileStatus = "added" | "modified" | "deleted" | "renamed";
|
|
61
|
+
export interface ChangedFile {
|
|
62
|
+
path: string;
|
|
63
|
+
status: FileStatus;
|
|
64
|
+
previousPath?: string;
|
|
65
|
+
hunks: Hunk[];
|
|
66
|
+
/** Empty for files that are not TypeScript. */
|
|
67
|
+
symbols: ChangedSymbol[];
|
|
68
|
+
}
|
|
69
|
+
export interface Changeset {
|
|
70
|
+
range: RevRange;
|
|
71
|
+
files: ChangedFile[];
|
|
72
|
+
/**
|
|
73
|
+
* Untracked files present in the working tree, which `git diff` omits and
|
|
74
|
+
* this changeset therefore does not describe. Reported so their absence is
|
|
75
|
+
* visible; zero when the range ends at a commit.
|
|
76
|
+
*/
|
|
77
|
+
untrackedCount?: number;
|
|
78
|
+
}
|
|
79
|
+
export type EffectKind = "network" | "filesystem" | "process" | "env" | "database" | "timing";
|
|
80
|
+
export type FactKind = "effect_added" | "effect_removed" | "guard_removed" | "export_added" | "export_removed" | "signature_changed" | "blast_radius" | "citation_rot";
|
|
81
|
+
export interface EvidenceRef {
|
|
82
|
+
file: string;
|
|
83
|
+
line: number;
|
|
84
|
+
excerpt: string;
|
|
85
|
+
/**
|
|
86
|
+
* Which revision `line` counts in. A removal — a guard, an effect, or an
|
|
87
|
+
* export that exists only on the before side — can only be evidenced by
|
|
88
|
+
* before-side text, whose line numbers need not exist in the working tree
|
|
89
|
+
* at all. Rendering that as a bare `path:line` sends anyone clicking
|
|
90
|
+
* through to an unrelated line. Omitted means the after side, which is
|
|
91
|
+
* the common case and needs no annotation.
|
|
92
|
+
*/
|
|
93
|
+
side?: "before" | "after";
|
|
94
|
+
}
|
|
95
|
+
export interface Fact {
|
|
96
|
+
/**
|
|
97
|
+
* Stable within a single run; referenced by a model claim's
|
|
98
|
+
* `correspondsTo` in Plan 3, which is what introduces model claims.
|
|
99
|
+
*/
|
|
100
|
+
id: string;
|
|
101
|
+
kind: FactKind;
|
|
102
|
+
/** Always equal to `evidence[0].file` — see `makeFact`, which derives it. */
|
|
103
|
+
file: string;
|
|
104
|
+
/** Always equal to `evidence[0].line` — see `makeFact`, which derives it. */
|
|
105
|
+
line: number;
|
|
106
|
+
/**
|
|
107
|
+
* The dotted path to the symbol this fact is about — `Worker.run`, not
|
|
108
|
+
* `run` — for the same reason `ChangedSymbol.qualifiedName` is: two classes
|
|
109
|
+
* in one file may each declare `render`, and a method may share a name with
|
|
110
|
+
* a top-level export. Named for the qualification rather than called
|
|
111
|
+
* `symbol` because `foldReach` matches facts across analyzers on
|
|
112
|
+
* (`file`, this): an analyzer that filled it with a bare name handed one
|
|
113
|
+
* symbol's reference count to another symbol's finding, and the field's
|
|
114
|
+
* old name made that look correct at every call site. Omitted by
|
|
115
|
+
* file-scoped facts, which are about no symbol at all.
|
|
116
|
+
*/
|
|
117
|
+
qualifiedSymbol?: string;
|
|
118
|
+
detail: Record<string, unknown>;
|
|
119
|
+
/** At least one. A fact that cannot show its evidence is not emitted. */
|
|
120
|
+
evidence: EvidenceRef[];
|
|
121
|
+
}
|
|
122
|
+
export type Tier = "verified" | "inferred" | "model";
|
|
123
|
+
export interface Finding {
|
|
124
|
+
id: string;
|
|
125
|
+
tier: Tier;
|
|
126
|
+
file: string;
|
|
127
|
+
line: number;
|
|
128
|
+
/** One line, shown as the finding headline. */
|
|
129
|
+
title: string;
|
|
130
|
+
/** One or two sentences of supporting explanation. */
|
|
131
|
+
body: string;
|
|
132
|
+
score: number;
|
|
133
|
+
evidence: EvidenceRef[];
|
|
134
|
+
/**
|
|
135
|
+
* How widely the changed symbol is used, when known. Not a finding of its
|
|
136
|
+
* own — an amplifier on this one. See `foldReach`.
|
|
137
|
+
*/
|
|
138
|
+
reach?: {
|
|
139
|
+
references: number;
|
|
140
|
+
sites: EvidenceRef[];
|
|
141
|
+
};
|
|
142
|
+
/** The model's reasoning, when a claim contributed to this finding. */
|
|
143
|
+
claim?: {
|
|
144
|
+
summary: string;
|
|
145
|
+
reasoning: string;
|
|
146
|
+
};
|
|
147
|
+
/**
|
|
148
|
+
* Carried over from the claim behind this finding; see `Claim.beyondIntent`.
|
|
149
|
+
* Lives here rather than inside `claim` so both reconcile paths set one
|
|
150
|
+
* field and `toFindingView` reads one field — a standalone finding has no
|
|
151
|
+
* `claim` object to hang it on. Never present on a `verified` finding: see
|
|
152
|
+
* `test/score/reconcile.test.ts`, "never renders a marker on a verified
|
|
153
|
+
* finding".
|
|
154
|
+
*/
|
|
155
|
+
beyondIntent?: true;
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* A model's interpretation of a change. A claim is not evidence: it carries
|
|
159
|
+
* no `EvidenceRef` of its own, and it can never overwrite a fact. It either
|
|
160
|
+
* annotates a fact — earning that fact's finding a richer explanation — or
|
|
161
|
+
* stands alone as something the analyzers did not see, labelled `model` so a
|
|
162
|
+
* reader knows to check it.
|
|
163
|
+
*/
|
|
164
|
+
export interface Claim {
|
|
165
|
+
id: string;
|
|
166
|
+
file: string;
|
|
167
|
+
line: number;
|
|
168
|
+
/** One sentence, shown as the finding headline when the claim stands alone. */
|
|
169
|
+
summary: string;
|
|
170
|
+
/** Why this matters. Shown as the body. */
|
|
171
|
+
reasoning: string;
|
|
172
|
+
/**
|
|
173
|
+
* The model's own 0..1 severity, advisory only. `reconcile` clamps it
|
|
174
|
+
* defensively (non-finite or out-of-range input becomes 0..1) before
|
|
175
|
+
* scaling a standalone finding's score, and that scale's ceiling sits
|
|
176
|
+
* strictly below the weakest score any analyzer fact can produce — so
|
|
177
|
+
* severity can move a claim within the model tier but never lift it past
|
|
178
|
+
* a fact.
|
|
179
|
+
*/
|
|
180
|
+
severity: number;
|
|
181
|
+
/** `Fact.id` this claim restates or explains, when it corresponds to one. */
|
|
182
|
+
correspondsTo?: string;
|
|
183
|
+
/**
|
|
184
|
+
* Set when the model says the change does something its stated intent does
|
|
185
|
+
* not account for. Absent or `true`, never `false`: there is no "covered by
|
|
186
|
+
* the stated intent" finding, only the absence of a mark.
|
|
187
|
+
*/
|
|
188
|
+
beyondIntent?: true;
|
|
189
|
+
}
|
|
190
|
+
export interface InterpretResult {
|
|
191
|
+
claims: Claim[];
|
|
192
|
+
/**
|
|
193
|
+
* The model that produced them, for the report's provenance line. Empty
|
|
194
|
+
* when the stage was skipped: a model that was merely *requested* produced
|
|
195
|
+
* nothing, and naming it would attribute a stage that never ran.
|
|
196
|
+
*/
|
|
197
|
+
model: string;
|
|
198
|
+
/** Set when the stage did not run; the reason is shown to the user. */
|
|
199
|
+
skipped?: string;
|
|
200
|
+
/**
|
|
201
|
+
* What the reader is owed about the stated intent when the stage ran but
|
|
202
|
+
* could not compare against a complete one. Mutually exclusive with
|
|
203
|
+
* `skipped`: a stage that did not run has nothing to say about intent. See
|
|
204
|
+
* `test/interpret/index.test.ts`, "never carries both a skipped reason and
|
|
205
|
+
* an intent note".
|
|
206
|
+
*/
|
|
207
|
+
intentNote?: string;
|
|
208
|
+
}
|
|
209
|
+
export interface AnalysisContext {
|
|
210
|
+
cwd: string;
|
|
211
|
+
range: RevRange;
|
|
212
|
+
/** File contents at a revision, or null if absent there. */
|
|
213
|
+
readAt(rev: string, path: string): Promise<string | null>;
|
|
214
|
+
/**
|
|
215
|
+
* A type-checked program at a revision. Built lazily and memoized —
|
|
216
|
+
* constructing one parses every TypeScript file in the repository, so
|
|
217
|
+
* analyzers that do not need the checker must not call this.
|
|
218
|
+
*/
|
|
219
|
+
programAt(rev: string): Promise<ts.Program>;
|
|
220
|
+
}
|
|
221
|
+
export type Analyzer = (changeset: Changeset, ctx: AnalysisContext) => Promise<Fact[]>;
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/** Sentinel revision: read files from the working tree rather than git. */
|
|
2
|
+
export const WORKTREE = "WORKTREE";
|
|
3
|
+
/**
|
|
4
|
+
* Directory, relative to the repository root, that urtext writes its own
|
|
5
|
+
* reports into. Lives here rather than in `report/write.ts` because
|
|
6
|
+
* `extract/diff.ts` needs it too — the untracked-file count has to leave
|
|
7
|
+
* urtext's own output out — and neither of those two modules should have to
|
|
8
|
+
* import the other to agree on the name.
|
|
9
|
+
*/
|
|
10
|
+
export const REPORT_DIR = ".urtext";
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/fonts/LICENSE
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
|
|
2
|
+
Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
Bitstream Vera Fonts Copyright
|
|
6
|
+
------------------------------
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
|
|
9
|
+
a trademark of Bitstream, Inc.
|
|
10
|
+
|
|
11
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
12
|
+
of the fonts accompanying this license ("Fonts") and associated
|
|
13
|
+
documentation files (the "Font Software"), to reproduce and distribute the
|
|
14
|
+
Font Software, including without limitation the rights to use, copy, merge,
|
|
15
|
+
publish, distribute, and/or sell copies of the Font Software, and to permit
|
|
16
|
+
persons to whom the Font Software is furnished to do so, subject to the
|
|
17
|
+
following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright and trademark notices and this permission notice shall
|
|
20
|
+
be included in all copies of one or more of the Font Software typefaces.
|
|
21
|
+
|
|
22
|
+
The Font Software may be modified, altered, or added to, and in particular
|
|
23
|
+
the designs of glyphs or characters in the Fonts may be modified and
|
|
24
|
+
additional glyphs or characters may be added to the Fonts, only if the fonts
|
|
25
|
+
are renamed to names not containing either the words "Bitstream" or the word
|
|
26
|
+
"Vera".
|
|
27
|
+
|
|
28
|
+
This License becomes null and void to the extent applicable to Fonts or Font
|
|
29
|
+
Software that has been modified and is distributed under the "Bitstream
|
|
30
|
+
Vera" names.
|
|
31
|
+
|
|
32
|
+
The Font Software may be sold as part of a larger software package but no
|
|
33
|
+
copy of one or more of the Font Software typefaces may be sold by itself.
|
|
34
|
+
|
|
35
|
+
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
36
|
+
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
|
|
37
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
|
|
38
|
+
TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
|
|
39
|
+
FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
|
|
40
|
+
ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
|
|
41
|
+
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
|
|
42
|
+
THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
|
|
43
|
+
FONT SOFTWARE.
|
|
44
|
+
|
|
45
|
+
Except as contained in this notice, the names of Gnome, the Gnome
|
|
46
|
+
Foundation, and Bitstream Inc., shall not be used in advertising or
|
|
47
|
+
otherwise to promote the sale, use or other dealings in this Font Software
|
|
48
|
+
without prior written authorization from the Gnome Foundation or Bitstream
|
|
49
|
+
Inc., respectively. For further information, contact: fonts at gnome dot
|
|
50
|
+
org.
|
|
51
|
+
|
|
52
|
+
Arev Fonts Copyright
|
|
53
|
+
------------------------------
|
|
54
|
+
|
|
55
|
+
Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
|
|
56
|
+
|
|
57
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
|
58
|
+
a copy of the fonts accompanying this license ("Fonts") and
|
|
59
|
+
associated documentation files (the "Font Software"), to reproduce
|
|
60
|
+
and distribute the modifications to the Bitstream Vera Font Software,
|
|
61
|
+
including without limitation the rights to use, copy, merge, publish,
|
|
62
|
+
distribute, and/or sell copies of the Font Software, and to permit
|
|
63
|
+
persons to whom the Font Software is furnished to do so, subject to
|
|
64
|
+
the following conditions:
|
|
65
|
+
|
|
66
|
+
The above copyright and trademark notices and this permission notice
|
|
67
|
+
shall be included in all copies of one or more of the Font Software
|
|
68
|
+
typefaces.
|
|
69
|
+
|
|
70
|
+
The Font Software may be modified, altered, or added to, and in
|
|
71
|
+
particular the designs of glyphs or characters in the Fonts may be
|
|
72
|
+
modified and additional glyphs or characters may be added to the
|
|
73
|
+
Fonts, only if the fonts are renamed to names not containing either
|
|
74
|
+
the words "Tavmjong Bah" or the word "Arev".
|
|
75
|
+
|
|
76
|
+
This License becomes null and void to the extent applicable to Fonts
|
|
77
|
+
or Font Software that has been modified and is distributed under the
|
|
78
|
+
"Tavmjong Bah Arev" names.
|
|
79
|
+
|
|
80
|
+
The Font Software may be sold as part of a larger software package but
|
|
81
|
+
no copy of one or more of the Font Software typefaces may be sold by
|
|
82
|
+
itself.
|
|
83
|
+
|
|
84
|
+
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
85
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
|
|
86
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
|
|
87
|
+
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
|
|
88
|
+
TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
|
89
|
+
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
|
|
90
|
+
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
91
|
+
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
|
|
92
|
+
OTHER DEALINGS IN THE FONT SOFTWARE.
|
|
93
|
+
|
|
94
|
+
Except as contained in this notice, the name of Tavmjong Bah shall not
|
|
95
|
+
be used in advertising or otherwise to promote the sale, use or other
|
|
96
|
+
dealings in this Font Software without prior written authorization
|
|
97
|
+
from Tavmjong Bah. For further information, contact: tavmjong @ free
|
|
98
|
+
. fr.
|
|
99
|
+
|
|
100
|
+
TeX Gyre DJV Math
|
|
101
|
+
-----------------
|
|
102
|
+
Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
|
|
103
|
+
|
|
104
|
+
Math extensions done by B. Jackowski, P. Strzelczyk and P. Pianowski
|
|
105
|
+
(on behalf of TeX users groups) are in public domain.
|
|
106
|
+
|
|
107
|
+
Letters imported from Euler Fraktur from AMSfonts are (c) American
|
|
108
|
+
Mathematical Society (see below).
|
|
109
|
+
Bitstream Vera Fonts Copyright
|
|
110
|
+
Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera
|
|
111
|
+
is a trademark of Bitstream, Inc.
|
|
112
|
+
|
|
113
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
114
|
+
of the fonts accompanying this license (“Fonts”) and associated
|
|
115
|
+
documentation
|
|
116
|
+
files (the “Font Software”), to reproduce and distribute the Font Software,
|
|
117
|
+
including without limitation the rights to use, copy, merge, publish,
|
|
118
|
+
distribute,
|
|
119
|
+
and/or sell copies of the Font Software, and to permit persons to whom
|
|
120
|
+
the Font Software is furnished to do so, subject to the following
|
|
121
|
+
conditions:
|
|
122
|
+
|
|
123
|
+
The above copyright and trademark notices and this permission notice
|
|
124
|
+
shall be
|
|
125
|
+
included in all copies of one or more of the Font Software typefaces.
|
|
126
|
+
|
|
127
|
+
The Font Software may be modified, altered, or added to, and in particular
|
|
128
|
+
the designs of glyphs or characters in the Fonts may be modified and
|
|
129
|
+
additional
|
|
130
|
+
glyphs or characters may be added to the Fonts, only if the fonts are
|
|
131
|
+
renamed
|
|
132
|
+
to names not containing either the words “Bitstream” or the word “Vera”.
|
|
133
|
+
|
|
134
|
+
This License becomes null and void to the extent applicable to Fonts or
|
|
135
|
+
Font Software
|
|
136
|
+
that has been modified and is distributed under the “Bitstream Vera”
|
|
137
|
+
names.
|
|
138
|
+
|
|
139
|
+
The Font Software may be sold as part of a larger software package but
|
|
140
|
+
no copy
|
|
141
|
+
of one or more of the Font Software typefaces may be sold by itself.
|
|
142
|
+
|
|
143
|
+
THE FONT SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
144
|
+
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
|
|
145
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
|
|
146
|
+
TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
|
|
147
|
+
FOUNDATION
|
|
148
|
+
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL,
|
|
149
|
+
SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN
|
|
150
|
+
ACTION
|
|
151
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR
|
|
152
|
+
INABILITY TO USE
|
|
153
|
+
THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
|
|
154
|
+
Except as contained in this notice, the names of GNOME, the GNOME
|
|
155
|
+
Foundation,
|
|
156
|
+
and Bitstream Inc., shall not be used in advertising or otherwise to promote
|
|
157
|
+
the sale, use or other dealings in this Font Software without prior written
|
|
158
|
+
authorization from the GNOME Foundation or Bitstream Inc., respectively.
|
|
159
|
+
For further information, contact: fonts at gnome dot org.
|
|
160
|
+
|
|
161
|
+
AMSFonts (v. 2.2) copyright
|
|
162
|
+
|
|
163
|
+
The PostScript Type 1 implementation of the AMSFonts produced by and
|
|
164
|
+
previously distributed by Blue Sky Research and Y&Y, Inc. are now freely
|
|
165
|
+
available for general use. This has been accomplished through the
|
|
166
|
+
cooperation
|
|
167
|
+
of a consortium of scientific publishers with Blue Sky Research and Y&Y.
|
|
168
|
+
Members of this consortium include:
|
|
169
|
+
|
|
170
|
+
Elsevier Science IBM Corporation Society for Industrial and Applied
|
|
171
|
+
Mathematics (SIAM) Springer-Verlag American Mathematical Society (AMS)
|
|
172
|
+
|
|
173
|
+
In order to assure the authenticity of these fonts, copyright will be
|
|
174
|
+
held by
|
|
175
|
+
the American Mathematical Society. This is not meant to restrict in any way
|
|
176
|
+
the legitimate use of the fonts, such as (but not limited to) electronic
|
|
177
|
+
distribution of documents containing these fonts, inclusion of these fonts
|
|
178
|
+
into other public domain or commercial font collections or computer
|
|
179
|
+
applications, use of the outline data to create derivative fonts and/or
|
|
180
|
+
faces, etc. However, the AMS does require that the AMS copyright notice be
|
|
181
|
+
removed from any derivative versions of the fonts which have been altered in
|
|
182
|
+
any way. In addition, to ensure the fidelity of TeX documents using Computer
|
|
183
|
+
Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
|
|
184
|
+
has requested that any alterations which yield different font metrics be
|
|
185
|
+
given a different name.
|
|
186
|
+
|
|
187
|
+
$Id$
|