Skip to content

feat(knowledge): regenerate _schema.md on the doc-integrity pass (generator is currently dead code) - #1685

Closed
elhoim wants to merge 1 commit into
danielmiessler:mainfrom
elhoim:feat/knowledge-schema-doc-regen
Closed

feat(knowledge): regenerate _schema.md on the doc-integrity pass (generator is currently dead code)#1685
elhoim wants to merge 1 commit into
danielmiessler:mainfrom
elhoim:feat/knowledge-schema-doc-regen

Conversation

@elhoim

@elhoim elhoim commented Jul 28, 2026

Copy link
Copy Markdown

GenerateKnowledgeSchemaDoc.ts is dead code — nothing in the tree invokes it. Two consequences follow:

  1. _schema.md does not exist on a fresh install. The schema doc the archive is supposed to be governed by simply isn't there.
  2. Where it does exist, it drifts from KnowledgeSchema.ts, which the doc itself names as the single source of truth.

This is not theoretical

On the archive this was found on, _schema.md declared kb-v3 canonical while describing 0.9% of the notes it governed — 17 of 1,801. The gap went unnoticed for as long as it did precisely because nothing regenerated the doc, so there was no moment at which the declaration and the reality were compared.

The same class of drift bit again during the repair: a change to the validation rule in validate() would not have appeared in the generated doc, because the generator reads the PER_TYPE_REQUIRED data table. Caught only because the doc was regenerated by hand and read.

The change

Wire the generator into DocIntegrity, which already runs a cross-reference pass, so _schema.md is rebuilt from KnowledgeSchema.ts every time integrity is checked.

  • Fire-and-forget, non-fatal. A generator failure logs and does not break the doc-integrity pass.
  • Subprocess, not import. GenerateKnowledgeSchemaDoc.ts executes main() at import time, so importing it would run the generator as a side effect of loading the handler.

Net effect: the schema doc exists on every install, and cannot silently disagree with the code that defines it.

Companion to #1684, which fixes a rule in the same schema. That PR changes behaviour in validate(); this one guarantees the generated doc reflects such changes.

GenerateKnowledgeSchemaDoc.ts is currently dead code — nothing invokes it.
Two consequences: _schema.md does not exist on a fresh install, and where it
does exist it drifts from KnowledgeSchema.ts, which is the declared source
of truth.

That drift is not theoretical. On the archive this was found on, _schema.md
declared kb-v3 while describing 0.9% of the notes it governed, and the gap
went unnoticed because nothing regenerated the doc.

Wire the generator into DocIntegrity so the doc is rebuilt from the schema
on every integrity pass. Fire-and-forget, non-fatal on failure, and run as
a subprocess rather than imported because the generator executes main() on
import.
@danielmiessler

Copy link
Copy Markdown
Owner

Ported into source with credit — thank you.

The public repo is generated from a private tree at release time, so merging here would be reverted at the next cut; the intent landed in source instead, with your handle and this PR number in the code comment at the fix site.

One note: local source had moved since your base, so the port is adapted rather than byte-identical — same fix, fitted to current code. Details are in the commit. Closing as ported.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants