Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(manifest): preserve comments in JSON5 manifests
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 pnpm#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.]
- Loading branch information
Showing
8 changed files
with
488 additions
and
153 deletions.
There are no files selected for viewing
9 changes: 9 additions & 0 deletions
9
packages/read-project-manifest/fixtures/commented-package-json5/modified.json5
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
/* This is an example of a package.json5 file with comments. */ | ||
{ | ||
/* pnpm should keep comments at the same indentation level */ | ||
name: 'foo', | ||
version: '1.0.0', // it should keep in-line comments on the same line | ||
// It should allow in-line comments with no other content | ||
type: 'commonjs', | ||
} | ||
/* And it should preserve comments at the end of the file. Note no newline. */ |
9 changes: 9 additions & 0 deletions
9
packages/read-project-manifest/fixtures/commented-package-json5/package.json5
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
/* This is an example of a package.json5 file with comments. */ | ||
{ | ||
/* pnpm should keep comments at the same indentation level */ | ||
name: 'foo', | ||
version: '1.0.0', // it should keep in-line comments on the same line | ||
// It should allow in-line comments with no other content | ||
type: 'module', | ||
} | ||
/* And it should preserve comments at the end of the file. Note no newline. */ |
2 changes: 2 additions & 0 deletions
2
packages/read-project-manifest/src/types/strip-comments-strings/index.d.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
// strip-comments-strings/index.d.ts | ||
declare module 'strip-comments-strings'; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.