# XeSoft Project Integrity Evidence Kit

This source-visible, dependency-free Node CLI writes a `pib-repository-snapshot-v0.1` JSON file from a clean Unity Git checkout. Generate one snapshot from the accepted revision and one from the candidate revision, review both files locally, then compare them in the browser-local Project Integrity Bot evaluator.

It does not upload anything. It contains no request client, telemetry, account, install script, or background process. Read `bin/pib-snapshot.mjs` before running it.

## What it observes

- tracked and non-ignored paths under `Assets`, `Packages`, and `ProjectSettings`;
- file sizes and path kinds;
- Unity `.meta` asset/GUID pairs;
- the Unity version from `ProjectSettings/ProjectVersion.txt`;
- direct Package Manager names and sanitized requirements from `Packages/manifest.json`;
- resolved package name, sanitized version, depth, and source class from `Packages/packages-lock.json` when present;
- candidate changed paths from `git diff --name-only`; and
- effective Git `filter` attributes plus bounded LFS pointer-form evidence for current changed files.

The JSON necessarily contains repository-relative Unity paths and `.meta` GUIDs. Treat it as project information: keep it local, inspect it before pasting, and do not share it outside the studio boundary without authorization.

## What it excludes

- absolute project paths;
- C# source, Unity YAML bodies, logs, assets, and binary contents;
- Git object IDs and LFS object hashes;
- package registry URLs, Git URLs, local package paths, and credentials;
- commit history beyond the candidate changed-path names; and
- personal, player, analytics, signing, or store data.

Version `0.1.0` does not inspect serialized Unity object bodies. `serializedReferences` is emitted as an empty bounded surface, so an otherwise clean comparison remains `REVIEW` rather than silently passing all five evidence surfaces.

## Requirements

- Node.js 20 or later;
- Git available on `PATH`;
- a clean, non-sparse Unity Git checkout; and
- the actual Unity asset serialization mode and filesystem path-case mode supplied as explicit labels.

## Run from the downloaded tarball

Extract the archive and call the source directly. No dependency installation is required.

```text
tar -xzf com.xesoft.project-integrity-evidence-0.1.0.tgz
node package/bin/pib-snapshot.mjs --help
```

Accepted revision:

```text
node package/bin/pib-snapshot.mjs \
  --mode baseline \
  --comparison-id pr-931 \
  --revision-label main@accepted \
  --serialization-mode ForceText \
  --path-case-mode case-sensitive \
  --output ../reference-snapshot.json
```

Candidate revision:

```text
node package/bin/pib-snapshot.mjs \
  --mode candidate \
  --base-ref origin/main \
  --comparison-id pr-931 \
  --revision-label pr-931 \
  --serialization-mode ForceText \
  --path-case-mode case-sensitive \
  --output ../candidate-snapshot.json
```

Run the two commands in their respective clean checkouts with the same comparison ID, serialization mode, and path-case mode. The candidate base ref must resolve to the accepted comparison point.

## Fail-closed behavior

The CLI writes no snapshot when:

- the working tree is dirty or sparse;
- a required argument or Unity project file is missing;
- a relevant path is a symbolic link;
- a `.meta` file has no single valid 32-character hexadecimal GUID;
- package JSON is malformed or exceeds its ceiling;
- a label, path, or inventory exceeds the evaluator bounds;
- the requested output is inside `Assets`, `Packages`, or `ProjectSettings`; or
- the output already exists and `--overwrite` was not supplied.

The process never modifies the repository. It creates only the requested JSON file and its parent directory.

## Compare locally

Review both JSON files, then paste them into:

`https://tools.xesoft.dev/labs/project-integrity-bot`

Nothing pasted into that evaluator leaves the browser. A bounded surface remains visible and prevents a clean-for-all-surfaces conclusion.

## Primary references

- Unity asset metadata: https://docs.unity3d.com/6000.0/Documentation/Manual/AssetMetadata.html
- Unity asset serialization mode: https://docs.unity3d.com/6000.0/Documentation/Manual/class-EditorManager.html
- Unity Package Manager lock files: https://docs.unity3d.com/6000.0/Documentation/Manual/upm-conflicts-auto.html
- Git file inventory: https://git-scm.com/docs/git-ls-files
- Git changed paths: https://git-scm.com/docs/git-diff
- Git attributes: https://git-scm.com/docs/git-check-attr
