Use npm package `strip-comments-strings` to find all comments in any
manifest file as it is read. Save them as part of the "file formatting"
detected by the manifest reader, noting for each the text of the lines
they are on, before, and after, and the line number as a fallback.
When the manifest is written, attempt to place each comment back in
the resulting JSON5 text, so that the text of the line it is on,
before, or after (in that priority order) matches the text at time of
reading. Otherwise, so that no comments are lost, replace the comment
on the same line number, adding a notation that it may have been
relocated (due to sorting dependencies, for example, it may no longer
be in the same "logical position" in the file, even though it is on
the same physical line number).
When comments are in fairly ordinary positions and the manifest does
not change too drastically (i.e. once the dependencies are sorted as
pnpm prefers, and there are not many parameters added all at once),
this strategy results in exact preservation of the comments, as a new
test shows.
The motivation for this commit is to take advantage of the feature of
JSON5 that it allows human-readable comments. For this feature to be
useful in the case of package.json5 manifests, those comments must be
preserved across manifest changes.
Partially resolves#2008. [That issue requests comment preservation
also for YAML manifests, but I have no experience working with YAML,
and it also requests that key order be preserved, but I did not
address key order because current code in the the pnpm manifest
reader/writer _explicitly_ reorders keys -- clearly deliberately --
so I did not want to simply remove code that appeared to have been
purposefully written and included.]
Co-authored-by: Zoltan Kochan <z@kochan.io>
