O que? Por que

Para o bem ou para o mal, o conteúdo de package.json tem crescido com complexidade cada vez maior. Nos primórdios do npm, o arquivo era simplesmente alguns metadados das dependências das quais um projeto / pacote dependia. Os projetos cresceram em complexidade e agora os testes, estruturas e outras bibliotecas são todas dependências que apareceriam juntas. Houve alguma separação com dependencies e devDependencies , mas essa é uma categorização aproximada. Agora temos ferramentas contribuindo e tomando residência no package.json com maior complexidade ... configurações monorepo, configurações de lint, configurações de commit, git hooks, nodemon, jest, a lista continua ...

Os comentários oferecem uma maneira de explicar toda a complexidade.

Ainda acho que os mantenedores da biblioteca ainda deveriam estar usando JSON puro para compatibilidade com versões anteriores, mas pelo menos oferecer esse avanço permitirá aos criadores de projetos (a grande maioria dos usuários) a capacidade de documentar seu package.json. Concedido, json permite que chaves duplicadas sirvam como comentários, mas isso parece muito com um hack.

Quão

Comportamento Atual

Um exemplo redigido e artificial:

{
  "name": "my-project",
  "version": "0.0.1",
  "license": "MIT",
  "scripts": {
    "build": "a bunch of scripts",
    "ci": "a bunch of scripts",
    "ci:local": "a bunch of scripts",
    "docsite": "a bunch of scripts",
    "docsite:combiner": "a bunch of scripts",
    "docsite:sassdoc": "a bunch of scripts",
    "docsite:tsdoc": "a bunch of scripts",
    "e2e": "a bunch of scripts",
    "html-sketchapp-install": "a bunch of scripts",
    "html-sketchapp": "a bunch of scripts",
    "lint": "a bunch of scripts",
    "sassdoc": "a bunch of scripts",
    "sassdoc:comp": "a bunch of scripts",
    "sassdoc:core": "a bunch of scripts",
    "start": "a bunch of scripts",
    "start:hmr": "a bunch of scripts",
    "start:qa": "a bunch of scripts",
    "start:dev": "a bunch of scripts",
    "generate-examples": "a bunch of scripts",
    "rebuild-markdown": "a bunch of scripts",
    "watch-examples": "a bunch of scripts",
    "test:cov": "a bunch of scripts",

    "test": "jest",
    "test:watch": "jest --watch",
    "test:cc": "jest --coverage"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  },
  "dependencies": {
    "@angular-devkit/build-angular": "~0.900.1",
    "@angular-devkit/build-ng-packagr": "~0.900.1",
    "@angular-devkit/core": "~9.0.0",
    "@angular-devkit/schematics": "~9.0.0",
    "@angular/animations": "~9.0.0",
    "@angular/cdk": "~9.0.0",
    "@angular/cli": "~9.0.1",
    "@angular/common": "~9.0.0",
    "@angular/compiler": "~9.0.0",
    "@angular/compiler-cli": "~9.0.0",
    "@angular/core": "~9.0.0",
    "@angular/forms": "~9.0.0",
    "@angular/language-service": "~9.0.0",
    "@angular/platform-browser": "~9.0.0",
    "@angular/platform-browser-dynamic": "~9.0.0",
    "@angular/router": "~9.0.0",
    "@angular/service-worker": "~9.0.0",
    "@angularclass/hmr": "2.1.3",
    "@ngrx/effects": "~8.6.0",
    "@ngrx/entity": "~8.6.0",
    "@ngrx/router-store": "~8.6.0",
    "@ngrx/schematics": "~8.6.0",
    "@ngrx/store": "~8.6.0",
    "@ngrx/store-devtools": "~8.6.0",
    "@types/jasmine": "~3.5.0",
    "@types/jasminewd2": "~2.0.3",
    "@types/lodash-es": "^4.17.3",
    "@types/node": "^12.11.1",
    "classlist.js": "1.1.20150312",
    "codelyzer": "^5.1.2",
    "console-polyfill": "0.3.0",
    "core-js": "^2.5.4",
    "cz-conventional-changelog": "1.2.0",
    "date-fns": "1.30.1",
    "highcharts": "^7.2.1",
    "highcharts-angular": "^2.4.0",
    "html2canvas": "^1.0.0-rc.5",
    "jasmine-core": "~3.5.0",
    "jasmine-spec-reporter": "~4.2.1",
    "karma": "~4.3.0",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage-istanbul-reporter": "~2.1.0",
    "karma-jasmine": "~2.0.1",
    "karma-jasmine-html-reporter": "^1.4.2",
    "lodash-es": "^4.17.11",
    "mime": "~2.4.2",
    "ngrx-store-freeze": "0.2.4",
    "ngx-monaco-editor": "~8.0.0",
    "ngx-quill": "^7.3.12",
    "pdfmake": "^0.1.64",
    "prettier": "1.19.1",
    "protractor": "~5.4.3",
    "quill": "^1.3.7",
    "rxjs": "~6.5.4",
    "rxjs-compat": "^6.0.0",
    "standard-changelog": "1.0.19",
    "svgxuse": "1.2.6",
    "ts-node": "~8.3.0",
    "tsickle": "^0.35.0",
    "tslib": "^1.10.0",
    "tslint": "~5.18.0",
    "typescript": "~3.7.5",
    "web-animations-js": "~2.3.1",
    "zone.js": "~0.10.2"
  },
  "devDependencies": {
    "@types/jest": "^24.0.6",
    "jest": "^24.1.0",
    "jest-preset-angular": "^6.0.2",
    "ts-node": "~7.0.1",
    "typescript": "3.2.4"
  },
  "jest": {
    "preset": "jest-preset-angular",
    "setupTestFrameworkScriptFile": "<rootDir>/setupJest.ts"
  },
  "nodemonConfig": {
    "ignore": [
      "**/example-module.ts"
    ],
    "watch": [
      "./a/bunch/of/stuff"
    ],
    "ext": "js ts md html"
  },
  "workspaces": {
    "packages": [
      "packages/*"
    ],
    "nohoist": [
      "**"
    ]
  }
}

Comportamento esperado

Um exemplo de package.json com comentários.

{
  "name": "my-project",
  "version": "0.0.1",
  "license": "MIT",
  "scripts": {
    "build": "a bunch of scripts",
    "ci": "a bunch of scripts",
    "ci:local": "a bunch of scripts",
    // for building our documentation site
    "docsite": "a bunch of scripts",
    "docsite:combiner": "a bunch of scripts",
    "docsite:sassdoc": "a bunch of scripts",
    "docsite:tsdoc": "a bunch of scripts",
    "e2e": "a bunch of scripts",
    "lint": "a bunch of scripts",
    "sassdoc": "a bunch of scripts",
    "sassdoc:comp": "a bunch of scripts",
    "sassdoc:core": "a bunch of scripts",
    "start": "a bunch of scripts",
    "start:hmr": "a bunch of scripts",
    "start:qa": "a bunch of scripts",
    "start:dev": "a bunch of scripts",
    "generate-examples": "a bunch of scripts",
    "rebuild-markdown": "a bunch of scripts",
    "watch-examples": "a bunch of scripts",
    "test:cov": "a bunch of scripts",

    "test": "jest",
    "test:watch": "jest --watch",
    "test:cc": "jest --coverage"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  },
  "dependencies": {
    // ANGULAR
    "@angular-devkit/build-angular": "~0.900.1",
    "@angular-devkit/build-ng-packagr": "~0.900.1",
    "@angular-devkit/core": "~9.0.0",
    "@angular-devkit/schematics": "~9.0.0",
    "@angular/animations": "~9.0.0",
    "@angular/cdk": "~9.0.0",
    "@angular/cli": "~9.0.1",
    "@angular/common": "~9.0.0",
    "@angular/compiler": "~9.0.0",
    "@angular/compiler-cli": "~9.0.0",
    "@angular/core": "~9.0.0",
    "@angular/forms": "~9.0.0",
    "@angular/language-service": "~9.0.0",
    "@angular/platform-browser": "~9.0.0",
    "@angular/platform-browser-dynamic": "~9.0.0",
    "@angular/router": "~9.0.0",
    "@angular/service-worker": "~9.0.0",
    "@angularclass/hmr": "2.1.3",

    "zone.js": "~0.10.2",
    "rxjs": "~6.5.4",
    "rxjs-compat": "^6.0.0",


    // polyfills for angular 
    "console-polyfill": "0.3.0",
    "core-js": "^2.5.4",
    "classlist.js": "1.1.20150312",
    "svgxuse": "1.2.6",
    "web-animations-js": "~2.3.1",

    // lint management

    "codelyzer": "^5.1.2",
    "prettier": "1.19.1",
    "tslint": "~5.18.0",

    // changelog creation
    "cz-conventional-changelog": "1.2.0",
    "standard-changelog": "1.0.19",

    // ngrx state management 
    "@ngrx/effects": "~8.6.0",
    "@ngrx/entity": "~8.6.0",
    "@ngrx/router-store": "~8.6.0",
    "@ngrx/schematics": "~8.6.0",
    "@ngrx/store": "~8.6.0",
    "@ngrx/store-devtools": "~8.6.0",
    "ngrx-store-freeze": "0.2.4",


    // library deps

    // Graphs support
    "highcharts": "^7.2.1",
    "highcharts-angular": "^2.4.0",

    // for creating pdfs
    "html2canvas": "^1.0.0-rc.5",
    "pdfmake": "^0.1.64",

    // rich text support
    "ngx-quill": "^7.3.12",
    "quill": "^1.3.7",




    // testing
    "jasmine-core": "~3.5.0",
    "jasmine-spec-reporter": "~4.2.1",
    "karma": "~4.3.0",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage-istanbul-reporter": "~2.1.0",
    "karma-jasmine": "~2.0.1",
    "karma-jasmine-html-reporter": "^1.4.2",

    // e2e testing
    "protractor": "~5.4.3",

    // typscript and compilation
    "ts-node": "~8.3.0",
    "tsickle": "^0.35.0",
    "tslib": "^1.10.0",
    "typescript": "~3.7.5",

    // misc deps
    "date-fns": "1.30.1",
    "lodash-es": "^4.17.11",
    "mime": "~2.4.2"
  },
  "devDependencies": {
    "@types/jasmine": "~3.5.0",
    "@types/jasminewd2": "~2.0.3",
    "@types/lodash-es": "^4.17.3",
    "@types/node": "^12.11.1",
    "@types/jest": "^24.0.6",
    "jest": "^24.1.0",
    "jest-preset-angular": "^6.0.2",
    "ts-node": "~7.0.1",
    "typescript": "3.2.4"
  },
  // complicated jest configuration here
  "jest": {
    "preset": "jest-preset-angular",
    "setupTestFrameworkScriptFile": "<rootDir>/setupJest.ts"
  },
  // use nodemon to trigger stuff
  "nodemonConfig": {
    "ignore": [
      "**/example-module.ts"
    ],
    "watch": [
      "./a/bunch/of/stuff"
    ],
    "ext": "js ts md html"
  },
  // extra libraries we are creating internally
  "workspaces": {
    "packages": [
      "packages/*"
    ],
    "nohoist": [
      "**"
    ]
  }
}

Referências

https://github.com/microsoft/node-jsonc-parser

Typescript usa comentários em seus arquivos tsconfig.json.