Skip to content

Commit 39bd7be

Browse files
cristianocclaude
andauthored
Semantic diff: draw reanalyze reports as findings (#8929)
Draw reanalyze reports as findings on the Semantic Diff page Why: A reanalyze change is the findings that appear, disappear or stay for a program. The page draws them as findings, aligned Before and After. A `Reanalyze` kind names reanalyze's findings for a program, and a `reanalyze` form holds the report as reanalyze prints it. Each finding is a row: the analysis tagged (once in the caption when every finding shares it), the location and the message. Before and After align by finding: a finding one report lacks faces a gap, a run of findings in both reports is one row that opens to show them, and a changed note such as the closing count faces its other version with the differing words marked. The skill states that a form holds a representative selection, with `…` marking what is left out, that its locations point into the example or a named file, and the command that prints a report. Signed-off-by: Cristiano Calcagno <cristianoc@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent b60e855 commit 39bd7be

4 files changed

Lines changed: 473 additions & 18 deletions

File tree

‎.claude/skills/records/SKILL.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,8 @@ Signed-off-by: Name <email>
7373
side, or once, with the captions, when the two are equal; a form with
7474
one version across the block under its version's label. Trees, code,
7575
text, matrices and mappings are drawn on aligned rows, a line common to
76-
both versions facing itself and the changed lines shaded; typing rules
76+
both versions facing itself and the changed lines shaded; reanalyze
77+
reports are drawn as rows of findings, aligned the same way; typing rules
7778
and rewrites are drawn as two figures side by side, the changed parts
7879
shaded: premises, conclusions, rule names and formulas, and each term of
7980
a rewrite against the term at its position.
@@ -95,6 +96,7 @@ The table lists the common kinds.
9596
| `Diagnostic` | an error or warning |
9697
| `Format` | the formatter's output |
9798
| `Representation` | how a value is represented in JavaScript |
99+
| `Reanalyze` | reanalyze's findings for a program |
98100

99101
## Forms
100102

@@ -111,7 +113,16 @@ The table lists the common kinds.
111113
| `rule` | inference rules and formulas | inference rule |
112114
| `matrix` | a clause matrix | matrix |
113115
| `representation` | how ReScript values map to JavaScript | mapping |
114-
116+
| `reanalyze` | the report exactly as reanalyze prints it | findings |
117+
118+
- A form holds a representative selection of the output, enough to see
119+
what changes and what stays; an example shows only the cases that
120+
matter. A line `…`, alone or followed by text such as
121+
`… 4 more like this`, marks the lines left out and is drawn muted.
122+
- The forms are the output for the example as shown, so the locations and
123+
names in them point into the example. Forms taken from a larger file,
124+
such as a test fixture, name that file in a caption, for example
125+
`Before (reanalyze): tests/…/Division.res`.
115126
- A tree is indented lines, two spaces a level, as the compiler prints it:
116127
`bsc -bs-no-builtin-ppx -only-parse -dparsetree file.res` prints the
117128
parse tree, `bsc -only-parse -dparsetree` the expanded one, and
@@ -131,6 +142,21 @@ The table lists the common kinds.
131142
cell a pattern; `label: text` lines are notes under it.
132143
- A `representation` is `ReScript ↦ JavaScript` lines; `label: text` lines
133144
are notes among them.
145+
- A `reanalyze` report is findings separated by blank lines, each an
146+
analysis line, a location line and the message. A report shows, for
147+
example, one finding that disappears, one that stays and the closing
148+
line with the totals, and a paragraph `…` stands for the findings left
149+
out. Each finding is a row: the analysis tagged, the location, the
150+
message; an analysis that every finding names tags the form once.
151+
Before and After align findings by their text: a run of findings in
152+
both reports is one row that opens to show them, a finding one report
153+
lacks faces a gap, and a note that changes, such as the closing count,
154+
faces its other version with the differing words marked. In a built
155+
project such as
156+
`tests/analysis_tests/tests-reanalyze/deadcode` (`yarn build` there),
157+
`dune exec rescript-tools -- reanalyze -exception -ci -suppress src -unsuppress src/<dir>`
158+
prints the exception analysis's report for the files under `src/<dir>`;
159+
`-dce` and `-termination` select the other analyses.
134160
- A form of another name is drawn as text.
135161

136162
## When to add a block
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- Semantic Diff pages draw reanalyze reports as findings, Before and After aligned by finding.

‎scripts/commitRecords.test.js‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -670,3 +670,153 @@ ${SIGNED}
670670
has(html, '<span class="stamp">/1002</span>');
671671
has(html, '<span class="p">#raw_expr</span>');
672672
});
673+
674+
const DIVIDE = `Exception Analysis
675+
Division.res:1:5-10
676+
divide might throw Division_by_zero (Division.res:1:27) and is not annotated with @throws(Division_by_zero)`;
677+
const DIVIDE_BY = `Exception Analysis
678+
Division.res:2:5-12
679+
divideBy might throw Division_by_zero (Division.res:2:37) and is not annotated with @throws(Division_by_zero)`;
680+
681+
const DEAD = `Warning Dead Value
682+
DeadTest.res:3:1-10
683+
deadValue is never used`;
684+
685+
test("a reanalyze report draws its findings aligned by identity, one analysis tagging the form", async () => {
686+
const html = await renderOne(`Skip literal divisors
687+
688+
Reanalyze modified (division):
689+
Before (reanalyze):
690+
${indented(`\n${DIVIDE}\n\n${DIVIDE_BY}`, " ")}
691+
After (reanalyze):
692+
${indented(`\n${DIVIDE_BY}`, " ")}
693+
694+
${SIGNED}
695+
`);
696+
has(
697+
html,
698+
'<h5 class="form"><span class="lang">reanalyze</span> <span class="tag">Exception Analysis</span></h5>',
699+
);
700+
has(html, '<div class="report rows-report">');
701+
has(
702+
html,
703+
'<div class="finding del" style="--r:1;--c:1"><div class="where"><code class="loc">Division.res:1:5-10</code></div><div class="msg">divide might throw Division_by_zero (<span class="ref">Division.res:1:27</span>) and is not annotated with <span class="a">@throws(Division_by_zero)</span></div></div>',
704+
);
705+
has(html, '<div class="finding gap" style="--r:1;--c:2"></div>');
706+
has(
707+
html,
708+
'<details class="same" style="--r:2"><summary>1 unchanged finding</summary><div class="report rows-report"><div class="finding" style="--r:1;--c:1"><div class="where"><code class="loc">Division.res:2:5-12</code>',
709+
);
710+
has(html, '<div class="finding dup" style="--r:1;--c:2">');
711+
assert.equal(html.split('<div class="finding del"').length - 1, 1);
712+
lacks(html, '<div class="finding add"');
713+
lacks(html, '<div class="where"><span class="tag">');
714+
});
715+
716+
test("an added finding is shaded added, and findings of several analyses keep their tags", async () => {
717+
const html = await renderOne(`Report dead values
718+
719+
Reanalyze modified (dead code):
720+
Before (reanalyze):
721+
${indented(`${DIVIDE}\n\nAnalysis reported 1 issues`, " ")}
722+
After (reanalyze):
723+
${indented(`${DEAD}\n\n${DIVIDE}\n\nAnalysis reported 2 issues (Warning Dead Value:1)`, " ")}
724+
725+
Reanalyze added (termination):
726+
After (reanalyze):
727+
Error Termination
728+
TestCyberTruck.res:29:28-39
729+
Possible infinite loop when calling alwaysLoop
730+
CallStack:
731+
1 alwaysLoop (TestCyberTruck.res:29)
732+
733+
${SIGNED}
734+
`);
735+
has(html, '<h5 class="form"><span class="lang">reanalyze</span></h5>');
736+
has(
737+
html,
738+
'<div class="finding add" style="--r:1;--c:2"><div class="where"><span class="tag">Warning Dead Value</span><code class="loc">DeadTest.res:3:1-10</code></div><div class="msg">deadValue is never used</div></div>',
739+
);
740+
has(html, '<div class="finding gap" style="--r:1;--c:1"></div>');
741+
has(
742+
html,
743+
'<summary>1 unchanged finding</summary><div class="report rows-report"><div class="finding" style="--r:1;--c:1"><div class="where"><span class="tag">Exception Analysis</span>',
744+
);
745+
has(
746+
html,
747+
'<div class="finding note mod" style="--r:3;--c:1"><div class="msg">Analysis reported <span class="del">1</span> issues</div></div>',
748+
);
749+
has(
750+
html,
751+
'<div class="finding note mod" style="--r:3;--c:2"><div class="msg">Analysis reported <span class="add">2</span> issues <span class="add">(</span>',
752+
);
753+
has(
754+
html,
755+
'<h5 class="form"><span class="lang">reanalyze</span> <span class="tag">Error Termination</span></h5><figure class="one"><figcaption class="vlabel">After</figcaption><div class="report"><div class="finding"><div class="where"><code class="loc">TestCyberTruck.res:29:28-39</code></div><div class="msg">Possible infinite loop when calling alwaysLoop\nCallStack:\n 1 alwaysLoop (TestCyberTruck.res:29)</div></div></div></figure>',
756+
);
757+
});
758+
759+
test("a run of unchanged findings is one row, and a changed count is one row", async () => {
760+
const html = await renderOne(`Skip literal divisors
761+
762+
Reanalyze modified (division):
763+
Before (reanalyze):
764+
${indented(`\n${DIVIDE}\n\n${DIVIDE_BY}\n\n${DIVIDE_BY.replaceAll("divideBy", "divideTo")}\n\nAnalysis reported 3 issues (Exception Analysis:3)`, " ")}
765+
After (reanalyze):
766+
${indented(`\n${DIVIDE_BY}\n\n${DIVIDE_BY.replaceAll("divideBy", "divideTo")}\n\nAnalysis reported 2 issues (Exception Analysis:2)`, " ")}
767+
768+
${SIGNED}
769+
`);
770+
has(
771+
html,
772+
'<details class="same" style="--r:2"><summary>2 unchanged findings</summary>',
773+
);
774+
has(html, '<div class="finding" style="--r:2;--c:1"><div class="where">');
775+
has(html, '<div class="finding dup" style="--r:2;--c:2"><div class="where">');
776+
has(html, "divideTo might throw");
777+
assert.equal(html.split('<details class="same"').length - 1, 1);
778+
has(
779+
html,
780+
'<div class="finding note mod" style="--r:3;--c:1"><div class="msg">Analysis reported <span class="del">3</span> issues (Exception Analysis:<span class="del">3</span>)</div></div>',
781+
);
782+
has(
783+
html,
784+
'<div class="finding note mod" style="--r:3;--c:2"><div class="msg">Analysis reported <span class="add">2</span> issues (Exception Analysis:<span class="add">2</span>)</div></div>',
785+
);
786+
lacks(html, '<div class="finding note del"');
787+
lacks(html, '<div class="finding note add"');
788+
has(
789+
html,
790+
".finding { background:var(--surface); border:1px solid var(--rule); border-radius:6px;",
791+
);
792+
});
793+
794+
test("an elision in a report is a muted row, and in code a muted line", async () => {
795+
const html = await renderOne(`Skip literal divisors
796+
797+
Reanalyze modified (division):
798+
Before (reanalyze):
799+
${indented(`${DIVIDE}\n\n… 4 more like this\n\n${DIVIDE_BY}`, " ")}
800+
After (reanalyze):
801+
${indented(`${DIVIDE_BY}`, " ")}
802+
803+
JS modified (division):
804+
Before (js):
805+
let a = 1;
806+
…
807+
After (js):
808+
let a = 2;
809+
… 3 more lines
810+
811+
${SIGNED}
812+
`);
813+
has(
814+
html,
815+
'<div class="finding elide" style="--r:2;--c:1"><div class="msg">… 4 more like this</div></div>',
816+
);
817+
has(html, '<div class="finding gap" style="--r:2;--c:2"></div>');
818+
lacks(html, "finding elide del");
819+
has(html, '<span class="ln elide" style="--r:3;--c:1;--i:0">…</span>');
820+
has(html, '<span class="ln elide" style="--r:3;--c:2;--i:0">… ');
821+
has(html, '<span class="ln del" style="--r:2;--c:1;--i:0">');
822+
});

0 commit comments

Comments
 (0)