chore: modernize deno deps and jsr publish

Author: ClaudiuCeia

.github/workflows/publish-jsr.yml

@@ -0,0 +1,52 @@
+name: Publish to JSR
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+      - "*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: publish-jsr-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v1
+        with:
+          deno-version: v2.x
+
+      - name: Verify tag matches deno.json version
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME}"
+          tag="${tag#v}"
+          version="$(deno eval --quiet --allow-read 'console.log(JSON.parse(Deno.readTextFileSync(\"deno.json\")).version)')"
+
+          if [[ "${tag}" != "${version}" ]]; then
+            echo "Tag (${GITHUB_REF_NAME}) does not match deno.json version (${version})."
+            exit 1
+          fi
+
+      - name: Format / Lint / Test
+        run: |
+          deno fmt --check
+          deno lint
+          deno task test
+
+      - name: Publish
+        run: |
+          # Tokenless publishing requires linking the JSR package to this GitHub repository
+          # in the package settings on jsr.io, and OIDC enabled via `id-token: write`.
+          deno publish

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+coverage/

.vscode/settings.json

@@ -1,4 +1,4 @@
 {
-    "deno.enable": true,
-    "deno.unstable": true
-}
+  "deno.enable": true,
+  "deno.unstable": true
+}

AGENTS.md

@@ -0,0 +1,61 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `mod.ts`: public entrypoint; re-exports the library API.
+- `src/`: implementation (currently `src/dhash.ts`).
+- `tests/`: Deno tests (`*.test.ts`) and image fixtures used by the tests.
+- `deno.json`: package metadata, import map, and tasks.
+
+Keep public exports flowing through `mod.ts`. If you add a new public
+function/type, export it from `mod.ts` and add/adjust tests under `tests/`.
+
+## Build, Test, and Development Commands
+
+- `deno task test`: runs the full test suite with the required permissions
+  (`--allow-read --allow-ffi --allow-env`).
+- `deno test`: useful for quick runs; mirror the permissions from
+  `deno task test` if tests fail due to denied access.
+- `deno fmt`: format the repo (preferred before committing).
+- `deno lint`: run Deno’s linter on TypeScript sources.
+- `deno check mod.ts`: type-check the public surface area.
+
+## Coding Style & Naming Conventions
+
+- TypeScript for Deno; follow `deno fmt` output (2-space indent, trailing commas
+  where applicable).
+- Prefer `@std/*` imports via `deno.json` import mappings (avoid ad-hoc path
+  utilities).
+- Naming:
+  - exported functions: `camelCase` (e.g. `toAscii`, `compare`).
+  - test files: `*.test.ts`.
+
+## Testing Guidelines
+
+- Use `Deno.test(...)` with `@std/assert`-style assertions (follow existing
+  patterns in `tests/dhash.test.ts`).
+- Optional coverage: `deno test --coverage=coverage` then
+  `deno coverage coverage` (output is ignored via `.gitignore`).
+- If you change hashing behavior, update expected hashes and/or fixtures in
+  `tests/` intentionally (include rationale in the PR).
+
+## Commit & Pull Request Guidelines
+
+- Commit messages follow Conventional Commits in this repo: `feat: ...`,
+  `fix: ...`, `chore: ...`, optionally scoped like `fix(dhash): ...`.
+- PRs should include:
+  - what changed and why (short, concrete),
+  - how to verify (e.g. `deno task test`),
+  - notes on permission changes or dependency changes (especially
+    `npm:sharp@...`) and any `deno.lock` updates.
+
+## Publishing (JSR)
+
+- Bump `version` in `deno.json`.
+- Validate locally: `deno fmt`, `deno lint`, `deno task test`.
+- Preview package contents: `deno publish --dry-run`.
+- Publish: `deno publish` (auth via token/login).
+- CI publish: push a semver tag matching `deno.json`’s version (e.g. `v0.2.0`).
+  GitHub Actions will run checks then publish via JSR’s tokenless GitHub Actions
+  flow (OIDC). This requires linking the package to this GitHub repo in the JSR
+  package settings.

README.md

@@ -1,20 +1,23 @@
-# dhash 
+# dhash
+
 _A `dhash` implementation for Deno._
 
-A fast algorithm that allows checking if two images are "kind of" the same (the same source image, slightly modified). Examples:
+A fast algorithm that allows checking if two images are "kind of" the same (the
+same source image, slightly modified). Examples:
 
-- A resized, compressed, slightly cropped, or color-altered image compared with the original
-- A watermarked image versus it's source 
+- A resized, compressed, slightly cropped, or color-altered image compared with
+  the original
+- A watermarked image versus it's source
 - Meme images (mostly the same template, different text)
 
-It does this by computing a `perceptual hash` of each image and then using it to compare similarity.
+It does this by computing a `perceptual hash` of each image and then using it to
+compare similarity.
 
 ```
 Perceptual hashing is the use of a fingerprinting algorithm that produces a 
 snippet or fingerprint of various forms of multimedia.
 ```
 
-
 Based on the
 ["Kind of Like That"](https://www.hackerfactor.com/blog/?/archives/529-Kind-of-Like-That.html)
 article by [Dr. Neal Krawetz](https://www.hackerfactor.com/about.php).
@@ -39,34 +42,28 @@ const [hash1, hash2] = await Promise.all([
 console.log(compare(hash1, hash2));
 ```
 
-There are also two functions that you may use to display the fingerprint in a
-non-hash form:
+Bit convention: this implementation sets bit `1` when the pixel intensity
+increases left-to-right (`left < right`). Use `dhash(src, { invert: true })` if
+you need the opposite convention to match another implementation.
+
+## API
+
+In addition to `dhash()` and `compare()`:
 
 ```ts
-/**
-     *  toAscii will return the fingerprint represented as a matrix of
-     *  black/white pixels, represented by default through unicode low density
-     *  and full blocks, ie:
-     *
-     *   ██░░██████░░░░░░
-     *   ░░██░░░░░░░░░░██
-     *   ██░░░░░░████░░██
-     *   ░░████░░████░░██
-     *   ░░░░░░░░░░░░░░██
-     *   ████████░░░░░░░░
-     *   ░░░░░░██░░░░░░░░
-     *   ░░░░░░░░░░░░░░░░
-     * /
-    toAscii(hash: string, chars: [string, string]): string
-
-    /**
-     * save will render the fingerprint as an 8x8px PNG file with black and
-     * white pixels, at the specified path.
-     *
-     * async save(hash: string, file: string): Promise<void>
-     */
+toAscii(hash: string, chars?: [string, string]): string
+raw(hash: string): Promise<Uint8Array> // PNG bytes for the 8x8 fingerprint
+save(hash: string, filePath: string): Promise<void> // writes `${filePath}.png`
 ```
 
+`toAscii()` always renders an 8x8 matrix (64 bits); leading zero bits are
+preserved.
+
+## Development
+
+- Run tests: `deno task test` (requires `--allow-read --allow-ffi --allow-env`
+  because `sharp` uses native bindings and reads fixtures).
+
 ## License
 
 MIT © [Claudiu Ceia](https://github.com/ClaudiuCeia)

deno.json

@@ -3,10 +3,22 @@
   "version": "0.2.0",
   "license": "MIT",
   "exports": "./mod.ts",
+  "nodeModulesDir": "auto",
+  "publish": {
+    "exclude": [
+      ".vscode",
+      "tests",
+      "coverage",
+      "node_modules",
+      "AGENTS.md"
+    ]
+  },
   "tasks": {
-    "test": "deno test --allow-net --allow-read --allow-ffi --allow-env"
+    "test": "deno test --allow-read --allow-ffi --allow-env"
   },
   "imports": {
-    "@std/path": "jsr:@std/path@^1.0.9"
+    "@std/assert": "jsr:@std/assert@^1.0.18",
+    "@std/path": "jsr:@std/path@^1.1.4",
+    "sharp": "npm:sharp@0.34.5"
   }
 }