itworx-knowledge-hub-Public/tools/leafwiki-inspector/README.md

Read-only LeafWiki inspector

This standard-library Python utility inventories a LeafWiki snapshot before an import adapter is selected.

It does not import data and does not assume a fixed LeafWiki schema.

Usage

python tools/leafwiki-inspector/inspect.py /read-only/leafwiki-snapshot \
  --output artifacts/leafwiki-inspection.json

Optional:

python tools/leafwiki-inspector/inspect.py /snapshot --include-root-path

The default report omits the absolute source root. It includes:

• deterministic file manifest and SHA-256 fingerprint;
• Markdown metadata and wiki-link targets;
• SQLite schema/table/column/index/foreign-key inventory;
• SQLite row counts without reading page bodies into the report;
• JSON top-level keys;
• asset/unknown counts;
• symlink descriptors and escape warnings;
• diagnostics.

Safety

• The utility never writes under the source root.
• SQLite is opened with mode=ro&immutable=1 and PRAGMA query_only.
• Symlinks are recorded but not followed.
• Output defaults to stdout or a path outside the source.
• It does not “repair” malformed Markdown or databases.
• A hash fingerprint should be captured before and after every later migration.

This tool is a discovery aid. The final importer and versioned adapters are implemented in M4 according to docs/17-leafwiki-migration.md.