random id's generated in .json output cause a lot of merge conflicts

[FirstVertex]

Search terms

.json, merge, id

Expected Behavior

When generating the .json output, there should be a reliable way to generate the node's id's which doesn't cause them to be scrambled each time it is generated.

Actual Behavior

Node id's get moved around which causes the entire .json output to fail git merge when 2 devs regenerated the .json output.

Steps to reproduce the bug

Use .json output format. Generate the output. Make a small addition to the jsdoc comments. Generate the json output again. Notice that the generated .json contains lots of changes to the id's of nodes.

tsconfig.json:

{
    "compilerOptions": {
        "declaration": true,
        "noImplicitAny": false,
        "strictNullChecks": false,
        "strictPropertyInitialization": false,
        "noFallthroughCasesInSwitch": true,
        "removeComments": false,
        "lib": ["dom", "es2017", "es2018"],
        "skipLibCheck": true,
        "module": "esnext",
        "target": "es2017",
        "moduleResolution": "node",
        "downlevelIteration": true,
        "noLib": false,
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "sourceMap": true,
        "rootDir": "src",
        "outDir": "dist",
        "baseUrl": ".",
        "paths": {
            "rxjs": ["node_modules/rxjs"]
        },
        "types": ["reflect-metadata", "jasmine"],
        "esModuleInterop": true
    },
    "exclude": ["node_modules", "tests", "dist", "test"]
}

How you are running TypeDoc + any relevant configuration files
npx typedoc --options typedoc-elements.json
typedoc-elements.json contents:

{
    "entryPoints": ["./src/elements/"],
    "exclude": ["./src/!(elements)/**"],
    "json": "../extensions/ext-docs/src/typeDocOut/ace-extension-elements.json",
    "excludePrivate": true,
    "excludeProtected": true,
    "excludeExternals": true,
    "includeVersion": true,
    "entryPointStrategy": "expand",
    "logLevel": "Error"
}

Environment

• Typedoc version: "~0.22.17"
• TypeScript version: "~4.7.2"
• Node.js version: 16.15.0
• OS: Windows 10

[Gerrit0]

ids are dependent on the order of conversion, which depends on what declarations are documented, so if you add a new export or remove something, I'd expect ids to change.

I tried adding a comment to a function and regenerating json docs with the latest version and saw no id changes. How ids are generated hasn't changed since I started maintaining TypeDoc years ago, so I'd expect it to be the same in the old version you're running.

I generally recommend not manually building docs with TypeDoc. I instead recommend setting up a pipeline to rebuild docs on push to the default branch and push the built site to a separate git repo/deploy branch, then devs don't have to remember to do so, or deal with merge conflicts. There's an example config in #1485 for GitHub actions.