source-package.json — Duplicate File and Photo Report

{
  "schema_version": 1,
  "runtimes": [
    {
      "name": "python",
      "versions": [
        "3.10"
      ]
    }
  ],
  "dependencies": [],
  "operations": [
    {
      "kind": "read",
      "description": "Read regular files beneath caller-selected roots to identify byte-identical copies using size, sample hashes, and full SHA-256 hashes.",
      "target_restrictions": [
        "Only regular files beneath the exact ROOT arguments",
        "Symlinks and special files are skipped; package directories are skipped unless --include-packages",
        "Files marked SF_DATALESS are listed as not_downloaded and are never opened"
      ]
    },
    {
      "kind": "create",
      "description": "Create one JSON report at the exact caller-selected --report path after a matching dry-run approval digest is supplied.",
      "target_restrictions": [
        "Only the exact --report destination selected by the caller",
        "A live create requires --approve matching the dry-run digest of the destination and canonical report bytes",
        "Existing paths and symlinks are refused; the report file is opened with create-only flags"
      ]
    }
  ],
  "authorization": {
    "mode": "none",
    "scopes": [],
    "credential_requirements": []
  },
  "network": {
    "domains": [],
    "destinations": [
      "Caller-selected local --report path only; no network destinations"
    ]
  },
  "safety": {
    "read_only_by_default": true,
    "dry_run_supported": true,
    "consequential_writes_require_authorization": true,
    "validation_controls": [
      "Dry-run computes a digest over the exact report destination and canonical JSON bytes",
      "Live --report creation requires a matching --approve digest",
      "Create-only report open refuses existing paths and symlinks",
      "Dataless files are detected from stat flags before opening and never read",
      "Partial results identify skipped paths and exit 2 unless --allow-partial",
      "Approval binds resolved output, its directory and parent device/inode identities, all ancestor identities, and exact JSON bytes; no-follow descriptor traversal verifies identities before exclusive relative creation. No folders are created.",
      "Reject parent traversal (..) and NUL. Local percent signs/backslashes are literal, never URL-decoded. Enumerate metadata including filtered entries; read only hash candidates. Stream observed size plus one growth byte; no stdin.",
      "macOS or Linux with POSIX directory descriptors and O_NOFOLLOW only; Windows exits 2 before filesystem I/O",
      "Symlinked or non-directory ancestors of a scan ROOT are input errors (exit 2 even with --allow-partial). Symlinked ancestors include a physical-path hint; regular-file ancestors are reported as not directories."
    ],
    "target_restrictions": [
      "Read only caller-selected roots; never delete, move, or modify scanned files",
      "Create at most one new report at the exact --report path"
    ]
  },
  "tests": {
    "files": [
      "tests/test_duplicate_file_report.py",
      "tests/test_hygiene.py"
    ],
    "fixtures": "synthetic_only",
    "provenance": "creator",
    "evidence": [
      "Creator-authored synthetic temporary-tree tests cover duplicate grouping and exit codes",
      "Tests inject dataless stat flags and unreadable-file errors without touching real cloud files",
      "Hygiene tests read only files inside the package; synthetic tests cover symlink swaps, directory replacement, traversal, unsupported platforms and bounded hashing",
      "Synthetic regressions cover fatal scan-root ancestor refusals, physical-path guidance and distinct regular-file ancestor messages."
    ]
  }
}

License: MIT (read it).

Back to the listing