Summary
Three places where docs/library-format.md describes a shape the code does not produce. Grouped because they are one file, one class of problem, and one fix.
The doc's stated purpose is that "external tools can read library entries without going through CodeCartographer itself", which is what makes these worth correcting rather than leaving.
1. latest is documented as a symlink and is never one
Both directory layout diagrams show latest -> v2, and the version resolution section treats a plain file as the fallback "on filesystems without symlink support".
writeLatestPointer in core/library.ts is unconditionally writeFile plus rename. The module comment states the intent: "The latest pointer is always a regular file (containing the version directory name as a single line), never a symlink", chosen for determinism across platforms and to avoid the Windows elevation requirement.
The code behaviour is right. The doc has the primary case and the fallback the wrong way round, and an external consumer following it would call readlink first.
2. The metadata field is source_dirty, and the doc names dirty
The source_commit row says: "If the analysis ran against a dirty working tree, this is the parent commit and a dirty: true field should be set."
The field written by buildMetadata and read by normalizeMetadata is source_dirty. dirty does not exist anywhere. source_dirty is also missing from the field table and from the example metadata.yaml, so it is undocumented while a field that is documented is unimplemented.
3. reasoning values and the MCP default both differ
The example comment says high | medium | low | default | null. The GenerationReasoning type is "high" | "medium" | "low" | "default" | "unknown", so null should read unknown.
The generation capture matrix says the MCP server passes reasoning through and otherwise falls back to default. buildGenerationFromArg in mcp-server/server.ts falls back to "unknown", matching normalizeGeneration in the core. unknown looks like the correct value, given the doc's own note that consumers should read unknown as neutral.
Environment
- CodeCartographer version: 0.16.0 (
77262ad)
Additional context
All three point the same way, towards editing the doc to match the code. Worth one pass over the whole document rather than three patches, since it has not been re-read against the implementation since the format landed.
Summary
Three places where
docs/library-format.mddescribes a shape the code does not produce. Grouped because they are one file, one class of problem, and one fix.The doc's stated purpose is that "external tools can read library entries without going through CodeCartographer itself", which is what makes these worth correcting rather than leaving.
1.
latestis documented as a symlink and is never oneBoth directory layout diagrams show
latest -> v2, and the version resolution section treats a plain file as the fallback "on filesystems without symlink support".writeLatestPointerincore/library.tsis unconditionallywriteFileplusrename. The module comment states the intent: "Thelatestpointer is always a regular file (containing the version directory name as a single line), never a symlink", chosen for determinism across platforms and to avoid the Windows elevation requirement.The code behaviour is right. The doc has the primary case and the fallback the wrong way round, and an external consumer following it would call
readlinkfirst.2. The metadata field is
source_dirty, and the doc namesdirtyThe
source_commitrow says: "If the analysis ran against a dirty working tree, this is the parent commit and adirty: truefield should be set."The field written by
buildMetadataand read bynormalizeMetadataissource_dirty.dirtydoes not exist anywhere.source_dirtyis also missing from the field table and from the examplemetadata.yaml, so it is undocumented while a field that is documented is unimplemented.3.
reasoningvalues and the MCP default both differThe example comment says
high | medium | low | default | null. TheGenerationReasoningtype is"high" | "medium" | "low" | "default" | "unknown", sonullshould readunknown.The generation capture matrix says the MCP server passes reasoning through and otherwise falls back to
default.buildGenerationFromArginmcp-server/server.tsfalls back to"unknown", matchingnormalizeGenerationin the core.unknownlooks like the correct value, given the doc's own note that consumers should readunknownas neutral.Environment
77262ad)Additional context
All three point the same way, towards editing the doc to match the code. Worth one pass over the whole document rather than three patches, since it has not been re-read against the implementation since the format landed.