Add script for finding missing `IO` specializations #683

jeltsch · 2025-04-14T17:18:07Z

This pull requests adds a script that helps in finding missing IO specializations, along with some example input and output.

When running the command scripts/find-missing-io-specialisations.sh src/**/*.hs on my Ubuntu 24.04 machine while being at the current main tip, 78a3231, I get the following output:

Database.LSMTree.Internal.Arena.newArenaManager
Database.LSMTree.Internal.Arena.withArena
Database.LSMTree.Internal.Arena.scrambleArena
Database.LSMTree.Internal.Arena.scrambleBlock
Database.LSMTree.Internal.Arena.withUnmanagedArena
Database.LSMTree.Internal.Arena.allocateFromArena
Database.LSMTree.Internal.Arena.newBlockWithFree
Database.LSMTree.Internal.BlobFile.readBlob
Database.LSMTree.Internal.BlobRef.releaseBlobRef
Database.LSMTree.Internal.BlobRef.readRawBlobRef
Database.LSMTree.Internal.ChecksumHandle.dropCache
Database.LSMTree.Internal.ChecksumHandle.closeHandle
Database.LSMTree.Internal.CRC32C.expectValidFile
Database.LSMTree.Internal.doesSnapshotDirExist
Database.LSMTree.Internal.IncomingRun.newIncomingSingleRun
Database.LSMTree.Internal.IncomingRun.newIncomingMergingRun
Database.LSMTree.Internal.IncomingRun.depositNominalCredits
Database.LSMTree.Internal.Merge.writeReaderEntry
Database.LSMTree.Internal.Merge.writeSerialisedEntry
Database.LSMTree.Internal.MergeSchedule.mkUnionCache
Database.LSMTree.Internal.MergeSchedule.duplicateUnionCache
Database.LSMTree.Internal.MergeSchedule.releaseUnionCache
Database.LSMTree.Internal.MergingRun.unsafeNew
Database.LSMTree.Internal.MergingRun.mergeType
Database.LSMTree.Internal.MergingRun.atomicReadCredits
Database.LSMTree.Internal.MergingRun.atomicModifyInt
Database.LSMTree.Internal.MergingRun.supplyChecked
Database.LSMTree.Internal.MergingRun.supplyCreditsRelative
Database.LSMTree.Internal.MergingRun.supplyCreditsAbsolute
Database.LSMTree.Internal.MergingTree.expectCompleted
Database.LSMTree.Internal.MergingTree.Lookup.mapMStrict
Database.LSMTree.Internal.RunReader.seekToDiskPage
Database.LSMTree.Internal.UniqCounter.newUniqCounter
Database.LSMTree.Internal.UniqCounter.incrUniqCounter
Database.LSMTree.Internal.Vector.mapMStrict
Database.LSMTree.Internal.Vector.imapMStrict
Database.LSMTree.Internal.Vector.forMStrict
Database.LSMTree.Internal.Vector.unsafeInsertWithMStrict

It should be checked that the same output arises on other systems, in particular such that do not use GNU sed.

wenkokke · 2025-04-14T17:28:42Z

As a preliminary note, it would be good to change the script to require no parameters (ie inline the source glob) and perhaps rename it to start with lint, for consistency.

jeltsch · 2025-04-14T17:46:16Z

I‘d like to keep the flexibility of being able to pass arbitrarily chosen Haskell source code to the script but realize that it would be good to have a script that just checks the present source code (probably of the main library only). What about keeping the script as it is and adding a wrapper script that passes the main library’s modules and have its name start with lint-?

wenkokke · 2025-04-14T20:33:52Z

What about keeping the script as it is and adding a wrapper script that passes the main library’s modules and have its name start with lint-?

Sounds great! Another option would be to default to all Haskell files (or just src/**/*.hs) but allow the first argument to the script to override this.

scripts/find-missing-io-specialisations.sh

wenkokke · 2025-04-15T11:19:33Z

I think it might be a good idea to add dinner comments to the sed script that explain the logic a bit, not per se on a command by command basis, but to explain the algorithm.

wenkokke · 2025-04-15T13:17:34Z

OTOH, it's sufficiently clear the script isn't malicious, so once there's a CI job that runs it on macOS and Windows, I'm happy to merge it under the understanding that it's not a complete guarantee on the absence of missing specialisations... which is true anyway, given the assumptions it makes.

jorisdral · 2025-04-15T13:46:56Z

Are there cases where the script returns false positives, and if not now, is it conceivable that it could do so in the future? If so, it might be good to think about how such false positives could be addressed, specially if it's a CI job we run that can hold up PRs

wenkokke · 2025-04-15T16:57:01Z

Are there cases where the script returns false positives, and if not now, is it conceivable that it could do so in the future? If so, it might be good to think about how such false positives could be addressed, specially if it's a CI job we run that can hold up PRs

@jeltsch already floated the idea of an allowlist for false positives.

jeltsch · 2025-04-16T14:35:13Z

f0f80d6 disables reporting of operations with inline directives. The expected result of running scripts/find-missing-io-specialisations.sh src/**/*.hs is now as follows:

Database.LSMTree.Internal.Arena.newArenaManager
Database.LSMTree.Internal.Arena.scrambleArena
Database.LSMTree.Internal.Arena.scrambleBlock
Database.LSMTree.Internal.Arena.withUnmanagedArena
Database.LSMTree.Internal.Arena.allocateFromArena
Database.LSMTree.Internal.Arena.newBlockWithFree
Database.LSMTree.Internal.ChecksumHandle.dropCache
Database.LSMTree.Internal.ChecksumHandle.closeHandle
Database.LSMTree.Internal.CRC32C.expectValidFile
Database.LSMTree.Internal.doesSnapshotDirExist
Database.LSMTree.Internal.IncomingRun.depositNominalCredits
Database.LSMTree.Internal.MergeSchedule.mkUnionCache
Database.LSMTree.Internal.MergeSchedule.duplicateUnionCache
Database.LSMTree.Internal.MergeSchedule.releaseUnionCache
Database.LSMTree.Internal.MergingTree.expectCompleted
Database.LSMTree.Internal.MergingTree.Lookup.mapMStrict
Database.LSMTree.Internal.RunReader.seekToDiskPage

jeltsch · 2025-04-16T15:01:09Z

OTOH, it's sufficiently clear the script isn't malicious, so once there's a CI job that runs it on macOS and Windows, I'm happy to merge it under the understanding that it's not a complete guarantee on the absence of missing specialisations... which is true anyway, given the assumptions it makes.

Are you thinking here of a CI job that applies the script to the codebase to ensure that there are no missing specializations or one that tests the script using the data in scripts/find-missing-io-specialisations.test?

Beside that, do you think it is necessary to have CI run this script on Windows? After all, it’s not part of the software we want to ship in the end but a utility intended to help us (and perhaps future contributors). I mean, if supporting Windows, using some Unix compatibility layer, is easy, then I’m not against it; I just don’t want to spend much effort on making this script Windows-compatible (note that initially I intended this script to just assist me in a particular task and not even make it into the repository 🙂)

jeltsch · 2025-04-16T19:40:00Z

I think it might be a good idea to add dinner comments to the sed script that explain the logic a bit, not per se on a command by command basis, but to explain the algorithm.

Done in 325c20e.

jeltsch · 2025-04-20T12:22:25Z

What about keeping the script as it is and adding a wrapper script that passes the main library’s modules and have its name start with lint-?

Sounds great!

I’ve realized this in 539f06a. The wrapper script not only automatically picks the source files of the main library but also enables users to explicitly allow certain missing IO specializations.

wenkokke · 2025-04-30T11:03:51Z

I've opened #697 which contains the changes in this PR, plus a few fixes.

The top-level script uses set -e which is not a POSIX shell feature and only works on Ubuntu because it lies and symlinks /bin/sh to /bin/bash.
The sed script does not work with macOS sed. Rather than fixing the sed script, I've altered the shell script to ask for gsed.

jeltsch · 2025-05-14T16:12:13Z

I’ve added another three commits, which contain changes from #697 and variants thereof.

jeltsch · 2025-05-14T16:25:51Z

The top-level script uses set -e which is not a POSIX shell feature and only works on Ubuntu because it lies and symlinks /bin/sh to /bin/bash.

Actually, set -e is a POSIX feature, at least according to the 2024 version of the standard.

Calling sh when sh is linked to bash doesn’t lead to a normal Bash session but one in POSIX compatibility mode. So “lying” is a bit of a strong accusation here (I guess nobody expects sh to be Stephen Bourne’s shell from 1979). 😉 Also note that some time ago Ubuntu changed the sh link to point to dash, Debian’s version of the Almquist Shell, a lean shell that actually lacks some POSIX features (at least the pipefail option).

jeltsch · 2025-05-14T16:28:29Z

The sed script does not work with macOS sed. Rather than fixing the sed script, I've altered the shell script to ask for gsed.

This was apparently a good idea. As we discussed already in the meeting, there seems to be no easy way to compare strings with sed in a fully POSIX-compatible way, as POSIX doesn’t guarantee backreferences in regular expressions to work.

wenkokke

LGTM. Are you happy to merge this in the current state, @jeltsch?

dcoutts

This all looks very impressive. I've never seen such a sophisticated sed script. All my sed scripts are one liners!

jeltsch · 2025-05-29T12:35:09Z

LGTM. Are you happy to merge this in the current state, @jeltsch?

Yes. 🙂 I’ll rebase it in a minute and then initiate the merging.

jeltsch · 2025-05-29T12:38:34Z

This all looks very impressive. I've never seen such a sophisticated sed script. All my sed scripts are one liners!

Glad that I managed to impress you. 😉

jeltsch requested review from dcoutts, jorisdral, mheinzel, recursion-ninja and wenkokke as code owners April 14, 2025 17:18

jeltsch self-assigned this Apr 14, 2025

jeltsch added the enhancement New feature or request label Apr 14, 2025

wenkokke reviewed Apr 15, 2025

View reviewed changes

scripts/find-missing-io-specialisations.sh Outdated Show resolved Hide resolved

jeltsch force-pushed the jeltsch/find-missing-io-specialisations branch 4 times, most recently from 130de00 to b018b5a Compare April 20, 2025 17:30

wenkokke mentioned this pull request Apr 30, 2025

Find missing IO specializations #697

Closed

jeltsch force-pushed the jeltsch/find-missing-io-specialisations branch 2 times, most recently from 75fc37b to 92e2a8e Compare May 20, 2025 14:35

wenkokke approved these changes May 28, 2025

View reviewed changes

wenkokke added this pull request to the merge queue May 28, 2025

wenkokke removed this pull request from the merge queue due to a manual request May 28, 2025

dcoutts approved these changes May 29, 2025

View reviewed changes

jeltsch added 14 commits May 29, 2025 15:37

Add script for finding missing IO specializations

1770af4

Disable reporting of operations with inline directives

897232f

Add comments to the sed script

700173d

Disable reporting of operations with unconstrained types

f37213f

Add IO specialisation linting script

e65b581

Make linters not consider the IO specialisation tests

4e022e5

Move the definition of static variables to the top

02acfcf

Add workflow job for IO specialisation linting

1649bed

Make sure that top-level modules are checked

174e47e

Clarify the description of the linting task

7a77b4a

Make find-absent.sh insist on using GNU sed

dc68c59

Rename io-specialisations to lint-io-specialisations

eaa1c94

Add missing IO specialization for hGetByteArrayExactly

cecde94

Correct the stated reason for the use of GNU sed

a5f12f9

jeltsch force-pushed the jeltsch/find-missing-io-specialisations branch from e05b1e4 to a5f12f9 Compare May 29, 2025 12:37

jeltsch enabled auto-merge May 29, 2025 12:37

jeltsch added this pull request to the merge queue May 29, 2025

Merged via the queue into main with commit a3efabc May 29, 2025
30 checks passed

jeltsch deleted the jeltsch/find-missing-io-specialisations branch May 29, 2025 13:45

Add script for finding missing IO specializations #683

Add script for finding missing IO specializations #683

Uh oh!

Conversation

jeltsch commented Apr 14, 2025

Uh oh!

wenkokke commented Apr 14, 2025

Uh oh!

jeltsch commented Apr 14, 2025

Uh oh!

wenkokke commented Apr 14, 2025

Uh oh!

Uh oh!

wenkokke commented Apr 15, 2025

Uh oh!

wenkokke commented Apr 15, 2025

Uh oh!

jorisdral commented Apr 15, 2025

Uh oh!

wenkokke commented Apr 15, 2025

Uh oh!

jeltsch commented Apr 16, 2025

Uh oh!

jeltsch commented Apr 16, 2025

Uh oh!

jeltsch commented Apr 16, 2025

Uh oh!

jeltsch commented Apr 20, 2025

Uh oh!

wenkokke commented Apr 30, 2025

Uh oh!

jeltsch commented May 14, 2025

Uh oh!

jeltsch commented May 14, 2025

Uh oh!

jeltsch commented May 14, 2025

Uh oh!

wenkokke left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcoutts left a comment

Choose a reason for hiding this comment

Uh oh!

jeltsch commented May 29, 2025

Uh oh!

jeltsch commented May 29, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Add script for finding missing `IO` specializations #683

Add script for finding missing `IO` specializations #683

wenkokke left a comment •

edited

Loading