---
nexo: '0.1'
kind: text
file:
  name: (code py) nexo_orphan_scanner.py
  size: 4183
  mimeType: text/x-python
  sha256: 4b9d3b457c3edd4c98bb9d10a092c25b6aed17c21eb3a31a033e949e187ea896
  md5: 368ce07bc5da80339a61687f83fe9aaa

text:
  encoding: utf-8
  lines: 126

code:
  language: python

tags:
- nexo
- nexofc
- cli-tool
- companion-audit
- python
- developer-tooling

provenance:
  kind:
    method: inferred
    validation: verified
  file.name:
    method: declared
    validation: reviewed
  file.size:
    method: extracted
    validation: verified
  file.mimeType:
    method: extracted
    validation: verified
  file.sha256:
    method: extracted
    validation: verified
  file.md5:
    method: extracted
    validation: verified
  text:
    method: extracted
    validation: verified
  code.language:
    method: inferred
    validation: verified
  title:
    method: declared
    validation: reviewed
  language:
    method: inferred
    validation: unverified
  tags:
    method: generated
    validation: unverified
  summary:
    method: generated
    validation: unverified
---

# Summary

`nexo_orphan_scanner.py` is a standalone Python 3 utility written for the nexoFC project. It is not part of the reference `nexo` CLI — it is an example of a small third-party tool built on top of the NEXO File Companion format, showing what an independent implementation can do with nothing more than the file-naming convention the format defines.

A NEXO companion always sits beside its asset as `<asset>.nexo.md`. Over time a folder tree can drift out of sync with that convention in two ways: an asset that was never processed and has no companion, or a companion left behind after its asset was renamed, moved, or deleted. This script walks a directory recursively, pairs every asset with a companion by file name, and reports both kinds of drift in a single run.

It also supports an optional `--verify-hashes` pass: for every correctly paired asset and companion, it recomputes the asset's SHA-256 and compares it against the `file.sha256` value declared in the companion's YAML front matter, flagging any mismatch. This mirrors, in miniature, the integrity check that `nexo audit` performs (`nexo-cli-0.1.md` §2.1) — recomputing a hash from the asset's actual bytes rather than trusting a stored value.

The script is deliberately read-only: it never writes, deletes, or modifies an asset or a companion, and it never invents a value it did not compute. It is meant as a reference example for anyone building tooling — indexers, backup auditors, digital-asset-management integrations — around the NEXO format rather than around the `nexo` CLI itself, reinforcing the Manifesto's point that NEXO content should stay useful without the application that produced it.

Usage:

```text
python nexo_orphan_scanner.py ./library --verify-hashes
```